• 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 (5) /**<\hideinitializer*/
63 
64 typedef struct aom_codec_alg_priv aom_codec_alg_priv_t;
65 typedef struct aom_codec_priv_enc_mr_cfg aom_codec_priv_enc_mr_cfg_t;
66 
67 /*!\brief init function pointer prototype
68  *
69  * Performs algorithm-specific initialization of the decoder context. This
70  * function is called by the generic aom_codec_init() wrapper function, so
71  * plugins implementing this interface may trust the input parameters to be
72  * properly initialized.
73  *
74  * \param[in] ctx   Pointer to this instance's context
75  * \retval #AOM_CODEC_OK
76  *     The input stream was recognized and decoder initialized.
77  * \retval #AOM_CODEC_MEM_ERROR
78  *     Memory operation failed.
79  */
80 typedef aom_codec_err_t (*aom_codec_init_fn_t)(
81     aom_codec_ctx_t *ctx, aom_codec_priv_enc_mr_cfg_t *data);
82 
83 /*!\brief destroy function pointer prototype
84  *
85  * Performs algorithm-specific destruction of the decoder context. This
86  * function is called by the generic aom_codec_destroy() wrapper function,
87  * so plugins implementing this interface may trust the input parameters
88  * to be properly initialized.
89  *
90  * \param[in] ctx   Pointer to this instance's context
91  * \retval #AOM_CODEC_OK
92  *     The input stream was recognized and decoder initialized.
93  * \retval #AOM_CODEC_MEM_ERROR
94  *     Memory operation failed.
95  */
96 typedef aom_codec_err_t (*aom_codec_destroy_fn_t)(aom_codec_alg_priv_t *ctx);
97 
98 /*!\brief parse stream info function pointer prototype
99  *
100  * Performs high level parsing of the bitstream. This function is called by the
101  * generic aom_codec_peek_stream_info() wrapper function, so plugins
102  * implementing this interface may trust the input parameters to be properly
103  * initialized.
104  *
105  * \param[in]      data    Pointer to a block of data to parse
106  * \param[in]      data_sz Size of the data buffer
107  * \param[in,out]  si      Pointer to stream info to update. The is_annexb
108  *                         member \ref MUST be properly initialized. This
109  *                         function sets the rest of the members.
110  *
111  * \retval #AOM_CODEC_OK
112  *     Bitstream is parsable and stream information updated
113  */
114 typedef aom_codec_err_t (*aom_codec_peek_si_fn_t)(const uint8_t *data,
115                                                   size_t data_sz,
116                                                   aom_codec_stream_info_t *si);
117 
118 /*!\brief Return information about the current stream.
119  *
120  * Returns information about the stream that has been parsed during decoding.
121  *
122  * \param[in]      ctx     Pointer to this instance's context
123  * \param[in,out]  si      Pointer to stream info to update
124  *
125  * \retval #AOM_CODEC_OK
126  *     Bitstream is parsable and stream information updated
127  */
128 typedef aom_codec_err_t (*aom_codec_get_si_fn_t)(aom_codec_alg_priv_t *ctx,
129                                                  aom_codec_stream_info_t *si);
130 
131 /*!\brief control function pointer prototype
132  *
133  * This function is used to exchange algorithm specific data with the decoder
134  * instance. This can be used to implement features specific to a particular
135  * algorithm.
136  *
137  * This function is called by the generic aom_codec_control() wrapper
138  * function, so plugins implementing this interface may trust the input
139  * parameters to be properly initialized. However,  this interface does not
140  * provide type safety for the exchanged data or assign meanings to the
141  * control codes. Those details should be specified in the algorithm's
142  * header file. In particular, the ctrl_id parameter is guaranteed to exist
143  * in the algorithm's control mapping table, and the data parameter may be NULL.
144  *
145  *
146  * \param[in]     ctx              Pointer to this instance's context
147  * \param[in]     ctrl_id          Algorithm specific control identifier
148  * \param[in,out] data             Data to exchange with algorithm instance.
149  *
150  * \retval #AOM_CODEC_OK
151  *     The internal state data was deserialized.
152  */
153 typedef aom_codec_err_t (*aom_codec_control_fn_t)(aom_codec_alg_priv_t *ctx,
154                                                   va_list ap);
155 
156 /*!\brief control function pointer mapping
157  *
158  * This structure stores the mapping between control identifiers and
159  * implementing functions. Each algorithm provides a list of these
160  * mappings. This list is searched by the aom_codec_control() wrapper
161  * function to determine which function to invoke. The special
162  * value {0, NULL} is used to indicate end-of-list, and must be
163  * present. The special value {0, <non-null>} can be used as a catch-all
164  * mapping. This implies that ctrl_id values chosen by the algorithm
165  * \ref MUST be non-zero.
166  */
167 typedef const struct aom_codec_ctrl_fn_map {
168   int ctrl_id;
169   aom_codec_control_fn_t fn;
170 } aom_codec_ctrl_fn_map_t;
171 
172 /*!\brief decode data function pointer prototype
173  *
174  * Processes a buffer of coded data. If the processing results in a new
175  * decoded frame becoming available, #AOM_CODEC_CB_PUT_SLICE and
176  * #AOM_CODEC_CB_PUT_FRAME events are generated as appropriate. This
177  * function is called by the generic aom_codec_decode() wrapper function,
178  * so plugins implementing this interface may trust the input parameters
179  * to be properly initialized.
180  *
181  * \param[in] ctx          Pointer to this instance's context
182  * \param[in] data         Pointer to this block of new coded data. If
183  *                         NULL, a #AOM_CODEC_CB_PUT_FRAME event is posted
184  *                         for the previously decoded frame.
185  * \param[in] data_sz      Size of the coded data, in bytes.
186  *
187  * \return Returns #AOM_CODEC_OK if the coded data was processed completely
188  *         and future pictures can be decoded without error. Otherwise,
189  *         see the descriptions of the other error codes in ::aom_codec_err_t
190  *         for recoverability capabilities.
191  */
192 typedef aom_codec_err_t (*aom_codec_decode_fn_t)(aom_codec_alg_priv_t *ctx,
193                                                  const uint8_t *data,
194                                                  size_t data_sz,
195                                                  void *user_priv);
196 
197 /*!\brief Decoded frames iterator
198  *
199  * Iterates over a list of the frames available for display. The iterator
200  * storage should be initialized to NULL to start the iteration. Iteration is
201  * complete when this function returns NULL.
202  *
203  * The list of available frames becomes valid upon completion of the
204  * aom_codec_decode call, and remains valid until the next call to
205  * aom_codec_decode.
206  *
207  * \param[in]     ctx      Pointer to this instance's context
208  * \param[in out] iter     Iterator storage, initialized to NULL
209  *
210  * \return Returns a pointer to an image, if one is ready for display. Frames
211  *         produced will always be in PTS (presentation time stamp) order.
212  */
213 typedef aom_image_t *(*aom_codec_get_frame_fn_t)(aom_codec_alg_priv_t *ctx,
214                                                  aom_codec_iter_t *iter);
215 
216 /*!\brief Pass in external frame buffers for the decoder to use.
217  *
218  * Registers functions to be called when libaom needs a frame buffer
219  * to decode the current frame and a function to be called when libaom does
220  * not internally reference the frame buffer. This set function must
221  * be called before the first call to decode or libaom will assume the
222  * default behavior of allocating frame buffers internally.
223  *
224  * \param[in] ctx          Pointer to this instance's context
225  * \param[in] cb_get       Pointer to the get callback function
226  * \param[in] cb_release   Pointer to the release callback function
227  * \param[in] cb_priv      Callback's private data
228  *
229  * \retval #AOM_CODEC_OK
230  *     External frame buffers will be used by libaom.
231  * \retval #AOM_CODEC_INVALID_PARAM
232  *     One or more of the callbacks were NULL.
233  * \retval #AOM_CODEC_ERROR
234  *     Decoder context not initialized, or algorithm not capable of
235  *     using external frame buffers.
236  *
237  * \note
238  * When decoding AV1, the application may be required to pass in at least
239  * #AOM_MAXIMUM_WORK_BUFFERS external frame
240  * buffers.
241  */
242 typedef aom_codec_err_t (*aom_codec_set_fb_fn_t)(
243     aom_codec_alg_priv_t *ctx, aom_get_frame_buffer_cb_fn_t cb_get,
244     aom_release_frame_buffer_cb_fn_t cb_release, void *cb_priv);
245 
246 typedef aom_codec_err_t (*aom_codec_encode_fn_t)(aom_codec_alg_priv_t *ctx,
247                                                  const aom_image_t *img,
248                                                  aom_codec_pts_t pts,
249                                                  unsigned long duration,
250                                                  aom_enc_frame_flags_t flags);
251 typedef const aom_codec_cx_pkt_t *(*aom_codec_get_cx_data_fn_t)(
252     aom_codec_alg_priv_t *ctx, aom_codec_iter_t *iter);
253 
254 typedef aom_codec_err_t (*aom_codec_enc_config_set_fn_t)(
255     aom_codec_alg_priv_t *ctx, const aom_codec_enc_cfg_t *cfg);
256 typedef aom_fixed_buf_t *(*aom_codec_get_global_headers_fn_t)(
257     aom_codec_alg_priv_t *ctx);
258 
259 typedef aom_image_t *(*aom_codec_get_preview_frame_fn_t)(
260     aom_codec_alg_priv_t *ctx);
261 
262 typedef aom_codec_err_t (*aom_codec_enc_mr_get_mem_loc_fn_t)(
263     const aom_codec_enc_cfg_t *cfg, void **mem_loc);
264 
265 /*!\brief usage configuration mapping
266  *
267  * This structure stores the mapping between usage identifiers and
268  * configuration structures. Each algorithm provides a list of these
269  * mappings. This list is searched by the aom_codec_enc_config_default()
270  * wrapper function to determine which config to return. The special value
271  * {-1, {0}} is used to indicate end-of-list, and must be present. At least
272  * one mapping must be present, in addition to the end-of-list.
273  *
274  */
275 typedef const struct aom_codec_enc_cfg_map {
276   int usage;
277   aom_codec_enc_cfg_t cfg;
278 } aom_codec_enc_cfg_map_t;
279 
280 /*!\brief Decoder algorithm interface interface
281  *
282  * All decoders \ref MUST expose a variable of this type.
283  */
284 struct aom_codec_iface {
285   const char *name;                   /**< Identification String  */
286   int abi_version;                    /**< Implemented ABI version */
287   aom_codec_caps_t caps;              /**< Decoder capabilities */
288   aom_codec_init_fn_t init;           /**< \copydoc ::aom_codec_init_fn_t */
289   aom_codec_destroy_fn_t destroy;     /**< \copydoc ::aom_codec_destroy_fn_t */
290   aom_codec_ctrl_fn_map_t *ctrl_maps; /**< \copydoc ::aom_codec_ctrl_fn_map_t */
291   struct aom_codec_dec_iface {
292     aom_codec_peek_si_fn_t peek_si; /**< \copydoc ::aom_codec_peek_si_fn_t */
293     aom_codec_get_si_fn_t get_si;   /**< \copydoc ::aom_codec_get_si_fn_t */
294     aom_codec_decode_fn_t decode;   /**< \copydoc ::aom_codec_decode_fn_t */
295     aom_codec_get_frame_fn_t
296         get_frame;                   /**< \copydoc ::aom_codec_get_frame_fn_t */
297     aom_codec_set_fb_fn_t set_fb_fn; /**< \copydoc ::aom_codec_set_fb_fn_t */
298   } dec;
299   struct aom_codec_enc_iface {
300     int cfg_map_count;
301     aom_codec_enc_cfg_map_t
302         *cfg_maps;                /**< \copydoc ::aom_codec_enc_cfg_map_t */
303     aom_codec_encode_fn_t encode; /**< \copydoc ::aom_codec_encode_fn_t */
304     aom_codec_get_cx_data_fn_t
305         get_cx_data; /**< \copydoc ::aom_codec_get_cx_data_fn_t */
306     aom_codec_enc_config_set_fn_t
307         cfg_set; /**< \copydoc ::aom_codec_enc_config_set_fn_t */
308     aom_codec_get_global_headers_fn_t
309         get_glob_hdrs; /**< \copydoc ::aom_codec_get_global_headers_fn_t */
310     aom_codec_get_preview_frame_fn_t
311         get_preview; /**< \copydoc ::aom_codec_get_preview_frame_fn_t */
312     aom_codec_enc_mr_get_mem_loc_fn_t
313         mr_get_mem_loc; /**< \copydoc ::aom_codec_enc_mr_get_mem_loc_fn_t */
314   } enc;
315 };
316 
317 /*!\brief Callback function pointer / user data pair storage */
318 typedef struct aom_codec_priv_cb_pair {
319   union {
320     aom_codec_put_frame_cb_fn_t put_frame;
321     aom_codec_put_slice_cb_fn_t put_slice;
322   } u;
323   void *user_priv;
324 } aom_codec_priv_cb_pair_t;
325 
326 /*!\brief Instance private storage
327  *
328  * This structure is allocated by the algorithm's init function. It can be
329  * extended in one of two ways. First, a second, algorithm specific structure
330  * can be allocated and the priv member pointed to it. Alternatively, this
331  * structure can be made the first member of the algorithm specific structure,
332  * and the pointer cast to the proper type.
333  */
334 struct aom_codec_priv {
335   const char *err_detail;
336   aom_codec_flags_t init_flags;
337   struct {
338     aom_codec_priv_cb_pair_t put_frame_cb;
339     aom_codec_priv_cb_pair_t put_slice_cb;
340   } dec;
341   struct {
342     aom_fixed_buf_t cx_data_dst_buf;
343     unsigned int cx_data_pad_before;
344     unsigned int cx_data_pad_after;
345     aom_codec_cx_pkt_t cx_data_pkt;
346     unsigned int total_encoders;
347   } enc;
348 };
349 
350 /*
351  * Multi-resolution encoding internal configuration
352  */
353 struct aom_codec_priv_enc_mr_cfg {
354   unsigned int mr_total_resolutions;
355   unsigned int mr_encoder_id;
356   struct aom_rational mr_down_sampling_factor;
357   void *mr_low_res_mode_info;
358 };
359 
360 #undef AOM_CTRL_USE_TYPE
361 #define AOM_CTRL_USE_TYPE(id, typ) \
362   static AOM_INLINE typ id##__value(va_list args) { return va_arg(args, typ); }
363 
364 #undef AOM_CTRL_USE_TYPE_DEPRECATED
365 #define AOM_CTRL_USE_TYPE_DEPRECATED(id, typ) \
366   static AOM_INLINE typ id##__value(va_list args) { return va_arg(args, typ); }
367 
368 #define CAST(id, arg) id##__value(arg)
369 
370 /* CODEC_INTERFACE convenience macro
371  *
372  * By convention, each codec interface is a struct with extern linkage, where
373  * the symbol is suffixed with _algo. A getter function is also defined to
374  * return a pointer to the struct, since in some cases it's easier to work
375  * with text symbols than data symbols (see issue #169). This function has
376  * the same name as the struct, less the _algo suffix. The CODEC_INTERFACE
377  * macro is provided to define this getter function automatically.
378  */
379 #define CODEC_INTERFACE(id)                          \
380   aom_codec_iface_t *id(void) { return &id##_algo; } \
381   aom_codec_iface_t id##_algo
382 
383 /* Internal Utility Functions
384  *
385  * The following functions are intended to be used inside algorithms as
386  * utilities for manipulating aom_codec_* data structures.
387  */
388 struct aom_codec_pkt_list {
389   unsigned int cnt;
390   unsigned int max;
391   struct aom_codec_cx_pkt pkts[1];
392 };
393 
394 #define aom_codec_pkt_list_decl(n)     \
395   union {                              \
396     struct aom_codec_pkt_list head;    \
397     struct {                           \
398       struct aom_codec_pkt_list head;  \
399       struct aom_codec_cx_pkt pkts[n]; \
400     } alloc;                           \
401   }
402 
403 #define aom_codec_pkt_list_init(m) \
404   (m)->alloc.head.cnt = 0,         \
405   (m)->alloc.head.max = sizeof((m)->alloc.pkts) / sizeof((m)->alloc.pkts[0])
406 
407 int aom_codec_pkt_list_add(struct aom_codec_pkt_list *,
408                            const struct aom_codec_cx_pkt *);
409 
410 const aom_codec_cx_pkt_t *aom_codec_pkt_list_get(
411     struct aom_codec_pkt_list *list, aom_codec_iter_t *iter);
412 
413 #include <stdio.h>
414 #include <setjmp.h>
415 
416 struct aom_internal_error_info {
417   aom_codec_err_t error_code;
418   int has_detail;
419   char detail[80];
420   int setjmp;  // Boolean: whether 'jmp' is valid.
421   jmp_buf jmp;
422 };
423 
424 #define CLANG_ANALYZER_NORETURN
425 #if defined(__has_feature)
426 #if __has_feature(attribute_analyzer_noreturn)
427 #undef CLANG_ANALYZER_NORETURN
428 #define CLANG_ANALYZER_NORETURN __attribute__((analyzer_noreturn))
429 #endif
430 #endif
431 
432 void aom_internal_error(struct aom_internal_error_info *info,
433                         aom_codec_err_t error, const char *fmt,
434                         ...) CLANG_ANALYZER_NORETURN;
435 
436 void aom_merge_corrupted_flag(int *corrupted, int value);
437 #ifdef __cplusplus
438 }  // extern "C"
439 #endif
440 
441 #endif  // AOM_AOM_INTERNAL_AOM_CODEC_INTERNAL_H_
442