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  * @param[in] bo : the buffer object
 516  * @return fd associated with the buffer object
 517  * @retval #tbm_fd
 518  * @see tbm_bo_import_fd()
 519  * @par Example
 520    @code
 521    #include <tbm_bufmgr.h>
 522
 523    int bufmgr_fd;
 524    tbm_fd bo_fd;
 525    tbm_bufmgr bufmgr;
 526    tbm_bo;
 527    tbm_error_e error;
 528
 529    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 530    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 531    bo_fd = tbm_bo_export (bo);
 532    if (bo_fd == 0)
 533    {
 534       error = tbm_get_last_error ();
 535       ...
 536    }
 537
 538    ...
 539
 540    tbm_bo_unref (bo);
 541    tbm_bufmgr_deinit (bufmgr);
 542    @endcode
 543   */
 544 tbm_fd tbm_bo_export_fd (tbm_bo bo);
 545
 546 /**
 547  * @brief Imports the buffer object associated with the key.
 548  * @details The reference count of the tbm_bo is 1.
 549  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 550  * @param[in] bufmgr : the buffer manager
 551  * @param[in] key : the key associated with the buffer object
 552  * @return a buffer object
 553  * @retval #tbm_bo
 554  * @see tbm_bo_export()
 555  * @par Example
 556    @code
 557    #include <tbm_bufmgr.h>
 558
 559    int bufmgr_fd;
 560    int bo_key;
 561    tbm_bufmgr bufmgr;
 562    tbm_bo;
 563    tbm_error_e error;
 564
 565    ...
 566
 567    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 568    bo = tbm_bo_import (key);
 569    if (bo == NULL)
 570    {
 571       error = tbm_get_last_error ();
 572       ...
 573    }
 574
 575    ...
 576
 577    tbm_bo_unref (bo);
 578    tbm_bufmgr_deinit (bufmgr);
 579    @endcode
 580   */
 581 tbm_bo        tbm_bo_import     (tbm_bufmgr bufmgr, tbm_key key);
 582
 583 /**
 584  * @brief Imports the buffer object associated with the fd.
 585  * @details The reference count of the tbm_bo is 1.
 586  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 587  * @param[in] bufmgr : the buffer manager
 588  * @param[in] fd : the fd associated with the buffer object
 589  * @return a buffer object
 590  * @retval #tbm_bo
 591  * @see tbm_bo_export_fd()
 592  * @par Example
 593    @code
 594    #include <tbm_bufmgr.h>
 595
 596    int bufmgr_fd;
 597    tbm_fd bo_fd;
 598    tbm_bufmgr bufmgr;
 599    tbm_bo bo;
 600    tbm_error_e error;
 601
 602    ...
 603
 604    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 605    bo_fd = tbm_bo_import_fd (bo_fd);
 606    if (bo_fd == 0)
 607    {
 608       error = tbm_get_last_error ();
 609       ...
 610    }
 611
 612    ...
 613
 614    tbm_bo_unref (bo);
 615    tbm_bufmgr_deinit (bufmgr);
 616    @endcode
 617   */
 618 tbm_bo        tbm_bo_import_fd  (tbm_bufmgr bufmgr, tbm_fd fd);
 619
 620 /**
 621  * @brief Gets the size of a bo.
 622  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 623  * @param[in] bo : the buffer object
 624  * @return 1 if this function succeeds, otherwise 0.
 625  * @see tbm_bo_alloc()
 626  * @par Example
 627    @code
 628    #include <tbm_bufmgr.h>
 629
 630    int bufmgr_fd;
 631    tbm_bufmgr bufmgr;
 632    tbm_bo;
 633    int size;
 634
 635    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 636    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 637    size = tbm_bo_size (bo);
 638
 639    ...
 640
 641    tbm_bo_unref (bo);
 642    tbm_bufmgr_deinit (bufmgr);
 643    @endcode
 644   */
 645 int           tbm_bo_size       (tbm_bo bo);
 646
 647 /**
 648  * @brief Gets the state where the buffer object is locked.
 649  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 650  * @param[in] bo : the buffer object
 651  * @return 1 if this bo is locked, otherwise 0.
 652  * @see tbm_bo_map()
 653  * @see tbm_bo_unmap()
 654  * @par Example
 655    @code
 656    #include <tbm_bufmgr.h>
 657
 658    int bufmgr_fd;
 659    tbm_bufmgr bufmgr;
 660    tbm_bo bo;
 661
 662    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 663    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 664
 665    ...
 666
 667    if (tbm_bo_locked (bo))
 668    {
 669
 670    ...
 671
 672    tbm_bo_unref (bo);
 673    tbm_bufmgr_deinit (bufmgr);
 674    @endcode
 675 */
 676 int           tbm_bo_locked     (tbm_bo bo);
 677
 678 /**
 679  * @brief Swaps the buffer object.
 680  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 681  * @param[in] bo1 : the buffer object
 682  * @param[in] bo2 : the buffer object
 683  * @return 1 if this function succeeds, otherwise 0.
 684  * @par Example
 685    @code
 686    #include <tbm_bufmgr.h>
 687
 688    int bufmgr_fd;
 689    tbm_bufmgr bufmgr;
 690    tbm_bo bo1;
 691    tbm_bo bo2;
 692    int ret;
 693    tbm_error_e error;
 694
 695    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 696    bo1 = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 697    bo2 = tbm_bo_alloc (bufmgr, 256 * 256, TBM_BO_DEFAULT);
 698
 699    ...
 700
 701    ret = tbm_bo_swap (bo1, bo2);
 702    if (ret == 0)
 703    {
 704       error = tbm_get_last_error ();
 705       ...
 706    }
 707
 708    ...
 709
 710    tbm_bo_unref (bo1);
 711    tbm_bo_unref (bo2);
 712    tbm_bufmgr_deinit (bufmgr);
 713    @endcode
 714  */
 715 int           tbm_bo_swap       (tbm_bo bo1, tbm_bo bo2);
 716
 717
 718 /**
 719  * @brief Called when the user data is deleted in buffer object.
 720  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 721  * @param[in] user_data User_data to be passed to callback function
 722  * @pre The callback must be registered using tbm_bo_add_user_data().\n
 723  * tbm_bo_delete_user_data() must be called to invoke this callback.
 724  * @see tbm_bo_add_user_data()
 725  * @see tbm_bo_delete_user_data()
 726  */
 727 typedef void (*tbm_data_free)(void *user_data);
 728
 729 /**
 730  * @brief Adds a user_data to the buffer object.
 731  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 732  * @param[in] bo : the buffer object
 733  * @param[in] key : the key associated with the user_data
 734  * @param[in] data_free_func : the function pointer to free the user_data
 735  * @return 1 if this function succeeds, otherwise 0.
 736  * @post tbm_data_free() will be called under certain conditions, after calling tbm_bo_delete_user_data().
 737  * @see tbm_data_free()
 738  * @see tbm_bo_set_user_data()
 739  * @see tbm_bo_get_user_data()
 740  * @see tbm_bo_delete_user_data()
 741  * @par Example
 742    @code
 743    #include <tbm_bufmgr.h>
 744
 745    void example_data_free (void *user_data)
 746    {
 747        char *data = (char*) user_data;
 748        free(data);
 749    }
 750
 751    int main()
 752    {
 753        int bufmgr_fd;
 754        tbm_bufmgr bufmgr;
 755        tbm_bo bo;
 756        char *user_data;
 757        char *get_data;
 758        int ret;
 759
 760        bufmgr = tbm_bufmgr_init (bufmgr_fd);
 761        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 762        user_data = (char*) malloc (sizeof(char) * 128);
 763
 764        ...
 765
 766        tbm_bo_add_user_data (bo, 1, example_data_free);
 767        tbm_bo_set_user_data (bo, 1, user_data);
 768
 769        ...
 770
 771        ret = tbm_bo_get_user_data (bo, 1, &get_data);
 772        tbm_bo_delete_user_data (bo, 1);
 773
 774        ...
 775
 776        tbm_bo_unref (bo);
 777        tbm_bufmgr_deinit (bufmgr);
 778    }
 779    @endcode
 780  */
 781
 782 int tbm_bo_add_user_data    (tbm_bo bo, unsigned long key, tbm_data_free data_free_func);
 783
 784 /**
 785  * @brief Deletes the user_data in the buffer object.
 786  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 787  * @param[in] bo : the buffer object
 788  * @param[in] key : the key associated with the user_date
 789  * @return 1 if this function succeeds, otherwise 0.
 790  * @see tbm_bo_add_user_data()
 791  * @see tbm_bo_get_user_data()
 792  * @see tbm_bo_delete_user_data()
 793  * @par Example
 794    @code
 795    #include <tbm_bufmgr.h>
 796
 797    void example_data_free (void *user_data)
 798    {
 799        char *data = (char*) user_data;
 800        free(data);
 801    }
 802
 803    int main()
 804    {
 805        int bufmgr_fd;
 806        tbm_bufmgr bufmgr;
 807        tbm_bo bo;
 808        char *user_data;
 809        char *get_data;
 810        int ret;
 811
 812        bufmgr = tbm_bufmgr_init (bufmgr_fd);
 813        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 814        user_data = (char*) malloc (sizeof(char) * 128);
 815
 816        ...
 817
 818        tbm_bo_add_user_data (bo, 1, example_data_free);
 819        tbm_bo_set_user_data (bo, 1, user_data);
 820
 821        ...
 822
 823        ret = tbm_bo_get_user_data (bo, 1, &get_data);
 824        tbm_bo_delete_user_data (bo, 1);
 825
 826        ...
 827
 828        tbm_bo_unref (bo);
 829        tbm_bufmgr_deinit (bufmgr);
 830    }
 831    @endcode
 832  */
 833 int tbm_bo_delete_user_data (tbm_bo bo, unsigned long key);
 834
 835 /**
 836  * @brief Sets a user_date to the buffer object.
 837  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 838  * @param[in] bo : the buffer object
 839  * @param[in] key : the key associated with the user_date
 840  * @param[in] data : a pointer of the user_data
 841  * @return 1 if this function succeeds, otherwise 0.
 842  * @see tbm_bo_add_user_data()
 843  * @see tbm_bo_set_user_data()
 844  * @see tbm_bo_delete_user_data()
 845  * @par Example
 846    @code
 847    #include <tbm_bufmgr.h>
 848
 849    void example_data_free (void *user_data)
 850    {
 851        char *data = (char*) user_data;
 852        free(data);
 853    }
 854
 855    int main()
 856    {
 857        int bufmgr_fd;
 858        tbm_bufmgr bufmgr;
 859        tbm_bo bo;
 860        char *user_data;
 861        char *get_data;
 862        int ret;
 863
 864        bufmgr = tbm_bufmgr_init (bufmgr_fd);
 865        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 866        user_data = (char*) malloc (sizeof(char) * 128);
 867
 868        ...
 869
 870        tbm_bo_add_user_data (bo, 1, example_data_free);
 871        tbm_bo_set_user_data (bo, 1, user_data);
 872
 873        ...
 874
 875        ret = tbm_bo_get_user_data (bo, 1, &get_data);
 876        tbm_bo_delete_user_data (bo, 1);
 877
 878        ...
 879
 880        tbm_bo_unref (bo);
 881        tbm_bufmgr_deinit (bufmgr);
 882    }
 883    @endcode
 884  */
 885 int tbm_bo_set_user_data    (tbm_bo bo, unsigned long key, void* data);
 886
 887 /**
 888  * @brief Gets a user_data from the buffer object with the key.
 889  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 890  * @param[in] bo : the buffer object
 891  * @param[in] key : the key associated with the user_date
 892  * @param[out] data : to get the user data
 893  * @return 1 if this function succeeds, otherwise 0.
 894  * @see tbm_bo_add_user_data()
 895  * @see tbm_bo_set_user_data()
 896  * @see tbm_bo_get_user_data()
 897  * @par Example
 898    @code
 899    #include <tbm_bufmgr.h>
 900
 901    void example_data_free (void *user_data)
 902    {
 903        char *data = (char*) user_data;
 904        free(data);
 905    }
 906
 907    int main()
 908    {
 909        int bufmgr_fd;
 910        tbm_bufmgr bufmgr;
 911        tbm_bo bo;
 912        char *user_data;
 913        char *get_data;
 914        int ret;
 915
 916        bufmgr = tbm_bufmgr_init (bufmgr_fd);
 917        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 918        user_data = (char*) malloc (sizeof(char) * 128);
 919
 920        ...
 921
 922        tbm_bo_add_user_data (bo, 1, example_data_free);
 923        tbm_bo_set_user_data (bo, 1, user_data);
 924
 925        ...
 926
 927        ret = tbm_bo_get_user_data (bo, 1, &get_data);
 928        tbm_bo_delete_user_data (bo, 1);
 929
 930        ...
 931
 932        tbm_bo_unref (bo);
 933        tbm_bufmgr_deinit (bufmgr);
 934    }
 935    @endcode
 936  */
 937 int tbm_bo_get_user_data    (tbm_bo bo, unsigned long key, void** data);
 938
 939 /**
 940  * @brief Gets the latest tbm_error.
 941  * @since_tizen 2.4
 942  * @return the latest tbm_error
 943  * @par Example
 944    @code
 945    #include <tbm_bufmgr.h>
 946
 947    int bufmgr_fd;
 948    tbm_bufmgr bufmgr;
 949    tbm_bo bo;
 950    tbm_bo_handle handle;
 951    tbm_error_e error;
 952
 953    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 954    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 955    if (!bo)
 956    {
 957       error = tbm_get_last_error ();
 958       ...
 959    }
 960
 961    ...
 962
 963    handle = tbm_bo_map (bo, TBM_DEVICE_2D, TBM_OPTION_READ|TBM_OPTION_WRITE);
 964    if (handle.ptr == NULL)
 965    {
 966       error = tbm_get_last_error ();
 967       ...
 968    }
 969
 970    ...
 971
 972    tbm_bo_unmap (bo);
 973    tbm_bo_unref (bo);
 974    tbm_bufmgr_deinit (bufmgr);
 975    @endcode
 976  */
 977 tbm_error_e tbm_get_last_error    (void);
 978
 979 #ifdef __cplusplus
 980 }
 981 #endif
 982
 983 #endif /* _TBM_BUFMGR_H_ */
 984