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,
 789                          tbm_data_free data_free_func);
 790
 791 /**
 792  * @brief Deletes the user_data in the buffer object.
 793  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 794  * @param[in] bo : the buffer object
 795  * @param[in] key : the key associated with the user_date
 796  * @return 1 if this function succeeds, otherwise 0.
 797  * @see tbm_bo_add_user_data()
 798  * @see tbm_bo_get_user_data()
 799  * @see tbm_bo_delete_user_data()
 800  * @par Example
 801    @code
 802    #include <tbm_bufmgr.h>
 803
 804    void example_data_free (void *user_data)
 805    {
 806        char *data = (char*) user_data;
 807        free(data);
 808    }
 809
 810    int main()
 811    {
 812        int bufmgr_fd;
 813        tbm_bufmgr bufmgr;
 814        tbm_bo bo;
 815        char *user_data;
 816        char *get_data;
 817        int ret;
 818
 819        bufmgr = tbm_bufmgr_init (bufmgr_fd);
 820        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 821        user_data = (char*) malloc (sizeof(char) * 128);
 822
 823        ...
 824
 825        tbm_bo_add_user_data (bo, 1, example_data_free);
 826        tbm_bo_set_user_data (bo, 1, user_data);
 827
 828        ...
 829
 830        ret = tbm_bo_get_user_data (bo, 1, &get_data);
 831        tbm_bo_delete_user_data (bo, 1);
 832
 833        ...
 834
 835        tbm_bo_unref (bo);
 836        tbm_bufmgr_deinit (bufmgr);
 837    }
 838    @endcode
 839  */
 840 int tbm_bo_delete_user_data(tbm_bo bo, unsigned long key);
 841
 842 /**
 843  * @brief Sets a user_date to the buffer object.
 844  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 845  * @param[in] bo : the buffer object
 846  * @param[in] key : the key associated with the user_date
 847  * @param[in] data : a pointer of the user_data
 848  * @return 1 if this function succeeds, otherwise 0.
 849  * @see tbm_bo_add_user_data()
 850  * @see tbm_bo_set_user_data()
 851  * @see tbm_bo_delete_user_data()
 852  * @par Example
 853    @code
 854    #include <tbm_bufmgr.h>
 855
 856    void example_data_free (void *user_data)
 857    {
 858        char *data = (char*) user_data;
 859        free(data);
 860    }
 861
 862    int main()
 863    {
 864        int bufmgr_fd;
 865        tbm_bufmgr bufmgr;
 866        tbm_bo bo;
 867        char *user_data;
 868        char *get_data;
 869        int ret;
 870
 871        bufmgr = tbm_bufmgr_init (bufmgr_fd);
 872        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 873        user_data = (char*) malloc (sizeof(char) * 128);
 874
 875        ...
 876
 877        tbm_bo_add_user_data (bo, 1, example_data_free);
 878        tbm_bo_set_user_data (bo, 1, user_data);
 879
 880        ...
 881
 882        ret = tbm_bo_get_user_data (bo, 1, &get_data);
 883        tbm_bo_delete_user_data (bo, 1);
 884
 885        ...
 886
 887        tbm_bo_unref (bo);
 888        tbm_bufmgr_deinit (bufmgr);
 889    }
 890    @endcode
 891  */
 892 int tbm_bo_set_user_data(tbm_bo bo, unsigned long key, void *data);
 893
 894 /**
 895  * @brief Gets a user_data from the buffer object with the key.
 896  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 897  * @param[in] bo : the buffer object
 898  * @param[in] key : the key associated with the user_date
 899  * @param[out] data : to get the user data
 900  * @return 1 if this function succeeds, otherwise 0.
 901  * @see tbm_bo_add_user_data()
 902  * @see tbm_bo_set_user_data()
 903  * @see tbm_bo_get_user_data()
 904  * @par Example
 905    @code
 906    #include <tbm_bufmgr.h>
 907
 908    void example_data_free (void *user_data)
 909    {
 910        char *data = (char*) user_data;
 911        free(data);
 912    }
 913
 914    int main()
 915    {
 916        int bufmgr_fd;
 917        tbm_bufmgr bufmgr;
 918        tbm_bo bo;
 919        char *user_data;
 920        char *get_data;
 921        int ret;
 922
 923        bufmgr = tbm_bufmgr_init (bufmgr_fd);
 924        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 925        user_data = (char*) malloc (sizeof(char) * 128);
 926
 927        ...
 928
 929        tbm_bo_add_user_data (bo, 1, example_data_free);
 930        tbm_bo_set_user_data (bo, 1, user_data);
 931
 932        ...
 933
 934        ret = tbm_bo_get_user_data (bo, 1, &get_data);
 935        tbm_bo_delete_user_data (bo, 1);
 936
 937        ...
 938
 939        tbm_bo_unref (bo);
 940        tbm_bufmgr_deinit (bufmgr);
 941    }
 942    @endcode
 943  */
 944 int tbm_bo_get_user_data(tbm_bo bo, unsigned long key, void **data);
 945
 946 /**
 947  * @brief Gets the latest tbm_error.
 948  * @since_tizen 2.4
 949  * @return the latest tbm_error
 950  * @par Example
 951    @code
 952    #include <tbm_bufmgr.h>
 953
 954    int bufmgr_fd;
 955    tbm_bufmgr bufmgr;
 956    tbm_bo bo;
 957    tbm_bo_handle handle;
 958    tbm_error_e error;
 959
 960    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 961    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 962    if (!bo)
 963    {
 964       error = tbm_get_last_error ();
 965       ...
 966    }
 967
 968    ...
 969
 970    handle = tbm_bo_map (bo, TBM_DEVICE_2D, TBM_OPTION_READ|TBM_OPTION_WRITE);
 971    if (handle.ptr == NULL)
 972    {
 973       error = tbm_get_last_error ();
 974       ...
 975    }
 976
 977    ...
 978
 979    tbm_bo_unmap (bo);
 980    tbm_bo_unref (bo);
 981    tbm_bufmgr_deinit (bufmgr);
 982    @endcode
 983  */
 984 tbm_error_e tbm_get_last_error(void);
 985
 986 /**
 987  * @brief Gets the tbm buffer capability.
 988  * @since_tizen 2.4
 989  * @param[in] bufmgr : the buffer manager
 990  * @return the tbm bufmgr capability
 991  * @par Example
 992    @code
 993    #include <tbm_bufmgr.h>
 994
 995    int bufmgr_fd;
 996    tbm_bufmgr bufmgr;
 997    unsigned int capability;
 998
 999    bufmgr = tbm_bufmgr_init (bufmgr_fd);
1000
1001    capability = tbm_bufmgr_get_capability (bufmgr);
1002
1003    tbm_bufmgr_deinit (bufmgr);
1004    @endcode
1005  */
1006 unsigned int tbm_bufmgr_get_capability(tbm_bufmgr bufmgr);
1007
1008 /**
1009  * @brief Gets the tbm bo flags.
1010  * @since_tizen 2.4
1011  * @param[in] bo : the buffer object
1012  * @return the tbm bo flags
1013  * @see TBM_BO_FLAGS
1014  * @par Example
1015    @code
1016    #include <tbm_bufmgr.h>
1017
1018    int bufmgr_fd;
1019    tbm_bufmgr bufmgr;
1020    tbm_bo;
1021    int flags;
1022
1023    bufmgr = tbm_bufmgr_init (bufmgr_fd);
1024    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
1025    flags = tbm_bo_get_flags (bo);
1026
1027    ...
1028
1029    tbm_bo_unref (bo);
1030    tbm_bufmgr_deinit (bufmgr);
1031
1032    @endcode
1033  */
1034 int tbm_bo_get_flags(tbm_bo bo);
1035
1036 /**
1037  * @brief Print out the information of tbm_bos.
1038  * @since_tizen 3.0
1039  * @param[in] bufmgr : the buffer manager
1040  */
1041 void tbm_bufmgr_debug_show(tbm_bufmgr bufmgr);
1042
1043 /**
1044  * @brief Print out the trace of tbm_bos.
1045  * @since_tizen 3.0
1046  * @param[in] bufmgr : the buffer manager
1047  * @param[in] onoff : 1 is on, and 0 is off
1048  */
1049 void tbm_bufmgr_debug_trace(tbm_bufmgr bufmgr, int onoff);
1050
1051 int tbm_bufmgr_bind_native_display(tbm_bufmgr bufmgr, void *NativeDisplay);
1052
1053 #ifdef __cplusplus
1054 }
1055 #endif
1056 #endif                                                  /* _TBM_BUFMGR_H_ */