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