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