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