src/tbm_surface.h

   1 /**************************************************************************
   2
   3 libtbm
   4
   5 Copyright 2014 Samsung Electronics co., Ltd. All Rights Reserved.
   6
   7 Contact: SooChan Lim <sc1.lim@samsung.com>, Sangjin Lee <lsj119@samsung.com>
   8 Inpyo Kang <mantiger@samsung.com>, Dongyeon Kim <dy5.kim@samsung.com>
   9 Boram Park <boram1288.park@samsung.com>, Changyeon Lee <cyeon.lee@samsung.com>
  10
  11 Permission is hereby granted, free of charge, to any person obtaining a
  12 copy of this software and associated documentation files (the
  13 "Software"), to deal in the Software without restriction, including
  14 without limitation the rights to use, copy, modify, merge, publish,
  15 distribute, sub license, and/or sell copies of the Software, and to
  16 permit persons to whom the Software is furnished to do so, subject to
  17 the following conditions:
  18
  19 The above copyright notice and this permission notice (including the
  20 next paragraph) shall be included in all copies or substantial portions
  21 of the Software.
  22
  23 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  24 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  25 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
  26 IN NO EVENT SHALL PRECISION INSIGHT AND/OR ITS SUPPLIERS BE LIABLE FOR
  27 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  28 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  29 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  30
  31 **************************************************************************/
  32
  33 #ifndef _TBM_SURFACE_H_
  34 #define _TBM_SURFACE_H_
  35
  36 /**
  37  * @addtogroup CAPI_UI_TBM_SURFACE_MODULE
  38  * @{
  39  */
  40
  41 #include <tbm_type.h>
  42 #include <tizen.h>
  43
  44 /**
  45  * \file tbm_surface.h
  46  * \brief TBM Surface
  47  */
  48
  49 /**
  50  * @brief Enumeration for tbm_surface error type.
  51  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  52  */
  53 typedef enum {
  54         TBM_SURFACE_ERROR_NONE = TIZEN_ERROR_NONE,                                                        /**< Successful */
  55         TBM_SURFACE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,  /**< Invalid parameter */
  56         TBM_SURFACE_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION,  /**< Invalid Operation */
  57 } tbm_surface_error_e;
  58
  59 /**
  60  * @brief Definition for the max number of TBM surface plane.
  61  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  62  */
  63 #define TBM_SURF_PLANE_MAX 4
  64
  65 /* option to map the tbm_surface */
  66 /**
  67  * @brief Definition for the access option to read.
  68  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  69  */
  70 #define TBM_SURF_OPTION_READ      (1 << 0)
  71 /**
  72  * @brief Definition for the access option to write.
  73  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  74  */
  75 #define TBM_SURF_OPTION_WRITE     (1 << 1)
  76
  77 /**
  78  * @brief Definition for the TBM plane struct.
  79  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  80  */
  81 typedef struct _tbm_surface_plane {
  82         unsigned char *ptr;       /**< Plane pointer */
  83         uint32_t size;            /**< Plane size */
  84         uint32_t offset;          /**< Plane offset */
  85         uint32_t stride;          /**< Plane stride */
  86
  87         void *reserved1;          /**< Reserved pointer1 */
  88         void *reserved2;          /**< Reserved pointer2 */
  89         void *reserved3;          /**< Reserved pointer3 */
  90 } tbm_surface_plane_s;
  91
  92 /**
  93  * @brief Definition for the TBM surface information struct.
  94  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  95  */
  96 typedef struct _tbm_surface_info {
  97         uint32_t width;          /**< TBM surface width */
  98         uint32_t height;         /**< TBM surface height */
  99         tbm_format format;       /**< TBM surface format*/
 100         uint32_t bpp;            /**< TBM surface bbp */
 101         uint32_t size;           /**< TBM surface size */
 102
 103         uint32_t num_planes;                                                    /**< The number of planes */
 104         tbm_surface_plane_s planes[TBM_SURF_PLANE_MAX]; /**< Array of planes */
 105
 106         void *reserved4;   /**< Reserved pointer4 */
 107         void *reserved5;   /**< Reserved pointer5 */
 108         void *reserved6;   /**< Reserved pointer6 */
 109 } tbm_surface_info_s;
 110
 111 #ifdef __cplusplus
 112 extern "C" {
 113 #endif
 114
 115 /**
 116  * @brief Queries surface format list and number of format supported by the system.
 117  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 118  *
 119  * @remarks You must release the formats using free().
 120  *
 121  * @param[out] formats  The format array which the system can support \n
 122  *                      This pointer has to be freed by user.
 123  * @param[out] num      The number of formats
 124  *
 125  * @return  #TBM_SURFACE_ERROR_NONE if this function succeeds,
 126  *          otherwise an error status value
 127  *
 128  * @retval #TBM_SURFACE_ERROR_NONE               Success
 129  * @retval #TBM_SURFACE_ERROR_INVALID_OPERATION  Invalid operation
 130  *
 131  * @par Example
 132    @code
 133    #include <tbm_surface.h>
 134
 135    uint32_t *formats;
 136    uint32_t format_num;
 137    int ret, i;
 138    tbm_surface_error_e tse;
 139
 140    tse = tbm_surface_query_formats (&formats, &format_num))
 141
 142    for( i = 0 ; i < format_num ; i++)
 143    {
 144        if (formats[i] == TBM_FORMAT_RGB332)
 145        {
 146    ....
 147
 148    free (formats);
 149    @endcode
 150  */
 151 int tbm_surface_query_formats(uint32_t **formats, uint32_t *num);
 152
 153 /**
 154  * @brief Creates the tbm_surface.
 155  * @details This function creates the tbm_surface with the given width, height, and format.
 156  *
 157  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 158  *
 159  * @remark The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 160  *
 161  * @param[in] width   The width of surface
 162  * @param[in] height  The height of surface
 163  * @param[in] format  The format of surface
 164  *
 165  * @return   #tbm_surface_h on success,
 166  *           otherwise @c NULL
 167  *
 168  * @retval #tbm_surface_h  The TBM surface handle
 169  *
 170  * @exception #TBM_SURFACE_ERROR_NONE               Success
 171  * @exception #TBM_SURFACE_ERROR_INVALID_PARAMETER  Invalid parameter
 172  * @exception #TBM_SURFACE_ERROR_INVALID_OPERATION  Invalid operation
 173  *
 174  * @see tbm_surface_destroy()
 175  *
 176  * @par Example
 177    @code
 178    #include <tbm_surface.h>
 179
 180    tbm_surface_h surface;
 181
 182    surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
 183
 184    ...
 185
 186    tbm_surface_destroy (surface);
 187    @endcode
 188  */
 189 tbm_surface_h tbm_surface_create(int width, int height, tbm_format format);
 190
 191 /**
 192  * @brief Destroys the tbm_surface.
 193  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 194  *
 195  * @param[in] surface  The #tbm_surface_h
 196  *
 197  * @return  #TBM_SURFACE_ERROR_NONE on success,
 198  *          otherwise an error status value
 199  *
 200  * @retval #TBM_SURFACE_ERROR_NONE               Success
 201  * @retval #TBM_SURFACE_ERROR_INVALID_PARAMETER  Invalid parameter
 202  *
 203  * @see tbm_surface_create()
 204  *
 205  * @par Example
 206    @code
 207    #include <tbm_surface.h>
 208
 209    tbm_surface_h surface;
 210
 211    surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
 212
 213    ...
 214
 215    tbm_surface_destroy (surface);
 216    @endcode
 217  */
 218 int tbm_surface_destroy(tbm_surface_h surface);
 219
 220 /**
 221  * @brief Maps the tbm_surface according to the access option.
 222  * @details After mapping tbm_surface, the information of tbm_surface is assigned in #tbm_surface_info_s struct. \n
 223  *          The information of tbm_surface has width, height, format, bpp, size, number of planes and information of planes. \n
 224  *          The information of planes has stride, offset, size and pointer of plane. \n
 225  *          #TBM_SURF_OPTION_READ indicates access option to read. \n
 226  *          #TBM_SURF_OPTION_WRITE indicates access option to write.
 227  *
 228  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 229  *
 230  * @param[in]  surface  The #tbm_surface_h
 231  * @param[in]  opt      The option to access the tbm_surface
 232  * @param[out] info     The information of the tbm_surface
 233  *
 234  * @return  #TBM_SURFACE_ERROR_NONE on success,
 235  *          otherwise an error status value
 236  *
 237  * @retval #TBM_SURFACE_ERROR_NONE               Success
 238  * @retval #TBM_SURFACE_ERROR_INVALID_PARAMETER  Invalid parameter
 239  * @retval #TBM_SURFACE_ERROR_INVALID_OPERATION  Invalid operation
 240  *
 241  * @see tbm_surface_unmap();
 242  *
 243  * @par Example
 244    @code
 245    #include <tbm_surface.h>
 246
 247    tbm_surface_h surface;
 248    tbm_surface_info_s info;
 249    int ret;
 250
 251    surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
 252    ret = tbm_surface_map (surface, TBM_SURF_OPTION_WRITE|TBM_SURF_OPTION_READ, &info);
 253
 254    ...
 255
 256    tbm_surface_unmap (surface);
 257    tbm_surface_destroy (surface);
 258    @endcode
 259  */
 260 int tbm_surface_map(tbm_surface_h surface, int opt, tbm_surface_info_s *info);
 261
 262 /**
 263  * @brief Unmaps the tbm_surface.
 264  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 265  *
 266  * @param[in] surface  The #tbm_surface_h
 267  *
 268  * @return  #TBM_SURFACE_ERROR_NONE on success,
 269  *          otherwise an error status value
 270  *
 271  * @retval #TBM_SURFACE_ERROR_NONE               Success
 272  * @retval #TBM_SURFACE_ERROR_INVALID_PARAMETER  Invalid parameter
 273  *
 274  * @see tbm_surface_map()
 275  *
 276  * @par Example
 277    @code
 278    #include <tbm_surface.h>
 279
 280    tbm_surface_h surface;
 281    tbm_surface_info_s info;
 282    int ret;
 283
 284    surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
 285    ret = tbm_surface_map (surface, TBM_SURF_OPTION_WRITE|TBM_SURF_OPTION_READ, &info);
 286
 287    ...
 288
 289    tbm_surface_unmap (surface);
 290    tbm_surface_destroy (surface);
 291    @endcode
 292  */
 293 int tbm_surface_unmap(tbm_surface_h surface);
 294
 295 /**
 296  * @brief Gets the information of the tbm_surface.
 297  * @details The information of tbm_surface is assigned in #tbm_surface_info_s struct. \n
 298  *          The information of tbm_surface has width, height, format, bpp, size, number of planes and information of planes. \n
 299  *          The information of planes has stride, offset, size and pointer of plane.
 300  *
 301  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 302  *
 303  * @param[in]   surface  The #tbm_surface_h
 304  * @param[out]  info     The information of the tbm_surface
 305  *
 306  * @return  #TBM_SURFACE_ERROR_NONE on success,
 307  *          otherwise an error status value
 308  *
 309  * @retval #TBM_SURFACE_ERROR_NONE               Success
 310  * @retval #TBM_SURFACE_ERROR_INVALID_PARAMETER  Invalid parameter
 311  * @retval #TBM_SURFACE_ERROR_INVALID_OPERATION  Invalid operation
 312  *
 313  * @see tbm_surface_map()
 314  *
 315  * @par Example
 316    @code
 317    #include <tbm_surface.h>
 318
 319    tbm_surface_h surface;
 320    tbm_surface_info_s info;
 321    int ret;
 322
 323    surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
 324    ret = tbm_surface_get_info (surface, &info);
 325
 326    ...
 327
 328    tbm_surface_destroy (surface);
 329    @endcode
 330  */
 331 int tbm_surface_get_info(tbm_surface_h surface, tbm_surface_info_s *info);
 332
 333 /**
 334  * @brief Gets the width of the tbm_surface.
 335  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 336  *
 337  * @param[in] surface  The #tbm_surface_h
 338  *
 339  * @return  The width of the tbm_surface on success,
 340  *          otherwise an error status value
 341  *
 342  * @retval #TBM_SURFACE_ERROR_INVALID_PARAMETER  Invalid parameter
 343  *
 344  * @par Example
 345    @code
 346    #include <tbm_surface.h>
 347
 348    tbm_surface_h surface;
 349    int width;
 350
 351    surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
 352
 353    ...
 354
 355    width = tbm_surface_get_width (surface);
 356
 357    ...
 358
 359    tbm_surface_destroy (surface);
 360    @endcode
 361  */
 362 int tbm_surface_get_width(tbm_surface_h surface);
 363
 364 /**
 365  * @brief Gets the height of the tbm_surface.
 366  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 367  *
 368  * @param[in] surface  The #tbm_surface_h
 369  *
 370  * @return  The height of the tbm_surface if this function succeeds,
 371  *          otherwise an error status value
 372  *
 373  * @retval #TBM_SURFACE_ERROR_INVALID_PARAMETER  Invalid parameter
 374  *
 375  * @par Example
 376    @code
 377    #include <tbm_surface.h>
 378
 379    tbm_surface_h surface;
 380    int height;
 381
 382    surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
 383
 384    ...
 385
 386    height = tbm_surface_get_height (surface);
 387
 388    ...
 389
 390    tbm_surface_destroy (surface);
 391    @endcode
 392  */
 393 int tbm_surface_get_height(tbm_surface_h surface);
 394
 395 /**
 396  * @brief Gets the format of the tbm_surface.
 397  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 398  *
 399  * @remark The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 400  *
 401  * @param[in] surface  The #tbm_surface_h
 402  *
 403  * @return  The format of the tbm_surface on success,
 404  *          otherwise @c 0 on failure
 405  *
 406  * @retval #tbm_format  The format of surface
 407  *
 408  * @exception #TBM_SURFACE_ERROR_NONE               Success
 409  * @exception #TBM_SURFACE_ERROR_INVALID_PARAMETER  Invalid parameter
 410  *
 411  * @par Example
 412    @code
 413    #include <tbm_surface.h>
 414
 415    tbm_surface_s surface;
 416    tbm_format format;
 417
 418    surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
 419
 420    ...
 421
 422    format = tbm_surface_get_format (surface);
 423
 424    ...
 425
 426    tbm_surface_destroy (surface);
 427    @endcode
 428  */
 429 tbm_format tbm_surface_get_format(tbm_surface_h surface);
 430
 431 #ifdef __cplusplus
 432 }
 433 #endif
 434 /**
 435 * @}
 436 */
 437 #endif                                                  /* _TBM_SURFACE_H_ */