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