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