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