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 /**
  36  * @internal
  37  * @addtogroup CAPI_UI_TBM_BUFMGR_MODULE
  38  * @{
  39  */
  40
  41 #include <tbm_type.h>
  42 #include <stdint.h>
  43
  44 /**
  45  * \file tbm_bufmgr.h
  46  * \brief Tizen Buffer Manager
  47  */
  48
  49 /**
  50  * @brief Definition for the tizen buffer manager
  51  * @since_tizen 2.3
  52  */
  53 typedef struct _tbm_bufmgr * tbm_bufmgr;
  54
  55 /**
  56  * @brief Definition for the tizen buffer object
  57  * @since_tizen 2.3
  58  */
  59 typedef struct _tbm_bo *tbm_bo;
  60 /**
  61  * @brief Definition for the key associated with the buffer object
  62  * @since_tizen 2.3
  63  */
  64 typedef uint32_t tbm_key;
  65 /**
  66  * @brief Definition for the file descripter of the system buffer manager
  67  * @since_tizen 2.3
  68  */
  69 typedef int32_t tbm_fd;
  70
  71
  72 /* TBM_DEVICE_TYPE */
  73
  74 /**
  75  * @brief Definition for the device type to get the default handle
  76  * @since_tizen 2.3
  77  */
  78 #define TBM_DEVICE_DEFAULT   0
  79 /**
  80  * @brief Definition for the device type to get the virtual memory
  81  * @since_tizen 2.3
  82  */
  83 #define TBM_DEVICE_CPU       1
  84 /**
  85  * @brief Definition for the device type to get the 2D memory handle
  86  * @since_tizen 2.3
  87  */
  88 #define TBM_DEVICE_2D        2
  89 /**
  90  * @brief Definition for the device type to get the 3D memory handle
  91  * @since_tizen 2.3
  92  */
  93 #define TBM_DEVICE_3D        3
  94 /**
  95  * @brief Definition for the device type to get the multimedia handle
  96  * @since_tizen 2.3
  97  */
  98 #define TBM_DEVICE_MM        4
  99
 100 /**
 101  * @brief Definition for the cache invalidate
 102  * @since_tizen 2.3
 103  */
 104 #define TBM_CACHE_INV            0x01
 105 /**
 106  * @brief Definition for the cache clean
 107  * @since_tizen 2.3
 108  */
 109 #define TBM_CACHE_CLN            0x02
 110
 111 /* TBM_OPTION */
 112
 113 /**
 114  * @brief Definition for the access option to read
 115  * @since_tizen 2.3
 116  */
 117 #define TBM_OPTION_READ      (1 << 0)
 118 /**
 119  * @brief Definition for the access option to write
 120  * @since_tizen 2.3
 121  */
 122 #define TBM_OPTION_WRITE     (1 << 1)
 123 /**
 124  * @brief Definition for the vendor specific option that depends on the backend
 125  * @since_tizen 2.3
 126  */
 127 #define TBM_OPTION_VENDOR    (0xffff0000)
 128
 129 /**
 130  * @brief tbm_bo_handle abstraction of the memory handle by TBM_DEVICE_TYPE
 131  * @since_tizen 2.3
 132  */
 133 typedef union _tbm_bo_handle
 134 {
 135    void     *ptr;
 136    int32_t  s32;
 137    uint32_t u32;
 138    int64_t  s64;
 139    uint64_t u64;
 140 } tbm_bo_handle;
 141
 142 /**
 143  * @brief Enumeration of bo memory type
 144  * @since_tizen 2.3
 145  */
 146 enum TBM_BO_FLAGS
 147 {
 148     TBM_BO_DEFAULT = 0,            /**< default memory: it depends on the backend         */
 149     TBM_BO_SCANOUT = (1<<0),       /**< scanout memory                                    */
 150     TBM_BO_NONCACHABLE = (1<<1),   /**< non-cachable memory                               */
 151     TBM_BO_WC = (1<<2),            /**< write-combine memory                              */
 152     TBM_BO_VENDOR = (0xffff0000), /**< vendor specific memory: it depends on the backend */
 153 };
 154
 155 #ifdef __cplusplus
 156 extern "C" {
 157 #endif
 158
 159 /* Functions for buffer manager */
 160
 161 /**
 162  * @brief Initializes the buffer manager.
 163  * @details If fd is lower than zero, fd is get drm fd in tbm_bufmgr_init function\n
 164  * 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
 165  * \n
 166  * BUFMGR_LOCK default is once\n
 167  * once : The previous bo which is locked is unlock when the new bo is trying to be locked\n
 168  * always : The new bo is locked until the previous bo which is locked is unlocked\n
 169  * never : Every bo is never locked.\n
 170  * \n
 171  * BUFMGR_MAP_CACHE default is true\n
 172  * true : use map cache flushing\n
 173  * false : to use map cache flushing
 174  * @since_tizen 2.3
 175  * @param[in] fd : file descripter of the system buffer manager
 176  * @return a buffer manager
 177  * @retval #tbm_bufmgr
 178  * @see tbm_bufmgr_deinit();
 179  * @par Example
 180    @code
 181    #include <tbm_bufmgr.h>
 182    int bufmgr_fd;
 183
 184
 185    setenv("BUFMGR_LOCK_TYPE", "once", 1);
 186    setenv("BUFMGR_MAP_CACHE", "true", 1);
 187
 188    tbm_bufmgr bufmgr;
 189    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 190
 191    ....
 192
 193    tbm_bufmgr_deinit (bufmgr);
 194    @endcode
 195  */
 196 tbm_bufmgr tbm_bufmgr_init   (int fd);
 197
 198 /**
 199  * @brief Deinitializes the buffer manager.
 200  * @since_tizen 2.3
 201  * @param[in] bufmgr : the buffer manager
 202  * @see tbm_bufmgr_init()
 203  * @par Example
 204    @code
 205    #include <tbm_bufmgr.h>
 206
 207    int bufmgr_fd;
 208    tbm_bufmgr bufmgr;
 209    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 210
 211    ....
 212
 213    tbm_bufmgr_deinit (bufmgr);
 214    @endcode
 215  */
 216 void       tbm_bufmgr_deinit (tbm_bufmgr bufmgr);
 217
 218 /* Functions for bo */
 219
 220 /**
 221  * @brief Allocates the buffer object.
 222  * @details This function create tbm_bo and set reference count to 1.\n
 223  * The user can craete tbm_bo with memory type flag #TBM_BO_FLAGS\n\n
 224  * #TBM_BO_DEFAULT indecates default memory: it depends on the backend\n
 225  * #TBM_BO_SCANOUT indecates scanout memory\n
 226  * #TBM_BO_NONCACHABLE indecates non-cachable memory\n
 227  * #TBM_BO_WC indecates write-combine memory\n
 228  * #TBM_BO_VENDOR indecates vendor specific memory: it depends on the tbm backend
 229  * @since_tizen 2.3
 230  * @param[in] bufmgr : the buffer manager
 231  * @param[in] size : the size of buffer object
 232  * @param[in] flags : the flags of memory type
 233  * @return a buffer object
 234  * @retval #tbm_bo
 235  * @par Example
 236    @code
 237    #include <tbm_bufmgr.h>
 238
 239    int bufmgr_fd;
 240    tbm_bufmgr bufmgr;
 241    tbm_bo;
 242
 243    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 244    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 245
 246    ....
 247
 248    tbm_bufmgr_deinit (bufmgr);
 249    @endcode
 250  */
 251 tbm_bo        tbm_bo_alloc      (tbm_bufmgr bufmgr, int size, int flags);
 252
 253 /**
 254  * @brief Increases the reference count of bo.
 255  * @since_tizen 2.3
 256  * @param[in] bo : the buffer object
 257  * @return a buffer object
 258  * @retval #tbm_bo
 259  * @see tbm_bo_unref()
 260  * @par Example
 261    @code
 262    #include <tbm_bufmgr.h>
 263
 264    int bufmgr_fd;
 265    tbm_bufmgr bufmgr;
 266    tbm_bo bo;
 267
 268    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 269    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 270
 271    ...
 272
 273    bo = tbm_bo_ref (bo);
 274
 275    ....
 276
 277    tbm_bufmgr_deinit (bufmgr);
 278    @endcode
 279  */
 280 tbm_bo        tbm_bo_ref        (tbm_bo bo);
 281
 282 /**
 283  * @brief Decreases the reference count of bo
 284  * @since_tizen 2.3
 285  * @param[in] bo : the buffer object
 286  * @see tbm_bo_ref()
 287  * @see tbm_bo_alloc()
 288  * @par Example
 289    @code
 290    #include <tbm_bufmgr.h>
 291
 292    int bufmgr_fd;
 293    tbm_bufmgr bufmgr;
 294    tbm_bo bo;
 295
 296    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 297    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 298
 299    ...
 300
 301    tbm_bo_unref (bo);
 302    tbm_bufmgr_deinit (bufmgr);
 303    @endcode
 304  */
 305 void          tbm_bo_unref      (tbm_bo bo);
 306
 307 /**
 308  * @brief Maps the buffer object according to the device type and the option.
 309  * @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
 310  * If the cache flush type of bufmgr set true, the map cache flushing is executed
 311  * 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
 312  * If the lock type of bufmgr set always, the new bo is locked until the previous bo which is locked is unlocked.\n
 313  * If the lock type of bufmgr set never, Every bo is never locked.\n\n
 314  * #TBM_DEVICE_DEFAULT indecates the default handle.\n
 315  * #TBM_DEVICE_2D indecates the 2D memory handle.\n
 316  * #TBM_DEVICE_3D indecates the 3D memory handle.\n
 317  * #TBM_DEVICE_CPU indecates the virtual memory handle.\n
 318  * #TBM_DEVICE_MM indecates the multimedia handle.\n\n
 319  * #TBM_OPTION_READ indecates the accss option to read.\n
 320  * #TBM_OPTION_WRITE indecates the access option to write.\n
 321  * #TBM_OPTION_VENDOR indecates the vendor specific option that depends on the backend.
 322  * @since_tizen 2.3
 323  * @param[in] bo : the buffer object
 324  * @param[in] device : the device type to get a handle
 325  * @param[in] opt : the option to access the buffer object
 326  * @return the handle of the buffer object
 327  * @retval #tbm_bo
 328  * @see tbm_bo_unmap()
 329  * @par Example
 330    @code
 331    #include <tbm_bufmgr.h>
 332
 333    int bufmgr_fd;
 334    tbm_bufmgr bufmgr;
 335    tbm_bo bo;
 336    tbm_bo_handle handle;
 337
 338    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 339    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 340
 341    ...
 342
 343    handle = tbm_bo_map (bo, TBM_DEVICE_2D, TBM_OPTION_READ|TBM_OPTION_WRITE);
 344
 345    ...
 346
 347    tbm_bo_unmap (bo);
 348    tbm_bo_unref (bo);
 349    tbm_bufmgr_deinit (bufmgr);
 350    @endcode
 351  */
 352 tbm_bo_handle tbm_bo_map        (tbm_bo bo, int device, int opt);
 353
 354 /**
 355  * @brief Unmaps the buffer object.
 356  * @since_tizen 2.3
 357  * @param[in] bo : the buffer object
 358  * @return 1 if this function succeeds, otherwise 0.
 359  * @see tbm_bo_map()
 360  * @par Example
 361    @code
 362    #include <tbm_bufmgr.h>
 363
 364    int bufmgr_fd;
 365    tbm_bufmgr bufmgr;
 366    tbm_bo bo
 367    tbm_bo_handle handle;
 368
 369    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 370    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 371
 372    ...
 373
 374    handle = tbm_bo_map (bo, TBM_DEVICE_2D, TBM_OPTION_READ|TBM_OPTION_WRITE);
 375
 376    ...
 377
 378    tbm_bo_unmap (bo);
 379    tbm_bo_unref (bo);
 380    tbm_bufmgr_deinit (bufmgr);
 381    @endcode
 382  */
 383 int           tbm_bo_unmap      (tbm_bo bo);
 384
 385 /**
 386  * @brief Gets the tbm_bo_handle according to the device type.
 387  * @details The tbm_bo_handle can be get without the map of the tbm_bo.\n
 388  * In this case, TBM does not guarantee the lock and the cache flush of the tbm_bo.\n\n
 389  * #TBM_DEVICE_DEFAULT indecates the default handle.\n
 390  * #TBM_DEVICE_2D indecates the 2D memory handle.\n
 391  * #TBM_DEVICE_3D indecates the 3D memory handle.\n
 392  * #TBM_DEVICE_CPU indecates the virtual memory handle.\n
 393  * #TBM_DEVICE_MM indecates the multimedia handle.
 394  * @since_tizen 2.3
 395  * @param[in] bo : the buffer object
 396  * @param[in] device : the device type to get a handle
 397  * @return the handle of the buffer object
 398  * @retval #tbm_bo_handle
 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_get_handle (bo, TBM_DEVICE_2D);
 414
 415    ...
 416
 417    tbm_bo_unref (bo);
 418    tbm_bufmgr_deinit (bufmgr);
 419    @endcode
 420   */
 421 tbm_bo_handle tbm_bo_get_handle (tbm_bo bo, int device);
 422
 423 /**
 424  * @brief Exports the buffer object by key.
 425  * @details The tbm_bo can be exported to the anther process with the unique key associated with the the tbm_bo.
 426  * @since_tizen 2.3
 427  * @param[in] bo : the buffer object
 428  * @return key associated with the buffer object
 429  * @retval #tbm_key
 430  * @see tbm_bo_import()
 431  * @par Example
 432    @code
 433    #include <tbm_bufmgr.h>
 434
 435    int bufmgr_fd;
 436    tbm_bufmgr bufmgr;
 437    tbm_bo;
 438    tbm_key key;
 439
 440    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 441    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 442    key = tbm_bo_export (bo);
 443
 444    ...
 445
 446    tbm_bo_unref (bo);
 447    tbm_bufmgr_deinit (bufmgr);
 448    @endcode
 449   */
 450 tbm_key  tbm_bo_export     (tbm_bo bo);
 451
 452 /**
 453  * @brief Exports the buffer object by fd.
 454  * @details The tbm_bo can be exported to the anther process with the unique fd associated with the the tbm_bo.
 455  * @since_tizen 2.3
 456  * @param[in] bo : the buffer object
 457  * @return fd associated with the buffer object
 458  * @retval #tbm_fd
 459  * @see tbm_bo_import_fd()
 460  * @par Example
 461    @code
 462    #include <tbm_bufmgr.h>
 463
 464    int bufmgr_fd;
 465    tbm_fd bo_fd;
 466    tbm_bufmgr bufmgr;
 467    tbm_bo;
 468
 469    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 470    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 471    bo_fd = tbm_bo_export (bo);
 472
 473    ...
 474
 475    tbm_bo_unref (bo);
 476    tbm_bufmgr_deinit (bufmgr);
 477    @endcode
 478   */
 479 tbm_fd tbm_bo_export_fd (tbm_bo bo);
 480
 481 /**
 482  * @brief Imports the buffer object associated with the key.
 483  * @details The reference count of the tbm_bo is 1.
 484  * @since_tizen 2.3
 485  * @param[in] bufmgr : the buffer manager
 486  * @param[in] key : the key associated with the buffer object
 487  * @return a buffer object
 488  * @retval #tbm_bo
 489  * @see tbm_bo_export()
 490  * @par Example
 491    @code
 492    #include <tbm_bufmgr.h>
 493
 494    int bufmgr_fd;
 495    int bo_key;
 496    tbm_bufmgr bufmgr;
 497    tbm_bo;
 498
 499    ...
 500
 501    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 502    bo = tbm_bo_import (key);
 503
 504    ...
 505
 506    tbm_bo_unref (bo);
 507    tbm_bufmgr_deinit (bufmgr);
 508    @endcode
 509   */
 510 tbm_bo        tbm_bo_import     (tbm_bufmgr bufmgr, tbm_key key);
 511
 512 /**
 513  * @brief Imports the buffer object associated with the fd.
 514  * @details The reference count of the tbm_bo is 1.
 515  * @since_tizen 2.3
 516  * @param[in] bufmgr : the buffer manager
 517  * @param[in] fd : the fd associated with the buffer object
 518  * @return a buffer object
 519  * @retval #tbm_bo
 520  * @see tbm_bo_export_fd()
 521  * @par Example
 522    @code
 523    #include <tbm_bufmgr.h>
 524
 525    int bufmgr_fd;
 526    tbm_fd bo_fd;
 527    tbm_bufmgr bufmgr;
 528    tbm_bo bo;
 529
 530    ...
 531
 532    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 533    bo = tbm_bo_import (bo_fd);
 534
 535    ...
 536
 537    tbm_bo_unref (bo);
 538    tbm_bufmgr_deinit (bufmgr);
 539    @endcode
 540   */
 541 tbm_bo        tbm_bo_import_fd  (tbm_bufmgr bufmgr, tbm_fd fd);
 542
 543 /**
 544  * @brief Gets the size of a bo.
 545  * @since_tizen 2.3
 546  * @param[in] bo : the buffer object
 547  * @return 1 if this function succeeds, otherwise 0.
 548  * @see tbm_bo_alloc()
 549  * @par Example
 550    @code
 551    #include <tbm_bufmgr.h>
 552
 553    int bufmgr_fd;
 554    tbm_bufmgr bufmgr;
 555    tbm_bo;
 556    int size;
 557
 558    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 559    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 560    size = tbm_bo_size (bo);
 561
 562    ...
 563
 564    tbm_bo_unref (bo);
 565    tbm_bufmgr_deinit (bufmgr);
 566    @endcode
 567   */
 568 int           tbm_bo_size       (tbm_bo bo);
 569
 570 /**
 571  * @brief Gets the state where the buffer object is locked.
 572  * @since_tizen 2.3
 573  * @param[in] bo : the buffer object
 574  * @return 1 if this bo is locked, otherwise 0.
 575  * @see tbm_bo_map()
 576  * @see tbm_bo_unmap()
 577  * @par Example
 578    @code
 579    #include <tbm_bufmgr.h>
 580
 581    int bufmgr_fd;
 582    tbm_bufmgr bufmgr;
 583    tbm_bo bo;
 584
 585    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 586    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 587
 588    ...
 589
 590    if (tbm_bo_locked (bo))
 591    {
 592
 593    ...
 594
 595    tbm_bo_unref (bo);
 596    tbm_bufmgr_deinit (bufmgr);
 597    @endcode
 598 */
 599 int           tbm_bo_locked     (tbm_bo bo);
 600
 601 /**
 602  * @brief Swaps the buffer object.
 603  * @since_tizen 2.3
 604  * @param[in] bo1 : the buffer object
 605  * @param[in] bo2 : the buffer object
 606  * @return 1 if this function succeeds, otherwise 0.
 607  * @par Example
 608    @code
 609    #include <tbm_bufmgr.h>
 610
 611    int bufmgr_fd;
 612    tbm_bufmgr bufmgr;
 613    tbm_bo bo1;
 614    tbm_bo bo2;
 615    int ret;
 616
 617    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 618    bo1 = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 619    bo2 = tbm_bo_alloc (bufmgr, 256 * 256, TBM_BO_DEFAULT);
 620
 621    ...
 622
 623    ret = tbm_bo_swap (bo1, bo2);
 624
 625    ...
 626
 627    tbm_bo_unref (bo1);
 628    tbm_bo_unref (bo2);
 629    tbm_bufmgr_deinit (bufmgr);
 630    @endcode
 631  */
 632 int           tbm_bo_swap       (tbm_bo bo1, tbm_bo bo2);
 633
 634
 635 /**
 636  * @brief Called when the user data is deleted in buffer object.
 637  * @since_tizen 2.3
 638  * @param[in] user_data User_data to be passed to callback function
 639  * @pre The callback must be registered using tbm_bo_add_user_data().\n
 640  * tbm_bo_delete_user_data() must be called to invoke this callback.
 641  * @see tbm_bo_add_user_data()
 642  * @see tbm_bo_delete_user_data()
 643  */
 644 typedef void (*tbm_data_free)(void *user_data);
 645
 646 /**
 647  * @brief Adds a user_data to the buffer object.
 648  * @since_tizen 2.3
 649  * @param[in] bo : the buffer object
 650  * @param[in] key : the key associated with the user_data
 651  * @param[in] data_free_func : the function pointer to free the user_data
 652  * @return 1 if this function succeeds, otherwise 0.
 653  * @post tbm_data_free() will be called under certain conditions, after calling tbm_bo_delete_user_data().
 654  * @see tbm_data_free()
 655  * @see tbm_bo_set_user_data()
 656  * @see tbm_bo_get_user_data()
 657  * @see tbm_bo_delete_user_data()
 658  * @par Example
 659    @code
 660    #include <tbm_bufmgr.h>
 661
 662    void example_data_free (void *user_data)
 663    {
 664        char *data = (char*) user_data;
 665        free(data);
 666    }
 667
 668    int main()
 669    {
 670        int bufmgr_fd;
 671        tbm_bufmgr bufmgr;
 672        tbm_bo bo;
 673        char *user_data;
 674        char *get_data;
 675        int ret;
 676
 677        bufmgr = tbm_bufmgr_init (bufmgr_fd);
 678        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 679        user_data = (char*) malloc (sizeof(char) * 128);
 680
 681        ...
 682
 683        tbm_bo_add_user_data (bo, 1, example_data_free);
 684        tbm_bo_set_user_data (bo, 1, user_data);
 685
 686        ...
 687
 688        ret = tbm_bo_get_user_data (bo, 1, &get_data);
 689        tbm_bo_delete_user_data (bo, 1);
 690
 691        ...
 692
 693        tbm_bo_unref (bo);
 694        tbm_bufmgr_deinit (bufmgr);
 695    }
 696    @endcode
 697  */
 698
 699 int tbm_bo_add_user_data    (tbm_bo bo, unsigned long key, tbm_data_free data_free_func);
 700
 701 /**
 702  * @brief Deletes the user_data in the buffer object.
 703  * @since_tizen 2.3
 704  * @param[in] bo : the buffer object
 705  * @param[in] key : the key associated with the user_date
 706  * @return 1 if this function succeeds, otherwise 0.
 707  * @see tbm_bo_add_user_data()
 708  * @see tbm_bo_get_user_data()
 709  * @see tbm_bo_delete_user_data()
 710  * @par Example
 711    @code
 712    #include <tbm_bufmgr.h>
 713
 714    void example_data_free (void *user_data)
 715    {
 716        char *data = (char*) user_data;
 717        free(data);
 718    }
 719
 720    int main()
 721    {
 722        int bufmgr_fd;
 723        tbm_bufmgr bufmgr;
 724        tbm_bo bo;
 725        char *user_data;
 726        char *get_data;
 727        int ret;
 728
 729        bufmgr = tbm_bufmgr_init (bufmgr_fd);
 730        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 731        user_data = (char*) malloc (sizeof(char) * 128);
 732
 733        ...
 734
 735        tbm_bo_add_user_data (bo, 1, example_data_free);
 736        tbm_bo_set_user_data (bo, 1, user_data);
 737
 738        ...
 739
 740        ret = tbm_bo_get_user_data (bo, 1, &get_data);
 741        tbm_bo_delete_user_data (bo, 1);
 742
 743        ...
 744
 745        tbm_bo_unref (bo);
 746        tbm_bufmgr_deinit (bufmgr);
 747    }
 748    @endcode
 749  */
 750 int tbm_bo_delete_user_data (tbm_bo bo, unsigned long key);
 751
 752 /**
 753  * @brief Sets a user_date to the buffer object.
 754  * @since_tizen 2.3
 755  * @param[in] bo : the buffer object
 756  * @param[in] key : the key associated with the user_date
 757  * @param[in] data : a pointer of the user_data
 758  * @return 1 if this function succeeds, otherwise 0.
 759  * @see tbm_bo_add_user_data()
 760  * @see tbm_bo_set_user_data()
 761  * @see tbm_bo_delete_user_data()
 762  * @par Example
 763    @code
 764    #include <tbm_bufmgr.h>
 765
 766    void example_data_free (void *user_data)
 767    {
 768        char *data = (char*) user_data;
 769        free(data);
 770    }
 771
 772    int main()
 773    {
 774        int bufmgr_fd;
 775        tbm_bufmgr bufmgr;
 776        tbm_bo bo;
 777        char *user_data;
 778        char *get_data;
 779        int ret;
 780
 781        bufmgr = tbm_bufmgr_init (bufmgr_fd);
 782        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 783        user_data = (char*) malloc (sizeof(char) * 128);
 784
 785        ...
 786
 787        tbm_bo_add_user_data (bo, 1, example_data_free);
 788        tbm_bo_set_user_data (bo, 1, user_data);
 789
 790        ...
 791
 792        ret = tbm_bo_get_user_data (bo, 1, &get_data);
 793        tbm_bo_delete_user_data (bo, 1);
 794
 795        ...
 796
 797        tbm_bo_unref (bo);
 798        tbm_bufmgr_deinit (bufmgr);
 799    }
 800    @endcode
 801  */
 802 int tbm_bo_set_user_data    (tbm_bo bo, unsigned long key, void* data);
 803
 804 /**
 805  * @brief Gets a user_data from the buffer object with the key.
 806  * @since_tizen 2.3
 807  * @param[in] bo : the buffer object
 808  * @param[in] key : the key associated with the user_date
 809  * @param[out] data : to get the user data
 810  * @return 1 if this function succeeds, otherwise 0.
 811  * @see tbm_bo_add_user_data()
 812  * @see tbm_bo_set_user_data()
 813  * @see tbm_bo_get_user_data()
 814  * @par Example
 815    @code
 816    #include <tbm_bufmgr.h>
 817
 818    void example_data_free (void *user_data)
 819    {
 820        char *data = (char*) user_data;
 821        free(data);
 822    }
 823
 824    int main()
 825    {
 826        int bufmgr_fd;
 827        tbm_bufmgr bufmgr;
 828        tbm_bo bo;
 829        char *user_data;
 830        char *get_data;
 831        int ret;
 832
 833        bufmgr = tbm_bufmgr_init (bufmgr_fd);
 834        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 835        user_data = (char*) malloc (sizeof(char) * 128);
 836
 837        ...
 838
 839        tbm_bo_add_user_data (bo, 1, example_data_free);
 840        tbm_bo_set_user_data (bo, 1, user_data);
 841
 842        ...
 843
 844        ret = tbm_bo_get_user_data (bo, 1, &get_data);
 845        tbm_bo_delete_user_data (bo, 1);
 846
 847        ...
 848
 849        tbm_bo_unref (bo);
 850        tbm_bufmgr_deinit (bufmgr);
 851    }
 852    @endcode
 853  */
 854 int tbm_bo_get_user_data    (tbm_bo bo, unsigned long key, void** data);
 855
 856 int tbm_bo_cache_flush  (tbm_bo bo, int flags);
 857
 858
 859 #ifdef __cplusplus
 860 }
 861 #endif
 862
 863 /**
 864 * @}
 865 */
 866
 867 #endif /* _TBM_BUFMGR_H_ */
 868