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