aomdx.h 9.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276
  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. /*!\defgroup aom_decoder AOMedia AOM/AV1 Decoder
  12. * \ingroup aom
  13. *
  14. * @{
  15. */
  16. /*!\file
  17. * \brief Provides definitions for using AOM or AV1 within the aom Decoder
  18. * interface.
  19. */
  20. #ifndef AOM_AOMDX_H_
  21. #define AOM_AOMDX_H_
  22. #ifdef __cplusplus
  23. extern "C" {
  24. #endif
  25. /* Include controls common to both the encoder and decoder */
  26. #include "aom/aom.h"
  27. /*!\name Algorithm interface for AV1
  28. *
  29. * This interface provides the capability to decode AV1 streams.
  30. * @{
  31. */
  32. extern aom_codec_iface_t aom_codec_av1_dx_algo;
  33. extern aom_codec_iface_t *aom_codec_av1_dx(void);
  34. /*!@} - end algorithm interface member group*/
  35. /** Data structure that stores bit accounting for debug
  36. */
  37. typedef struct Accounting Accounting;
  38. #ifndef AOM_INSPECTION_H_
  39. /** Callback that inspects decoder frame data.
  40. */
  41. typedef void (*aom_inspect_cb)(void *decoder, void *ctx);
  42. #endif
  43. /*!\brief Structure to hold inspection callback and context.
  44. *
  45. * Defines a structure to hold the inspection callback function and calling
  46. * context.
  47. */
  48. typedef struct aom_inspect_init {
  49. /*! Inspection callback. */
  50. aom_inspect_cb inspect_cb;
  51. /*! Inspection context. */
  52. void *inspect_ctx;
  53. } aom_inspect_init;
  54. /*!\brief Structure to hold a tile's start address and size in the bitstream.
  55. *
  56. * Defines a structure to hold a tile's start address and size in the bitstream.
  57. */
  58. typedef struct aom_tile_data {
  59. /*! Tile data size. */
  60. size_t coded_tile_data_size;
  61. /*! Tile's start address. */
  62. const void *coded_tile_data;
  63. /*! Extra size information. */
  64. size_t extra_size;
  65. } aom_tile_data;
  66. /*!\brief Structure to hold the external reference frame pointer.
  67. *
  68. * Define a structure to hold the external reference frame pointer.
  69. */
  70. typedef struct av1_ext_ref_frame {
  71. /*! Start pointer of external references. */
  72. aom_image_t *img;
  73. /*! Number of available external references. */
  74. int num;
  75. } av1_ext_ref_frame_t;
  76. /*!\enum aom_dec_control_id
  77. * \brief AOM decoder control functions
  78. *
  79. * This set of macros define the control functions available for the AOM
  80. * decoder interface.
  81. *
  82. * \sa #aom_codec_control
  83. */
  84. enum aom_dec_control_id {
  85. /** control function to get info on which reference frames were updated
  86. * by the last decode
  87. */
  88. AOMD_GET_LAST_REF_UPDATES = AOM_DECODER_CTRL_ID_START,
  89. /** check if the indicated frame is corrupted */
  90. AOMD_GET_FRAME_CORRUPTED,
  91. /** control function to get info on which reference frames were used
  92. * by the last decode
  93. */
  94. AOMD_GET_LAST_REF_USED,
  95. /** control function to get the dimensions that the current frame is decoded
  96. * at. This may be different to the intended display size for the frame as
  97. * specified in the wrapper or frame header (see AV1D_GET_DISPLAY_SIZE). */
  98. AV1D_GET_FRAME_SIZE,
  99. /** control function to get the current frame's intended display dimensions
  100. * (as specified in the wrapper or frame header). This may be different to
  101. * the decoded dimensions of this frame (see AV1D_GET_FRAME_SIZE). */
  102. AV1D_GET_DISPLAY_SIZE,
  103. /** control function to get the bit depth of the stream. */
  104. AV1D_GET_BIT_DEPTH,
  105. /** control function to set the byte alignment of the planes in the reference
  106. * buffers. Valid values are power of 2, from 32 to 1024. A value of 0 sets
  107. * legacy alignment. I.e. Y plane is aligned to 32 bytes, U plane directly
  108. * follows Y plane, and V plane directly follows U plane. Default value is 0.
  109. */
  110. AV1_SET_BYTE_ALIGNMENT,
  111. /** control function to invert the decoding order to from right to left. The
  112. * function is used in a test to confirm the decoding independence of tile
  113. * columns. The function may be used in application where this order
  114. * of decoding is desired.
  115. *
  116. * TODO(yaowu): Rework the unit test that uses this control, and in a future
  117. * release, this test-only control shall be removed.
  118. */
  119. AV1_INVERT_TILE_DECODE_ORDER,
  120. /** control function to set the skip loop filter flag. Valid values are
  121. * integers. The decoder will skip the loop filter when its value is set to
  122. * nonzero. If the loop filter is skipped the decoder may accumulate decode
  123. * artifacts. The default value is 0.
  124. */
  125. AV1_SET_SKIP_LOOP_FILTER,
  126. /** control function to retrieve a pointer to the Accounting struct. When
  127. * compiled without --enable-accounting, this returns AOM_CODEC_INCAPABLE.
  128. * If called before a frame has been decoded, this returns AOM_CODEC_ERROR.
  129. * The caller should ensure that AOM_CODEC_OK is returned before attempting
  130. * to dereference the Accounting pointer.
  131. */
  132. AV1_GET_ACCOUNTING,
  133. /** control function to get last decoded frame quantizer. Returned value uses
  134. * internal quantizer scale defined by the codec.
  135. */
  136. AOMD_GET_LAST_QUANTIZER,
  137. /** control function to set the range of tile decoding. A value that is
  138. * greater and equal to zero indicates only the specific row/column is
  139. * decoded. A value that is -1 indicates the whole row/column is decoded.
  140. * A special case is both values are -1 that means the whole frame is
  141. * decoded.
  142. */
  143. AV1_SET_DECODE_TILE_ROW,
  144. AV1_SET_DECODE_TILE_COL,
  145. /** control function to set the tile coding mode. A value that is equal to
  146. * zero indicates the tiles are coded in normal tile mode. A value that is
  147. * 1 indicates the tiles are coded in large-scale tile mode.
  148. */
  149. AV1_SET_TILE_MODE,
  150. /** control function to get the frame header information of an encoded frame
  151. * in the bitstream. This provides a way to access a frame's header data.
  152. */
  153. AV1D_GET_FRAME_HEADER_INFO,
  154. /** control function to get the start address and size of a tile in the coded
  155. * bitstream. This provides a way to access a specific tile's bitstream data.
  156. */
  157. AV1D_GET_TILE_DATA,
  158. /** control function to set the external references' pointers in the decoder.
  159. * This is used while decoding the tile list OBU in large-scale tile coding
  160. * mode.
  161. */
  162. AV1D_SET_EXT_REF_PTR,
  163. /** control function to enable the ext-tile software debug and testing code in
  164. * the decoder.
  165. */
  166. AV1D_EXT_TILE_DEBUG,
  167. /** control function to indicate whether bitstream is in Annex-B format. */
  168. AV1D_SET_IS_ANNEXB,
  169. /** control function to indicate which operating point to use. A scalable
  170. * stream may define multiple operating points, each of which defines a
  171. * set of temporal and spatial layers to be processed. The operating point
  172. * index may take a value between 0 and operating_points_cnt_minus_1 (which
  173. * is at most 31).
  174. */
  175. AV1D_SET_OPERATING_POINT,
  176. /** control function to indicate whether to output one frame per temporal
  177. * unit (the default), or one frame per spatial layer.
  178. * In a scalable stream, each temporal unit corresponds to a single "frame"
  179. * of video, and within a temporal unit there may be multiple spatial layers
  180. * with different versions of that frame.
  181. * For video playback, only the highest-quality version (within the
  182. * selected operating point) is needed, but for some use cases it is useful
  183. * to have access to multiple versions of a frame when they are available.
  184. */
  185. AV1D_SET_OUTPUT_ALL_LAYERS,
  186. /** control function to set an aom_inspect_cb callback that is invoked each
  187. * time a frame is decoded. When compiled without --enable-inspection, this
  188. * returns AOM_CODEC_INCAPABLE.
  189. */
  190. AV1_SET_INSPECTION_CALLBACK,
  191. AOM_DECODER_CTRL_ID_MAX,
  192. };
  193. /*!\cond */
  194. /*!\brief AOM decoder control function parameter type
  195. *
  196. * Defines the data types that AOMD control functions take. Note that
  197. * additional common controls are defined in aom.h
  198. *
  199. */
  200. AOM_CTRL_USE_TYPE(AOMD_GET_LAST_REF_UPDATES, int *)
  201. #define AOM_CTRL_AOMD_GET_LAST_REF_UPDATES
  202. AOM_CTRL_USE_TYPE(AOMD_GET_FRAME_CORRUPTED, int *)
  203. #define AOM_CTRL_AOMD_GET_FRAME_CORRUPTED
  204. AOM_CTRL_USE_TYPE(AOMD_GET_LAST_REF_USED, int *)
  205. #define AOM_CTRL_AOMD_GET_LAST_REF_USED
  206. AOM_CTRL_USE_TYPE(AOMD_GET_LAST_QUANTIZER, int *)
  207. #define AOM_CTRL_AOMD_GET_LAST_QUANTIZER
  208. AOM_CTRL_USE_TYPE(AV1D_GET_DISPLAY_SIZE, int *)
  209. #define AOM_CTRL_AV1D_GET_DISPLAY_SIZE
  210. AOM_CTRL_USE_TYPE(AV1D_GET_BIT_DEPTH, unsigned int *)
  211. #define AOM_CTRL_AV1D_GET_BIT_DEPTH
  212. AOM_CTRL_USE_TYPE(AV1D_GET_FRAME_SIZE, int *)
  213. #define AOM_CTRL_AV1D_GET_FRAME_SIZE
  214. AOM_CTRL_USE_TYPE(AV1_INVERT_TILE_DECODE_ORDER, int)
  215. #define AOM_CTRL_AV1_INVERT_TILE_DECODE_ORDER
  216. AOM_CTRL_USE_TYPE(AV1_GET_ACCOUNTING, Accounting **)
  217. #define AOM_CTRL_AV1_GET_ACCOUNTING
  218. AOM_CTRL_USE_TYPE(AV1_SET_DECODE_TILE_ROW, int)
  219. #define AOM_CTRL_AV1_SET_DECODE_TILE_ROW
  220. AOM_CTRL_USE_TYPE(AV1_SET_DECODE_TILE_COL, int)
  221. #define AOM_CTRL_AV1_SET_DECODE_TILE_COL
  222. AOM_CTRL_USE_TYPE(AV1_SET_TILE_MODE, unsigned int)
  223. #define AOM_CTRL_AV1_SET_TILE_MODE
  224. AOM_CTRL_USE_TYPE(AV1D_GET_FRAME_HEADER_INFO, aom_tile_data *)
  225. #define AOM_CTRL_AV1D_GET_FRAME_HEADER_INFO
  226. AOM_CTRL_USE_TYPE(AV1D_GET_TILE_DATA, aom_tile_data *)
  227. #define AOM_CTRL_AV1D_GET_TILE_DATA
  228. AOM_CTRL_USE_TYPE(AV1D_SET_EXT_REF_PTR, av1_ext_ref_frame_t *)
  229. #define AOM_CTRL_AV1D_SET_EXT_REF_PTR
  230. AOM_CTRL_USE_TYPE(AV1D_EXT_TILE_DEBUG, unsigned int)
  231. #define AOM_CTRL_AV1D_EXT_TILE_DEBUG
  232. AOM_CTRL_USE_TYPE(AV1D_SET_IS_ANNEXB, unsigned int)
  233. #define AOM_CTRL_AV1D_SET_IS_ANNEXB
  234. AOM_CTRL_USE_TYPE(AV1D_SET_OPERATING_POINT, int)
  235. #define AOM_CTRL_AV1D_SET_OPERATING_POINT
  236. AOM_CTRL_USE_TYPE(AV1D_SET_OUTPUT_ALL_LAYERS, int)
  237. #define AOM_CTRL_AV1D_SET_OUTPUT_ALL_LAYERS
  238. AOM_CTRL_USE_TYPE(AV1_SET_INSPECTION_CALLBACK, aom_inspect_init *)
  239. #define AOM_CTRL_AV1_SET_INSPECTION_CALLBACK
  240. /*!\endcond */
  241. /*! @} - end defgroup aom_decoder */
  242. #ifdef __cplusplus
  243. } // extern "C"
  244. #endif
  245. #endif // AOM_AOMDX_H_