include/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
  43 /**
  44  * \file tbm_surface.h
  45  * \brief TBM Surface
  46  */
  47
  48 /**
  49  * @brief Enumeration for tbm_surface error type.
  50  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  51  */
  52 typedef enum {
  53         TBM_SURFACE_ERROR_NONE = TIZEN_ERROR_NONE,                                                        /**< Successful */
  54         TBM_SURFACE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,  /**< Invalid parameter */
  55         TBM_SURFACE_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION,  /**< Invalid Operation */
  56 } tbm_surface_error_e;
  57
  58 /**
  59  * @brief Definition for the max number of TBM surface plane.
  60  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  61  */
  62 #define TBM_SURF_PLANE_MAX 4
  63
  64 /* option to map the tbm_surface */
  65 /**
  66  * @brief Definition for the access option to read.
  67  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  68  */
  69 #define TBM_SURF_OPTION_READ      (1 << 0)
  70 /**
  71  * @brief Definition for the access option to write.
  72  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  73  */
  74 #define TBM_SURF_OPTION_WRITE     (1 << 1)
  75
  76 /**
  77  * @brief Definition for the TBM plane struct.
  78  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  79  */
  80 typedef struct _tbm_surface_plane {
  81         unsigned char *ptr;       /**< Plane pointer */
  82         uint32_t size;            /**< Plane size */
  83         uint32_t offset;          /**< Plane offset */
  84         uint32_t stride;          /**< Plane stride */
  85
  86         void *reserved1;          /**< Reserved pointer1 */
  87         void *reserved2;          /**< Reserved pointer2 */
  88         void *reserved3;          /**< Reserved pointer3 */
  89 } tbm_surface_plane_s;
  90
  91 /**
  92  * @brief Definition for the TBM surface information struct.
  93  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  94  */
  95 typedef struct _tbm_surface_info {
  96         uint32_t width;          /**< TBM surface width */
  97         uint32_t height;         /**< TBM surface height */
  98         tbm_format format;       /**< TBM surface format*/
  99         uint32_t bpp;            /**< TBM surface bbp */
 100         uint32_t size;           /**< TBM surface size */
 101
 102         uint32_t num_planes;                                                    /**< The number of planes */
 103         tbm_surface_plane_s planes[TBM_SURF_PLANE_MAX]; /**< Array of planes */
 104
 105         void *reserved4;   /**< Reserved pointer4 */
 106         void *reserved5;   /**< Reserved pointer5 */
 107         void *reserved6;   /**< Reserved pointer6 */
 108 } tbm_surface_info_s;
 109
 110 #ifdef __cplusplus
 111 extern "C" {
 112 #endif
 113
 114 /**
 115  * @brief Queries surface format list and number of format supported by the system.
 116  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 117  *
 118  * @remarks You must release the formats using free().
 119  *
 120  * @param[out] formats  The format array which the system can support \n
 121  *                      This pointer has to be freed by user.
 122  * @param[out] num      The number of formats
 123  *
 124  * @return  #TBM_SURFACE_ERROR_NONE if this function succeeds,
 125  *          otherwise an error status value
 126  *
 127  * @retval #TBM_SURFACE_ERROR_NONE               Success
 128  * @retval #TBM_SURFACE_ERROR_INVALID_OPERATION  Invalid operation
 129  *
 130  * @par Example
 131    @code
 132    #include <tbm_surface.h>
 133
 134    uint32_t *formats;
 135    uint32_t format_num;
 136    int ret, i;
 137    tbm_surface_error_e tse;
 138
 139    tse = tbm_surface_query_formats (&formats, &format_num))
 140
 141    for( i = 0 ; i < format_num ; i++)
 142    {
 143        if (formats[i] == TBM_FORMAT_RGB332)
 144        {
 145    ....
 146
 147    free (formats);
 148    @endcode
 149  */
 150 int tbm_surface_query_formats(uint32_t **formats, uint32_t *num);
 151
 152 /**
 153  * @brief Creates the tbm_surface.
 154  * @details This function creates the tbm_surface with the given width, height, and format.
 155  *
 156  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 157  *
 158  * @remark The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 159  *
 160  * @param[in] width   The width of surface
 161  * @param[in] height  The height of surface
 162  * @param[in] format  The format of surface
 163  *
 164  * @return   #tbm_surface_h on success,
 165  *           otherwise @c NULL
 166  *
 167  * @retval #tbm_surface_h  The TBM surface handle
 168  *
 169  * @exception #TBM_SURFACE_ERROR_NONE               Success
 170  * @exception #TBM_SURFACE_ERROR_INVALID_PARAMETER  Invalid parameter
 171  * @exception #TBM_SURFACE_ERROR_INVALID_OPERATION  Invalid operation
 172  *
 173  * @see tbm_surface_destroy()
 174  *
 175  * @par Example
 176    @code
 177    #include <tbm_surface.h>
 178
 179    tbm_surface_h surface;
 180
 181    surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
 182
 183    ...
 184
 185    tbm_surface_destroy (surface);
 186    @endcode
 187  */
 188 tbm_surface_h tbm_surface_create(int width, int height, tbm_format format);
 189
 190 /**
 191  * @brief Destroys the tbm_surface.
 192  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 193  *
 194  * @param[in] surface  The #tbm_surface_h
 195  *
 196  * @return  #TBM_SURFACE_ERROR_NONE on success,
 197  *          otherwise an error status value
 198  *
 199  * @retval #TBM_SURFACE_ERROR_NONE               Success
 200  * @retval #TBM_SURFACE_ERROR_INVALID_PARAMETER  Invalid parameter
 201  *
 202  * @see tbm_surface_create()
 203  *
 204  * @par Example
 205    @code
 206    #include <tbm_surface.h>
 207
 208    tbm_surface_h surface;
 209
 210    surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
 211
 212    ...
 213
 214    tbm_surface_destroy (surface);
 215    @endcode
 216  */
 217 int tbm_surface_destroy(tbm_surface_h surface);
 218
 219 /**
 220  * @brief Maps the tbm_surface according to the access option.
 221  * @details After mapping tbm_surface, the information of tbm_surface is assigned in #tbm_surface_info_s struct. \n
 222  *          The information of tbm_surface has width, height, format, bpp, size, number of planes and information of planes. \n
 223  *          The information of planes has stride, offset, size and pointer of plane. \n
 224  *          #TBM_SURF_OPTION_READ indicates access option to read. \n
 225  *          #TBM_SURF_OPTION_WRITE indicates access option to write.
 226  *
 227  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 228  *
 229  * @param[in]  surface  The #tbm_surface_h
 230  * @param[in]  opt      The option to access the tbm_surface
 231  * @param[out] info     The information of the tbm_surface
 232  *
 233  * @return  #TBM_SURFACE_ERROR_NONE on success,
 234  *          otherwise an error status value
 235  *
 236  * @retval #TBM_SURFACE_ERROR_NONE               Success
 237  * @retval #TBM_SURFACE_ERROR_INVALID_PARAMETER  Invalid parameter
 238  * @retval #TBM_SURFACE_ERROR_INVALID_OPERATION  Invalid operation
 239  *
 240  * @see tbm_surface_unmap();
 241  *
 242  * @par Example
 243    @code
 244    #include <tbm_surface.h>
 245
 246    tbm_surface_h surface;
 247    tbm_surface_info_s info;
 248    int ret;
 249
 250    surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
 251    ret = tbm_surface_map (surface, TBM_SURF_OPTION_WRITE|TBM_SURF_OPTION_READ, &info);
 252
 253    ...
 254
 255    tbm_surface_unmap (surface);
 256    tbm_surface_destroy (surface);
 257    @endcode
 258  */
 259 int tbm_surface_map(tbm_surface_h surface, int opt, tbm_surface_info_s *info);
 260
 261 /**
 262  * @brief Unmaps the tbm_surface.
 263  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 264  *
 265  * @param[in] surface  The #tbm_surface_h
 266  *
 267  * @return  #TBM_SURFACE_ERROR_NONE on success,
 268  *          otherwise an error status value
 269  *
 270  * @retval #TBM_SURFACE_ERROR_NONE               Success
 271  * @retval #TBM_SURFACE_ERROR_INVALID_PARAMETER  Invalid parameter
 272  *
 273  * @see tbm_surface_map()
 274  *
 275  * @par Example
 276    @code
 277    #include <tbm_surface.h>
 278
 279    tbm_surface_h surface;
 280    tbm_surface_info_s info;
 281    int ret;
 282
 283    surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
 284    ret = tbm_surface_map (surface, TBM_SURF_OPTION_WRITE|TBM_SURF_OPTION_READ, &info);
 285
 286    ...
 287
 288    tbm_surface_unmap (surface);
 289    tbm_surface_destroy (surface);
 290    @endcode
 291  */
 292 int tbm_surface_unmap(tbm_surface_h surface);
 293
 294 /**
 295  * @brief Gets the information of the tbm_surface.
 296  * @details The information of tbm_surface is assigned in #tbm_surface_info_s struct. \n
 297  *          The information of tbm_surface has width, height, format, bpp, size, number of planes and information of planes. \n
 298  *          The information of planes has stride, offset, size and pointer of plane.
 299  *
 300  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 301  *
 302  * @param[in]   surface  The #tbm_surface_h
 303  * @param[out]  info     The information of the tbm_surface
 304  *
 305  * @return  #TBM_SURFACE_ERROR_NONE on success,
 306  *          otherwise an error status value
 307  *
 308  * @retval #TBM_SURFACE_ERROR_NONE               Success
 309  * @retval #TBM_SURFACE_ERROR_INVALID_PARAMETER  Invalid parameter
 310  * @retval #TBM_SURFACE_ERROR_INVALID_OPERATION  Invalid operation
 311  *
 312  * @see tbm_surface_map()
 313  *
 314  * @par Example
 315    @code
 316    #include <tbm_surface.h>
 317
 318    tbm_surface_h surface;
 319    tbm_surface_info_s info;
 320    int ret;
 321
 322    surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
 323    ret = tbm_surface_get_info (surface, &info);
 324
 325    ...
 326
 327    tbm_surface_destroy (surface);
 328    @endcode
 329  */
 330 int tbm_surface_get_info(tbm_surface_h surface, tbm_surface_info_s *info);
 331
 332 /**
 333  * @brief Gets the width of the tbm_surface.
 334  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 335  *
 336  * @param[in] surface  The #tbm_surface_h
 337  *
 338  * @return  The width of the tbm_surface on success,
 339  *          otherwise an error status value
 340  *
 341  * @retval #TBM_SURFACE_ERROR_INVALID_PARAMETER  Invalid parameter
 342  *
 343  * @par Example
 344    @code
 345    #include <tbm_surface.h>
 346
 347    tbm_surface_h surface;
 348    int width;
 349
 350    surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
 351
 352    ...
 353
 354    width = tbm_surface_get_width (surface);
 355
 356    ...
 357
 358    tbm_surface_destroy (surface);
 359    @endcode
 360  */
 361 int tbm_surface_get_width(tbm_surface_h surface);
 362
 363 /**
 364  * @brief Gets the height of the tbm_surface.
 365  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 366  *
 367  * @param[in] surface  The #tbm_surface_h
 368  *
 369  * @return  The height of the tbm_surface if this function succeeds,
 370  *          otherwise an error status value
 371  *
 372  * @retval #TBM_SURFACE_ERROR_INVALID_PARAMETER  Invalid parameter
 373  *
 374  * @par Example
 375    @code
 376    #include <tbm_surface.h>
 377
 378    tbm_surface_h surface;
 379    int height;
 380
 381    surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
 382
 383    ...
 384
 385    height = tbm_surface_get_height (surface);
 386
 387    ...
 388
 389    tbm_surface_destroy (surface);
 390    @endcode
 391  */
 392 int tbm_surface_get_height(tbm_surface_h surface);
 393
 394 /**
 395  * @brief Gets the format of the tbm_surface.
 396  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 397  *
 398  * @remark The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 399  *
 400  * @param[in] surface  The #tbm_surface_h
 401  *
 402  * @return  The format of the tbm_surface on success,
 403  *          otherwise @c 0 on failure
 404  *
 405  * @retval #tbm_format  The format of surface
 406  *
 407  * @exception #TBM_SURFACE_ERROR_NONE               Success
 408  * @exception #TBM_SURFACE_ERROR_INVALID_PARAMETER  Invalid parameter
 409  *
 410  * @par Example
 411    @code
 412    #include <tbm_surface.h>
 413
 414    tbm_surface_s surface;
 415    tbm_format format;
 416
 417    surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
 418
 419    ...
 420
 421    format = tbm_surface_get_format (surface);
 422
 423    ...
 424
 425    tbm_surface_destroy (surface);
 426    @endcode
 427  */
 428 tbm_format tbm_surface_get_format(tbm_surface_h surface);
 429
 430 #ifdef __cplusplus
 431 }
 432 #endif
 433 /**
 434 * @}
 435 */
 436 #endif                                                  /* _TBM_SURFACE_H_ */