• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 /*!\file
13  * \brief Describes the decoder algorithm interface for algorithm
14  *        implementations.
15  *
16  * This file defines the private structures and data types that are only
17  * relevant to implementing an algorithm, as opposed to using it.
18  *
19  * To create a decoder algorithm class, an interface structure is put
20  * into the global namespace:
21  *     <pre>
22  *     my_codec.c:
23  *       aom_codec_iface_t my_codec = {
24  *           "My Codec v1.0",
25  *           AOM_CODEC_ALG_ABI_VERSION,
26  *           ...
27  *       };
28  *     </pre>
29  *
30  * An application instantiates a specific decoder instance by using
31  * aom_codec_init() and a pointer to the algorithm's interface structure:
32  *     <pre>
33  *     my_app.c:
34  *       extern aom_codec_iface_t my_codec;
35  *       {
36  *           aom_codec_ctx_t algo;
37  *           res = aom_codec_init(&algo, &my_codec);
38  *       }
39  *     </pre>
40  *
41  * Once initialized, the instance is managed using other functions from
42  * the aom_codec_* family.
43  */
44 #ifndef AOM_AOM_INTERNAL_AOM_CODEC_INTERNAL_H_
45 #define AOM_AOM_INTERNAL_AOM_CODEC_INTERNAL_H_
46 #include "../aom_decoder.h"
47 #include "../aom_encoder.h"
48 #include <stdarg.h>
49 
50 #ifdef __cplusplus
51 extern "C" {
52 #endif
53 
54 /*!\brief Current ABI version number
55  *
56  * \internal
57  * If this file is altered in any way that changes the ABI, this value
58  * must be bumped.  Examples include, but are not limited to, changing
59  * types, removing or reassigning enums, adding/removing/rearranging
60  * fields to structures
61  */
62 #define AOM_CODEC_INTERNAL_ABI_VERSION (7) /**<\hideinitializer*/
63 
64 typedef struct aom_codec_alg_priv aom_codec_alg_priv_t;
65 
66 /*!\brief init function pointer prototype
67  *
68  * Performs algorithm-specific initialization of the decoder context. This
69  * function is called by the generic aom_codec_init() wrapper function, so
70  * plugins implementing this interface may trust the input parameters to be
71  * properly initialized.
72  *
73  * \param[in] ctx   Pointer to this instance's context
74  * \retval #AOM_CODEC_OK
75  *     The input stream was recognized and decoder initialized.
76  * \retval #AOM_CODEC_MEM_ERROR
77  *     Memory operation failed.
78  */
79 typedef aom_codec_err_t (*aom_codec_init_fn_t)(aom_codec_ctx_t *ctx);
80 
81 /*!\brief destroy function pointer prototype
82  *
83  * Performs algorithm-specific destruction of the decoder context. This
84  * function is called by the generic aom_codec_destroy() wrapper function,
85  * so plugins implementing this interface may trust the input parameters
86  * to be properly initialized.
87  *
88  * \param[in] ctx   Pointer to this instance's context
89  * \retval #AOM_CODEC_OK
90  *     The input stream was recognized and decoder initialized.
91  * \retval #AOM_CODEC_MEM_ERROR
92  *     Memory operation failed.
93  */
94 typedef aom_codec_err_t (*aom_codec_destroy_fn_t)(aom_codec_alg_priv_t *ctx);
95 
96 /*!\brief parse stream info function pointer prototype
97  *
98  * Performs high level parsing of the bitstream. This function is called by the
99  * generic aom_codec_peek_stream_info() wrapper function, so plugins
100  * implementing this interface may trust the input parameters to be properly
101  * initialized.
102  *
103  * \param[in]      data    Pointer to a block of data to parse
104  * \param[in]      data_sz Size of the data buffer
105  * \param[in,out]  si      Pointer to stream info to update. The is_annexb
106  *                         member \ref MUST be properly initialized. This
107  *                         function sets the rest of the members.
108  *
109  * \retval #AOM_CODEC_OK
110  *     Bitstream is parsable and stream information updated
111  */
112 typedef aom_codec_err_t (*aom_codec_peek_si_fn_t)(const uint8_t *data,
113                                                   size_t data_sz,
114                                                   aom_codec_stream_info_t *si);
115 
116 /*!\brief Return information about the current stream.
117  *
118  * Returns information about the stream that has been parsed during decoding.
119  *
120  * \param[in]      ctx     Pointer to this instance's context
121  * \param[in,out]  si      Pointer to stream info to update
122  *
123  * \retval #AOM_CODEC_OK
124  *     Bitstream is parsable and stream information updated
125  */
126 typedef aom_codec_err_t (*aom_codec_get_si_fn_t)(aom_codec_alg_priv_t *ctx,
127                                                  aom_codec_stream_info_t *si);
128 
129 /*!\brief control function pointer prototype
130  *
131  * This function is used to exchange algorithm specific data with the decoder
132  * instance. This can be used to implement features specific to a particular
133  * algorithm.
134  *
135  * This function is called by the generic aom_codec_control() wrapper
136  * function, so plugins implementing this interface may trust the input
137  * parameters to be properly initialized. However,  this interface does not
138  * provide type safety for the exchanged data or assign meanings to the
139  * control IDs. Those details should be specified in the algorithm's
140  * header file. In particular, the ctrl_id parameter is guaranteed to exist
141  * in the algorithm's control mapping table, and the data parameter may be NULL.
142  *
143  *
144  * \param[in]     ctx              Pointer to this instance's context
145  * \param[in]     ctrl_id          Algorithm specific control identifier
146  * \param[in,out] data             Data to exchange with algorithm instance.
147  *
148  * \retval #AOM_CODEC_OK
149  *     The internal state data was deserialized.
150  */
151 typedef aom_codec_err_t (*aom_codec_control_fn_t)(aom_codec_alg_priv_t *ctx,
152                                                   va_list ap);
153 
154 /*!\brief control function pointer mapping
155  *
156  * This structure stores the mapping between control identifiers and
157  * implementing functions. Each algorithm provides a list of these
158  * mappings. This list is searched by the aom_codec_control() wrapper
159  * function to determine which function to invoke. The special
160  * value {0, NULL} is used to indicate end-of-list, and must be
161  * present. The special value {0, <non-null>} can be used as a catch-all
162  * mapping. This implies that ctrl_id values chosen by the algorithm
163  * \ref MUST be non-zero.
164  */
165 typedef const struct aom_codec_ctrl_fn_map {
166   int ctrl_id;
167   aom_codec_control_fn_t fn;
168 } aom_codec_ctrl_fn_map_t;
169 
170 /*!\brief decode data function pointer prototype
171  *
172  * Processes a buffer of coded data. This function is called by the generic
173  * aom_codec_decode() wrapper function, so plugins implementing this interface
174  * may trust the input parameters to be properly initialized.
175  *
176  * \param[in] ctx          Pointer to this instance's context
177  * \param[in] data         Pointer to this block of new coded data.
178  * \param[in] data_sz      Size of the coded data, in bytes.
179  *
180  * \return Returns #AOM_CODEC_OK if the coded data was processed completely
181  *         and future pictures can be decoded without error. Otherwise,
182  *         see the descriptions of the other error codes in ::aom_codec_err_t
183  *         for recoverability capabilities.
184  */
185 typedef aom_codec_err_t (*aom_codec_decode_fn_t)(aom_codec_alg_priv_t *ctx,
186                                                  const uint8_t *data,
187                                                  size_t data_sz,
188                                                  void *user_priv);
189 
190 /*!\brief Decoded frames iterator
191  *
192  * Iterates over a list of the frames available for display. The iterator
193  * storage should be initialized to NULL to start the iteration. Iteration is
194  * complete when this function returns NULL.
195  *
196  * The list of available frames becomes valid upon completion of the
197  * aom_codec_decode call, and remains valid until the next call to
198  * aom_codec_decode.
199  *
200  * \param[in]     ctx      Pointer to this instance's context
201  * \param[in out] iter     Iterator storage, initialized to NULL
202  *
203  * \return Returns a pointer to an image, if one is ready for display. Frames
204  *         produced will always be in PTS (presentation time stamp) order.
205  */
206 typedef aom_image_t *(*aom_codec_get_frame_fn_t)(aom_codec_alg_priv_t *ctx,
207                                                  aom_codec_iter_t *iter);
208 
209 /*!\brief Pass in external frame buffers for the decoder to use.
210  *
211  * Registers functions to be called when libaom needs a frame buffer
212  * to decode the current frame and a function to be called when libaom does
213  * not internally reference the frame buffer. This set function must
214  * be called before the first call to decode or libaom will assume the
215  * default behavior of allocating frame buffers internally.
216  *
217  * \param[in] ctx          Pointer to this instance's context
218  * \param[in] cb_get       Pointer to the get callback function
219  * \param[in] cb_release   Pointer to the release callback function
220  * \param[in] cb_priv      Callback's private data
221  *
222  * \retval #AOM_CODEC_OK
223  *     External frame buffers will be used by libaom.
224  * \retval #AOM_CODEC_INVALID_PARAM
225  *     One or more of the callbacks were NULL.
226  * \retval #AOM_CODEC_ERROR
227  *     Decoder context not initialized, or algorithm not capable of
228  *     using external frame buffers.
229  *
230  * \note
231  * When decoding AV1, the application may be required to pass in at least
232  * #AOM_MAXIMUM_WORK_BUFFERS external frame
233  * buffers.
234  */
235 typedef aom_codec_err_t (*aom_codec_set_fb_fn_t)(
236     aom_codec_alg_priv_t *ctx, aom_get_frame_buffer_cb_fn_t cb_get,
237     aom_release_frame_buffer_cb_fn_t cb_release, void *cb_priv);
238 
239 typedef aom_codec_err_t (*aom_codec_encode_fn_t)(aom_codec_alg_priv_t *ctx,
240                                                  const aom_image_t *img,
241                                                  aom_codec_pts_t pts,
242                                                  unsigned long duration,
243                                                  aom_enc_frame_flags_t flags);
244 typedef const aom_codec_cx_pkt_t *(*aom_codec_get_cx_data_fn_t)(
245     aom_codec_alg_priv_t *ctx, aom_codec_iter_t *iter);
246 
247 typedef aom_codec_err_t (*aom_codec_enc_config_set_fn_t)(
248     aom_codec_alg_priv_t *ctx, const aom_codec_enc_cfg_t *cfg);
249 typedef aom_fixed_buf_t *(*aom_codec_get_global_headers_fn_t)(
250     aom_codec_alg_priv_t *ctx);
251 
252 typedef aom_image_t *(*aom_codec_get_preview_frame_fn_t)(
253     aom_codec_alg_priv_t *ctx);
254 
255 /*!\brief Decoder algorithm interface interface
256  *
257  * All decoders \ref MUST expose a variable of this type.
258  */
259 struct aom_codec_iface {
260   const char *name;                   /**< Identification String  */
261   int abi_version;                    /**< Implemented ABI version */
262   aom_codec_caps_t caps;              /**< Decoder capabilities */
263   aom_codec_init_fn_t init;           /**< \copydoc ::aom_codec_init_fn_t */
264   aom_codec_destroy_fn_t destroy;     /**< \copydoc ::aom_codec_destroy_fn_t */
265   aom_codec_ctrl_fn_map_t *ctrl_maps; /**< \copydoc ::aom_codec_ctrl_fn_map_t */
266   struct aom_codec_dec_iface {
267     aom_codec_peek_si_fn_t peek_si; /**< \copydoc ::aom_codec_peek_si_fn_t */
268     aom_codec_get_si_fn_t get_si;   /**< \copydoc ::aom_codec_get_si_fn_t */
269     aom_codec_decode_fn_t decode;   /**< \copydoc ::aom_codec_decode_fn_t */
270     aom_codec_get_frame_fn_t
271         get_frame;                   /**< \copydoc ::aom_codec_get_frame_fn_t */
272     aom_codec_set_fb_fn_t set_fb_fn; /**< \copydoc ::aom_codec_set_fb_fn_t */
273   } dec;
274   struct aom_codec_enc_iface {
275     int cfg_count;
276     const aom_codec_enc_cfg_t *cfgs; /**< \copydoc ::aom_codec_enc_cfg_t */
277     aom_codec_encode_fn_t encode;    /**< \copydoc ::aom_codec_encode_fn_t */
278     aom_codec_get_cx_data_fn_t
279         get_cx_data; /**< \copydoc ::aom_codec_get_cx_data_fn_t */
280     aom_codec_enc_config_set_fn_t
281         cfg_set; /**< \copydoc ::aom_codec_enc_config_set_fn_t */
282     aom_codec_get_global_headers_fn_t
283         get_glob_hdrs; /**< \copydoc ::aom_codec_get_global_headers_fn_t */
284     aom_codec_get_preview_frame_fn_t
285         get_preview; /**< \copydoc ::aom_codec_get_preview_frame_fn_t */
286   } enc;
287 };
288 
289 /*!\brief Instance private storage
290  *
291  * This structure is allocated by the algorithm's init function. It can be
292  * extended in one of two ways. First, a second, algorithm specific structure
293  * can be allocated and the priv member pointed to it. Alternatively, this
294  * structure can be made the first member of the algorithm specific structure,
295  * and the pointer cast to the proper type.
296  */
297 struct aom_codec_priv {
298   const char *err_detail;
299   aom_codec_flags_t init_flags;
300   struct {
301     aom_fixed_buf_t cx_data_dst_buf;
302     unsigned int cx_data_pad_before;
303     unsigned int cx_data_pad_after;
304     aom_codec_cx_pkt_t cx_data_pkt;
305   } enc;
306 };
307 
308 #define CAST(id, arg) va_arg((arg), aom_codec_control_type_##id)
309 
310 /* CODEC_INTERFACE convenience macro
311  *
312  * By convention, each codec interface is a struct with extern linkage, where
313  * the symbol is suffixed with _algo. A getter function is also defined to
314  * return a pointer to the struct, since in some cases it's easier to work
315  * with text symbols than data symbols (see issue #169). This function has
316  * the same name as the struct, less the _algo suffix. The CODEC_INTERFACE
317  * macro is provided to define this getter function automatically.
318  */
319 #define CODEC_INTERFACE(id)                          \
320   aom_codec_iface_t *id(void) { return &id##_algo; } \
321   aom_codec_iface_t id##_algo
322 
323 /* Internal Utility Functions
324  *
325  * The following functions are intended to be used inside algorithms as
326  * utilities for manipulating aom_codec_* data structures.
327  */
328 struct aom_codec_pkt_list {
329   unsigned int cnt;
330   unsigned int max;
331   struct aom_codec_cx_pkt pkts[1];
332 };
333 
334 #define aom_codec_pkt_list_decl(n)     \
335   union {                              \
336     struct aom_codec_pkt_list head;    \
337     struct {                           \
338       struct aom_codec_pkt_list head;  \
339       struct aom_codec_cx_pkt pkts[n]; \
340     } alloc;                           \
341   }
342 
343 #define aom_codec_pkt_list_init(m) \
344   (m)->alloc.head.cnt = 0,         \
345   (m)->alloc.head.max = sizeof((m)->alloc.pkts) / sizeof((m)->alloc.pkts[0])
346 
347 int aom_codec_pkt_list_add(struct aom_codec_pkt_list *,
348                            const struct aom_codec_cx_pkt *);
349 
350 const aom_codec_cx_pkt_t *aom_codec_pkt_list_get(
351     struct aom_codec_pkt_list *list, aom_codec_iter_t *iter);
352 
353 #include <stdio.h>
354 #include <setjmp.h>
355 
356 struct aom_internal_error_info {
357   aom_codec_err_t error_code;
358   int has_detail;
359   char detail[80];
360   int setjmp;  // Boolean: whether 'jmp' is valid.
361   jmp_buf jmp;
362 };
363 
364 #define CLANG_ANALYZER_NORETURN
365 #if defined(__has_feature)
366 #if __has_feature(attribute_analyzer_noreturn)
367 #undef CLANG_ANALYZER_NORETURN
368 #define CLANG_ANALYZER_NORETURN __attribute__((analyzer_noreturn))
369 #endif
370 #endif
371 
372 void aom_internal_error(struct aom_internal_error_info *info,
373                         aom_codec_err_t error, const char *fmt,
374                         ...) CLANG_ANALYZER_NORETURN;
375 
376 void aom_merge_corrupted_flag(int *corrupted, int value);
377 #ifdef __cplusplus
378 }  // extern "C"
379 #endif
380 
381 #endif  // AOM_AOM_INTERNAL_AOM_CODEC_INTERNAL_H_
382