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 /**
 176  * @brief Enumeration of buffer manager lock try for bo
 177  * @since_tizen 5.0
 178  */
 179 typedef enum {
 180         TBM_BUFMGR_BO_LOCK_TYPE_NEVER = 0,  /**< the bufmgr do not try to lock the bos when the tbm_bo_map is called. */
 181         TBM_BUFMGR_BO_LOCK_TYPE_ONCE,       /**< the bufmgr tries to lock the bos only once when the tbm_bo_map is called. */
 182         TBM_BUFMGR_BO_LOCK_TYPE_ALWAYS,     /**< the bufmgr always tries to lock the bos when the tbm_bo_map is called. */
 183 } tbm_bufmgr_bo_lock_type;
 184
 185 #ifdef __cplusplus
 186 extern "C" {
 187 #endif
 188
 189 /* Functions for buffer manager */
 190
 191 /**
 192  * @brief Initializes the buffer manager.
 193  * @details If fd is lower than zero, fd is get drm fd in tbm_bufmgr_init function\n
 194  * 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
 195  * \n
 196  * BUFMGR_LOCK default is once\n
 197  * once : The previous bo which is locked is unlock when the new bo is trying to be locked\n
 198  * always : The new bo is locked until the previous bo which is locked is unlocked\n
 199  * never : Every bo is never locked.\n
 200  * \n
 201  * BUFMGR_MAP_CACHE default is true\n
 202  * true : use map cache flushing\n
 203  * false : to use map cache flushing
 204  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 205  * @param[in] fd : file descripter of the system buffer manager
 206  * @return a buffer manager
 207  * @retval #tbm_bufmgr
 208  * @see tbm_bufmgr_deinit();
 209  * @par Example
 210    @code
 211    #include <tbm_bufmgr.h>
 212    int bufmgr_fd;
 213
 214    setenv("BUFMGR_LOCK_TYPE", "once", 1);
 215    setenv("BUFMGR_MAP_CACHE", "true", 1);
 216
 217    tbm_bufmgr bufmgr;
 218    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 219
 220    ....
 221
 222    tbm_bufmgr_deinit (bufmgr);
 223    @endcode
 224  */
 225 tbm_bufmgr tbm_bufmgr_init(int fd);
 226
 227 /**
 228  * @brief Deinitializes the buffer manager.
 229  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 230  * @param[in] bufmgr : the buffer manager
 231  * @see tbm_bufmgr_init()
 232  * @par Example
 233    @code
 234    #include <tbm_bufmgr.h>
 235
 236    int bufmgr_fd;
 237    tbm_bufmgr bufmgr;
 238    tbm_error_e error;
 239    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 240    if (!bufmgr)
 241    {
 242       error = tbm_get_last_error ();
 243       ...
 244    }
 245
 246    ....
 247
 248    tbm_bufmgr_deinit (bufmgr);
 249    @endcode
 250  */
 251 void tbm_bufmgr_deinit(tbm_bufmgr bufmgr);
 252
 253 /* Functions for bo */
 254
 255 /**
 256  * @brief Allocates the buffer object.
 257  * @details This function create tbm_bo and set reference count to 1.\n
 258  * The user can craete tbm_bo with memory type flag #TBM_BO_FLAGS\n\n
 259  * #TBM_BO_DEFAULT indecates default memory: it depends on the backend\n
 260  * #TBM_BO_SCANOUT indecates scanout memory\n
 261  * #TBM_BO_NONCACHABLE indecates non-cachable memory\n
 262  * #TBM_BO_WC indecates write-combine memory\n
 263  * #TBM_BO_VENDOR indecates vendor specific memory: it depends on the tbm backend
 264  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 265  * @param[in] bufmgr : the buffer manager
 266  * @param[in] size : the size of buffer object
 267  * @param[in] flags : the flags of memory type
 268  * @return a buffer object
 269  * @retval #tbm_bo
 270  * @par Example
 271    @code
 272    #include <tbm_bufmgr.h>
 273
 274    int bufmgr_fd;
 275    tbm_bufmgr bufmgr;
 276    tbm_bo;
 277    tbm_error_e error;
 278
 279    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 280    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 281    if (!bo)
 282    {
 283       error = tbm_get_last_error ();
 284       ...
 285    }
 286
 287    ....
 288
 289    tbm_bufmgr_deinit (bufmgr);
 290    @endcode
 291  */
 292 tbm_bo tbm_bo_alloc(tbm_bufmgr bufmgr, int size, int flags);
 293
 294 /**
 295  * @brief Increases the reference count of bo.
 296  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 297  * @param[in] bo : the buffer object
 298  * @return a buffer object
 299  * @retval #tbm_bo
 300  * @see tbm_bo_unref()
 301  * @par Example
 302    @code
 303    #include <tbm_bufmgr.h>
 304
 305    int bufmgr_fd;
 306    tbm_bufmgr bufmgr;
 307    tbm_bo bo;
 308
 309    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 310    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 311
 312    ...
 313
 314    bo = tbm_bo_ref (bo);
 315
 316    ....
 317
 318    tbm_bufmgr_deinit (bufmgr);
 319    @endcode
 320  */
 321 tbm_bo tbm_bo_ref(tbm_bo bo);
 322
 323 /**
 324  * @brief Decreases the reference count of bo
 325  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 326  * @param[in] bo : the buffer object
 327  * @see tbm_bo_ref()
 328  * @see tbm_bo_alloc()
 329  * @par Example
 330    @code
 331    #include <tbm_bufmgr.h>
 332
 333    int bufmgr_fd;
 334    tbm_bufmgr bufmgr;
 335    tbm_bo bo;
 336
 337    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 338    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 339
 340    ...
 341
 342    tbm_bo_unref (bo);
 343    tbm_bufmgr_deinit (bufmgr);
 344    @endcode
 345  */
 346 void tbm_bo_unref(tbm_bo bo);
 347
 348 /**
 349  * @brief Maps the buffer object according to the device type and the option.
 350  * @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
 351  * If the cache flush type of bufmgr set true, the map cache flushing is executed
 352  * 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
 353  * If the lock type of bufmgr set always, the new bo is locked until the previous bo which is locked is unlocked.\n
 354  * If the lock type of bufmgr set never, Every bo is never locked.\n\n
 355  * #TBM_DEVICE_DEFAULT indecates the default handle.\n
 356  * #TBM_DEVICE_2D indecates the 2D memory handle.\n
 357  * #TBM_DEVICE_3D indecates the 3D memory handle.\n
 358  * #TBM_DEVICE_CPU indecates the virtual memory handle.\n
 359  * #TBM_DEVICE_MM indecates the multimedia handle.\n\n
 360  * #TBM_OPTION_READ indecates the accss option to read.\n
 361  * #TBM_OPTION_WRITE indecates the access option to write.\n
 362  * #TBM_OPTION_VENDOR indecates the vendor specific option that depends on the backend.
 363  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 364  * @param[in] bo : the buffer object
 365  * @param[in] device : the device type to get a handle
 366  * @param[in] opt : the option to access the buffer object
 367  * @return the handle of the buffer object
 368  * @exception #TBM_ERROR_NONE            Success
 369  * @exception #TBM_ERROR_BO_LOCK_FAILED  tbm_bo lock failed
 370  * @exception #TBM_ERROR_BO_MAP_FAILED   tbm_bo map failed
 371  * @retval #tbm_bo
 372  * @see tbm_bo_unmap()
 373  * @par Example
 374    @code
 375    #include <tbm_bufmgr.h>
 376
 377    int bufmgr_fd;
 378    tbm_bufmgr bufmgr;
 379    tbm_bo bo;
 380    tbm_bo_handle handle;
 381    tbm_error_e error;
 382
 383    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 384    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 385
 386    ...
 387
 388    handle = tbm_bo_map (bo, TBM_DEVICE_2D, TBM_OPTION_READ|TBM_OPTION_WRITE);
 389    if (handle.ptr == NULL)
 390    {
 391       error = tbm_get_last_error ();
 392       ...
 393    }
 394
 395    ...
 396
 397    tbm_bo_unmap (bo);
 398    tbm_bo_unref (bo);
 399    tbm_bufmgr_deinit (bufmgr);
 400    @endcode
 401  */
 402 tbm_bo_handle tbm_bo_map(tbm_bo bo, int device, int opt);
 403
 404 /**
 405  * @brief Unmaps the buffer object.
 406  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 407  * @param[in] bo : the buffer object
 408  * @return 1 if this function succeeds, otherwise 0.
 409  * @see tbm_bo_map()
 410  * @par Example
 411    @code
 412    #include <tbm_bufmgr.h>
 413
 414    int bufmgr_fd;
 415    tbm_bufmgr bufmgr;
 416    tbm_bo bo
 417    tbm_bo_handle handle;
 418
 419    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 420    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 421
 422    ...
 423
 424    handle = tbm_bo_map (bo, TBM_DEVICE_2D, TBM_OPTION_READ|TBM_OPTION_WRITE);
 425
 426    ...
 427
 428    tbm_bo_unmap (bo);
 429    tbm_bo_unref (bo);
 430    tbm_bufmgr_deinit (bufmgr);
 431    @endcode
 432  */
 433 int tbm_bo_unmap(tbm_bo bo);
 434
 435 /**
 436  * @brief Gets the tbm_bo_handle according to the device type.
 437  * @details The tbm_bo_handle can be get without the map of the tbm_bo.\n
 438  * In this case, TBM does not guarantee the lock and the cache flush of the tbm_bo.\n\n
 439  * #TBM_DEVICE_DEFAULT indecates the default handle.\n
 440  * #TBM_DEVICE_2D indecates the 2D memory handle.\n
 441  * #TBM_DEVICE_3D indecates the 3D memory handle.\n
 442  * #TBM_DEVICE_CPU indecates the virtual memory handle.\n
 443  * #TBM_DEVICE_MM indecates the multimedia handle.
 444  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 445  * @param[in] bo : the buffer object
 446  * @param[in] device : the device type to get a handle
 447  * @return the handle of the buffer object
 448  * @retval #tbm_bo_handle
 449  * @par Example
 450    @code
 451    #include <tbm_bufmgr.h>
 452
 453    int bufmgr_fd;
 454    tbm_bufmgr bufmgr;
 455    tbm_bo bo;
 456    tbm_bo_handle handle;
 457    tbm_error_e error;
 458
 459    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 460    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 461
 462    ...
 463
 464    handle = tbm_bo_get_handle (bo, TBM_DEVICE_2D);
 465    if (handle.ptr == NULL)
 466    {
 467       error = tbm_get_last_error ();
 468       ...
 469    }
 470
 471    ...
 472
 473    tbm_bo_unref (bo);
 474    tbm_bufmgr_deinit (bufmgr);
 475    @endcode
 476   */
 477 tbm_bo_handle tbm_bo_get_handle(tbm_bo bo, int device);
 478
 479 /**
 480  * @brief Exports the buffer object by key.
 481  * @details The tbm_bo can be exported to the anther process with the unique key associated with the the tbm_bo.
 482  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 483  * @param[in] bo : the buffer object
 484  * @return key associated with the buffer object
 485  * @retval #tbm_key
 486  * @see tbm_bo_import()
 487  * @par Example
 488    @code
 489    #include <tbm_bufmgr.h>
 490
 491    int bufmgr_fd;
 492    tbm_bufmgr bufmgr;
 493    tbm_bo;
 494    tbm_key key;
 495    tbm_error_e error;
 496
 497    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 498    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 499    key = tbm_bo_export (bo);
 500    if (key == 0)
 501    {
 502       error = tbm_get_last_error ();
 503       ...
 504    }
 505
 506    ...
 507
 508    tbm_bo_unref (bo);
 509    tbm_bufmgr_deinit (bufmgr);
 510    @endcode
 511   */
 512 tbm_key tbm_bo_export(tbm_bo bo);
 513
 514 /**
 515  * @brief Exports the buffer object by fd.
 516  * @details The tbm_bo can be exported to the anther process with the unique fd associated with the the tbm_bo.
 517  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 518  * @remarks You must release the fd using close().
 519  * @param[in] bo : the buffer object
 520  * @return fd associated with the buffer object
 521  * @retval #tbm_fd
 522  * @see tbm_bo_import_fd()
 523  * @par Example
 524    @code
 525    #include <tbm_bufmgr.h>
 526
 527    int bufmgr_fd;
 528    tbm_fd bo_fd;
 529    tbm_bufmgr bufmgr;
 530    tbm_bo;
 531    tbm_error_e error;
 532
 533    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 534    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 535    bo_fd = tbm_bo_export (bo);
 536    if (bo_fd == 0)
 537    {
 538       error = tbm_get_last_error ();
 539       ...
 540    }
 541
 542    ...
 543
 544    tbm_bo_unref (bo);
 545    tbm_bufmgr_deinit (bufmgr);
 546    @endcode
 547   */
 548 tbm_fd tbm_bo_export_fd(tbm_bo bo);
 549
 550 /**
 551  * @brief Imports the buffer object associated with the key.
 552  * @details The reference count of the tbm_bo is 1.
 553  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 554  * @param[in] bufmgr : the buffer manager
 555  * @param[in] key : the key associated with the buffer object
 556  * @return a buffer object
 557  * @retval #tbm_bo
 558  * @see tbm_bo_export()
 559  * @par Example
 560    @code
 561    #include <tbm_bufmgr.h>
 562
 563    int bufmgr_fd;
 564    int bo_key;
 565    tbm_bufmgr bufmgr;
 566    tbm_bo;
 567    tbm_error_e error;
 568
 569    ...
 570
 571    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 572    bo = tbm_bo_import (bufmgr, key);
 573    if (bo == NULL)
 574    {
 575       error = tbm_get_last_error ();
 576       ...
 577    }
 578
 579    ...
 580
 581    tbm_bo_unref (bo);
 582    tbm_bufmgr_deinit (bufmgr);
 583    @endcode
 584   */
 585 tbm_bo tbm_bo_import(tbm_bufmgr bufmgr, tbm_key key);
 586
 587 /**
 588  * @brief Imports the buffer object associated with the fd.
 589  * @details The reference count of the tbm_bo is 1.
 590  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 591  * @remarks You must release the fd using close().
 592  * @param[in] bufmgr : the buffer manager
 593  * @param[in] fd : the fd associated with the buffer object
 594  * @return a buffer object
 595  * @retval #tbm_bo
 596  * @see tbm_bo_export_fd()
 597  * @par Example
 598    @code
 599    #include <tbm_bufmgr.h>
 600
 601    int bufmgr_fd;
 602    tbm_fd bo_fd;
 603    tbm_bufmgr bufmgr;
 604    tbm_bo bo;
 605    tbm_error_e error;
 606
 607    ...
 608
 609    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 610    bo = tbm_bo_import_fd (bo_fd);
 611    if (bo == 0)
 612    {
 613       error = tbm_get_last_error ();
 614       ...
 615    }
 616
 617    ...
 618
 619    tbm_bo_unref (bo);
 620    tbm_bufmgr_deinit (bufmgr);
 621    @endcode
 622   */
 623 tbm_bo tbm_bo_import_fd(tbm_bufmgr bufmgr, tbm_fd fd);
 624
 625 /**
 626  * @brief Gets the size of a bo.
 627  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 628  * @param[in] bo : the buffer object
 629  * @return 1 if this function succeeds, otherwise 0.
 630  * @see tbm_bo_alloc()
 631  * @par Example
 632    @code
 633    #include <tbm_bufmgr.h>
 634
 635    int bufmgr_fd;
 636    tbm_bufmgr bufmgr;
 637    tbm_bo;
 638    int size;
 639
 640    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 641    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 642    size = tbm_bo_size (bo);
 643
 644    ...
 645
 646    tbm_bo_unref (bo);
 647    tbm_bufmgr_deinit (bufmgr);
 648    @endcode
 649   */
 650 int tbm_bo_size(tbm_bo bo);
 651
 652 /**
 653  * @brief Gets the state where the buffer object is locked.
 654  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 655  * @param[in] bo : the buffer object
 656  * @return 1 if this bo is locked, otherwise 0.
 657  * @see tbm_bo_map()
 658  * @see tbm_bo_unmap()
 659  * @par Example
 660    @code
 661    #include <tbm_bufmgr.h>
 662
 663    int bufmgr_fd;
 664    tbm_bufmgr bufmgr;
 665    tbm_bo bo;
 666
 667    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 668    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 669
 670    ...
 671
 672    if (tbm_bo_locked (bo))
 673    {
 674
 675    ...
 676
 677    tbm_bo_unref (bo);
 678    tbm_bufmgr_deinit (bufmgr);
 679    @endcode
 680 */
 681 int tbm_bo_locked(tbm_bo bo);
 682
 683 /**
 684  * @brief Swaps the buffer object.
 685  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 686  * @param[in] bo1 : the buffer object
 687  * @param[in] bo2 : the buffer object
 688  * @return 1 if this function succeeds, otherwise 0.
 689  * @par Example
 690    @code
 691    #include <tbm_bufmgr.h>
 692
 693    int bufmgr_fd;
 694    tbm_bufmgr bufmgr;
 695    tbm_bo bo1;
 696    tbm_bo bo2;
 697    int ret;
 698    tbm_error_e error;
 699
 700    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 701    bo1 = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 702    bo2 = tbm_bo_alloc (bufmgr, 256 * 256, TBM_BO_DEFAULT);
 703
 704    ...
 705
 706    ret = tbm_bo_swap (bo1, bo2);
 707    if (ret == 0)
 708    {
 709       error = tbm_get_last_error ();
 710       ...
 711    }
 712
 713    ...
 714
 715    tbm_bo_unref (bo1);
 716    tbm_bo_unref (bo2);
 717    tbm_bufmgr_deinit (bufmgr);
 718    @endcode
 719  */
 720 int tbm_bo_swap(tbm_bo bo1, tbm_bo bo2);
 721
 722 /**
 723  * @brief Called when the user data is deleted in buffer object.
 724  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 725  * @param[in] user_data User_data to be passed to callback function
 726  * @pre The callback must be registered using tbm_bo_add_user_data().\n
 727  * tbm_bo_delete_user_data() must be called to invoke this callback.
 728  * @see tbm_bo_add_user_data()
 729  * @see tbm_bo_delete_user_data()
 730  */
 731 typedef void (*tbm_data_free) (void *user_data);
 732
 733 /**
 734  * @brief Adds a user_data to the buffer object.
 735  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 736  * @param[in] bo : the buffer object
 737  * @param[in] key : the key associated with the user_data
 738  * @param[in] data_free_func : the function pointer to free the user_data
 739  * @return 1 if this function succeeds, otherwise 0.
 740  * @post tbm_data_free() will be called under certain conditions, after calling tbm_bo_delete_user_data().
 741  * @see tbm_data_free()
 742  * @see tbm_bo_set_user_data()
 743  * @see tbm_bo_get_user_data()
 744  * @see tbm_bo_delete_user_data()
 745  * @par Example
 746    @code
 747    #include <tbm_bufmgr.h>
 748
 749    void example_data_free (void *user_data)
 750    {
 751        char *data = (char*) user_data;
 752        free(data);
 753    }
 754
 755    int main()
 756    {
 757        int bufmgr_fd;
 758        tbm_bufmgr bufmgr;
 759        tbm_bo bo;
 760        char *user_data;
 761        char *get_data;
 762        int ret;
 763
 764        bufmgr = tbm_bufmgr_init (bufmgr_fd);
 765        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 766        user_data = (char*) malloc (sizeof(char) * 128);
 767
 768        ...
 769
 770        tbm_bo_add_user_data (bo, 1, example_data_free);
 771        tbm_bo_set_user_data (bo, 1, user_data);
 772
 773        ...
 774
 775        ret = tbm_bo_get_user_data (bo, 1, &get_data);
 776        tbm_bo_delete_user_data (bo, 1);
 777
 778        ...
 779
 780        tbm_bo_unref (bo);
 781        tbm_bufmgr_deinit (bufmgr);
 782    }
 783    @endcode
 784  */
 785
 786 int tbm_bo_add_user_data(tbm_bo bo, unsigned long key,
 787                          tbm_data_free data_free_func);
 788
 789 /**
 790  * @brief Deletes the user_data in the buffer object.
 791  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 792  * @param[in] bo : the buffer object
 793  * @param[in] key : the key associated with the user_date
 794  * @return 1 if this function succeeds, otherwise 0.
 795  * @see tbm_bo_add_user_data()
 796  * @see tbm_bo_get_user_data()
 797  * @see tbm_bo_delete_user_data()
 798  * @par Example
 799    @code
 800    #include <tbm_bufmgr.h>
 801
 802    void example_data_free (void *user_data)
 803    {
 804        char *data = (char*) user_data;
 805        free(data);
 806    }
 807
 808    int main()
 809    {
 810        int bufmgr_fd;
 811        tbm_bufmgr bufmgr;
 812        tbm_bo bo;
 813        char *user_data;
 814        char *get_data;
 815        int ret;
 816
 817        bufmgr = tbm_bufmgr_init (bufmgr_fd);
 818        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 819        user_data = (char*) malloc (sizeof(char) * 128);
 820
 821        ...
 822
 823        tbm_bo_add_user_data (bo, 1, example_data_free);
 824        tbm_bo_set_user_data (bo, 1, user_data);
 825
 826        ...
 827
 828        ret = tbm_bo_get_user_data (bo, 1, &get_data);
 829        tbm_bo_delete_user_data (bo, 1);
 830
 831        ...
 832
 833        tbm_bo_unref (bo);
 834        tbm_bufmgr_deinit (bufmgr);
 835    }
 836    @endcode
 837  */
 838 int tbm_bo_delete_user_data(tbm_bo bo, unsigned long key);
 839
 840 /**
 841  * @brief Sets a user_date to the buffer object.
 842  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 843  * @param[in] bo : the buffer object
 844  * @param[in] key : the key associated with the user_date
 845  * @param[in] data : a pointer of the user_data
 846  * @return 1 if this function succeeds, otherwise 0.
 847  * @see tbm_bo_add_user_data()
 848  * @see tbm_bo_set_user_data()
 849  * @see tbm_bo_delete_user_data()
 850  * @par Example
 851    @code
 852    #include <tbm_bufmgr.h>
 853
 854    void example_data_free (void *user_data)
 855    {
 856        char *data = (char*) user_data;
 857        free(data);
 858    }
 859
 860    int main()
 861    {
 862        int bufmgr_fd;
 863        tbm_bufmgr bufmgr;
 864        tbm_bo bo;
 865        char *user_data;
 866        char *get_data;
 867        int ret;
 868
 869        bufmgr = tbm_bufmgr_init (bufmgr_fd);
 870        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 871        user_data = (char*) malloc (sizeof(char) * 128);
 872
 873        ...
 874
 875        tbm_bo_add_user_data (bo, 1, example_data_free);
 876        tbm_bo_set_user_data (bo, 1, user_data);
 877
 878        ...
 879
 880        ret = tbm_bo_get_user_data (bo, 1, &get_data);
 881        tbm_bo_delete_user_data (bo, 1);
 882
 883        ...
 884
 885        tbm_bo_unref (bo);
 886        tbm_bufmgr_deinit (bufmgr);
 887    }
 888    @endcode
 889  */
 890 int tbm_bo_set_user_data(tbm_bo bo, unsigned long key, void *data);
 891
 892 /**
 893  * @brief Gets a user_data from the buffer object with the key.
 894  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 895  * @param[in] bo : the buffer object
 896  * @param[in] key : the key associated with the user_date
 897  * @param[out] data : to get the user data
 898  * @return 1 if this function succeeds, otherwise 0.
 899  * @see tbm_bo_add_user_data()
 900  * @see tbm_bo_set_user_data()
 901  * @see tbm_bo_get_user_data()
 902  * @par Example
 903    @code
 904    #include <tbm_bufmgr.h>
 905
 906    void example_data_free (void *user_data)
 907    {
 908        char *data = (char*) user_data;
 909        free(data);
 910    }
 911
 912    int main()
 913    {
 914        int bufmgr_fd;
 915        tbm_bufmgr bufmgr;
 916        tbm_bo bo;
 917        char *user_data;
 918        char *get_data;
 919        int ret;
 920
 921        bufmgr = tbm_bufmgr_init (bufmgr_fd);
 922        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 923        user_data = (char*) malloc (sizeof(char) * 128);
 924
 925        ...
 926
 927        tbm_bo_add_user_data (bo, 1, example_data_free);
 928        tbm_bo_set_user_data (bo, 1, user_data);
 929
 930        ...
 931
 932        ret = tbm_bo_get_user_data (bo, 1, &get_data);
 933        tbm_bo_delete_user_data (bo, 1);
 934
 935        ...
 936
 937        tbm_bo_unref (bo);
 938        tbm_bufmgr_deinit (bufmgr);
 939    }
 940    @endcode
 941  */
 942 int tbm_bo_get_user_data(tbm_bo bo, unsigned long key, void **data);
 943
 944 /**
 945  * @brief Gets the latest tbm_error.
 946  * @since_tizen 2.4
 947  * @return the latest tbm_error
 948  * @par Example
 949    @code
 950    #include <tbm_bufmgr.h>
 951
 952    int bufmgr_fd;
 953    tbm_bufmgr bufmgr;
 954    tbm_bo bo;
 955    tbm_bo_handle handle;
 956    tbm_error_e error;
 957
 958    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 959    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 960    if (!bo)
 961    {
 962       error = tbm_get_last_error ();
 963       ...
 964    }
 965
 966    ...
 967
 968    handle = tbm_bo_map (bo, TBM_DEVICE_2D, TBM_OPTION_READ|TBM_OPTION_WRITE);
 969    if (handle.ptr == NULL)
 970    {
 971       error = tbm_get_last_error ();
 972       ...
 973    }
 974
 975    ...
 976
 977    tbm_bo_unmap (bo);
 978    tbm_bo_unref (bo);
 979    tbm_bufmgr_deinit (bufmgr);
 980    @endcode
 981  */
 982 tbm_error_e tbm_get_last_error(void);
 983
 984 /**
 985  * @brief Gets the tbm buffer capability.
 986  * @since_tizen 2.4
 987  * @param[in] bufmgr : the buffer manager
 988  * @return the tbm bufmgr capability
 989  * @par Example
 990    @code
 991    #include <tbm_bufmgr.h>
 992
 993    int bufmgr_fd;
 994    tbm_bufmgr bufmgr;
 995    unsigned int capability;
 996
 997    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 998
 999    capability = tbm_bufmgr_get_capability (bufmgr);
1000
1001    tbm_bufmgr_deinit (bufmgr);
1002    @endcode
1003  */
1004 unsigned int tbm_bufmgr_get_capability(tbm_bufmgr bufmgr);
1005
1006 /**
1007  * @brief Gets the tbm bo flags.
1008  * @since_tizen 2.4
1009  * @param[in] bo : the buffer object
1010  * @return the tbm bo flags
1011  * @see TBM_BO_FLAGS
1012  * @par Example
1013    @code
1014    #include <tbm_bufmgr.h>
1015
1016    int bufmgr_fd;
1017    tbm_bufmgr bufmgr;
1018    tbm_bo;
1019    int flags;
1020
1021    bufmgr = tbm_bufmgr_init (bufmgr_fd);
1022    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
1023    flags = tbm_bo_get_flags (bo);
1024
1025    ...
1026
1027    tbm_bo_unref (bo);
1028    tbm_bufmgr_deinit (bufmgr);
1029
1030    @endcode
1031  */
1032 int tbm_bo_get_flags(tbm_bo bo);
1033
1034 /**
1035  * @brief bind the native_display.
1036  * @since_tizen 3.0
1037  * @param[in] bufmgr : the buffer manager
1038  * @param[in] native_display : the native_display
1039  */
1040 int tbm_bufmgr_bind_native_display(tbm_bufmgr bufmgr, void *native_display);
1041
1042 /**
1043  * @brief Initializes the buffer manager at the display server.
1044  * @details use this api to initialize the tbm_bufmgr at the display server.
1045  * @since_tizen 5.0
1046  */
1047 tbm_bufmgr tbm_bufmgr_server_init(void);
1048
1049 /**
1050  * @brief Print out the information of tbm_bos.
1051  * @since_tizen 3.0
1052  * @param[in] bufmgr : the buffer manager
1053  */
1054 void tbm_bufmgr_debug_show(tbm_bufmgr bufmgr);
1055
1056 /**
1057  * @brief Get string with the information of tbm_bos.
1058  * @since_tizen 3.0
1059  * @param[in] bufmgr : the buffer manager
1060  * @return sting with info if this function succeeds, otherwise NULL. It has to be free by user.
1061  */
1062 char * tbm_bufmgr_debug_tbm_info_get(tbm_bufmgr bufmgr);
1063
1064 /**
1065  * @brief Print out the trace of tbm_bos.
1066  * @since_tizen 3.0
1067  * @param[in] bufmgr : the buffer manager
1068  * @param[in] onoff : 1 is on, and 0 is off
1069  */
1070 void tbm_bufmgr_debug_trace(tbm_bufmgr bufmgr, int onoff);
1071
1072 /**
1073  * @brief Dump all tbm surfaces
1074  * @param[in] path : the given dump path
1075  * @return 1 if this function succeeds, otherwise 0.
1076  */
1077 int tbm_bufmgr_debug_dump_all(char *path);
1078
1079 /**
1080  * @brief Start the dump debugging for queue.
1081  * @since_tizen 3.0
1082  * @param[in] path : the given dump path
1083  * @param[in] count : the dump count number
1084  * @param[in] onoff : 1 is on, and 0 is off, if onoff==0 path and count are ignored
1085  * @return 1 if this function succeeds, otherwise 0.
1086  */
1087 int tbm_bufmgr_debug_queue_dump(char *path, int count, int onoff);
1088
1089 /**
1090  * @brief Set scale factor for the nearest calling tbm_bufmgr_debug_dump_all() or tbm_bufmgr_debug_queue_dump()
1091  * @since_tizen 3.0
1092  * @param[in] scale : the scale factor, 0 - disable scaling
1093  * @par Example
1094    @code
1095    #include <tbm_bufmgr.h>
1096
1097    // Dump all surface with scale factor 0.5
1098    tbm_bufmgr_debug_dump_set_scale(0.5);
1099    tbm_bufmgr_debug_dump_all("/tmp/");
1100
1101    // Start the dump debugging for queue with scale factor 0.5
1102    tbm_bufmgr_debug_dump_set_scale(0.2);
1103    tbm_bufmgr_debug_queue_dump("/tmp/", 10, 1);
1104
1105    @endcode
1106  */
1107 void tbm_bufmgr_debug_dump_set_scale(double scale);
1108
1109 /**
1110  * @brief Get ref_count of a global tbm_bufmgr
1111  * @since_tizen 5.0
1112  */
1113 int tbm_bufmgr_debug_get_ref_count(void);
1114
1115 #ifdef __cplusplus
1116 }
1117 #endif
1118 #endif                                                  /* _TBM_BUFMGR_H_ */