blob: 66b3cb6b1bc96d1d2188037119ca821ecbe10abc [file] [log] [blame]
John Koleszar0ea50ce2010-05-18 11:58:33 -04001/*
Lester Lu6bc30d62021-12-16 19:13:21 +00002 * Copyright (c) 2021, Alliance for Open Media. All rights reserved
John Koleszar0ea50ce2010-05-18 11:58:33 -04003 *
Lester Lu6bc30d62021-12-16 19:13:21 +00004 * This source code is subject to the terms of the BSD 3-Clause Clear License
5 * and the Alliance for Open Media Patent License 1.0. If the BSD 3-Clause Clear
6 * License was not distributed with this source code in the LICENSE file, you
7 * can obtain it at aomedia.org/license/software-license/bsd-3-c-c/. If the
8 * Alliance for Open Media Patent License 1.0 was not distributed with this
9 * source code in the PATENTS file, you can obtain it at
10 * aomedia.org/license/patent-license/.
John Koleszar0ea50ce2010-05-18 11:58:33 -040011 */
12
Elliott Karpilovskycbe219b2020-04-22 16:21:06 -070013///////////////////////////////////////////////////////////////////////////////
14// Internal implementation details
15///////////////////////////////////////////////////////////////////////////////
16//
17// There are two levels of interfaces used to access the AOM codec: the
18// the aom_codec_iface and the aom_codec_ctx.
19//
20// 1. aom_codec_iface_t
21// (Related files: aom/aom_codec.h, aom/src/aom_codec.c,
22// aom/internal/aom_codec_internal.h, av1/av1_cx_iface.c,
23// av1/av1_dx_iface.c)
24//
25// Used to initialize the codec context, which contains the configuration for
26// for modifying the encoder/decoder during run-time. See the other
27// documentation in this header file for more details. For the most part,
28// users will call helper functions, such as aom_codec_iface_name,
29// aom_codec_get_caps, etc., to interact with it.
30//
31// The main purpose of the aom_codec_iface_t is to provide a way to generate
32// a default codec config, find out what capabilities the implementation has,
33// and create an aom_codec_ctx_t (which is actually used to interact with the
34// codec).
35//
36// Note that the implementations for the AV1 algorithm are located in
37// av1/av1_cx_iface.c and av1/av1_dx_iface.c
38//
39//
40// 2. aom_codec_ctx_t
41// (Related files: aom/aom_codec.h, av1/av1_cx_iface.c, av1/av1_dx_iface.c,
42// aom/aomcx.h, aom/aomdx.h, aom/src/aom_encoder.c, aom/src/aom_decoder.c)
43//
44// The actual interface between user code and the codec. It stores the name
45// of the codec, a pointer back to the aom_codec_iface_t that initialized it,
46// initialization flags, a config for either encoder or the decoder, and a
47// pointer to internal data.
48//
49// The codec is configured / queried through calls to aom_codec_control,
Elliott Karpilovsky60dd0f92020-04-30 19:19:27 -070050// which takes a control ID (listed in aomcx.h and aomdx.h) and a parameter.
51// In the case of "getter" control IDs, the parameter is modified to have
52// the requested value; in the case of "setter" control IDs, the codec's
Elliott Karpilovskycbe219b2020-04-22 16:21:06 -070053// configuration is changed based on the parameter. Note that a aom_codec_err_t
54// is returned, which indicates if the operation was successful or not.
55//
56// Note that for the encoder, the aom_codec_alg_priv_t points to the
57// the aom_codec_alg_priv structure in av1/av1_cx_iface.c, and for the decoder,
58// the struct in av1/av1_dx_iface.c. Variables such as AV1_COMP cpi are stored
59// here and also used in the core algorithm.
60//
61// At the end, aom_codec_destroy should be called for each initialized
62// aom_codec_ctx_t.
63
John Koleszar0ea50ce2010-05-18 11:58:33 -040064/*!\defgroup codec Common Algorithm Interface
65 * This abstraction allows applications to easily support multiple video
66 * formats with minimal code duplication. This section describes the interface
67 * common to all codecs (both encoders and decoders).
68 * @{
69 */
70
James Zernf42d52e2011-02-16 17:54:49 -080071/*!\file
John Koleszar0ea50ce2010-05-18 11:58:33 -040072 * \brief Describes the codec algorithm interface to applications.
73 *
74 * This file describes the interface between an application and a
75 * video codec algorithm.
76 *
77 * An application instantiates a specific codec instance by using
Wan-Teh Changb1b8c682020-04-24 09:30:52 -070078 * aom_codec_dec_init() or aom_codec_enc_init() and a pointer to the
79 * algorithm's interface structure:
John Koleszar0ea50ce2010-05-18 11:58:33 -040080 * <pre>
81 * my_app.c:
Yaowu Xuf883b422016-08-30 14:01:10 -070082 * extern aom_codec_iface_t my_codec;
John Koleszar0ea50ce2010-05-18 11:58:33 -040083 * {
Yaowu Xuf883b422016-08-30 14:01:10 -070084 * aom_codec_ctx_t algo;
Wan-Teh Changb1b8c682020-04-24 09:30:52 -070085 * int threads = 4;
86 * aom_codec_dec_cfg_t cfg = { threads, 0, 0, 1 };
87 * res = aom_codec_dec_init(&algo, &my_codec, &cfg, 0);
John Koleszar0ea50ce2010-05-18 11:58:33 -040088 * }
89 * </pre>
90 *
elliottkd43b65b2018-09-03 16:50:42 -070091 * Once initialized, the instance is managed using other functions from
Yaowu Xuf883b422016-08-30 14:01:10 -070092 * the aom_codec_* family.
John Koleszar0ea50ce2010-05-18 11:58:33 -040093 */
James Zerne1cbb132018-08-22 14:10:36 -070094#ifndef AOM_AOM_AOM_CODEC_H_
95#define AOM_AOM_AOM_CODEC_H_
Adrian Grangef58eca92013-10-24 15:11:36 -070096
John Koleszar0ea50ce2010-05-18 11:58:33 -040097#ifdef __cplusplus
98extern "C" {
99#endif
100
Tom Finegandd3e2a52018-05-23 14:33:09 -0700101#include "aom/aom_image.h"
102#include "aom/aom_integer.h"
John Koleszar0ea50ce2010-05-18 11:58:33 -0400103
clang-format83a52072016-08-08 20:22:13 -0700104/*!\brief Decorator indicating a function is deprecated */
James Zernef9ff452017-10-05 22:42:45 -0700105#ifndef AOM_DEPRECATED
John Koleszar0ea50ce2010-05-18 11:58:33 -0400106#if defined(__GNUC__) && __GNUC__
James Zernef9ff452017-10-05 22:42:45 -0700107#define AOM_DEPRECATED __attribute__((deprecated))
John Koleszar0ea50ce2010-05-18 11:58:33 -0400108#elif defined(_MSC_VER)
James Zernef9ff452017-10-05 22:42:45 -0700109#define AOM_DEPRECATED
John Koleszar0ea50ce2010-05-18 11:58:33 -0400110#else
James Zernef9ff452017-10-05 22:42:45 -0700111#define AOM_DEPRECATED
James Zernd034bfa2012-11-27 14:03:36 -0800112#endif
James Zernef9ff452017-10-05 22:42:45 -0700113#endif /* AOM_DEPRECATED */
James Zernd034bfa2012-11-27 14:03:36 -0800114
James Zernef9ff452017-10-05 22:42:45 -0700115#ifndef AOM_DECLSPEC_DEPRECATED
James Zernd034bfa2012-11-27 14:03:36 -0800116#if defined(__GNUC__) && __GNUC__
James Zernef9ff452017-10-05 22:42:45 -0700117#define AOM_DECLSPEC_DEPRECATED /**< \copydoc #AOM_DEPRECATED */
James Zernd034bfa2012-11-27 14:03:36 -0800118#elif defined(_MSC_VER)
James Zernef9ff452017-10-05 22:42:45 -0700119/*!\brief \copydoc #AOM_DEPRECATED */
120#define AOM_DECLSPEC_DEPRECATED __declspec(deprecated)
James Zernd034bfa2012-11-27 14:03:36 -0800121#else
James Zernef9ff452017-10-05 22:42:45 -0700122#define AOM_DECLSPEC_DEPRECATED /**< \copydoc #AOM_DEPRECATED */
John Koleszar0ea50ce2010-05-18 11:58:33 -0400123#endif
James Zernef9ff452017-10-05 22:42:45 -0700124#endif /* AOM_DECLSPEC_DEPRECATED */
John Koleszar0ea50ce2010-05-18 11:58:33 -0400125
clang-format83a52072016-08-08 20:22:13 -0700126/*!\brief Decorator indicating a function is potentially unused */
James Zernef9ff452017-10-05 22:42:45 -0700127#ifdef AOM_UNUSED
Nico Weber8a64f512015-08-07 13:56:47 -0700128#elif defined(__GNUC__) || defined(__clang__)
James Zernef9ff452017-10-05 22:42:45 -0700129#define AOM_UNUSED __attribute__((unused))
John Koleszar0ea50ce2010-05-18 11:58:33 -0400130#else
James Zernef9ff452017-10-05 22:42:45 -0700131#define AOM_UNUSED
John Koleszar0ea50ce2010-05-18 11:58:33 -0400132#endif
133
Urvang Joshicb586f32016-09-20 11:36:33 -0700134/*!\brief Decorator indicating that given struct/union/enum is packed */
135#ifndef ATTRIBUTE_PACKED
136#if defined(__GNUC__) && __GNUC__
137#define ATTRIBUTE_PACKED __attribute__((packed))
138#elif defined(_MSC_VER)
139#define ATTRIBUTE_PACKED
140#else
141#define ATTRIBUTE_PACKED
142#endif
143#endif /* ATTRIBUTE_PACKED */
144
clang-format83a52072016-08-08 20:22:13 -0700145/*!\brief Current ABI version number
146 *
147 * \internal
148 * If this file is altered in any way that changes the ABI, this value
149 * must be bumped. Examples include, but are not limited to, changing
150 * types, removing or reassigning enums, adding/removing/rearranging
151 * fields to structures
152 */
Bohan Li45ab7842020-12-21 13:27:47 -0800153#define AOM_CODEC_ABI_VERSION (6 + AOM_IMAGE_ABI_VERSION) /**<\hideinitializer*/
John Koleszar0ea50ce2010-05-18 11:58:33 -0400154
clang-format83a52072016-08-08 20:22:13 -0700155/*!\brief Algorithm return codes */
Satish Kumar Suman9b1252e2018-12-25 11:21:18 +0530156typedef enum {
clang-format83a52072016-08-08 20:22:13 -0700157 /*!\brief Operation completed without error */
Yaowu Xuf883b422016-08-30 14:01:10 -0700158 AOM_CODEC_OK,
John Koleszar0ea50ce2010-05-18 11:58:33 -0400159
clang-format83a52072016-08-08 20:22:13 -0700160 /*!\brief Unspecified error */
Yaowu Xuf883b422016-08-30 14:01:10 -0700161 AOM_CODEC_ERROR,
John Koleszar0ea50ce2010-05-18 11:58:33 -0400162
clang-format83a52072016-08-08 20:22:13 -0700163 /*!\brief Memory operation failed */
Yaowu Xuf883b422016-08-30 14:01:10 -0700164 AOM_CODEC_MEM_ERROR,
John Koleszar0ea50ce2010-05-18 11:58:33 -0400165
clang-format83a52072016-08-08 20:22:13 -0700166 /*!\brief ABI version mismatch */
Yaowu Xuf883b422016-08-30 14:01:10 -0700167 AOM_CODEC_ABI_MISMATCH,
John Koleszar0ea50ce2010-05-18 11:58:33 -0400168
clang-format83a52072016-08-08 20:22:13 -0700169 /*!\brief Algorithm does not have required capability */
Yaowu Xuf883b422016-08-30 14:01:10 -0700170 AOM_CODEC_INCAPABLE,
John Koleszar0ea50ce2010-05-18 11:58:33 -0400171
clang-format83a52072016-08-08 20:22:13 -0700172 /*!\brief The given bitstream is not supported.
John Koleszarc6b90392012-07-13 15:21:29 -0700173 *
clang-format83a52072016-08-08 20:22:13 -0700174 * The bitstream was unable to be parsed at the highest level. The decoder
175 * is unable to proceed. This error \ref SHOULD be treated as fatal to the
176 * stream. */
Yaowu Xuf883b422016-08-30 14:01:10 -0700177 AOM_CODEC_UNSUP_BITSTREAM,
clang-format83a52072016-08-08 20:22:13 -0700178
179 /*!\brief Encoded bitstream uses an unsupported feature
John Koleszarc6b90392012-07-13 15:21:29 -0700180 *
clang-format83a52072016-08-08 20:22:13 -0700181 * The decoder does not implement a feature required by the encoder. This
182 * return code should only be used for features that prevent future
183 * pictures from being properly decoded. This error \ref MAY be treated as
184 * fatal to the stream or \ref MAY be treated as fatal to the current GOP.
John Koleszarc6b90392012-07-13 15:21:29 -0700185 */
Yaowu Xuf883b422016-08-30 14:01:10 -0700186 AOM_CODEC_UNSUP_FEATURE,
clang-format83a52072016-08-08 20:22:13 -0700187
188 /*!\brief The coded data for this stream is corrupt or incomplete
189 *
190 * There was a problem decoding the current frame. This return code
191 * should only be used for failures that prevent future pictures from
192 * being properly decoded. This error \ref MAY be treated as fatal to the
193 * stream or \ref MAY be treated as fatal to the current GOP. If decoding
194 * is continued for the current GOP, artifacts may be present.
195 */
Yaowu Xuf883b422016-08-30 14:01:10 -0700196 AOM_CODEC_CORRUPT_FRAME,
clang-format83a52072016-08-08 20:22:13 -0700197
198 /*!\brief An application-supplied parameter is not valid.
199 *
200 */
Yaowu Xuf883b422016-08-30 14:01:10 -0700201 AOM_CODEC_INVALID_PARAM,
clang-format83a52072016-08-08 20:22:13 -0700202
203 /*!\brief An iterator reached the end of list.
204 *
205 */
Yaowu Xuf883b422016-08-30 14:01:10 -0700206 AOM_CODEC_LIST_END
clang-format83a52072016-08-08 20:22:13 -0700207
Satish Kumar Suman9b1252e2018-12-25 11:21:18 +0530208} aom_codec_err_t;
clang-format83a52072016-08-08 20:22:13 -0700209
210/*! \brief Codec capabilities bitfield
211 *
212 * Each codec advertises the capabilities it supports as part of its
Yaowu Xuf883b422016-08-30 14:01:10 -0700213 * ::aom_codec_iface_t interface structure. Capabilities are extra interfaces
clang-format83a52072016-08-08 20:22:13 -0700214 * or functionality, and are not required to be supported.
215 *
Yaowu Xuf883b422016-08-30 14:01:10 -0700216 * The available flags are specified by AOM_CODEC_CAP_* defines.
clang-format83a52072016-08-08 20:22:13 -0700217 */
Yaowu Xuf883b422016-08-30 14:01:10 -0700218typedef long aom_codec_caps_t;
219#define AOM_CODEC_CAP_DECODER 0x1 /**< Is a decoder */
220#define AOM_CODEC_CAP_ENCODER 0x2 /**< Is an encoder */
John Koleszar0ea50ce2010-05-18 11:58:33 -0400221
clang-format83a52072016-08-08 20:22:13 -0700222/*! \brief Initialization-time Feature Enabling
223 *
224 * Certain codec features must be known at initialization time, to allow for
225 * proper memory allocation.
226 *
Yaowu Xuf883b422016-08-30 14:01:10 -0700227 * The available flags are specified by AOM_CODEC_USE_* defines.
clang-format83a52072016-08-08 20:22:13 -0700228 */
Yaowu Xuf883b422016-08-30 14:01:10 -0700229typedef long aom_codec_flags_t;
John Koleszar0ea50ce2010-05-18 11:58:33 -0400230
Yaowu Xu047b7c92019-11-11 11:21:23 -0800231/*!\brief Time Stamp Type
232 *
233 * An integer, which when multiplied by the stream's time base, provides
234 * the absolute time of a sample.
235 */
236typedef int64_t aom_codec_pts_t;
237
clang-format83a52072016-08-08 20:22:13 -0700238/*!\brief Codec interface structure.
239 *
240 * Contains function pointers and other data private to the codec
Elliott Karpilovsky7026d4b2020-03-22 19:21:51 -0700241 * implementation. This structure is opaque to the application. Common
242 * functions used with this structure:
Elliott Karpilovsky675162b2020-04-24 17:36:57 -0700243 * - aom_codec_iface_name(aom_codec_iface_t *iface): get the
244 * name of the codec
245 * - aom_codec_get_caps(aom_codec_iface_t *iface): returns
246 * the capabilities of the codec
247 * - aom_codec_enc_config_default: generate the default config for
248 * initializing the encoder (see documention in aom_encoder.h)
Elliott Karpilovsky7026d4b2020-03-22 19:21:51 -0700249 * - aom_codec_dec_init, aom_codec_enc_init: initialize the codec context
Elliott Karpilovsky675162b2020-04-24 17:36:57 -0700250 * structure (see documentation on aom_codec_ctx).
251 *
252 * To get access to the AV1 encoder and decoder, use aom_codec_av1_cx() and
253 * aom_codec_av1_dx().
clang-format83a52072016-08-08 20:22:13 -0700254 */
Yaowu Xuf883b422016-08-30 14:01:10 -0700255typedef const struct aom_codec_iface aom_codec_iface_t;
John Koleszar0ea50ce2010-05-18 11:58:33 -0400256
clang-format83a52072016-08-08 20:22:13 -0700257/*!\brief Codec private data structure.
258 *
259 * Contains data private to the codec implementation. This structure is opaque
260 * to the application.
261 */
Yaowu Xuf883b422016-08-30 14:01:10 -0700262typedef struct aom_codec_priv aom_codec_priv_t;
John Koleszar0ea50ce2010-05-18 11:58:33 -0400263
Mufaddal Chakera8f12f7b2020-06-23 14:31:50 +0530264/*!\brief Compressed Frame Flags
265 *
266 * This type represents a bitfield containing information about a compressed
267 * frame that may be useful to an application. The most significant 16 bits
268 * can be used by an algorithm to provide additional detail, for example to
269 * support frame types that are codec specific (MPEG-1 D-frames for example)
270 */
271typedef uint32_t aom_codec_frame_flags_t;
272#define AOM_FRAME_IS_KEY 0x1 /**< frame is the start of a GOP */
273/*!\brief frame can be dropped without affecting the stream (no future frame
274 * depends on this one) */
275#define AOM_FRAME_IS_DROPPABLE 0x2
276/*!\brief this is an INTRA_ONLY frame */
277#define AOM_FRAME_IS_INTRAONLY 0x10
278/*!\brief this is an S-frame */
279#define AOM_FRAME_IS_SWITCH 0x20
280/*!\brief this is an error-resilient frame */
281#define AOM_FRAME_IS_ERROR_RESILIENT 0x40
282/*!\brief this is a key-frame dependent recovery-point frame */
283#define AOM_FRAME_IS_DELAYED_RANDOM_ACCESS_POINT 0x80
284
clang-format83a52072016-08-08 20:22:13 -0700285/*!\brief Iterator
286 *
287 * Opaque storage used for iterating over lists.
288 */
Yaowu Xuf883b422016-08-30 14:01:10 -0700289typedef const void *aom_codec_iter_t;
John Koleszar0ea50ce2010-05-18 11:58:33 -0400290
clang-format83a52072016-08-08 20:22:13 -0700291/*!\brief Codec context structure
292 *
293 * All codecs \ref MUST support this context structure fully. In general,
294 * this data should be considered private to the codec algorithm, and
295 * not be manipulated or examined by the calling application. Applications
296 * may reference the 'name' member to get a printable description of the
297 * algorithm.
298 */
Yaowu Xuf883b422016-08-30 14:01:10 -0700299typedef struct aom_codec_ctx {
clang-format83a52072016-08-08 20:22:13 -0700300 const char *name; /**< Printable interface name */
Yaowu Xuf883b422016-08-30 14:01:10 -0700301 aom_codec_iface_t *iface; /**< Interface pointers */
302 aom_codec_err_t err; /**< Last returned error */
clang-format83a52072016-08-08 20:22:13 -0700303 const char *err_detail; /**< Detailed info, if available */
Yaowu Xuf883b422016-08-30 14:01:10 -0700304 aom_codec_flags_t init_flags; /**< Flags passed at init time */
clang-format83a52072016-08-08 20:22:13 -0700305 union {
306 /**< Decoder Configuration Pointer */
Yaowu Xuf883b422016-08-30 14:01:10 -0700307 const struct aom_codec_dec_cfg *dec;
clang-format83a52072016-08-08 20:22:13 -0700308 /**< Encoder Configuration Pointer */
Yaowu Xuf883b422016-08-30 14:01:10 -0700309 const struct aom_codec_enc_cfg *enc;
clang-format83a52072016-08-08 20:22:13 -0700310 const void *raw;
311 } config; /**< Configuration pointer aliasing union */
Yaowu Xuf883b422016-08-30 14:01:10 -0700312 aom_codec_priv_t *priv; /**< Algorithm private storage */
313} aom_codec_ctx_t;
John Koleszar0ea50ce2010-05-18 11:58:33 -0400314
clang-format83a52072016-08-08 20:22:13 -0700315/*!\brief Bit depth for codec
316 * *
317 * This enumeration determines the bit depth of the codec.
318 */
Satish Kumar Suman9b1252e2018-12-25 11:21:18 +0530319typedef enum aom_bit_depth {
320 AOM_BITS_8 = 8, /**< 8 bits */
321 AOM_BITS_10 = 10, /**< 10 bits */
322 AOM_BITS_12 = 12, /**< 12 bits */
323} aom_bit_depth_t;
John Koleszar0ea50ce2010-05-18 11:58:33 -0400324
clang-format83a52072016-08-08 20:22:13 -0700325/*!\brief Superblock size selection.
326 *
327 * Defines the superblock size used for encoding. The superblock size can
328 * either be fixed at 64x64 or 128x128 pixels, or it can be dynamically
329 * selected by the encoder for each frame.
330 */
Satish Kumar Suman9b1252e2018-12-25 11:21:18 +0530331typedef enum aom_superblock_size {
332 AOM_SUPERBLOCK_SIZE_64X64, /**< Always use 64x64 superblocks. */
333 AOM_SUPERBLOCK_SIZE_128X128, /**< Always use 128x128 superblocks. */
334 AOM_SUPERBLOCK_SIZE_DYNAMIC /**< Select superblock size dynamically. */
335} aom_superblock_size_t;
John Koleszar0ea50ce2010-05-18 11:58:33 -0400336
clang-format83a52072016-08-08 20:22:13 -0700337/*
338 * Library Version Number Interface
339 *
340 * For example, see the following sample return values:
Yaowu Xuf883b422016-08-30 14:01:10 -0700341 * aom_codec_version() (1<<16 | 2<<8 | 3)
342 * aom_codec_version_str() "v1.2.3-rc1-16-gec6a1ba"
343 * aom_codec_version_extra_str() "rc1-16-gec6a1ba"
clang-format83a52072016-08-08 20:22:13 -0700344 */
John Koleszar0ea50ce2010-05-18 11:58:33 -0400345
clang-format83a52072016-08-08 20:22:13 -0700346/*!\brief Return the version information (as an integer)
347 *
348 * Returns a packed encoding of the library version number. This will only
Wan-Teh Chang9b88e492020-04-23 21:58:32 -0700349 * include the major.minor.patch component of the version number. Note that this
350 * encoded value should be accessed through the macros provided, as the encoding
351 * may change in the future.
clang-format83a52072016-08-08 20:22:13 -0700352 *
353 */
Yaowu Xuf883b422016-08-30 14:01:10 -0700354int aom_codec_version(void);
John Koleszar0ea50ce2010-05-18 11:58:33 -0400355
Wan-Teh Chang9b88e492020-04-23 21:58:32 -0700356/*!\brief Return the major version number */
Yaowu Xuf883b422016-08-30 14:01:10 -0700357#define aom_codec_version_major() ((aom_codec_version() >> 16) & 0xff)
John Koleszar0ea50ce2010-05-18 11:58:33 -0400358
Wan-Teh Chang9b88e492020-04-23 21:58:32 -0700359/*!\brief Return the minor version number */
Yaowu Xuf883b422016-08-30 14:01:10 -0700360#define aom_codec_version_minor() ((aom_codec_version() >> 8) & 0xff)
John Koleszar0ea50ce2010-05-18 11:58:33 -0400361
Wan-Teh Chang9b88e492020-04-23 21:58:32 -0700362/*!\brief Return the patch version number */
Yaowu Xuf883b422016-08-30 14:01:10 -0700363#define aom_codec_version_patch() ((aom_codec_version() >> 0) & 0xff)
Geza Lore454989f2016-03-24 13:56:05 +0000364
clang-format83a52072016-08-08 20:22:13 -0700365/*!\brief Return the version information (as a string)
366 *
367 * Returns a printable string containing the full library version number. This
Wan-Teh Chang9b88e492020-04-23 21:58:32 -0700368 * may contain additional text following the three digit version number, as to
369 * indicate release candidates, prerelease versions, etc.
clang-format83a52072016-08-08 20:22:13 -0700370 *
371 */
Yaowu Xuf883b422016-08-30 14:01:10 -0700372const char *aom_codec_version_str(void);
John Koleszar0ea50ce2010-05-18 11:58:33 -0400373
clang-format83a52072016-08-08 20:22:13 -0700374/*!\brief Return the version information (as a string)
375 *
376 * Returns a printable "extra string". This is the component of the string
Wan-Teh Chang9b88e492020-04-23 21:58:32 -0700377 * returned by aom_codec_version_str() following the three digit version number.
clang-format83a52072016-08-08 20:22:13 -0700378 *
379 */
Yaowu Xuf883b422016-08-30 14:01:10 -0700380const char *aom_codec_version_extra_str(void);
John Koleszar0ea50ce2010-05-18 11:58:33 -0400381
clang-format83a52072016-08-08 20:22:13 -0700382/*!\brief Return the build configuration
383 *
384 * Returns a printable string containing an encoded version of the build
Yaowu Xuf883b422016-08-30 14:01:10 -0700385 * configuration. This may be useful to aom support.
clang-format83a52072016-08-08 20:22:13 -0700386 *
387 */
Yaowu Xuf883b422016-08-30 14:01:10 -0700388const char *aom_codec_build_config(void);
John Koleszar0ea50ce2010-05-18 11:58:33 -0400389
clang-format83a52072016-08-08 20:22:13 -0700390/*!\brief Return the name for a given interface
391 *
392 * Returns a human readable string for name of the given codec interface.
393 *
394 * \param[in] iface Interface pointer
395 *
396 */
Yaowu Xuf883b422016-08-30 14:01:10 -0700397const char *aom_codec_iface_name(aom_codec_iface_t *iface);
John Koleszar0ea50ce2010-05-18 11:58:33 -0400398
clang-format83a52072016-08-08 20:22:13 -0700399/*!\brief Convert error number to printable string
400 *
401 * Returns a human readable string for the last error returned by the
402 * algorithm. The returned error will be one line and will not contain
403 * any newline characters.
404 *
405 *
406 * \param[in] err Error number.
407 *
408 */
Yaowu Xuf883b422016-08-30 14:01:10 -0700409const char *aom_codec_err_to_string(aom_codec_err_t err);
John Koleszar0ea50ce2010-05-18 11:58:33 -0400410
clang-format83a52072016-08-08 20:22:13 -0700411/*!\brief Retrieve error synopsis for codec context
412 *
413 * Returns a human readable string for the last error returned by the
414 * algorithm. The returned error will be one line and will not contain
415 * any newline characters.
416 *
417 *
418 * \param[in] ctx Pointer to this instance's context.
419 *
420 */
Yaowu Xuf883b422016-08-30 14:01:10 -0700421const char *aom_codec_error(aom_codec_ctx_t *ctx);
John Koleszar0ea50ce2010-05-18 11:58:33 -0400422
clang-format83a52072016-08-08 20:22:13 -0700423/*!\brief Retrieve detailed error information for codec context
424 *
425 * Returns a human readable string providing detailed information about
426 * the last error.
427 *
428 * \param[in] ctx Pointer to this instance's context.
429 *
430 * \retval NULL
431 * No detailed information is available.
432 */
Yaowu Xuf883b422016-08-30 14:01:10 -0700433const char *aom_codec_error_detail(aom_codec_ctx_t *ctx);
John Koleszar0ea50ce2010-05-18 11:58:33 -0400434
clang-format83a52072016-08-08 20:22:13 -0700435/* REQUIRED FUNCTIONS
436 *
437 * The following functions are required to be implemented for all codecs.
438 * They represent the base case functionality expected of all codecs.
439 */
John Koleszar0ea50ce2010-05-18 11:58:33 -0400440
clang-format83a52072016-08-08 20:22:13 -0700441/*!\brief Destroy a codec instance
442 *
443 * Destroys a codec context, freeing any associated memory buffers.
444 *
445 * \param[in] ctx Pointer to this instance's context
446 *
Yaowu Xuf883b422016-08-30 14:01:10 -0700447 * \retval #AOM_CODEC_OK
clang-format83a52072016-08-08 20:22:13 -0700448 * The codec algorithm initialized.
Yaowu Xuf883b422016-08-30 14:01:10 -0700449 * \retval #AOM_CODEC_MEM_ERROR
clang-format83a52072016-08-08 20:22:13 -0700450 * Memory allocation failed.
451 */
Yaowu Xuf883b422016-08-30 14:01:10 -0700452aom_codec_err_t aom_codec_destroy(aom_codec_ctx_t *ctx);
John Koleszar0ea50ce2010-05-18 11:58:33 -0400453
clang-format83a52072016-08-08 20:22:13 -0700454/*!\brief Get the capabilities of an algorithm.
455 *
456 * Retrieves the capabilities bitfield from the algorithm's interface.
457 *
458 * \param[in] iface Pointer to the algorithm interface
459 *
460 */
Yaowu Xuf883b422016-08-30 14:01:10 -0700461aom_codec_caps_t aom_codec_get_caps(aom_codec_iface_t *iface);
John Koleszar0ea50ce2010-05-18 11:58:33 -0400462
Elliott Karpilovsky60dd0f92020-04-30 19:19:27 -0700463/*!\name Codec Control
clang-format83a52072016-08-08 20:22:13 -0700464 *
Elliott Karpilovsky60dd0f92020-04-30 19:19:27 -0700465 * The aom_codec_control function exchanges algorithm specific data with the
466 * codec instance. Additionally, the macro AOM_CODEC_CONTROL_TYPECHECKED is
467 * provided, which will type-check the parameter against the control ID before
468 * calling aom_codec_control - note that this macro requires the control ID
469 * to be directly encoded in it, e.g.,
470 * AOM_CODEC_CONTROL_TYPECHECKED(&ctx, AOME_SET_CPUUSED, 8).
clang-format83a52072016-08-08 20:22:13 -0700471 *
Elliott Karpilovsky60dd0f92020-04-30 19:19:27 -0700472 * The codec control IDs can be found in aom.h, aomcx.h, and aomdx.h
473 * (defined as aom_com_control_id, aome_enc_control_id, and aom_dec_control_id).
474 * @{
475 */
476/*!\brief Algorithm Control
clang-format83a52072016-08-08 20:22:13 -0700477 *
Elliott Karpilovsky60dd0f92020-04-30 19:19:27 -0700478 * aom_codec_control takes a context, a control ID, and a third parameter
479 * (with varying type). If the context is non-null and an error occurs,
480 * ctx->err will be set to the same value as the return value.
clang-format83a52072016-08-08 20:22:13 -0700481 *
482 * \param[in] ctx Pointer to this instance's context
483 * \param[in] ctrl_id Algorithm specific control identifier
484 *
Yaowu Xuf883b422016-08-30 14:01:10 -0700485 * \retval #AOM_CODEC_OK
clang-format83a52072016-08-08 20:22:13 -0700486 * The control request was processed.
Yaowu Xuf883b422016-08-30 14:01:10 -0700487 * \retval #AOM_CODEC_ERROR
clang-format83a52072016-08-08 20:22:13 -0700488 * The control request was not processed.
Yaowu Xuf883b422016-08-30 14:01:10 -0700489 * \retval #AOM_CODEC_INVALID_PARAM
clang-format83a52072016-08-08 20:22:13 -0700490 * The data was not valid.
491 */
Elliott Karpilovsky60dd0f92020-04-30 19:19:27 -0700492aom_codec_err_t aom_codec_control(aom_codec_ctx_t *ctx, int ctrl_id, ...);
John Koleszar0ea50ce2010-05-18 11:58:33 -0400493
Bohan Li45ab7842020-12-21 13:27:47 -0800494/*!\brief Key & Value API
495 *
496 * aom_codec_set_option() takes a context, a key (option name) and a value. If
497 * the context is non-null and an error occurs, ctx->err will be set to the same
498 * value as the return value.
499 *
500 * \param[in] ctx Pointer to this instance's context
501 * \param[in] name The name of the option (key)
502 * \param[in] value The value of the option
503 *
504 * \retval #AOM_CODEC_OK
505 * The value of the option was set.
506 * \retval #AOM_CODEC_INVALID_PARAM
507 * The data was not valid.
508 * \retval #AOM_CODEC_ERROR
509 * The option was not successfully set.
510 */
511aom_codec_err_t aom_codec_set_option(aom_codec_ctx_t *ctx, const char *name,
512 const char *value);
513
Elliott Karpilovsky60dd0f92020-04-30 19:19:27 -0700514/*!\brief aom_codec_control wrapper macro (adds type-checking, less flexible)
clang-format83a52072016-08-08 20:22:13 -0700515 *
516 * This macro allows for type safe conversions across the variadic parameter
Elliott Karpilovsky60dd0f92020-04-30 19:19:27 -0700517 * to aom_codec_control(). However, it requires the explicit control ID
518 * be passed in (it cannot be passed in via a variable) -- otherwise a compiler
519 * error will occur. After the type checking, it calls aom_codec_control.
clang-format83a52072016-08-08 20:22:13 -0700520 */
Elliott Karpilovsky60dd0f92020-04-30 19:19:27 -0700521#define AOM_CODEC_CONTROL_TYPECHECKED(ctx, id, data) \
522 aom_codec_control_typechecked_##id(ctx, id, data) /**<\hideinitializer*/
John Koleszar0ea50ce2010-05-18 11:58:33 -0400523
Elliott Karpilovsky60dd0f92020-04-30 19:19:27 -0700524/*!\brief Creates typechecking mechanisms for aom_codec_control
clang-format83a52072016-08-08 20:22:13 -0700525 *
Elliott Karpilovsky60dd0f92020-04-30 19:19:27 -0700526 * It defines a static function with the correctly typed arguments as a wrapper
527 * to the type-unsafe aom_codec_control function. It also creates a typedef
528 * for each type.
clang-format83a52072016-08-08 20:22:13 -0700529 */
Elliott Karpilovsky60dd0f92020-04-30 19:19:27 -0700530#define AOM_CTRL_USE_TYPE(id, typ) \
531 static aom_codec_err_t aom_codec_control_typechecked_##id( \
532 aom_codec_ctx_t *, int, typ) AOM_UNUSED; \
533 static aom_codec_err_t aom_codec_control_typechecked_##id( \
534 aom_codec_ctx_t *ctx, int ctrl, typ data) { \
535 return aom_codec_control(ctx, ctrl, data); \
536 } /**<\hideinitializer*/ \
537 typedef typ aom_codec_control_type_##id;
538/*!@} end Codec Control group */
John Koleszar0ea50ce2010-05-18 11:58:33 -0400539
Tom Finegan95d900a2017-12-01 10:00:50 -0800540/*!\brief OBU types. */
Satish Kumar Suman9b1252e2018-12-25 11:21:18 +0530541typedef enum ATTRIBUTE_PACKED {
Tom Finegan95d900a2017-12-01 10:00:50 -0800542 OBU_SEQUENCE_HEADER = 1,
Tom Finegan3e632742017-12-01 10:08:53 -0800543 OBU_TEMPORAL_DELIMITER = 2,
Tom Finegan95d900a2017-12-01 10:00:50 -0800544 OBU_FRAME_HEADER = 3,
545 OBU_TILE_GROUP = 4,
546 OBU_METADATA = 5,
Vignesh Venkatasubramanianb2ce34e2018-03-05 16:57:40 -0800547 OBU_FRAME = 6,
Tom Fineganf9273812018-03-14 09:49:45 -0700548 OBU_REDUNDANT_FRAME_HEADER = 7,
Yunqing Wang167b09e2018-05-24 16:02:32 -0700549 OBU_TILE_LIST = 8,
Tom Finegan95d900a2017-12-01 10:00:50 -0800550 OBU_PADDING = 15,
Satish Kumar Suman9b1252e2018-12-25 11:21:18 +0530551} OBU_TYPE;
Tom Finegan95d900a2017-12-01 10:00:50 -0800552
553/*!\brief OBU metadata types. */
Satish Kumar Suman9b1252e2018-12-25 11:21:18 +0530554typedef enum {
Cyril Concolato33c38702018-05-08 10:17:14 -0700555 OBU_METADATA_TYPE_AOM_RESERVED_0 = 0,
Tom Finegan3e632742017-12-01 10:08:53 -0800556 OBU_METADATA_TYPE_HDR_CLL = 1,
557 OBU_METADATA_TYPE_HDR_MDCV = 2,
Soo-Chul Hanf8589862018-01-24 03:13:14 +0000558 OBU_METADATA_TYPE_SCALABILITY = 3,
Cyril Concolato33c38702018-05-08 10:17:14 -0700559 OBU_METADATA_TYPE_ITUT_T35 = 4,
Ilya Brailovskiyfe946eb2018-04-05 18:09:58 -0700560 OBU_METADATA_TYPE_TIMECODE = 5,
Satish Kumar Suman9b1252e2018-12-25 11:21:18 +0530561} OBU_METADATA_TYPE;
Tom Finegan95d900a2017-12-01 10:00:50 -0800562
Tom Finegan8fe8d512018-03-14 10:38:49 -0700563/*!\brief Returns string representation of OBU_TYPE.
564 *
565 * \param[in] type The OBU_TYPE to convert to string.
566 */
567const char *aom_obu_type_to_string(OBU_TYPE type);
568
clang-format83a52072016-08-08 20:22:13 -0700569/*!@} - end defgroup codec*/
John Koleszar0ea50ce2010-05-18 11:58:33 -0400570#ifdef __cplusplus
571}
572#endif
James Zerne1cbb132018-08-22 14:10:36 -0700573#endif // AOM_AOM_AOM_CODEC_H_