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