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 /**
  99  * @brief Definition for the cache invalidate
 100  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 101  */
 102 #define TBM_CACHE_INV            0x01
 103 /**
 104  * @brief Definition for the cache clean
 105  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 106  */
 107 #define TBM_CACHE_CLN            0x02
 108
 109 /* TBM_OPTION */
 110
 111 /**
 112  * @brief Definition for the access option to read
 113  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 114  */
 115 #define TBM_OPTION_READ      (1 << 0)
 116 /**
 117  * @brief Definition for the access option to write
 118  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 119  */
 120 #define TBM_OPTION_WRITE     (1 << 1)
 121 /**
 122  * @brief Definition for the vendor specific option that depends on the backend
 123  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 124  */
 125 #define TBM_OPTION_VENDOR    (0xffff0000)
 126
 127 /**
 128  * @brief tbm_bo_handle abstraction of the memory handle by TBM_DEVICE_TYPE
 129  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 130  */
 131 typedef union _tbm_bo_handle {
 132         void *ptr;
 133         int32_t s32;
 134         uint32_t u32;
 135         int64_t s64;
 136         uint64_t u64;
 137 } tbm_bo_handle;
 138
 139 /**
 140  * @brief Enumeration of bo memory type
 141  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 142  */
 143 enum TBM_BO_FLAGS {
 144         TBM_BO_DEFAULT = 0,                        /**< default memory: it depends on the backend         */
 145         TBM_BO_SCANOUT = (1 << 0),         /**< scanout memory                                    */
 146         TBM_BO_NONCACHABLE = (1 << 1), /**< non-cachable memory                               */
 147         TBM_BO_WC = (1 << 2),              /**< write-combine memory                              */
 148         TBM_BO_VENDOR = (0xffff0000), /**< vendor specific memory: it depends on the backend */
 149 };
 150
 151 /**
 152  * @brief Enumeration for tbm error type.
 153  * @since_tizen 2.4
 154  */
 155 typedef enum {
 156         TBM_ERROR_NONE = 0,                                             /**< Successful */
 157         TBM_BO_ERROR_GET_FD_FAILED = TBM_ERROR_BASE | 0x0101,     /**< failed to get fd failed */
 158         TBM_BO_ERROR_HEAP_ALLOC_FAILED = TBM_ERROR_BASE | 0x0102, /**< failed to allocate the heap memory */
 159         TBM_BO_ERROR_LOAD_MODULE_FAILED = TBM_ERROR_BASE | 0x0103,/**< failed to load module*/
 160         TBM_BO_ERROR_THREAD_INIT_FAILED = TBM_ERROR_BASE | 0x0104,/**< failed to initialize the pthread */
 161         TBM_BO_ERROR_BO_ALLOC_FAILED = TBM_ERROR_BASE | 0x0105,   /**< failed to allocate tbm_bo */
 162         TBM_BO_ERROR_INIT_STATE_FAILED = TBM_ERROR_BASE | 0x0106, /**< failed to initialize the state of tbm_bo */
 163         TBM_BO_ERROR_IMPORT_FAILED = TBM_ERROR_BASE | 0x0107,     /**< failed to import the handle of tbm_bo */
 164         TBM_BO_ERROR_IMPORT_FD_FAILED = TBM_ERROR_BASE | 0x0108,  /**< failed to import fd of tbm_bo */
 165         TBM_BO_ERROR_EXPORT_FAILED = TBM_ERROR_BASE | 0x0109,     /**< failed to export the handle of the tbm_bo */
 166         TBM_BO_ERROR_EXPORT_FD_FAILED = TBM_ERROR_BASE | 0x01010, /**< failed to export fd of tbm_bo */
 167         TBM_BO_ERROR_GET_HANDLE_FAILED = TBM_ERROR_BASE | 0x0111, /**< failed to get the tbm_bo_handle */
 168         TBM_BO_ERROR_LOCK_FAILED = TBM_ERROR_BASE | 0x0112,               /**< failed to lock the tbm_bo */
 169         TBM_BO_ERROR_MAP_FAILED = TBM_ERROR_BASE | 0x0113,                /**< failed to map the tbm_bo to get the tbm_bo_handle */
 170         TBM_BO_ERROR_UNMAP_FAILED = TBM_ERROR_BASE | 0x0114,      /**< failed to unmap the tbm_bo */
 171         TBM_BO_ERROR_SWAP_FAILED = TBM_ERROR_BASE | 0x0115,               /**< failed to swap the tbm_bos */
 172         TBM_BO_ERROR_DUP_FD_FAILED = TBM_ERROR_BASE | 0x0116,     /**< failed to duplicate fd */
 173 } tbm_error_e;
 174
 175 /**
 176  * @brief Enumeration of tbm buffer manager capability.
 177  * @since_tizen 2.4
 178  */
 179 enum TBM_BUFMGR_CAPABILITY {
 180         TBM_BUFMGR_CAPABILITY_NONE = 0,                                 /**< Not Support capability*/
 181         TBM_BUFMGR_CAPABILITY_SHARE_KEY = (1 << 0),             /**< Support sharing buffer by tbm key */
 182         TBM_BUFMGR_CAPABILITY_SHARE_FD = (1 << 1),              /**< Support sharing buffer by tbm fd */
 183 };
 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 (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_fd = tbm_bo_import_fd (bo_fd);
 611    if (bo_fd == 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, tbm_data_free data_free_func);
 787
 788 /**
 789  * @brief Deletes the user_data in the buffer object.
 790  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 791  * @param[in] bo : the buffer object
 792  * @param[in] key : the key associated with the user_date
 793  * @return 1 if this function succeeds, otherwise 0.
 794  * @see tbm_bo_add_user_data()
 795  * @see tbm_bo_get_user_data()
 796  * @see tbm_bo_delete_user_data()
 797  * @par Example
 798    @code
 799    #include <tbm_bufmgr.h>
 800
 801    void example_data_free (void *user_data)
 802    {
 803        char *data = (char*) user_data;
 804        free(data);
 805    }
 806
 807    int main()
 808    {
 809        int bufmgr_fd;
 810        tbm_bufmgr bufmgr;
 811        tbm_bo bo;
 812        char *user_data;
 813        char *get_data;
 814        int ret;
 815
 816        bufmgr = tbm_bufmgr_init (bufmgr_fd);
 817        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 818        user_data = (char*) malloc (sizeof(char) * 128);
 819
 820        ...
 821
 822        tbm_bo_add_user_data (bo, 1, example_data_free);
 823        tbm_bo_set_user_data (bo, 1, user_data);
 824
 825        ...
 826
 827        ret = tbm_bo_get_user_data (bo, 1, &get_data);
 828        tbm_bo_delete_user_data (bo, 1);
 829
 830        ...
 831
 832        tbm_bo_unref (bo);
 833        tbm_bufmgr_deinit (bufmgr);
 834    }
 835    @endcode
 836  */
 837 int tbm_bo_delete_user_data(tbm_bo bo, unsigned long key);
 838
 839 /**
 840  * @brief Sets a user_date to the buffer object.
 841  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 842  * @param[in] bo : the buffer object
 843  * @param[in] key : the key associated with the user_date
 844  * @param[in] data : a pointer of the user_data
 845  * @return 1 if this function succeeds, otherwise 0.
 846  * @see tbm_bo_add_user_data()
 847  * @see tbm_bo_set_user_data()
 848  * @see tbm_bo_delete_user_data()
 849  * @par Example
 850    @code
 851    #include <tbm_bufmgr.h>
 852
 853    void example_data_free (void *user_data)
 854    {
 855        char *data = (char*) user_data;
 856        free(data);
 857    }
 858
 859    int main()
 860    {
 861        int bufmgr_fd;
 862        tbm_bufmgr bufmgr;
 863        tbm_bo bo;
 864        char *user_data;
 865        char *get_data;
 866        int ret;
 867
 868        bufmgr = tbm_bufmgr_init (bufmgr_fd);
 869        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 870        user_data = (char*) malloc (sizeof(char) * 128);
 871
 872        ...
 873
 874        tbm_bo_add_user_data (bo, 1, example_data_free);
 875        tbm_bo_set_user_data (bo, 1, user_data);
 876
 877        ...
 878
 879        ret = tbm_bo_get_user_data (bo, 1, &get_data);
 880        tbm_bo_delete_user_data (bo, 1);
 881
 882        ...
 883
 884        tbm_bo_unref (bo);
 885        tbm_bufmgr_deinit (bufmgr);
 886    }
 887    @endcode
 888  */
 889 int tbm_bo_set_user_data(tbm_bo bo, unsigned long key, void *data);
 890
 891 /**
 892  * @brief Gets a user_data from the buffer object with the key.
 893  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 894  * @param[in] bo : the buffer object
 895  * @param[in] key : the key associated with the user_date
 896  * @param[out] data : to get the user data
 897  * @return 1 if this function succeeds, otherwise 0.
 898  * @see tbm_bo_add_user_data()
 899  * @see tbm_bo_set_user_data()
 900  * @see tbm_bo_get_user_data()
 901  * @par Example
 902    @code
 903    #include <tbm_bufmgr.h>
 904
 905    void example_data_free (void *user_data)
 906    {
 907        char *data = (char*) user_data;
 908        free(data);
 909    }
 910
 911    int main()
 912    {
 913        int bufmgr_fd;
 914        tbm_bufmgr bufmgr;
 915        tbm_bo bo;
 916        char *user_data;
 917        char *get_data;
 918        int ret;
 919
 920        bufmgr = tbm_bufmgr_init (bufmgr_fd);
 921        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 922        user_data = (char*) malloc (sizeof(char) * 128);
 923
 924        ...
 925
 926        tbm_bo_add_user_data (bo, 1, example_data_free);
 927        tbm_bo_set_user_data (bo, 1, user_data);
 928
 929        ...
 930
 931        ret = tbm_bo_get_user_data (bo, 1, &get_data);
 932        tbm_bo_delete_user_data (bo, 1);
 933
 934        ...
 935
 936        tbm_bo_unref (bo);
 937        tbm_bufmgr_deinit (bufmgr);
 938    }
 939    @endcode
 940  */
 941 int tbm_bo_get_user_data(tbm_bo bo, unsigned long key, void **data);
 942
 943 /**
 944  * @brief Gets the latest tbm_error.
 945  * @since_tizen 2.4
 946  * @return the latest tbm_error
 947  * @par Example
 948    @code
 949    #include <tbm_bufmgr.h>
 950
 951    int bufmgr_fd;
 952    tbm_bufmgr bufmgr;
 953    tbm_bo bo;
 954    tbm_bo_handle handle;
 955    tbm_error_e error;
 956
 957    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 958    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 959    if (!bo)
 960    {
 961       error = tbm_get_last_error ();
 962       ...
 963    }
 964
 965    ...
 966
 967    handle = tbm_bo_map (bo, TBM_DEVICE_2D, TBM_OPTION_READ|TBM_OPTION_WRITE);
 968    if (handle.ptr == NULL)
 969    {
 970       error = tbm_get_last_error ();
 971       ...
 972    }
 973
 974    ...
 975
 976    tbm_bo_unmap (bo);
 977    tbm_bo_unref (bo);
 978    tbm_bufmgr_deinit (bufmgr);
 979    @endcode
 980  */
 981 tbm_error_e tbm_get_last_error(void);
 982
 983 /**
 984  * @brief Gets the tbm buffer capability.
 985  * @since_tizen 2.4
 986  * @param[in] bufmgr : the buffer manager
 987  * @return the tbm bufmgr capability
 988  * @par Example
 989    @code
 990    #include <tbm_bufmgr.h>
 991
 992    int bufmgr_fd;
 993    tbm_bufmgr bufmgr;
 994    unsigned int capability;
 995
 996    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 997
 998    capability = tbm_bufmgr_get_capability (bufmgr);
 999
1000    tbm_bufmgr_deinit (bufmgr);
1001    @endcode
1002  */
1003 unsigned int tbm_bufmgr_get_capability(tbm_bufmgr bufmgr);
1004
1005 /**
1006  * @brief Gets the tbm bo flags.
1007  * @since_tizen 2.4
1008  * @param[in] bo : the buffer object
1009  * @return the tbm bo flags
1010  * @see TBM_BO_FLAGS
1011  * @par Example
1012    @code
1013    #include <tbm_bufmgr.h>
1014
1015    int bufmgr_fd;
1016    tbm_bufmgr bufmgr;
1017    tbm_bo;
1018    int flags;
1019
1020    bufmgr = tbm_bufmgr_init (bufmgr_fd);
1021    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
1022    flags = tbm_bo_get_flags (bo);
1023
1024    ...
1025
1026    tbm_bo_unref (bo);
1027    tbm_bufmgr_deinit (bufmgr);
1028
1029    @endcode
1030  */
1031 int tbm_bo_get_flags(tbm_bo bo);
1032
1033 /**
1034  * @brief Print out the information of tbm_bos.
1035  * @since_tizen 3.0
1036  * @param[in] bufmgr : the buffer manager
1037  */
1038 void tbm_bufmgr_debug_show (tbm_bufmgr bufmgr);
1039
1040 /**
1041  * @brief Print out the trace of tbm_bos.
1042  * @since_tizen 3.0
1043  * @param[in] bufmgr : the buffer manager
1044  * @param[in] onoff : 1 is on, and 0 is off
1045  */
1046 void tbm_bufmgr_debug_trace (tbm_bufmgr bufmgr, int onoff);
1047
1048
1049
1050 #ifdef __cplusplus
1051 }
1052 #endif
1053 #endif                                                  /* _TBM_BUFMGR_H_ */