src/tbm_bufmgr.h

   1 /**************************************************************************
   2
   3 libtbm
   4
   5 Copyright 2012 Samsung Electronics co., Ltd. All Rights Reserved.
   6
   7 Contact: SooChan Lim <sc1.lim@samsung.com>, Sangjin Lee <lsj119@samsung.com>
   8 Boram Park <boram1288.park@samsung.com>, Changyeon Lee <cyeon.lee@samsung.com>
   9
  10 Permission is hereby granted, free of charge, to any person obtaining a
  11 copy of this software and associated documentation files (the
  12 "Software"), to deal in the Software without restriction, including
  13 without limitation the rights to use, copy, modify, merge, publish,
  14 distribute, sub license, and/or sell copies of the Software, and to
  15 permit persons to whom the Software is furnished to do so, subject to
  16 the following conditions:
  17
  18 The above copyright notice and this permission notice (including the
  19 next paragraph) shall be included in all copies or substantial portions
  20 of the Software.
  21
  22 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  23 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  24 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
  25 IN NO EVENT SHALL PRECISION INSIGHT AND/OR ITS SUPPLIERS BE LIABLE FOR
  26 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  27 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  28 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  29
  30 **************************************************************************/
  31
  32 #ifndef _TBM_BUFMGR_H_
  33 #define _TBM_BUFMGR_H_
  34
  35 #include <tbm_type.h>
  36 #include <stdint.h>
  37
  38 /* tbm error base : this error base is same as TIZEN_ERROR_TBM in tizen_error.h */
  39 #ifndef TBM_ERROR_BASE
  40 #define TBM_ERROR_BASE                  -0x02830000
  41 #endif
  42
  43 /**
  44  * \file tbm_bufmgr.h
  45  * \brief Tizen Buffer Manager
  46  */
  47
  48 /**
  49  * @brief Definition for the tizen buffer manager
  50  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  51  */
  52 typedef struct _tbm_bufmgr *tbm_bufmgr;
  53
  54 /**
  55  * @brief Definition for the tizen buffer object
  56  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  57  */
  58 typedef struct _tbm_bo *tbm_bo;
  59 /**
  60  * @brief Definition for the key associated with the buffer object
  61  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  62  */
  63 typedef uint32_t tbm_key;
  64 /**
  65  * @brief Definition for the file descripter of the system buffer manager
  66  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  67  */
  68 typedef int32_t tbm_fd;
  69
  70 /* TBM_DEVICE_TYPE */
  71
  72 /**
  73  * @brief Definition for the device type to get the default handle
  74  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  75  */
  76 #define TBM_DEVICE_DEFAULT   0
  77 /**
  78  * @brief Definition for the device type to get the virtual memory
  79  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  80  */
  81 #define TBM_DEVICE_CPU       1
  82 /**
  83  * @brief Definition for the device type to get the 2D memory handle
  84  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  85  */
  86 #define TBM_DEVICE_2D        2
  87 /**
  88  * @brief Definition for the device type to get the 3D memory handle
  89  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  90  */
  91 #define TBM_DEVICE_3D        3
  92 /**
  93  * @brief Definition for the device type to get the multimedia handle
  94  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  95  */
  96 #define TBM_DEVICE_MM        4
  97
  98 /* TBM_OPTION */
  99
 100 /**
 101  * @brief Definition for the access option to read
 102  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 103  */
 104 #define TBM_OPTION_READ      (1 << 0)
 105 /**
 106  * @brief Definition for the access option to write
 107  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 108  */
 109 #define TBM_OPTION_WRITE     (1 << 1)
 110 /**
 111  * @brief Definition for the vendor specific option that depends on the backend
 112  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 113  */
 114 #define TBM_OPTION_VENDOR    (0xffff0000)
 115
 116 /**
 117  * @brief tbm_bo_handle abstraction of the memory handle by TBM_DEVICE_TYPE
 118  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 119  */
 120 typedef union _tbm_bo_handle {
 121         void *ptr;
 122         int32_t s32;
 123         uint32_t u32;
 124         int64_t s64;
 125         uint64_t u64;
 126 } tbm_bo_handle;
 127
 128 /**
 129  * @brief Enumeration of bo memory type
 130  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 131  */
 132 enum TBM_BO_FLAGS {
 133         TBM_BO_DEFAULT = 0,                        /**< default memory: it depends on the backend         */
 134         TBM_BO_SCANOUT = (1 << 0),         /**< scanout memory                                    */
 135         TBM_BO_NONCACHABLE = (1 << 1), /**< non-cachable memory                               */
 136         TBM_BO_WC = (1 << 2),              /**< write-combine memory                              */
 137         TBM_BO_VENDOR = (0xffff0000), /**< vendor specific memory: it depends on the backend */
 138 };
 139
 140 /**
 141  * @brief Enumeration for tbm error type.
 142  * @since_tizen 2.4
 143  */
 144 typedef enum {
 145         TBM_ERROR_NONE = 0,                                             /**< Successful */
 146         TBM_BO_ERROR_GET_FD_FAILED = TBM_ERROR_BASE | 0x0101,     /**< failed to get fd failed */
 147         TBM_BO_ERROR_HEAP_ALLOC_FAILED = TBM_ERROR_BASE | 0x0102, /**< failed to allocate the heap memory */
 148         TBM_BO_ERROR_LOAD_MODULE_FAILED = TBM_ERROR_BASE | 0x0103,/**< failed to load module*/
 149         TBM_BO_ERROR_THREAD_INIT_FAILED = TBM_ERROR_BASE | 0x0104,/**< failed to initialize the pthread */
 150         TBM_BO_ERROR_BO_ALLOC_FAILED = TBM_ERROR_BASE | 0x0105,   /**< failed to allocate tbm_bo */
 151         TBM_BO_ERROR_INIT_STATE_FAILED = TBM_ERROR_BASE | 0x0106, /**< failed to initialize the state of tbm_bo */
 152         TBM_BO_ERROR_IMPORT_FAILED = TBM_ERROR_BASE | 0x0107,     /**< failed to import the handle of tbm_bo */
 153         TBM_BO_ERROR_IMPORT_FD_FAILED = TBM_ERROR_BASE | 0x0108,  /**< failed to import fd of tbm_bo */
 154         TBM_BO_ERROR_EXPORT_FAILED = TBM_ERROR_BASE | 0x0109,     /**< failed to export the handle of the tbm_bo */
 155         TBM_BO_ERROR_EXPORT_FD_FAILED = TBM_ERROR_BASE | 0x01010, /**< failed to export fd of tbm_bo */
 156         TBM_BO_ERROR_GET_HANDLE_FAILED = TBM_ERROR_BASE | 0x0111, /**< failed to get the tbm_bo_handle */
 157         TBM_BO_ERROR_LOCK_FAILED = TBM_ERROR_BASE | 0x0112,               /**< failed to lock the tbm_bo */
 158         TBM_BO_ERROR_MAP_FAILED = TBM_ERROR_BASE | 0x0113,                /**< failed to map the tbm_bo to get the tbm_bo_handle */
 159         TBM_BO_ERROR_UNMAP_FAILED = TBM_ERROR_BASE | 0x0114,      /**< failed to unmap the tbm_bo */
 160         TBM_BO_ERROR_SWAP_FAILED = TBM_ERROR_BASE | 0x0115,               /**< failed to swap the tbm_bos */
 161         TBM_BO_ERROR_DUP_FD_FAILED = TBM_ERROR_BASE | 0x0116,     /**< failed to duplicate fd */
 162 } tbm_error_e;
 163
 164 /**
 165  * @brief Enumeration of tbm buffer manager capability.
 166  * @since_tizen 2.4
 167  */
 168 enum TBM_BUFMGR_CAPABILITY {
 169         TBM_BUFMGR_CAPABILITY_NONE = 0,                                 /**< Not Support capability*/
 170         TBM_BUFMGR_CAPABILITY_SHARE_KEY = (1 << 0),             /**< Support sharing buffer by tbm key */
 171         TBM_BUFMGR_CAPABILITY_SHARE_FD = (1 << 1),              /**< Support sharing buffer by tbm fd */
 172         TBM_BUFMGR_CAPABILITY_TBM_SYNC = (1 << 2),              /**< Support tbm sync */
 173 };
 174
 175 #ifdef __cplusplus
 176 extern "C" {
 177 #endif
 178
 179 /* Functions for buffer manager */
 180
 181 /**
 182  * @brief Initializes the buffer manager.
 183  * @details If fd is lower than zero, fd is get drm fd in tbm_bufmgr_init function\n
 184  * The user can decide the lock type and cache flush type with the environment variables, which are BUFMGR_LOCK_TYPE and BUFMGR_MAP_CACHE.\n
 185  * \n
 186  * BUFMGR_LOCK default is once\n
 187  * once : The previous bo which is locked is unlock when the new bo is trying to be locked\n
 188  * always : The new bo is locked until the previous bo which is locked is unlocked\n
 189  * never : Every bo is never locked.\n
 190  * \n
 191  * BUFMGR_MAP_CACHE default is true\n
 192  * true : use map cache flushing\n
 193  * false : to use map cache flushing
 194  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 195  * @param[in] fd : file descripter of the system buffer manager
 196  * @return a buffer manager
 197  * @retval #tbm_bufmgr
 198  * @see tbm_bufmgr_deinit();
 199  * @par Example
 200    @code
 201    #include <tbm_bufmgr.h>
 202    int bufmgr_fd;
 203
 204    setenv("BUFMGR_LOCK_TYPE", "once", 1);
 205    setenv("BUFMGR_MAP_CACHE", "true", 1);
 206
 207    tbm_bufmgr bufmgr;
 208    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 209
 210    ....
 211
 212    tbm_bufmgr_deinit (bufmgr);
 213    @endcode
 214  */
 215 tbm_bufmgr tbm_bufmgr_init(int fd);
 216
 217 /**
 218  * @brief Deinitializes the buffer manager.
 219  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 220  * @param[in] bufmgr : the buffer manager
 221  * @see tbm_bufmgr_init()
 222  * @par Example
 223    @code
 224    #include <tbm_bufmgr.h>
 225
 226    int bufmgr_fd;
 227    tbm_bufmgr bufmgr;
 228    tbm_error_e error;
 229    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 230    if (!bufmgr)
 231    {
 232       error = tbm_get_last_error ();
 233       ...
 234    }
 235
 236    ....
 237
 238    tbm_bufmgr_deinit (bufmgr);
 239    @endcode
 240  */
 241 void tbm_bufmgr_deinit(tbm_bufmgr bufmgr);
 242
 243 /* Functions for bo */
 244
 245 /**
 246  * @brief Allocates the buffer object.
 247  * @details This function create tbm_bo and set reference count to 1.\n
 248  * The user can craete tbm_bo with memory type flag #TBM_BO_FLAGS\n\n
 249  * #TBM_BO_DEFAULT indecates default memory: it depends on the backend\n
 250  * #TBM_BO_SCANOUT indecates scanout memory\n
 251  * #TBM_BO_NONCACHABLE indecates non-cachable memory\n
 252  * #TBM_BO_WC indecates write-combine memory\n
 253  * #TBM_BO_VENDOR indecates vendor specific memory: it depends on the tbm backend
 254  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 255  * @param[in] bufmgr : the buffer manager
 256  * @param[in] size : the size of buffer object
 257  * @param[in] flags : the flags of memory type
 258  * @return a buffer object
 259  * @retval #tbm_bo
 260  * @par Example
 261    @code
 262    #include <tbm_bufmgr.h>
 263
 264    int bufmgr_fd;
 265    tbm_bufmgr bufmgr;
 266    tbm_bo;
 267    tbm_error_e error;
 268
 269    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 270    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 271    if (!bo)
 272    {
 273       error = tbm_get_last_error ();
 274       ...
 275    }
 276
 277    ....
 278
 279    tbm_bufmgr_deinit (bufmgr);
 280    @endcode
 281  */
 282 tbm_bo tbm_bo_alloc(tbm_bufmgr bufmgr, int size, int flags);
 283
 284 /**
 285  * @brief Increases the reference count of bo.
 286  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 287  * @param[in] bo : the buffer object
 288  * @return a buffer object
 289  * @retval #tbm_bo
 290  * @see tbm_bo_unref()
 291  * @par Example
 292    @code
 293    #include <tbm_bufmgr.h>
 294
 295    int bufmgr_fd;
 296    tbm_bufmgr bufmgr;
 297    tbm_bo bo;
 298
 299    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 300    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 301
 302    ...
 303
 304    bo = tbm_bo_ref (bo);
 305
 306    ....
 307
 308    tbm_bufmgr_deinit (bufmgr);
 309    @endcode
 310  */
 311 tbm_bo tbm_bo_ref(tbm_bo bo);
 312
 313 /**
 314  * @brief Decreases the reference count of bo
 315  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 316  * @param[in] bo : the buffer object
 317  * @see tbm_bo_ref()
 318  * @see tbm_bo_alloc()
 319  * @par Example
 320    @code
 321    #include <tbm_bufmgr.h>
 322
 323    int bufmgr_fd;
 324    tbm_bufmgr bufmgr;
 325    tbm_bo bo;
 326
 327    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 328    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 329
 330    ...
 331
 332    tbm_bo_unref (bo);
 333    tbm_bufmgr_deinit (bufmgr);
 334    @endcode
 335  */
 336 void tbm_bo_unref(tbm_bo bo);
 337
 338 /**
 339  * @brief Maps the buffer object according to the device type and the option.
 340  * @details Cache flushing and Locking is executed, while tbm_bo is mapping in the proper condition according to the device type and the access option.\n
 341  * If the cache flush type of bufmgr set true, the map cache flushing is executed
 342  * If the lock type of bufmgr set once, the previous bo which is locked is unlock when the new bo is trying to be locked.\n
 343  * If the lock type of bufmgr set always, the new bo is locked until the previous bo which is locked is unlocked.\n
 344  * If the lock type of bufmgr set never, Every bo is never locked.\n\n
 345  * #TBM_DEVICE_DEFAULT indecates the default handle.\n
 346  * #TBM_DEVICE_2D indecates the 2D memory handle.\n
 347  * #TBM_DEVICE_3D indecates the 3D memory handle.\n
 348  * #TBM_DEVICE_CPU indecates the virtual memory handle.\n
 349  * #TBM_DEVICE_MM indecates the multimedia handle.\n\n
 350  * #TBM_OPTION_READ indecates the accss option to read.\n
 351  * #TBM_OPTION_WRITE indecates the access option to write.\n
 352  * #TBM_OPTION_VENDOR indecates the vendor specific option that depends on the backend.
 353  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 354  * @param[in] bo : the buffer object
 355  * @param[in] device : the device type to get a handle
 356  * @param[in] opt : the option to access the buffer object
 357  * @return the handle of the buffer object
 358  * @exception #TBM_ERROR_NONE            Success
 359  * @exception #TBM_ERROR_BO_LOCK_FAILED  tbm_bo lock failed
 360  * @exception #TBM_ERROR_BO_MAP_FAILED   tbm_bo map failed
 361  * @retval #tbm_bo
 362  * @see tbm_bo_unmap()
 363  * @par Example
 364    @code
 365    #include <tbm_bufmgr.h>
 366
 367    int bufmgr_fd;
 368    tbm_bufmgr bufmgr;
 369    tbm_bo bo;
 370    tbm_bo_handle handle;
 371    tbm_error_e error;
 372
 373    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 374    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 375
 376    ...
 377
 378    handle = tbm_bo_map (bo, TBM_DEVICE_2D, TBM_OPTION_READ|TBM_OPTION_WRITE);
 379    if (handle.ptr == NULL)
 380    {
 381       error = tbm_get_last_error ();
 382       ...
 383    }
 384
 385    ...
 386
 387    tbm_bo_unmap (bo);
 388    tbm_bo_unref (bo);
 389    tbm_bufmgr_deinit (bufmgr);
 390    @endcode
 391  */
 392 tbm_bo_handle tbm_bo_map(tbm_bo bo, int device, int opt);
 393
 394 /**
 395  * @brief Unmaps the buffer object.
 396  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 397  * @param[in] bo : the buffer object
 398  * @return 1 if this function succeeds, otherwise 0.
 399  * @see tbm_bo_map()
 400  * @par Example
 401    @code
 402    #include <tbm_bufmgr.h>
 403
 404    int bufmgr_fd;
 405    tbm_bufmgr bufmgr;
 406    tbm_bo bo
 407    tbm_bo_handle handle;
 408
 409    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 410    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 411
 412    ...
 413
 414    handle = tbm_bo_map (bo, TBM_DEVICE_2D, TBM_OPTION_READ|TBM_OPTION_WRITE);
 415
 416    ...
 417
 418    tbm_bo_unmap (bo);
 419    tbm_bo_unref (bo);
 420    tbm_bufmgr_deinit (bufmgr);
 421    @endcode
 422  */
 423 int tbm_bo_unmap(tbm_bo bo);
 424
 425 /**
 426  * @brief Gets the tbm_bo_handle according to the device type.
 427  * @details The tbm_bo_handle can be get without the map of the tbm_bo.\n
 428  * In this case, TBM does not guarantee the lock and the cache flush of the tbm_bo.\n\n
 429  * #TBM_DEVICE_DEFAULT indecates the default handle.\n
 430  * #TBM_DEVICE_2D indecates the 2D memory handle.\n
 431  * #TBM_DEVICE_3D indecates the 3D memory handle.\n
 432  * #TBM_DEVICE_CPU indecates the virtual memory handle.\n
 433  * #TBM_DEVICE_MM indecates the multimedia handle.
 434  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 435  * @param[in] bo : the buffer object
 436  * @param[in] device : the device type to get a handle
 437  * @return the handle of the buffer object
 438  * @retval #tbm_bo_handle
 439  * @par Example
 440    @code
 441    #include <tbm_bufmgr.h>
 442
 443    int bufmgr_fd;
 444    tbm_bufmgr bufmgr;
 445    tbm_bo bo;
 446    tbm_bo_handle handle;
 447    tbm_error_e error;
 448
 449    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 450    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 451
 452    ...
 453
 454    handle = tbm_bo_get_handle (bo, TBM_DEVICE_2D);
 455    if (handle.ptr == NULL)
 456    {
 457       error = tbm_get_last_error ();
 458       ...
 459    }
 460
 461    ...
 462
 463    tbm_bo_unref (bo);
 464    tbm_bufmgr_deinit (bufmgr);
 465    @endcode
 466   */
 467 tbm_bo_handle tbm_bo_get_handle(tbm_bo bo, int device);
 468
 469 /**
 470  * @brief Exports the buffer object by key.
 471  * @details The tbm_bo can be exported to the anther process with the unique key associated with the the tbm_bo.
 472  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 473  * @param[in] bo : the buffer object
 474  * @return key associated with the buffer object
 475  * @retval #tbm_key
 476  * @see tbm_bo_import()
 477  * @par Example
 478    @code
 479    #include <tbm_bufmgr.h>
 480
 481    int bufmgr_fd;
 482    tbm_bufmgr bufmgr;
 483    tbm_bo;
 484    tbm_key key;
 485    tbm_error_e error;
 486
 487    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 488    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 489    key = tbm_bo_export (bo);
 490    if (key == 0)
 491    {
 492       error = tbm_get_last_error ();
 493       ...
 494    }
 495
 496    ...
 497
 498    tbm_bo_unref (bo);
 499    tbm_bufmgr_deinit (bufmgr);
 500    @endcode
 501   */
 502 tbm_key tbm_bo_export(tbm_bo bo);
 503
 504 /**
 505  * @brief Exports the buffer object by fd.
 506  * @details The tbm_bo can be exported to the anther process with the unique fd associated with the the tbm_bo.
 507  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 508  * @remarks You must release the fd using close().
 509  * @param[in] bo : the buffer object
 510  * @return fd associated with the buffer object
 511  * @retval #tbm_fd
 512  * @see tbm_bo_import_fd()
 513  * @par Example
 514    @code
 515    #include <tbm_bufmgr.h>
 516
 517    int bufmgr_fd;
 518    tbm_fd bo_fd;
 519    tbm_bufmgr bufmgr;
 520    tbm_bo;
 521    tbm_error_e error;
 522
 523    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 524    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 525    bo_fd = tbm_bo_export (bo);
 526    if (bo_fd == 0)
 527    {
 528       error = tbm_get_last_error ();
 529       ...
 530    }
 531
 532    ...
 533
 534    tbm_bo_unref (bo);
 535    tbm_bufmgr_deinit (bufmgr);
 536    @endcode
 537   */
 538 tbm_fd tbm_bo_export_fd(tbm_bo bo);
 539
 540 /**
 541  * @brief Imports the buffer object associated with the key.
 542  * @details The reference count of the tbm_bo is 1.
 543  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 544  * @param[in] bufmgr : the buffer manager
 545  * @param[in] key : the key associated with the buffer object
 546  * @return a buffer object
 547  * @retval #tbm_bo
 548  * @see tbm_bo_export()
 549  * @par Example
 550    @code
 551    #include <tbm_bufmgr.h>
 552
 553    int bufmgr_fd;
 554    int bo_key;
 555    tbm_bufmgr bufmgr;
 556    tbm_bo;
 557    tbm_error_e error;
 558
 559    ...
 560
 561    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 562    bo = tbm_bo_import (bufmgr, key);
 563    if (bo == NULL)
 564    {
 565       error = tbm_get_last_error ();
 566       ...
 567    }
 568
 569    ...
 570
 571    tbm_bo_unref (bo);
 572    tbm_bufmgr_deinit (bufmgr);
 573    @endcode
 574   */
 575 tbm_bo tbm_bo_import(tbm_bufmgr bufmgr, tbm_key key);
 576
 577 /**
 578  * @brief Imports the buffer object associated with the fd.
 579  * @details The reference count of the tbm_bo is 1.
 580  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 581  * @remarks You must release the fd using close().
 582  * @param[in] bufmgr : the buffer manager
 583  * @param[in] fd : the fd associated with the buffer object
 584  * @return a buffer object
 585  * @retval #tbm_bo
 586  * @see tbm_bo_export_fd()
 587  * @par Example
 588    @code
 589    #include <tbm_bufmgr.h>
 590
 591    int bufmgr_fd;
 592    tbm_fd bo_fd;
 593    tbm_bufmgr bufmgr;
 594    tbm_bo bo;
 595    tbm_error_e error;
 596
 597    ...
 598
 599    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 600    bo = tbm_bo_import_fd (bo_fd);
 601    if (bo == 0)
 602    {
 603       error = tbm_get_last_error ();
 604       ...
 605    }
 606
 607    ...
 608
 609    tbm_bo_unref (bo);
 610    tbm_bufmgr_deinit (bufmgr);
 611    @endcode
 612   */
 613 tbm_bo tbm_bo_import_fd(tbm_bufmgr bufmgr, tbm_fd fd);
 614
 615 /**
 616  * @brief Gets the size of a bo.
 617  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 618  * @param[in] bo : the buffer object
 619  * @return 1 if this function succeeds, otherwise 0.
 620  * @see tbm_bo_alloc()
 621  * @par Example
 622    @code
 623    #include <tbm_bufmgr.h>
 624
 625    int bufmgr_fd;
 626    tbm_bufmgr bufmgr;
 627    tbm_bo;
 628    int size;
 629
 630    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 631    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 632    size = tbm_bo_size (bo);
 633
 634    ...
 635
 636    tbm_bo_unref (bo);
 637    tbm_bufmgr_deinit (bufmgr);
 638    @endcode
 639   */
 640 int tbm_bo_size(tbm_bo bo);
 641
 642 /**
 643  * @brief Gets the state where the buffer object is locked.
 644  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 645  * @param[in] bo : the buffer object
 646  * @return 1 if this bo is locked, otherwise 0.
 647  * @see tbm_bo_map()
 648  * @see tbm_bo_unmap()
 649  * @par Example
 650    @code
 651    #include <tbm_bufmgr.h>
 652
 653    int bufmgr_fd;
 654    tbm_bufmgr bufmgr;
 655    tbm_bo bo;
 656
 657    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 658    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 659
 660    ...
 661
 662    if (tbm_bo_locked (bo))
 663    {
 664
 665    ...
 666
 667    tbm_bo_unref (bo);
 668    tbm_bufmgr_deinit (bufmgr);
 669    @endcode
 670 */
 671 int tbm_bo_locked(tbm_bo bo);
 672
 673 /**
 674  * @brief Swaps the buffer object.
 675  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 676  * @param[in] bo1 : the buffer object
 677  * @param[in] bo2 : the buffer object
 678  * @return 1 if this function succeeds, otherwise 0.
 679  * @par Example
 680    @code
 681    #include <tbm_bufmgr.h>
 682
 683    int bufmgr_fd;
 684    tbm_bufmgr bufmgr;
 685    tbm_bo bo1;
 686    tbm_bo bo2;
 687    int ret;
 688    tbm_error_e error;
 689
 690    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 691    bo1 = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 692    bo2 = tbm_bo_alloc (bufmgr, 256 * 256, TBM_BO_DEFAULT);
 693
 694    ...
 695
 696    ret = tbm_bo_swap (bo1, bo2);
 697    if (ret == 0)
 698    {
 699       error = tbm_get_last_error ();
 700       ...
 701    }
 702
 703    ...
 704
 705    tbm_bo_unref (bo1);
 706    tbm_bo_unref (bo2);
 707    tbm_bufmgr_deinit (bufmgr);
 708    @endcode
 709  */
 710 int tbm_bo_swap(tbm_bo bo1, tbm_bo bo2);
 711
 712 /**
 713  * @brief Called when the user data is deleted in buffer object.
 714  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 715  * @param[in] user_data User_data to be passed to callback function
 716  * @pre The callback must be registered using tbm_bo_add_user_data().\n
 717  * tbm_bo_delete_user_data() must be called to invoke this callback.
 718  * @see tbm_bo_add_user_data()
 719  * @see tbm_bo_delete_user_data()
 720  */
 721 typedef void (*tbm_data_free) (void *user_data);
 722
 723 /**
 724  * @brief Adds a user_data to the buffer object.
 725  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 726  * @param[in] bo : the buffer object
 727  * @param[in] key : the key associated with the user_data
 728  * @param[in] data_free_func : the function pointer to free the user_data
 729  * @return 1 if this function succeeds, otherwise 0.
 730  * @post tbm_data_free() will be called under certain conditions, after calling tbm_bo_delete_user_data().
 731  * @see tbm_data_free()
 732  * @see tbm_bo_set_user_data()
 733  * @see tbm_bo_get_user_data()
 734  * @see tbm_bo_delete_user_data()
 735  * @par Example
 736    @code
 737    #include <tbm_bufmgr.h>
 738
 739    void example_data_free (void *user_data)
 740    {
 741        char *data = (char*) user_data;
 742        free(data);
 743    }
 744
 745    int main()
 746    {
 747        int bufmgr_fd;
 748        tbm_bufmgr bufmgr;
 749        tbm_bo bo;
 750        char *user_data;
 751        char *get_data;
 752        int ret;
 753
 754        bufmgr = tbm_bufmgr_init (bufmgr_fd);
 755        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 756        user_data = (char*) malloc (sizeof(char) * 128);
 757
 758        ...
 759
 760        tbm_bo_add_user_data (bo, 1, example_data_free);
 761        tbm_bo_set_user_data (bo, 1, user_data);
 762
 763        ...
 764
 765        ret = tbm_bo_get_user_data (bo, 1, &get_data);
 766        tbm_bo_delete_user_data (bo, 1);
 767
 768        ...
 769
 770        tbm_bo_unref (bo);
 771        tbm_bufmgr_deinit (bufmgr);
 772    }
 773    @endcode
 774  */
 775
 776 int tbm_bo_add_user_data(tbm_bo bo, unsigned long key,
 777                          tbm_data_free data_free_func);
 778
 779 /**
 780  * @brief Deletes the user_data in the buffer object.
 781  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 782  * @param[in] bo : the buffer object
 783  * @param[in] key : the key associated with the user_date
 784  * @return 1 if this function succeeds, otherwise 0.
 785  * @see tbm_bo_add_user_data()
 786  * @see tbm_bo_get_user_data()
 787  * @see tbm_bo_delete_user_data()
 788  * @par Example
 789    @code
 790    #include <tbm_bufmgr.h>
 791
 792    void example_data_free (void *user_data)
 793    {
 794        char *data = (char*) user_data;
 795        free(data);
 796    }
 797
 798    int main()
 799    {
 800        int bufmgr_fd;
 801        tbm_bufmgr bufmgr;
 802        tbm_bo bo;
 803        char *user_data;
 804        char *get_data;
 805        int ret;
 806
 807        bufmgr = tbm_bufmgr_init (bufmgr_fd);
 808        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 809        user_data = (char*) malloc (sizeof(char) * 128);
 810
 811        ...
 812
 813        tbm_bo_add_user_data (bo, 1, example_data_free);
 814        tbm_bo_set_user_data (bo, 1, user_data);
 815
 816        ...
 817
 818        ret = tbm_bo_get_user_data (bo, 1, &get_data);
 819        tbm_bo_delete_user_data (bo, 1);
 820
 821        ...
 822
 823        tbm_bo_unref (bo);
 824        tbm_bufmgr_deinit (bufmgr);
 825    }
 826    @endcode
 827  */
 828 int tbm_bo_delete_user_data(tbm_bo bo, unsigned long key);
 829
 830 /**
 831  * @brief Sets a user_date to the buffer object.
 832  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 833  * @param[in] bo : the buffer object
 834  * @param[in] key : the key associated with the user_date
 835  * @param[in] data : a pointer of the user_data
 836  * @return 1 if this function succeeds, otherwise 0.
 837  * @see tbm_bo_add_user_data()
 838  * @see tbm_bo_set_user_data()
 839  * @see tbm_bo_delete_user_data()
 840  * @par Example
 841    @code
 842    #include <tbm_bufmgr.h>
 843
 844    void example_data_free (void *user_data)
 845    {
 846        char *data = (char*) user_data;
 847        free(data);
 848    }
 849
 850    int main()
 851    {
 852        int bufmgr_fd;
 853        tbm_bufmgr bufmgr;
 854        tbm_bo bo;
 855        char *user_data;
 856        char *get_data;
 857        int ret;
 858
 859        bufmgr = tbm_bufmgr_init (bufmgr_fd);
 860        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 861        user_data = (char*) malloc (sizeof(char) * 128);
 862
 863        ...
 864
 865        tbm_bo_add_user_data (bo, 1, example_data_free);
 866        tbm_bo_set_user_data (bo, 1, user_data);
 867
 868        ...
 869
 870        ret = tbm_bo_get_user_data (bo, 1, &get_data);
 871        tbm_bo_delete_user_data (bo, 1);
 872
 873        ...
 874
 875        tbm_bo_unref (bo);
 876        tbm_bufmgr_deinit (bufmgr);
 877    }
 878    @endcode
 879  */
 880 int tbm_bo_set_user_data(tbm_bo bo, unsigned long key, void *data);
 881
 882 /**
 883  * @brief Gets a user_data from the buffer object with the key.
 884  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 885  * @param[in] bo : the buffer object
 886  * @param[in] key : the key associated with the user_date
 887  * @param[out] data : to get the user data
 888  * @return 1 if this function succeeds, otherwise 0.
 889  * @see tbm_bo_add_user_data()
 890  * @see tbm_bo_set_user_data()
 891  * @see tbm_bo_get_user_data()
 892  * @par Example
 893    @code
 894    #include <tbm_bufmgr.h>
 895
 896    void example_data_free (void *user_data)
 897    {
 898        char *data = (char*) user_data;
 899        free(data);
 900    }
 901
 902    int main()
 903    {
 904        int bufmgr_fd;
 905        tbm_bufmgr bufmgr;
 906        tbm_bo bo;
 907        char *user_data;
 908        char *get_data;
 909        int ret;
 910
 911        bufmgr = tbm_bufmgr_init (bufmgr_fd);
 912        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 913        user_data = (char*) malloc (sizeof(char) * 128);
 914
 915        ...
 916
 917        tbm_bo_add_user_data (bo, 1, example_data_free);
 918        tbm_bo_set_user_data (bo, 1, user_data);
 919
 920        ...
 921
 922        ret = tbm_bo_get_user_data (bo, 1, &get_data);
 923        tbm_bo_delete_user_data (bo, 1);
 924
 925        ...
 926
 927        tbm_bo_unref (bo);
 928        tbm_bufmgr_deinit (bufmgr);
 929    }
 930    @endcode
 931  */
 932 int tbm_bo_get_user_data(tbm_bo bo, unsigned long key, void **data);
 933
 934 /**
 935  * @brief Gets the latest tbm_error.
 936  * @since_tizen 2.4
 937  * @return the latest tbm_error
 938  * @par Example
 939    @code
 940    #include <tbm_bufmgr.h>
 941
 942    int bufmgr_fd;
 943    tbm_bufmgr bufmgr;
 944    tbm_bo bo;
 945    tbm_bo_handle handle;
 946    tbm_error_e error;
 947
 948    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 949    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 950    if (!bo)
 951    {
 952       error = tbm_get_last_error ();
 953       ...
 954    }
 955
 956    ...
 957
 958    handle = tbm_bo_map (bo, TBM_DEVICE_2D, TBM_OPTION_READ|TBM_OPTION_WRITE);
 959    if (handle.ptr == NULL)
 960    {
 961       error = tbm_get_last_error ();
 962       ...
 963    }
 964
 965    ...
 966
 967    tbm_bo_unmap (bo);
 968    tbm_bo_unref (bo);
 969    tbm_bufmgr_deinit (bufmgr);
 970    @endcode
 971  */
 972 tbm_error_e tbm_get_last_error(void);
 973
 974 /**
 975  * @brief Gets the tbm buffer capability.
 976  * @since_tizen 2.4
 977  * @param[in] bufmgr : the buffer manager
 978  * @return the tbm bufmgr capability
 979  * @par Example
 980    @code
 981    #include <tbm_bufmgr.h>
 982
 983    int bufmgr_fd;
 984    tbm_bufmgr bufmgr;
 985    unsigned int capability;
 986
 987    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 988
 989    capability = tbm_bufmgr_get_capability (bufmgr);
 990
 991    tbm_bufmgr_deinit (bufmgr);
 992    @endcode
 993  */
 994 unsigned int tbm_bufmgr_get_capability(tbm_bufmgr bufmgr);
 995
 996 /**
 997  * @brief Gets the tbm bo flags.
 998  * @since_tizen 2.4
 999  * @param[in] bo : the buffer object
1000  * @return the tbm bo flags
1001  * @see TBM_BO_FLAGS
1002  * @par Example
1003    @code
1004    #include <tbm_bufmgr.h>
1005
1006    int bufmgr_fd;
1007    tbm_bufmgr bufmgr;
1008    tbm_bo;
1009    int flags;
1010
1011    bufmgr = tbm_bufmgr_init (bufmgr_fd);
1012    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
1013    flags = tbm_bo_get_flags (bo);
1014
1015    ...
1016
1017    tbm_bo_unref (bo);
1018    tbm_bufmgr_deinit (bufmgr);
1019
1020    @endcode
1021  */
1022 int tbm_bo_get_flags(tbm_bo bo);
1023
1024 /**
1025  * @brief bind the native_display.
1026  * @since_tizen 3.0
1027  * @param[in] bufmgr : the buffer manager
1028  * @param[in] native_display : the native_display
1029  */
1030 int tbm_bufmgr_bind_native_display(tbm_bufmgr bufmgr, void *native_display);
1031
1032 /**
1033  * @brief Print out the information of tbm_bos.
1034  * @since_tizen 3.0
1035  * @param[in] bufmgr : the buffer manager
1036  */
1037 void tbm_bufmgr_debug_show(tbm_bufmgr bufmgr);
1038
1039 /**
1040  * @brief Get string with the information of tbm_bos.
1041  * @since_tizen 3.0
1042  * @param[in] bufmgr : the buffer manager
1043  * @return sting with info if this function succeeds, otherwise NULL. It has to be free by user.
1044  */
1045 char * tbm_bufmgr_debug_tbm_info_get(tbm_bufmgr bufmgr);
1046
1047 /**
1048  * @brief Print out the trace of tbm_bos.
1049  * @since_tizen 3.0
1050  * @param[in] bufmgr : the buffer manager
1051  * @param[in] onoff : 1 is on, and 0 is off
1052  */
1053 void tbm_bufmgr_debug_trace(tbm_bufmgr bufmgr, int onoff);
1054
1055 /**
1056  * @brief Dump all tbm surfaces
1057  * @param[in] path : the given dump path
1058  * @return 1 if this function succeeds, otherwise 0.
1059  */
1060 int tbm_bufmgr_debug_dump_all(char *path);
1061
1062 /**
1063  * @brief Start the dump debugging for queue.
1064  * @since_tizen 3.0
1065  * @param[in] path : the given dump path
1066  * @param[in] count : the dump count number
1067  * @param[in] onoff : 1 is on, and 0 is off, if onoff==0 path and count are ignored
1068  * @return 1 if this function succeeds, otherwise 0.
1069  */
1070 int tbm_bufmgr_debug_queue_dump(char *path, int count, int onoff);
1071
1072 /**
1073  * @brief Set scale factor for the nearest calling tbm_bufmgr_debug_dump_all() or tbm_bufmgr_debug_queue_dump()
1074  * @since_tizen 3.0
1075  * @param[in] scale : the scale factor, 0 - disable scaling
1076  * @par Example
1077    @code
1078    #include <tbm_bufmgr.h>
1079
1080    // Dump all surface with scale factor 0.5
1081    tbm_bufmgr_debug_dump_set_scale(0.5);
1082    tbm_bufmgr_debug_dump_all("/tmp/");
1083
1084    // Start the dump debugging for queue with scale factor 0.5
1085    tbm_bufmgr_debug_dump_set_scale(0.2);
1086    tbm_bufmgr_debug_queue_dump("/tmp/", 10, 1);
1087
1088    @endcode
1089  */
1090 void tbm_bufmgr_debug_dump_set_scale(double scale);
1091
1092 /**
1093  * @brief Get ref_count of a global tbm_bufmgr
1094  * @since_tizen 5.0
1095  */
1096 int tbm_bufmgr_debug_get_ref_count(void);
1097
1098 #ifdef __cplusplus
1099 }
1100 #endif
1101 #endif                                                  /* _TBM_BUFMGR_H_ */