blob: 63e3586243a0b3038ca7c849e8b4875a77535ac5 [file] [log] [blame]
Andrew Top61a84952019-04-30 15:07:33 -07001/*
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/*!\defgroup codec Common Algorithm Interface
13 * This abstraction allows applications to easily support multiple video
14 * formats with minimal code duplication. This section describes the interface
15 * common to all codecs (both encoders and decoders).
16 * @{
17 */
18
19/*!\file
20 * \brief Describes the codec algorithm interface to applications.
21 *
22 * This file describes the interface between an application and a
23 * video codec algorithm.
24 *
25 * An application instantiates a specific codec instance by using
26 * aom_codec_init() and a pointer to the algorithm's interface structure:
27 * <pre>
28 * my_app.c:
29 * extern aom_codec_iface_t my_codec;
30 * {
31 * aom_codec_ctx_t algo;
32 * res = aom_codec_init(&algo, &my_codec);
33 * }
34 * </pre>
35 *
36 * Once initialized, the instance is manged using other functions from
37 * the aom_codec_* family.
38 */
39#ifndef AOM_AOM_CODEC_H_
40#define AOM_AOM_CODEC_H_
41
42#ifdef __cplusplus
43extern "C" {
44#endif
45
46#include "aom/aom_image.h"
47#include "aom/aom_integer.h"
48
49/*!\brief Decorator indicating a function is deprecated */
50#ifndef AOM_DEPRECATED
51#if defined(__GNUC__) && __GNUC__
52#define AOM_DEPRECATED __attribute__((deprecated))
53#elif defined(_MSC_VER)
54#define AOM_DEPRECATED
55#else
56#define AOM_DEPRECATED
57#endif
58#endif /* AOM_DEPRECATED */
59
60#ifndef AOM_DECLSPEC_DEPRECATED
61#if defined(__GNUC__) && __GNUC__
62#define AOM_DECLSPEC_DEPRECATED /**< \copydoc #AOM_DEPRECATED */
63#elif defined(_MSC_VER)
64/*!\brief \copydoc #AOM_DEPRECATED */
65#define AOM_DECLSPEC_DEPRECATED __declspec(deprecated)
66#else
67#define AOM_DECLSPEC_DEPRECATED /**< \copydoc #AOM_DEPRECATED */
68#endif
69#endif /* AOM_DECLSPEC_DEPRECATED */
70
71/*!\brief Decorator indicating a function is potentially unused */
72#ifdef AOM_UNUSED
73#elif defined(__GNUC__) || defined(__clang__)
74#define AOM_UNUSED __attribute__((unused))
75#else
76#define AOM_UNUSED
77#endif
78
79/*!\brief Decorator indicating that given struct/union/enum is packed */
80#ifndef ATTRIBUTE_PACKED
81#if defined(__GNUC__) && __GNUC__
82#define ATTRIBUTE_PACKED __attribute__((packed))
83#elif defined(_MSC_VER)
84#define ATTRIBUTE_PACKED
85#else
86#define ATTRIBUTE_PACKED
87#endif
88#endif /* ATTRIBUTE_PACKED */
89
90/*!\brief Current ABI version number
91 *
92 * \internal
93 * If this file is altered in any way that changes the ABI, this value
94 * must be bumped. Examples include, but are not limited to, changing
95 * types, removing or reassigning enums, adding/removing/rearranging
96 * fields to structures
97 */
98#define AOM_CODEC_ABI_VERSION (3 + AOM_IMAGE_ABI_VERSION) /**<\hideinitializer*/
99
100/*!\brief Algorithm return codes */
101typedef enum {
102 /*!\brief Operation completed without error */
103 AOM_CODEC_OK,
104
105 /*!\brief Unspecified error */
106 AOM_CODEC_ERROR,
107
108 /*!\brief Memory operation failed */
109 AOM_CODEC_MEM_ERROR,
110
111 /*!\brief ABI version mismatch */
112 AOM_CODEC_ABI_MISMATCH,
113
114 /*!\brief Algorithm does not have required capability */
115 AOM_CODEC_INCAPABLE,
116
117 /*!\brief The given bitstream is not supported.
118 *
119 * The bitstream was unable to be parsed at the highest level. The decoder
120 * is unable to proceed. This error \ref SHOULD be treated as fatal to the
121 * stream. */
122 AOM_CODEC_UNSUP_BITSTREAM,
123
124 /*!\brief Encoded bitstream uses an unsupported feature
125 *
126 * The decoder does not implement a feature required by the encoder. This
127 * return code should only be used for features that prevent future
128 * pictures from being properly decoded. This error \ref MAY be treated as
129 * fatal to the stream or \ref MAY be treated as fatal to the current GOP.
130 */
131 AOM_CODEC_UNSUP_FEATURE,
132
133 /*!\brief The coded data for this stream is corrupt or incomplete
134 *
135 * There was a problem decoding the current frame. This return code
136 * should only be used for failures that prevent future pictures from
137 * being properly decoded. This error \ref MAY be treated as fatal to the
138 * stream or \ref MAY be treated as fatal to the current GOP. If decoding
139 * is continued for the current GOP, artifacts may be present.
140 */
141 AOM_CODEC_CORRUPT_FRAME,
142
143 /*!\brief An application-supplied parameter is not valid.
144 *
145 */
146 AOM_CODEC_INVALID_PARAM,
147
148 /*!\brief An iterator reached the end of list.
149 *
150 */
151 AOM_CODEC_LIST_END
152
153} aom_codec_err_t;
154
155/*! \brief Codec capabilities bitfield
156 *
157 * Each codec advertises the capabilities it supports as part of its
158 * ::aom_codec_iface_t interface structure. Capabilities are extra interfaces
159 * or functionality, and are not required to be supported.
160 *
161 * The available flags are specified by AOM_CODEC_CAP_* defines.
162 */
163typedef long aom_codec_caps_t;
164#define AOM_CODEC_CAP_DECODER 0x1 /**< Is a decoder */
165#define AOM_CODEC_CAP_ENCODER 0x2 /**< Is an encoder */
166
167/*! \brief Initialization-time Feature Enabling
168 *
169 * Certain codec features must be known at initialization time, to allow for
170 * proper memory allocation.
171 *
172 * The available flags are specified by AOM_CODEC_USE_* defines.
173 */
174typedef long aom_codec_flags_t;
175
176/*!\brief Codec interface structure.
177 *
178 * Contains function pointers and other data private to the codec
179 * implementation. This structure is opaque to the application.
180 */
181typedef const struct aom_codec_iface aom_codec_iface_t;
182
183/*!\brief Codec private data structure.
184 *
185 * Contains data private to the codec implementation. This structure is opaque
186 * to the application.
187 */
188typedef struct aom_codec_priv aom_codec_priv_t;
189
190/*!\brief Iterator
191 *
192 * Opaque storage used for iterating over lists.
193 */
194typedef const void *aom_codec_iter_t;
195
196/*!\brief Codec context structure
197 *
198 * All codecs \ref MUST support this context structure fully. In general,
199 * this data should be considered private to the codec algorithm, and
200 * not be manipulated or examined by the calling application. Applications
201 * may reference the 'name' member to get a printable description of the
202 * algorithm.
203 */
204typedef struct aom_codec_ctx {
205 const char *name; /**< Printable interface name */
206 aom_codec_iface_t *iface; /**< Interface pointers */
207 aom_codec_err_t err; /**< Last returned error */
208 const char *err_detail; /**< Detailed info, if available */
209 aom_codec_flags_t init_flags; /**< Flags passed at init time */
210 union {
211 /**< Decoder Configuration Pointer */
212 const struct aom_codec_dec_cfg *dec;
213 /**< Encoder Configuration Pointer */
214 const struct aom_codec_enc_cfg *enc;
215 const void *raw;
216 } config; /**< Configuration pointer aliasing union */
217 aom_codec_priv_t *priv; /**< Algorithm private storage */
218} aom_codec_ctx_t;
219
220/*!\brief Bit depth for codec
221 * *
222 * This enumeration determines the bit depth of the codec.
223 */
224typedef enum aom_bit_depth {
225 AOM_BITS_8 = 8, /**< 8 bits */
226 AOM_BITS_10 = 10, /**< 10 bits */
227 AOM_BITS_12 = 12, /**< 12 bits */
228} aom_bit_depth_t;
229
230/*!\brief Superblock size selection.
231 *
232 * Defines the superblock size used for encoding. The superblock size can
233 * either be fixed at 64x64 or 128x128 pixels, or it can be dynamically
234 * selected by the encoder for each frame.
235 */
236typedef enum aom_superblock_size {
237 AOM_SUPERBLOCK_SIZE_64X64, /**< Always use 64x64 superblocks. */
238 AOM_SUPERBLOCK_SIZE_128X128, /**< Always use 128x128 superblocks. */
239 AOM_SUPERBLOCK_SIZE_DYNAMIC /**< Select superblock size dynamically. */
240} aom_superblock_size_t;
241
242/*
243 * Library Version Number Interface
244 *
245 * For example, see the following sample return values:
246 * aom_codec_version() (1<<16 | 2<<8 | 3)
247 * aom_codec_version_str() "v1.2.3-rc1-16-gec6a1ba"
248 * aom_codec_version_extra_str() "rc1-16-gec6a1ba"
249 */
250
251/*!\brief Return the version information (as an integer)
252 *
253 * Returns a packed encoding of the library version number. This will only
254 * include
255 * the major.minor.patch component of the version number. Note that this encoded
256 * value should be accessed through the macros provided, as the encoding may
257 * change
258 * in the future.
259 *
260 */
261int aom_codec_version(void);
262#define AOM_VERSION_MAJOR(v) \
263 ((v >> 16) & 0xff) /**< extract major from packed version */
264#define AOM_VERSION_MINOR(v) \
265 ((v >> 8) & 0xff) /**< extract minor from packed version */
266#define AOM_VERSION_PATCH(v) \
267 ((v >> 0) & 0xff) /**< extract patch from packed version */
268
269/*!\brief Return the version major number */
270#define aom_codec_version_major() ((aom_codec_version() >> 16) & 0xff)
271
272/*!\brief Return the version minor number */
273#define aom_codec_version_minor() ((aom_codec_version() >> 8) & 0xff)
274
275/*!\brief Return the version patch number */
276#define aom_codec_version_patch() ((aom_codec_version() >> 0) & 0xff)
277
278/*!\brief Return the version information (as a string)
279 *
280 * Returns a printable string containing the full library version number. This
281 * may
282 * contain additional text following the three digit version number, as to
283 * indicate
284 * release candidates, prerelease versions, etc.
285 *
286 */
287const char *aom_codec_version_str(void);
288
289/*!\brief Return the version information (as a string)
290 *
291 * Returns a printable "extra string". This is the component of the string
292 * returned
293 * by aom_codec_version_str() following the three digit version number.
294 *
295 */
296const char *aom_codec_version_extra_str(void);
297
298/*!\brief Return the build configuration
299 *
300 * Returns a printable string containing an encoded version of the build
301 * configuration. This may be useful to aom support.
302 *
303 */
304const char *aom_codec_build_config(void);
305
306/*!\brief Return the name for a given interface
307 *
308 * Returns a human readable string for name of the given codec interface.
309 *
310 * \param[in] iface Interface pointer
311 *
312 */
313const char *aom_codec_iface_name(aom_codec_iface_t *iface);
314
315/*!\brief Convert error number to printable string
316 *
317 * Returns a human readable string for the last error returned by the
318 * algorithm. The returned error will be one line and will not contain
319 * any newline characters.
320 *
321 *
322 * \param[in] err Error number.
323 *
324 */
325const char *aom_codec_err_to_string(aom_codec_err_t err);
326
327/*!\brief Retrieve error synopsis for codec context
328 *
329 * Returns a human readable string for the last error returned by the
330 * algorithm. The returned error will be one line and will not contain
331 * any newline characters.
332 *
333 *
334 * \param[in] ctx Pointer to this instance's context.
335 *
336 */
337const char *aom_codec_error(aom_codec_ctx_t *ctx);
338
339/*!\brief Retrieve detailed error information for codec context
340 *
341 * Returns a human readable string providing detailed information about
342 * the last error.
343 *
344 * \param[in] ctx Pointer to this instance's context.
345 *
346 * \retval NULL
347 * No detailed information is available.
348 */
349const char *aom_codec_error_detail(aom_codec_ctx_t *ctx);
350
351/* REQUIRED FUNCTIONS
352 *
353 * The following functions are required to be implemented for all codecs.
354 * They represent the base case functionality expected of all codecs.
355 */
356
357/*!\brief Destroy a codec instance
358 *
359 * Destroys a codec context, freeing any associated memory buffers.
360 *
361 * \param[in] ctx Pointer to this instance's context
362 *
363 * \retval #AOM_CODEC_OK
364 * The codec algorithm initialized.
365 * \retval #AOM_CODEC_MEM_ERROR
366 * Memory allocation failed.
367 */
368aom_codec_err_t aom_codec_destroy(aom_codec_ctx_t *ctx);
369
370/*!\brief Get the capabilities of an algorithm.
371 *
372 * Retrieves the capabilities bitfield from the algorithm's interface.
373 *
374 * \param[in] iface Pointer to the algorithm interface
375 *
376 */
377aom_codec_caps_t aom_codec_get_caps(aom_codec_iface_t *iface);
378
379/*!\brief Control algorithm
380 *
381 * This function is used to exchange algorithm specific data with the codec
382 * instance. This can be used to implement features specific to a particular
383 * algorithm.
384 *
385 * This wrapper function dispatches the request to the helper function
386 * associated with the given ctrl_id. It tries to call this function
387 * transparently, but will return #AOM_CODEC_ERROR if the request could not
388 * be dispatched.
389 *
390 * Note that this function should not be used directly. Call the
391 * #aom_codec_control wrapper macro instead.
392 *
393 * \param[in] ctx Pointer to this instance's context
394 * \param[in] ctrl_id Algorithm specific control identifier
395 *
396 * \retval #AOM_CODEC_OK
397 * The control request was processed.
398 * \retval #AOM_CODEC_ERROR
399 * The control request was not processed.
400 * \retval #AOM_CODEC_INVALID_PARAM
401 * The data was not valid.
402 */
403aom_codec_err_t aom_codec_control_(aom_codec_ctx_t *ctx, int ctrl_id, ...);
404#if defined(AOM_DISABLE_CTRL_TYPECHECKS) && AOM_DISABLE_CTRL_TYPECHECKS
405#define aom_codec_control(ctx, id, data) aom_codec_control_(ctx, id, data)
406#define AOM_CTRL_USE_TYPE(id, typ)
407#define AOM_CTRL_USE_TYPE_DEPRECATED(id, typ)
408#define AOM_CTRL_VOID(id, typ)
409
410#else
411/*!\brief aom_codec_control wrapper macro
412 *
413 * This macro allows for type safe conversions across the variadic parameter
414 * to aom_codec_control_().
415 *
416 * \internal
417 * It works by dispatching the call to the control function through a wrapper
418 * function named with the id parameter.
419 */
420#define aom_codec_control(ctx, id, data) \
421 aom_codec_control_##id(ctx, id, data) /**<\hideinitializer*/
422
423/*!\brief aom_codec_control type definition macro
424 *
425 * This macro allows for type safe conversions across the variadic parameter
426 * to aom_codec_control_(). It defines the type of the argument for a given
427 * control identifier.
428 *
429 * \internal
430 * It defines a static function with
431 * the correctly typed arguments as a wrapper to the type-unsafe internal
432 * function.
433 */
434#define AOM_CTRL_USE_TYPE(id, typ) \
435 static aom_codec_err_t aom_codec_control_##id(aom_codec_ctx_t *, int, typ) \
436 AOM_UNUSED; \
437 \
438 static aom_codec_err_t aom_codec_control_##id(aom_codec_ctx_t *ctx, \
439 int ctrl_id, typ data) { \
440 return aom_codec_control_(ctx, ctrl_id, data); \
441 } /**<\hideinitializer*/
442
443/*!\brief aom_codec_control deprecated type definition macro
444 *
445 * Like #AOM_CTRL_USE_TYPE, but indicates that the specified control is
446 * deprecated and should not be used. Consult the documentation for your
447 * codec for more information.
448 *
449 * \internal
450 * It defines a static function with the correctly typed arguments as a
451 * wrapper to the type-unsafe internal function.
452 */
453#define AOM_CTRL_USE_TYPE_DEPRECATED(id, typ) \
454 AOM_DECLSPEC_DEPRECATED static aom_codec_err_t aom_codec_control_##id( \
455 aom_codec_ctx_t *, int, typ) AOM_DEPRECATED AOM_UNUSED; \
456 \
457 AOM_DECLSPEC_DEPRECATED static aom_codec_err_t aom_codec_control_##id( \
458 aom_codec_ctx_t *ctx, int ctrl_id, typ data) { \
459 return aom_codec_control_(ctx, ctrl_id, data); \
460 } /**<\hideinitializer*/
461
462/*!\brief aom_codec_control void type definition macro
463 *
464 * This macro allows for type safe conversions across the variadic parameter
465 * to aom_codec_control_(). It indicates that a given control identifier takes
466 * no argument.
467 *
468 * \internal
469 * It defines a static function without a data argument as a wrapper to the
470 * type-unsafe internal function.
471 */
472#define AOM_CTRL_VOID(id) \
473 static aom_codec_err_t aom_codec_control_##id(aom_codec_ctx_t *, int) \
474 AOM_UNUSED; \
475 \
476 static aom_codec_err_t aom_codec_control_##id(aom_codec_ctx_t *ctx, \
477 int ctrl_id) { \
478 return aom_codec_control_(ctx, ctrl_id); \
479 } /**<\hideinitializer*/
480
481#endif
482
483/*!\brief OBU types. */
484typedef enum ATTRIBUTE_PACKED {
485 OBU_SEQUENCE_HEADER = 1,
486 OBU_TEMPORAL_DELIMITER = 2,
487 OBU_FRAME_HEADER = 3,
488 OBU_TILE_GROUP = 4,
489 OBU_METADATA = 5,
490 OBU_FRAME = 6,
491 OBU_REDUNDANT_FRAME_HEADER = 7,
492 OBU_TILE_LIST = 8,
493 OBU_PADDING = 15,
494} OBU_TYPE;
495
496/*!\brief OBU metadata types. */
497typedef enum {
498 OBU_METADATA_TYPE_AOM_RESERVED_0 = 0,
499 OBU_METADATA_TYPE_HDR_CLL = 1,
500 OBU_METADATA_TYPE_HDR_MDCV = 2,
501 OBU_METADATA_TYPE_SCALABILITY = 3,
502 OBU_METADATA_TYPE_ITUT_T35 = 4,
503 OBU_METADATA_TYPE_TIMECODE = 5,
504} OBU_METADATA_TYPE;
505
506/*!\brief Returns string representation of OBU_TYPE.
507 *
508 * \param[in] type The OBU_TYPE to convert to string.
509 */
510const char *aom_obu_type_to_string(OBU_TYPE type);
511
512/*!\brief Config Options
513 *
514 * This type allows to enumerate and control options defined for control
515 * via config file at runtime.
516 */
517typedef struct cfg_options {
518 /*!\brief Reflects if ext_partition should be enabled
519 *
520 * If this value is non-zero it enabled the feature
521 */
522 unsigned int ext_partition;
523} cfg_options_t;
524
525/*!@} - end defgroup codec*/
526#ifdef __cplusplus
527}
528#endif
529#endif // AOM_AOM_CODEC_H_