include/tbm_surface_queue.h

   1 /**************************************************************************
   2
   3 libtbm
   4
   5 Copyright 2014 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_SURFACE_QUEUE_H_
  33 #define _TBM_SURFACE_QUEUE_H_
  34
  35 #include <tbm_surface.h>
  36 #include <tbm_type_common.h>
  37 #include <tbm_error.h>
  38
  39 typedef enum {
  40         TBM_SURFACE_QUEUE_TRACE_NONE = 0,
  41         TBM_SURFACE_QUEUE_TRACE_DEQUEUE = 1,
  42         TBM_SURFACE_QUEUE_TRACE_ENQUEUE = 2,
  43         TBM_SURFACE_QUEUE_TRACE_ACQUIRE = 3,
  44         TBM_SURFACE_QUEUE_TRACE_RELEASE = 4,
  45         TBM_SURFACE_QUEUE_TRACE_CANCEL_DEQUEUE = 5,
  46         TBM_SURFACE_QUEUE_TRACE_CANCEL_ACQUIRE = 6,
  47 } tbm_surface_queue_trace;
  48
  49 typedef enum {
  50         TBM_SURFACE_QUEUE_MODE_NONE = 0,
  51         /**
  52          * GUARANTEE_CYCLE mode must do enqueue/aquire/release or cancel_dequeue
  53          * for the tbm_surface which is dequeued before tbm_surface_queue is reset.
  54          */
  55         TBM_SURFACE_QUEUE_MODE_GUARANTEE_CYCLE = (1 << 0),
  56 } tbm_surface_queue_mode;
  57
  58 typedef struct _tbm_surface_queue *tbm_surface_queue_h;
  59
  60 typedef void (*tbm_surface_queue_notify_cb)(tbm_surface_queue_h surface_queue,
  61                 void *data);
  62
  63 typedef tbm_surface_h (*tbm_surface_alloc_cb)(tbm_surface_queue_h surface_queue,
  64                 void *data);
  65
  66 typedef tbm_surface_h (*tbm_surface_alloc_cb2)(tbm_surface_queue_h surface_queue,
  67                 int width, int height, int format, int flags, void *data);
  68
  69 typedef void (*tbm_surface_free_cb)(tbm_surface_queue_h surface_queue,
  70                 void *data, tbm_surface_h surface);
  71
  72 typedef void (*tbm_surface_queue_trace_cb)(tbm_surface_queue_h surface_queue,
  73                 tbm_surface_h surface, tbm_surface_queue_trace trace, void *data);
  74
  75 #ifdef __cplusplus
  76 extern "C" {
  77 #endif
  78
  79 /**
  80  * @brief Creates the tbm_surface_queue_h.
  81  * @details This function creates the tbm_surfac_queue_h with the given queue_size, width, height, format, flags.
  82  *
  83  * @param[in] queue_size   The size of the tbm_surface_queue
  84  * @param[in] width        The width of the tbm_surface_queue
  85  * @param[in] height       The height of the tbm_surface_queue
  86  * @param[in] format       The format of the tbm_surface_queue
  87  * @param[in] flags        The flags of the tbm_surface_queue
  88  *
  89  * @return   #tbm_surface_queue_h on success,
  90  *           otherwise @c NULL
  91  *
  92  * @see tbm_surface_queue_destroy()
  93  *
  94  * @par Example
  95    @code
  96    #include <tbm_surface_queue.h>
  97
  98    tbm_surface_queue_h surface_queue;
  99
 100    surface_queue = tbm_surface_queue_create(3, 128, 128, TBM_FORMAT_ARGB888, TBM_BO_DEFAULT);
 101
 102    ...
 103
 104    tbm_surface_queue_destroy (surface_queue);
 105    @endcode
 106  */
 107 tbm_surface_queue_h tbm_surface_queue_create(int queue_size, int width,
 108                 int height, int format, int flags);
 109
 110 /**
 111  * @brief Creates the sequence tbm_surface_queue_h.
 112  * @details This function creates the sequence tbm_surface_queue_h with the given queue_size, width, height, format, flags.
 113  *
 114  * @param[in] queue_size   The size of the tbm_surface_queue
 115  * @param[in] width        The width of the tbm_surface_queue
 116  * @param[in] height       The height of the tbm_surface_queue
 117  * @param[in] format       The format of the tbm_surface_queue
 118  * @param[in] flags        The flags of the tbm_surface_queue
 119  *
 120  * @return   #tbm_surface_queue_h on success,
 121  *           otherwise @c NULL
 122  *
 123  * @see tbm_surface_queue_destroy()
 124  *
 125  * @par Example
 126    @code
 127    #include <tbm_surface_queue.h>
 128
 129    tbm_surface_queue_h surface_queue;
 130
 131    surface_queue = tbm_surface_queue_sequence_create(3, 128, 128, TBM_FORMAT_ARGB888, TBM_BO_DEFAULT);
 132
 133    ...
 134
 135    tbm_surface_queue_destroy (surface_queue);
 136    @endcode
 137  */
 138 tbm_surface_queue_h tbm_surface_queue_sequence_create(int queue_size, int width,
 139                 int height, int format, int flags);
 140
 141 /**
 142  * @brief Destroys the tbm_surface_queue.
 143  *
 144  * @param[in] surface_queue  The #tbm_surface_queue_h
 145  *
 146  * @return  #TBM_SURFACE_QUEUE_ERROR_NONE on success,
 147  *          otherwise an error status value
 148  *
 149  * @see tbm_surface_queue_create()
 150  * @see tbm_surface_queue_sequence_create()
 151  *
 152  * @par Example
 153    @code
 154    #include <tbm_surface_queue.h>
 155
 156    tbm_surface_queue_h surface_queue;
 157
 158    surface_queue = tbm_surface_queue_create(3, 128, 128, TBM_FORMAT_ARGB888, TBM_BO_DEFAULT);
 159
 160    ...
 161
 162    tbm_surface_queue_destroy(surface_queue);
 163    @endcode
 164  */
 165 void tbm_surface_queue_destroy(tbm_surface_queue_h surface_queue);
 166
 167 /**
 168  * @brief Sets allocate callback to the tbm_surface_queue.
 169  *        alloc_cb is called when the tbm_surface_queue try to allocate the tbm_surface and
 170  *        the tbm_surface_queue dequeue the tbm_surface returned in alloc_cb
 171  *        free_cb is called when the tbm_surface_queue unreference the tbm_surface.
 172  *
 173  * @remarks You must use either tbm_surface_queue_set_alloc_cb or tbm_surface_queue_set_alloc_cb2
 174  *
 175  * @param[in] surface_queue  The #tbm_surface_queue_h
 176  * @param[in] alloc_cb       The callback of allocate
 177  * @param[in] free_cb        The callback of free
 178  * @param[in] data           The user data
 179  *
 180  * @return  #TBM_SURFACE_QUEUE_ERROR_NONE on success,
 181  *          otherwise an error status value
 182  */
 183 tbm_surface_queue_error_e tbm_surface_queue_set_alloc_cb(
 184         tbm_surface_queue_h surface_queue,
 185         tbm_surface_alloc_cb alloc_cb,
 186         tbm_surface_free_cb free_cb,
 187         void *data);
 188
 189 /**
 190  * @brief Sets allocate callback to the tbm_surface_queue.
 191  *        alloc_cb2 is called when the tbm_surface_queue try to allocate the tbm_surface and
 192  *        the tbm_surface_queue dequeue the tbm_surface returned in alloc_cb2
 193  *        free_cb is called when the tbm_surface_queue unreference the tbm_surface.
 194  *
 195  * @remarks You must use either tbm_surface_queue_set_alloc_cb or tbm_surface_queue_set_alloc_cb2
 196  *
 197  * @param[in] surface_queue  The #tbm_surface_queue_h
 198  * @param[in] alloc_cb2      The callback of allocate
 199  * @param[in] free_cb        The callback of free
 200  * @param[in] data           The user data
 201  *
 202  * @return  #TBM_SURFACE_QUEUE_ERROR_NONE on success,
 203  *          otherwise an error status value
 204  */
 205 tbm_surface_queue_error_e tbm_surface_queue_set_alloc_cb2(
 206         tbm_surface_queue_h surface_queue,
 207         tbm_surface_alloc_cb2 alloc_cb2,
 208         tbm_surface_free_cb free_cb,
 209         void *data);
 210
 211 /**
 212  * @brief Gets the width of the tbm_surface_queue.
 213  *
 214  * @param[in] surface_queue  The #tbm_surface_queue_h
 215  *
 216  * @return  The width of the tbm_surface_queue on success,
 217  *          otherwise an error status value
 218  */
 219 int tbm_surface_queue_get_width(tbm_surface_queue_h surface_queue);
 220
 221 /**
 222  * @brief Gets the height of the tbm_surface_queue.
 223  *
 224  * @param[in] surface_queue  The #tbm_surface_queue_h
 225  *
 226  * @return  The height of the tbm_surface_queue on success,
 227  *          otherwise an error status value
 228  */
 229 int tbm_surface_queue_get_height(tbm_surface_queue_h surface_queue);
 230
 231 /**
 232  * @brief Gets the format of the tbm_surface_queue.
 233  *
 234  * @param[in] surface_queue  The #tbm_surface_queue_h
 235  *
 236  * @return  The format of the tbm_surface_queue on success,
 237  *          otherwise an error status value
 238  */
 239 int tbm_surface_queue_get_format(tbm_surface_queue_h surface_queue);
 240
 241 /**
 242  * @brief Gets the size of the tbm_surface_queue.
 243  *
 244  * @param[in] surface_queue  The #tbm_surface_queue_h
 245  *
 246  * @return  The size of the tbm_surface_queue on success,
 247  *          otherwise an error status value
 248  */
 249 int tbm_surface_queue_get_size(tbm_surface_queue_h surface_queue);
 250
 251 /**
 252  * @brief Gets the tbm_surfaces used by tbm_surface_queue.
 253  *        Return only surfaces are allocated and current used by the tbm_surface_queue.
 254  *        the tbm_surface_queue allocate surface when can_dequeue or dequeue.
 255  *        if the tbm_surface_queue allocate 2 surface even if queue size is 3,
 256  *        this function will return 2 surfaces.
 257  *        if the tbm_surface_queue is flushed, this function will return none surfaces.
 258  *
 259  * @remarks You must release the surfaces using free().
 260  *
 261  * @param[in]  surface_queue  The #tbm_surface_queue_h
 262  * @param[out] surfaces       The array of the tbm_surfaces
 263  * @param[out] num            The number of the array
 264  *
 265  * @return  #TBM_SURFACE_ERROR_NONE on success,
 266  *          otherwise an error status value
 267  *
 268  *
 269  * @par Example
 270    @code
 271    #include <tbm_surface_queue.h>
 272
 273    tbm_surface_queue_h surface_queue;
 274    tbm_surface_h *surfaces;
 275    int num;
 276    tbm_surface_queue_error_e tsq_err = TBM_SURFACE_QUEUE_ERROR_NONE;
 277
 278    ...
 279
 280    tsq_err = tbm_surface_queue_get_surfaces(surface_queue, surfaces, &num);
 281    if (tsq_err != TBM_SURFACE_QUEUE_ERROR_NONE) {
 282    ...
 283    }
 284
 285    ...
 286
 287    free(surfaces);
 288
 289    @endcode
 290  */
 291 tbm_surface_queue_error_e tbm_surface_queue_get_surfaces(
 292         tbm_surface_queue_h surface_queue,
 293         tbm_surface_h *surfaces, int *num);
 294
 295 tbm_surface_queue_error_e tbm_surface_queue_get_acquirable_surfaces(
 296         tbm_surface_queue_h surface_queue,
 297         tbm_surface_h *surfaces, int *num);
 298
 299 /**
 300  * @brief Gets number of the tbm_surfaces by tbm_surface_queue_trace.
 301  *
 302  * @param[in]  surface_queue  The #tbm_surface_queue_h
 303  * @param[in]  trace          The #tbm_surface_queue_trace
 304  * @param[out] num            The number of the surfaces
 305  *
 306  * @return  #TBM_SURFACE_ERROR_NONE on success,
 307  *          otherwise an error status value
 308  *
 309  *
 310  * @par Example
 311    @code
 312    #include <tbm_surface_queue.h>
 313
 314    tbm_surface_queue_h surface_queue;
 315    int num;
 316    tbm_surface_queue_error_e tsq_err = TBM_SURFACE_QUEUE_ERROR_NONE;
 317
 318    ...
 319
 320    tsq_err = tbm_surface_queue_get_trace_surface_num(surface_queue, TBM_SURFACE_QUEUE_TRACE_DEQUEUE, &num);
 321    if (tsq_err != TBM_SURFACE_QUEUE_ERROR_NONE) {
 322    ...
 323    }
 324
 325    ...
 326
 327    @endcode
 328  */
 329 tbm_surface_queue_error_e tbm_surface_queue_get_trace_surface_num(
 330                         tbm_surface_queue_h surface_queue, tbm_surface_queue_trace trace, int *num);
 331
 332 /**
 333  * @brief Sets size of the tbm_surface_queue.
 334  *
 335  * @param[in]  surface_queue  The #tbm_surface_queue_h
 336  * @param[in]  queue_size     The size of the tbm_surface_queue
 337  * @param[in]  flush          flush the tbm_surface_queue
 338   *
 339  * @return  #TBM_SURFACE_ERROR_NONE on success,
 340  *          otherwise an error status value
 341  *
 342  *
 343  * @par Example
 344    @code
 345    #include <tbm_surface_queue.h>
 346
 347    tbm_surface_queue_h surface_queue;
 348    tbm_surface_queue_error_e tsq_err = TBM_SURFACE_QUEUE_ERROR_NONE;
 349
 350    ...
 351
 352    tsq_err = tbm_surface_queue_set_size(surface_queue, 2, 1);
 353    if (tsq_err != TBM_SURFACE_QUEUE_ERROR_NONE) {
 354    ...
 355    }
 356
 357    ...
 358
 359    @endcode
 360  */
 361 tbm_surface_queue_error_e tbm_surface_queue_set_size(
 362                 tbm_surface_queue_h surface_queue, int queue_size, int flush);
 363
 364 /**
 365  * @brief Sets modes of the tbm_surface_queue.
 366  *
 367  * @param[in]  surface_queue  The #tbm_surface_queue_h
 368  * @param[in]  modes          modes of The #tbm_surface_queue_mode
 369   *
 370  * @return  #TBM_SURFACE_ERROR_NONE on success,
 371  *          otherwise an error status value
 372  *
 373  *
 374  * @par Example
 375    @code
 376    #include <tbm_surface_queue.h>
 377
 378    tbm_surface_queue_h surface_queue;
 379    tbm_surface_queue_error_e tsq_err = TBM_SURFACE_QUEUE_ERROR_NONE;
 380
 381    surface_queue = tbm_surface_queue_create(3, 128, 128, TBM_FORMAT_ARGB888, TBM_BO_DEFAULT);
 382
 383    ...
 384
 385    tsq_err = tbm_surface_queue_set_modes(surface_queue, TBM_SURFACE_QUEUE_MODE_GUARANTEE_CYCLE);
 386    if (tsq_err != TBM_SURFACE_QUEUE_ERROR_NONE) {
 387    ...
 388    }
 389
 390    ...
 391
 392    @endcode
 393  */
 394 tbm_surface_queue_error_e tbm_surface_queue_set_modes(
 395                         tbm_surface_queue_h surface_queue, int modes);
 396
 397 /**
 398  * @brief Sets sync count of the tbm_surface_queue.
 399  *
 400  * @param[in]  surface_queue  The #tbm_surface_queue_h
 401  * @param[in]  sync_count     The sync count
 402  *
 403  * @return  #TBM_SURFACE_ERROR_NONE on success,
 404  *          otherwise an error status value
 405  */
 406 tbm_surface_queue_error_e tbm_surface_queue_set_sync_count(
 407                         tbm_surface_queue_h surface_queue, unsigned int sync_count);
 408
 409 /**
 410  * @brief Check the tbm_surface_queue can dequeue the tbm_surface.
 411  *        if wait is 1, this function isn't return until another thread release
 412  *        the tbm_surface to the tbm_surface_queue
 413  *
 414  * @param[in]  surface_queue  The #tbm_surface_queue_h
 415  * @param[in]  wait           wait releasing the tbm_surface
 416  *
 417  * @return 1 if it can it, otherwise 0.
 418  *
 419  *
 420  * @par Example
 421    @code
 422    #include <tbm_surface_queue.h>
 423
 424    tbm_surface_queue_h surface_queue;
 425
 426    ...
 427
 428    if (tbm_surface_queue_can_dequeue(surface_queue, 0)) {
 429
 430    }
 431
 432    ...
 433
 434    @endcode
 435  */
 436 int tbm_surface_queue_can_dequeue(tbm_surface_queue_h surface_queue, int wait);
 437
 438 /**
 439  * @brief Check the tbm_surface_queue can acquire the tbm_surface.
 440  *        if wait is 1, this function isn't return until another thread enqueue
 441  *        the tbm_surface to the tbm_surface_queue
 442  *
 443  * @param[in]  surface_queue  The #tbm_surface_queue_h
 444  * @param[in]  wait           wait enqueueing the tbm_surface
 445  *
 446  * @return 1 if it can it, otherwise 0.
 447  *
 448  *
 449  * @par Example
 450    @code
 451    #include <tbm_surface_queue.h>
 452
 453    tbm_surface_queue_h surface_queue;
 454
 455    ...
 456
 457    if (tbm_surface_queue_can_acquire(surface_queue, 0)) {
 458
 459    }
 460
 461    ...
 462
 463    @endcode
 464  */
 465 int tbm_surface_queue_can_acquire(tbm_surface_queue_h surface_queue, int wait);
 466
 467 /**
 468  * @brief Dequeue the tbm_surface from the tbm_surface_queue.
 469  *
 470  * @param[in]  surface_queue  The #tbm_surface_queue_h
 471  * @param[out] surface        The #tbm_surface_h
 472  *
 473  * @return  #TBM_SURFACE_ERROR_NONE on success,
 474  *          otherwise an error status value
 475  *
 476  *
 477  * @par Example
 478    @code
 479    #include <tbm_surface_queue.h>
 480
 481    tbm_surface_queue_h surface_queue;
 482    tbm_surface_queue_error_e tsq_err = TBM_SURFACE_QUEUE_ERROR_NONE;
 483    tbm_surface_h surface;
 484
 485    ...
 486
 487    if (tbm_surface_queue_can_dequeue(surface_queue, 0)) {
 488       tsq_err = tbm_surface_queue_dequeue(surface_queue, &surface);
 489       if (tsq_err != TBM_SURFACE_QUEUE_ERROR_NONE) {
 490           ...
 491       }
 492    }
 493
 494    ...
 495
 496    @endcode
 497  */
 498 tbm_surface_queue_error_e tbm_surface_queue_dequeue(
 499                 tbm_surface_queue_h surface_queue, tbm_surface_h *surface);
 500
 501 /**
 502  * @brief Enqueue the tbm_surface to the tbm_surface_queue.
 503  *
 504  * @param[in]  surface_queue  The #tbm_surface_queue_h
 505  * @param[in]  surface        The #tbm_surface_h
 506  *
 507  * @return  #TBM_SURFACE_ERROR_NONE on success,
 508  *          otherwise an error status value
 509  *
 510  *
 511  * @par Example
 512    @code
 513    #include <tbm_surface_queue.h>
 514
 515    tbm_surface_queue_h surface_queue;
 516    tbm_surface_queue_error_e tsq_err = TBM_SURFACE_QUEUE_ERROR_NONE;
 517    tbm_surface_h surface;
 518
 519    if (tbm_surface_queue_can_dequeue(surface_queue, 0)) {
 520       tsq_err = tbm_surface_queue_dequeue(surface_queue, &surface);
 521       if (tsq_err != TBM_SURFACE_QUEUE_ERROR_NONE) {
 522           ...
 523       }
 524    } else {
 525        ...
 526    }
 527
 528    ...
 529
 530    tsq_err = tbm_surface_queue_enqueue(surface_queue, surface);
 531    if (tsq_err != TBM_SURFACE_QUEUE_ERROR_NONE) {
 532        ...
 533    }
 534
 535    ...
 536
 537    @endcode
 538  */
 539 tbm_surface_queue_error_e tbm_surface_queue_enqueue(
 540                 tbm_surface_queue_h surface_queue, tbm_surface_h surface);
 541
 542 /**
 543  * @brief Acquire the tbm_surface from the tbm_surface_queue.
 544  *
 545  * @param[in]  surface_queue  The #tbm_surface_queue_h
 546  * @param[out] surface        The #tbm_surface_h
 547  *
 548  * @return  #TBM_SURFACE_ERROR_NONE on success,
 549  *          otherwise an error status value
 550  *
 551  *
 552  * @par Example
 553    @code
 554    #include <tbm_surface_queue.h>
 555
 556    tbm_surface_queue_h surface_queue;
 557    tbm_surface_queue_error_e tsq_err = TBM_SURFACE_QUEUE_ERROR_NONE;
 558    tbm_surface_h surface, surface2;
 559
 560    if (tbm_surface_queue_can_dequeue(surface_queue, 0)) {
 561       tsq_err = tbm_surface_queue_dequeue(surface_queue, &surface);
 562       if (tsq_err != TBM_SURFACE_QUEUE_ERROR_NONE) {
 563           ...
 564       }
 565    } else {
 566        ...
 567    }
 568
 569    ...
 570
 571    tsq_err = tbm_surface_queue_enqueue(surface_queue, surface);
 572    if (tsq_err != TBM_SURFACE_QUEUE_ERROR_NONE) {
 573        ...
 574    }
 575
 576    ...
 577
 578    if (tbm_surface_queue_can_acquire(surface_queue, 0)) {
 579       tsq_err = tbm_surface_queue_acquire(surface_queue, &surface2)
 580       if (tsq_err != TBM_SURFACE_QUEUE_ERROR_NONE) {
 581           ...
 582       }
 583    }
 584
 585    ...
 586
 587    @endcode
 588  */
 589 tbm_surface_queue_error_e tbm_surface_queue_acquire(
 590                 tbm_surface_queue_h surface_queue, tbm_surface_h *surface);
 591
 592 /**
 593  * @brief Release the tbm_surface to the tbm_surface_queue.
 594  *        the tbm_surface should be released when the tbm_surface can be dequeued and rendered.
 595  *        if the tbm_surface is released even though consumer is using it, it cause issue.
 596  *
 597  * @param[in]  surface_queue  The #tbm_surface_queue_h
 598  * @param[in]  surface        The #tbm_surface_h
 599  *
 600  * @return  #TBM_SURFACE_ERROR_NONE on success,
 601  *          otherwise an error status value
 602  *
 603  *
 604  * @par Example
 605    @code
 606    #include <tbm_surface_queue.h>
 607
 608    tbm_surface_queue_h surface_queue;
 609    tbm_surface_queue_error_e tsq_err = TBM_SURFACE_QUEUE_ERROR_NONE;
 610    tbm_surface_h surface, surface2;
 611
 612    if (tbm_surface_queue_can_dequeue(surface_queue, 0)) {
 613       tsq_err = tbm_surface_queue_dequeue(surface_queue, &surface);
 614       if (tsq_err != TBM_SURFACE_QUEUE_ERROR_NONE) {
 615           ...
 616       }
 617    } else {
 618        ...
 619    }
 620
 621    ...
 622
 623    tsq_err = tbm_surface_queue_enqueue(surface_queue, surface);
 624    if (tsq_err != TBM_SURFACE_QUEUE_ERROR_NONE) {
 625        ...
 626    }
 627
 628    ...
 629
 630    if (tbm_surface_queue_can_acquire(surface_queue, 0)) {
 631        tsq_err = tbm_surface_queue_acquire(surface_queue, &surface2)
 632        if (tsq_err != TBM_SURFACE_QUEUE_ERROR_NONE) {
 633            ...
 634        }
 635    } else {
 636        ...
 637    }
 638    ...
 639
 640    tsq_err = tbm_surface_queue_release(surface_queue, surface2)
 641    if (tsq_err != TBM_SURFACE_QUEUE_ERROR_NONE) {
 642        ...
 643    }
 644
 645    @endcode
 646  */
 647 tbm_surface_queue_error_e tbm_surface_queue_release(
 648                 tbm_surface_queue_h surface_queue, tbm_surface_h surface);
 649
 650 /**
 651  * @brief Cancel dequeue the tbm_surface to the tbm_surface_queue.
 652  *
 653  * @param[in]  surface_queue  The #tbm_surface_queue_h
 654  * @param[in]  surface        The #tbm_surface_h
 655  *
 656  * @return  #TBM_SURFACE_ERROR_NONE on success,
 657  *          otherwise an error status value
 658  *
 659  *
 660  * @par Example
 661    @code
 662    #include <tbm_surface_queue.h>
 663
 664    tbm_surface_queue_h surface_queue;
 665    tbm_surface_queue_error_e tsq_err = TBM_SURFACE_QUEUE_ERROR_NONE;
 666    tbm_surface_h surface;
 667
 668    if (tbm_surface_queue_can_dequeue(surface_queue, 0)) {
 669       tsq_err = tbm_surface_queue_dequeue(surface_queue, &surface);
 670       if (tsq_err != TBM_SURFACE_QUEUE_ERROR_NONE) {
 671           ...
 672       }
 673    } else {
 674        ...
 675    }
 676
 677    tsq_err = tbm_surface_queue_cancel_dequeue(surface_queue, surface);
 678    if (tsq_err != TBM_SURFACE_QUEUE_ERROR_NONE) {
 679        ...
 680    }
 681
 682    ...
 683
 684    @endcode
 685  */
 686 tbm_surface_queue_error_e tbm_surface_queue_cancel_dequeue(
 687                 tbm_surface_queue_h surface_queue, tbm_surface_h surface);
 688
 689 /**
 690  * @brief Cancel acquire the tbm_surface to the tbm_surface_queue.
 691  *
 692  * @param[in]  surface_queue  The #tbm_surface_queue_h
 693  * @param[in]  surface        The #tbm_surface_h
 694  *
 695  * @return  #TBM_SURFACE_ERROR_NONE on success,
 696  *          otherwise an error status value
 697  *
 698  *
 699  * @par Example
 700    @code
 701    #include <tbm_surface_queue.h>
 702
 703    tbm_surface_queue_h surface_queue;
 704    tbm_surface_queue_error_e tsq_err = TBM_SURFACE_QUEUE_ERROR_NONE;
 705    tbm_surface_h surface;
 706
 707    if (tbm_surface_queue_can_acquire(surface_queue, 0)) {
 708        tsq_err = tbm_surface_queue_acquire(surface_queue, &surface);
 709        if (tsq_err != TBM_SURFACE_QUEUE_ERROR_NONE) {
 710            ...
 711       }
 712    } else {
 713        ...
 714    }
 715
 716    tsq_err = tbm_surface_queue_cancel_acquire(surface_queue, surface);
 717    if (tsq_err != TBM_SURFACE_QUEUE_ERROR_NONE) {
 718        ...
 719    }
 720
 721    ...
 722
 723    @endcode
 724  */
 725 tbm_surface_queue_error_e tbm_surface_queue_cancel_acquire(
 726                 tbm_surface_queue_h surface_queue, tbm_surface_h surface);
 727
 728 /**
 729  * @brief Reset the tbm_surface_queue.
 730  *
 731  * @param[in]  surface_queue  The #tbm_surface_queue_h
 732  * @param[in]  width          The width of the tbm_surface_queue
 733  * @param[in]  height         The height of the tbm_surface_queue
 734  * @param[in]  format         The format of the tbm_surface_queue
 735  *
 736  * @return  #TBM_SURFACE_ERROR_NONE on success,
 737  *          otherwise an error status value
 738  *
 739  *
 740  * @par Example
 741    @code
 742    #include <tbm_surface_queue.h>
 743
 744    tbm_surface_queue_h surface_queue;
 745    tbm_surface_queue_error_e tsq_err = TBM_SURFACE_QUEUE_ERROR_NONE;
 746
 747    tsq_err = tbm_surface_queue_reset(surface_queue, 256,256, TBM_FORMAT_YUV420);
 748    if (tsq_err != TBM_SURFACE_QUEUE_ERROR_NONE) {
 749        ...
 750    }
 751
 752    ...
 753
 754    @endcode
 755  */
 756 tbm_surface_queue_error_e tbm_surface_queue_reset(
 757                 tbm_surface_queue_h surface_queue, int width, int height, int format);
 758
 759 /**
 760  * @brief Flush the tbm_surface_queue.
 761  *
 762  * @param[in]  surface_queue  The #tbm_surface_queue_h
 763  *
 764  * @return  #TBM_SURFACE_ERROR_NONE on success,
 765  *          otherwise an error status value
 766  */
 767 tbm_surface_queue_error_e tbm_surface_queue_flush(tbm_surface_queue_h surface_queue);
 768
 769 /**
 770  * @brief Free Flush the tbm_surface_queue.
 771  *        only the released tbm_surface is flushed.
 772  *
 773  * @param[in]  surface_queue  The #tbm_surface_queue_h
 774  *
 775  * @return  #TBM_SURFACE_ERROR_NONE on success,
 776  *          otherwise an error status value
 777  */
 778 tbm_surface_queue_error_e tbm_surface_queue_free_flush(tbm_surface_queue_h surface_queue);
 779
 780 /**
 781  * @brief Notify reset of the tbm_surface_queue.
 782  *
 783  * @param[in]  surface_queue  The #tbm_surface_queue_h
 784  *
 785  * @return  #TBM_SURFACE_ERROR_NONE on success,
 786  *          otherwise an error status value
 787  */
 788 tbm_surface_queue_error_e tbm_surface_queue_notify_reset(tbm_surface_queue_h surface_queue);
 789
 790 /**
 791  * @brief Notify dequeuable of the tbm_surface_queue.
 792  *
 793  * @param[in]  surface_queue  The #tbm_surface_queue_h
 794  *
 795  * @return  #TBM_SURFACE_ERROR_NONE on success,
 796  *          otherwise an error status value
 797  */
 798 tbm_surface_queue_error_e tbm_surface_queue_notify_dequeuable(tbm_surface_queue_h surface_queue);
 799
 800 /**
 801  * @brief Add callback of destroy to the tbm_surface_queue.
 802  *
 803  * @param[in]  surface_queue  The #tbm_surface_queue_h
 804  * @param[in]  destroy_cb     The callback of destroy
 805  * @param[in]  data           The user data
 806  *
 807  * @return  #TBM_SURFACE_ERROR_NONE on success,
 808  *          otherwise an error status value
 809  */
 810 tbm_surface_queue_error_e tbm_surface_queue_add_destroy_cb(
 811         tbm_surface_queue_h surface_queue, tbm_surface_queue_notify_cb destroy_cb,
 812         void *data);
 813
 814 /**
 815  * @brief Remove callback of destroy from the tbm_surface_queue.
 816  *
 817  * @param[in]  surface_queue  The #tbm_surface_queue_h
 818  * @param[in]  destroy_cb     The callback of destroy
 819  * @param[in]  data           The user data
 820  *
 821  * @return  #TBM_SURFACE_ERROR_NONE on success,
 822  *          otherwise an error status value
 823  */
 824 tbm_surface_queue_error_e tbm_surface_queue_remove_destroy_cb(
 825         tbm_surface_queue_h surface_queue, tbm_surface_queue_notify_cb destroy_cb,
 826         void *data);
 827
 828 /**
 829  * @brief Add callback of reset to the tbm_surface_queue.
 830  *
 831  * @param[in]  surface_queue  The #tbm_surface_queue_h
 832  * @param[in]  reset_cb       The callback of reset
 833  * @param[in]  data           The user data
 834  *
 835  * @return  #TBM_SURFACE_ERROR_NONE on success,
 836  *          otherwise an error status value
 837  */
 838 tbm_surface_queue_error_e tbm_surface_queue_add_reset_cb(
 839         tbm_surface_queue_h surface_queue, tbm_surface_queue_notify_cb reset_cb,
 840         void *data);
 841
 842 /**
 843  * @brief Remove callback of reset from the tbm_surface_queue.
 844  *
 845  * @param[in]  surface_queue  The #tbm_surface_queue_h
 846  * @param[in]  reset_cb       The callback of reset
 847  * @param[in]  data           The user data
 848  *
 849  * @return  #TBM_SURFACE_ERROR_NONE on success,
 850  *          otherwise an error status value
 851  */
 852 tbm_surface_queue_error_e tbm_surface_queue_remove_reset_cb(
 853         tbm_surface_queue_h surface_queue, tbm_surface_queue_notify_cb reset_cb,
 854         void *data);
 855
 856 /**
 857  * @brief Add callback of dequeuable to the tbm_surface_queue.
 858  *
 859  * @param[in]  surface_queue  The #tbm_surface_queue_h
 860  * @param[in]  dequeuable_cb  The callback of dequeuable
 861  * @param[in]  data           The user data
 862  *
 863  * @return  #TBM_SURFACE_ERROR_NONE on success,
 864  *          otherwise an error status value
 865  */
 866 tbm_surface_queue_error_e tbm_surface_queue_add_dequeuable_cb(
 867         tbm_surface_queue_h surface_queue, tbm_surface_queue_notify_cb dequeuable_cb,
 868         void *data);
 869
 870 /**
 871  * @brief Remove callback of dequeuable from the tbm_surface_queue.
 872  *
 873  * @param[in]  surface_queue  The #tbm_surface_queue_h
 874  * @param[in]  dequeuable_cb  The callback of dequeuable
 875  * @param[in]  data           The user data
 876  *
 877  * @return  #TBM_SURFACE_ERROR_NONE on success,
 878  *          otherwise an error status value
 879  */
 880 tbm_surface_queue_error_e tbm_surface_queue_remove_dequeuable_cb(
 881         tbm_surface_queue_h surface_queue, tbm_surface_queue_notify_cb dequeuable_cb,
 882         void *data);
 883
 884 /**
 885  * @brief Add callback of dequeue to the tbm_surface_queue.
 886  *
 887  * @param[in]  surface_queue  The #tbm_surface_queue_h
 888  * @param[in]  dequeue_cb     The callback of dequeue
 889  * @param[in]  data           The user data
 890  *
 891  * @return  #TBM_SURFACE_ERROR_NONE on success,
 892  *          otherwise an error status value
 893  */
 894 tbm_surface_queue_error_e tbm_surface_queue_add_dequeue_cb(
 895         tbm_surface_queue_h surface_queue, tbm_surface_queue_notify_cb dequeue_cb,
 896         void *data);
 897
 898 /**
 899  * @brief Remove callback of dequeue from the tbm_surface_queue.
 900  *
 901  * @param[in]  surface_queue  The #tbm_surface_queue_h
 902  * @param[in]  dequeue_cb     The callback of dequeue
 903  * @param[in]  data           The user data
 904  *
 905  * @return  #TBM_SURFACE_ERROR_NONE on success,
 906  *          otherwise an error status value
 907  */
 908 tbm_surface_queue_error_e tbm_surface_queue_remove_dequeue_cb(
 909         tbm_surface_queue_h surface_queue, tbm_surface_queue_notify_cb dequeue_cb,
 910         void *data);
 911
 912 /**
 913  * @brief Add callback of can_dequeue to the tbm_surface_queue.
 914  *
 915  * @param[in]  surface_queue  The #tbm_surface_queue_h
 916  * @param[in]  can_dequeue_cb The callback of can_dequeue
 917  * @param[in]  data           The user data
 918  *
 919  * @return  #TBM_SURFACE_ERROR_NONE on success,
 920  *          otherwise an error status value
 921  */
 922 tbm_surface_queue_error_e tbm_surface_queue_add_can_dequeue_cb(
 923         tbm_surface_queue_h surface_queue, tbm_surface_queue_notify_cb can_dequeue_cb,
 924         void *data);
 925
 926 /**
 927  * @brief Remove callback of can_dequeue from the tbm_surface_queue.
 928  *
 929  * @param[in]  surface_queue  The #tbm_surface_queue_h
 930  * @param[in]  can_dequeue_cb The callback of can_dequeue
 931  * @param[in]  data           The user data
 932  *
 933  * @return  #TBM_SURFACE_ERROR_NONE on success,
 934  *          otherwise an error status value
 935  */
 936 tbm_surface_queue_error_e tbm_surface_queue_remove_can_dequeue_cb(
 937         tbm_surface_queue_h surface_queue, tbm_surface_queue_notify_cb can_dequeue_cb,
 938         void *data);
 939
 940 /**
 941  * @brief Add callback of acquirable to the tbm_surface_queue.
 942  *
 943  * @param[in]  surface_queue  The #tbm_surface_queue_h
 944  * @param[in]  acquirable_cb  The callback of acquirable
 945  * @param[in]  data           The user data
 946  *
 947  * @return  #TBM_SURFACE_ERROR_NONE on success,
 948  *          otherwise an error status value
 949  */
 950 tbm_surface_queue_error_e tbm_surface_queue_add_acquirable_cb(
 951         tbm_surface_queue_h surface_queue, tbm_surface_queue_notify_cb acquirable_cb,
 952         void *data);
 953
 954 /**
 955  * @brief Remove callback of acquirable form the tbm_surface_queue.
 956  *
 957  * @param[in]  surface_queue  The #tbm_surface_queue_h
 958  * @param[in]  acquirable_cb  The callback of acquirable
 959  * @param[in]  data           The user data
 960  *
 961  * @return  #TBM_SURFACE_ERROR_NONE on success,
 962  *          otherwise an error status value
 963  */
 964 tbm_surface_queue_error_e tbm_surface_queue_remove_acquirable_cb(
 965         tbm_surface_queue_h surface_queue, tbm_surface_queue_notify_cb acquirable_cb,
 966         void *data);
 967
 968 /**
 969  * @brief Add callback of trace to the tbm_surface_queue.
 970  *
 971  * @param[in]  surface_queue  The #tbm_surface_queue_h
 972  * @param[in]  trace_cb       The callback of trace
 973  * @param[in]  data           The user data
 974  *
 975  * @return  #TBM_SURFACE_ERROR_NONE on success,
 976  *          otherwise an error status value
 977  */
 978 tbm_surface_queue_error_e tbm_surface_queue_add_trace_cb(
 979         tbm_surface_queue_h surface_queue, tbm_surface_queue_trace_cb trace_cb,
 980         void *data);
 981
 982 /**
 983  * @brief Remove callback of trace from the tbm_surface_queue.
 984  *
 985  * @param[in]  surface_queue  The #tbm_surface_queue_h
 986  * @param[in]  trace_cb       The callback of trace
 987  * @param[in]  data           The user data
 988  *
 989  * @return  #TBM_SURFACE_ERROR_NONE on success,
 990  *          otherwise an error status value
 991  */
 992 tbm_surface_queue_error_e tbm_surface_queue_remove_trace_cb(
 993         tbm_surface_queue_h surface_queue, tbm_surface_queue_trace_cb trace_cb,
 994         void *data);
 995
 996 tbm_surface_queue_error_e
 997 tbm_surface_queue_can_dequeue_wait_timeout(
 998         tbm_surface_queue_h surface_queue, int ms_timeout);
 999
1000 #ifdef __cplusplus
1001 }
1002 #endif
1003 #endif                                                  /* _TBM_SURFACE_H_ */