aom/aom_frame_buffer.h

   1 /*
   2  * Copyright (c) 2016, Alliance for Open Media. All rights reserved
   3  *
   4  * This source code is subject to the terms of the BSD 2 Clause License and
   5  * the Alliance for Open Media Patent License 1.0. If the BSD 2 Clause License
   6  * was not distributed with this source code in the LICENSE file, you can
   7  * obtain it at www.aomedia.org/license/software. If the Alliance for Open
   8  * Media Patent License 1.0 was not distributed with this source code in the
   9  * PATENTS file, you can obtain it at www.aomedia.org/license/patent.
  10  */
  11
  12 #ifndef AOM_AOM_FRAME_BUFFER_H_
  13 #define AOM_AOM_FRAME_BUFFER_H_
  14
  15 /*!\file
  16  * \brief Describes the decoder external frame buffer interface.
  17  */
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif
  22
  23 #include "./aom_integer.h"
  24
  25 /*!\brief The maximum number of work buffers used by libaom.
  26  *  Support maximum 4 threads to decode video in parallel.
  27  *  Each thread will use one work buffer.
  28  * TODO(hkuang): Add support to set number of worker threads dynamically.
  29  */
  30 #define AOM_MAXIMUM_WORK_BUFFERS 8
  31
  32 /*!\brief The maximum number of reference buffers that a AV1 encoder may use.
  33  */
  34 #define AOM_MAXIMUM_REF_BUFFERS 8
  35
  36 /*!\brief External frame buffer
  37  *
  38  * This structure holds allocated frame buffers used by the decoder.
  39  */
  40 typedef struct aom_codec_frame_buffer {
  41   uint8_t *data; /**< Pointer to the data buffer */
  42   size_t size;   /**< Size of data in bytes */
  43   void *priv;    /**< Frame's private data */
  44 } aom_codec_frame_buffer_t;
  45
  46 /*!\brief get frame buffer callback prototype
  47  *
  48  * This callback is invoked by the decoder to retrieve data for the frame
  49  * buffer in order for the decode call to complete. The callback must
  50  * allocate at least min_size in bytes and assign it to fb->data. The callback
  51  * must zero out all the data allocated. Then the callback must set fb->size
  52  * to the allocated size. The application does not need to align the allocated
  53  * data. The callback is triggered when the decoder needs a frame buffer to
  54  * decode a compressed image into. This function may be called more than once
  55  * for every call to aom_codec_decode. The application may set fb->priv to
  56  * some data which will be passed back in the ximage and the release function
  57  * call. |fb| is guaranteed to not be NULL. On success the callback must
  58  * return 0. Any failure the callback must return a value less than 0.
  59  *
  60  * \param[in] priv         Callback's private data
  61  * \param[in] new_size     Size in bytes needed by the buffer
  62  * \param[in,out] fb       Pointer to aom_codec_frame_buffer_t
  63  */
  64 typedef int (*aom_get_frame_buffer_cb_fn_t)(void *priv, size_t min_size,
  65                                             aom_codec_frame_buffer_t *fb);
  66
  67 /*!\brief release frame buffer callback prototype
  68  *
  69  * This callback is invoked by the decoder when the frame buffer is not
  70  * referenced by any other buffers. |fb| is guaranteed to not be NULL. On
  71  * success the callback must return 0. Any failure the callback must return
  72  * a value less than 0.
  73  *
  74  * \param[in] priv         Callback's private data
  75  * \param[in] fb           Pointer to aom_codec_frame_buffer_t
  76  */
  77 typedef int (*aom_release_frame_buffer_cb_fn_t)(void *priv,
  78                                                 aom_codec_frame_buffer_t *fb);
  79
  80 #ifdef __cplusplus
  81 }  // extern "C"
  82 #endif
  83
  84 #endif  // AOM_AOM_FRAME_BUFFER_H_