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