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