ut/stubs/tbm_bufmgr.h

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