AOMedia AV1 Codec
aom_codec.h
Go to the documentation of this file.
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 
13 // Internal implementation details
15 //
16 // There are two levels of interfaces used to access the AOM codec: the
17 // aom_codec_iface and the aom_codec_ctx.
18 //
19 // 1. aom_codec_iface_t
20 // (Related files: aom/aom_codec.h, aom/src/aom_codec.c,
21 // aom/internal/aom_codec_internal.h, av1/av1_cx_iface.c,
22 // av1/av1_dx_iface.c)
23 //
24 // Used to initialize the codec context, which contains the configuration for
25 // for modifying the encoder/decoder during run-time. See the other
26 // documentation in this header file for more details. For the most part,
27 // users will call helper functions, such as aom_codec_iface_name,
28 // aom_codec_get_caps, etc., to interact with it.
29 //
30 // The main purpose of the aom_codec_iface_t is to provide a way to generate
31 // a default codec config, find out what capabilities the implementation has,
32 // and create an aom_codec_ctx_t (which is actually used to interact with the
33 // codec).
34 //
35 // Note that the implementations for the AV1 algorithm are located in
36 // av1/av1_cx_iface.c and av1/av1_dx_iface.c
37 //
38 //
39 // 2. aom_codec_ctx_t
40 // (Related files: aom/aom_codec.h, av1/av1_cx_iface.c, av1/av1_dx_iface.c,
41 // aom/aomcx.h, aom/aomdx.h, aom/src/aom_encoder.c, aom/src/aom_decoder.c)
42 //
43 // The actual interface between user code and the codec. It stores the name
44 // of the codec, a pointer back to the aom_codec_iface_t that initialized it,
45 // initialization flags, a config for either encoder or the decoder, and a
46 // pointer to internal data.
47 //
48 // The codec is configured / queried through calls to aom_codec_control,
49 // which takes a control ID (listed in aomcx.h and aomdx.h) and a parameter.
50 // In the case of "getter" control IDs, the parameter is modified to have
51 // the requested value; in the case of "setter" control IDs, the codec's
52 // configuration is changed based on the parameter. Note that a aom_codec_err_t
53 // is returned, which indicates if the operation was successful or not.
54 //
55 // Note that for the encoder, the aom_codec_alg_priv_t points to the
56 // the aom_codec_alg_priv structure in av1/av1_cx_iface.c, and for the decoder,
57 // the struct in av1/av1_dx_iface.c. Variables such as AV1_COMP cpi are stored
58 // here and also used in the core algorithm.
59 //
60 // At the end, aom_codec_destroy should be called for each initialized
61 // aom_codec_ctx_t.
62 
93 #ifndef AOM_AOM_AOM_CODEC_H_
94 #define AOM_AOM_AOM_CODEC_H_
95 
96 #ifdef __cplusplus
97 extern "C" {
98 #endif
99 
100 #include "aom/aom_image.h"
101 #include "aom/aom_integer.h"
102 
104 #ifndef AOM_DEPRECATED
105 #if defined(__GNUC__)
106 #define AOM_DEPRECATED __attribute__((deprecated))
107 #elif defined(_MSC_VER)
108 #define AOM_DEPRECATED
109 #else
110 #define AOM_DEPRECATED
111 #endif
112 #endif /* AOM_DEPRECATED */
113 
114 #ifndef AOM_DECLSPEC_DEPRECATED
115 #if defined(__GNUC__)
116 #define AOM_DECLSPEC_DEPRECATED
117 #elif defined(_MSC_VER)
118 
119 #define AOM_DECLSPEC_DEPRECATED __declspec(deprecated)
120 #else
121 #define AOM_DECLSPEC_DEPRECATED
122 #endif
123 #endif /* AOM_DECLSPEC_DEPRECATED */
124 
126 #ifdef AOM_UNUSED
127 #elif defined(__GNUC__) || defined(__clang__)
128 #define AOM_UNUSED __attribute__((unused))
129 #else
130 #define AOM_UNUSED
131 #endif
132 
134 #ifndef ATTRIBUTE_PACKED
135 #if defined(__GNUC__)
136 #define ATTRIBUTE_PACKED __attribute__((packed))
137 #elif defined(_MSC_VER)
138 #define ATTRIBUTE_PACKED
139 #else
140 #define ATTRIBUTE_PACKED
141 #endif
142 #endif /* ATTRIBUTE_PACKED */
143 
152 #define AOM_CODEC_ABI_VERSION (7 + AOM_IMAGE_ABI_VERSION)
155 typedef enum {
156 
158 
161 
164 
167 
170 
177 
186 
196 
201 
206 
208 
217 typedef long aom_codec_caps_t;
218 #define AOM_CODEC_CAP_DECODER 0x1
219 #define AOM_CODEC_CAP_ENCODER 0x2
232 typedef long aom_codec_flags_t;
233 
234 // Experimental feature policy
235 //
236 // New features may be marked as experimental. Experimental features are not
237 // part of the stable API and may be modified or removed in a future release.
238 // Experimental features are made available only if you pass the
239 // AOM_CODEC_USE_EXPERIMENTAL flag to the codec init function.
240 //
241 // If you use experimental features, you must rebuild your code whenever you
242 // update to a new libaom release, and you must be prepared to modify your code
243 // when an experimental feature you use is modified or removed. If you are not
244 // sure, DO NOT use experimental features.
245 #define AOM_CODEC_USE_EXPERIMENTAL 0x1
252 typedef int64_t aom_codec_pts_t;
253 
271 typedef const struct aom_codec_iface aom_codec_iface_t;
272 
278 typedef struct aom_codec_priv aom_codec_priv_t;
279 
287 typedef uint32_t aom_codec_frame_flags_t;
288 #define AOM_FRAME_IS_KEY 0x1u
291 #define AOM_FRAME_IS_DROPPABLE 0x2u
292 
293 #define AOM_FRAME_IS_INTRAONLY 0x10u
294 
295 #define AOM_FRAME_IS_SWITCH 0x20u
296 
297 #define AOM_FRAME_IS_ERROR_RESILIENT 0x40u
298 
299 #define AOM_FRAME_IS_DELAYED_RANDOM_ACCESS_POINT 0x80u
300 
305 typedef const void *aom_codec_iter_t;
306 
315 typedef struct aom_codec_ctx {
316  const char *name;
319  const char *err_detail;
321  union {
323  const struct aom_codec_dec_cfg *dec;
325  const struct aom_codec_enc_cfg *enc;
326  const void *raw;
327  } config;
330 
335 typedef enum aom_bit_depth {
337  AOM_BITS_10 = 10,
338  AOM_BITS_12 = 12,
340 
347 typedef enum aom_superblock_size {
352 
353 /*
354  * Library Version Number Interface
355  *
356  * For example, see the following sample return values:
357  * aom_codec_version() (1<<16 | 2<<8 | 3)
358  * aom_codec_version_str() "v1.2.3-rc1-16-gec6a1ba"
359  * aom_codec_version_extra_str() "rc1-16-gec6a1ba"
360  */
361 
370 int aom_codec_version(void);
371 
373 #define aom_codec_version_major() ((aom_codec_version() >> 16) & 0xff)
374 
376 #define aom_codec_version_minor() ((aom_codec_version() >> 8) & 0xff)
377 
379 #define aom_codec_version_patch() ((aom_codec_version() >> 0) & 0xff)
380 
388 const char *aom_codec_version_str(void);
389 
396 const char *aom_codec_version_extra_str(void);
397 
404 const char *aom_codec_build_config(void);
405 
414 
426 
437 const char *aom_codec_error(const aom_codec_ctx_t *ctx);
438 
451 const char *aom_codec_error_detail(const aom_codec_ctx_t *ctx);
452 
453 /* REQUIRED FUNCTIONS
454  *
455  * The following functions are required to be implemented for all codecs.
456  * They represent the base case functionality expected of all codecs.
457  */
458 
473 
482 
513 aom_codec_err_t aom_codec_control(aom_codec_ctx_t *ctx, int ctrl_id, ...);
514 
533  const char *value);
534 
542 #define AOM_CODEC_CONTROL_TYPECHECKED(ctx, id, data) \
543  aom_codec_control_typechecked_##id(ctx, id, data)
551 #define AOM_CTRL_USE_TYPE(id, typ) \
552  static aom_codec_err_t aom_codec_control_typechecked_##id( \
553  aom_codec_ctx_t *, int, typ) AOM_UNUSED; \
554  static aom_codec_err_t aom_codec_control_typechecked_##id( \
555  aom_codec_ctx_t *ctx, int ctrl, typ data) { \
556  return aom_codec_control(ctx, ctrl, data); \
557  } \
558  typedef typ aom_codec_control_type_##id;
559 
562 typedef enum ATTRIBUTE_PACKED {
563  OBU_SEQUENCE_HEADER = 1,
564  OBU_TEMPORAL_DELIMITER = 2,
565  OBU_FRAME_HEADER = 3,
566  OBU_TILE_GROUP = 4,
567  OBU_METADATA = 5,
568  OBU_FRAME = 6,
569  OBU_REDUNDANT_FRAME_HEADER = 7,
570  OBU_TILE_LIST = 8,
571  OBU_PADDING = 15,
572 } OBU_TYPE;
573 
575 typedef enum {
576  OBU_METADATA_TYPE_AOM_RESERVED_0 = 0,
577  OBU_METADATA_TYPE_HDR_CLL = 1,
578  OBU_METADATA_TYPE_HDR_MDCV = 2,
579  OBU_METADATA_TYPE_SCALABILITY = 3,
580  OBU_METADATA_TYPE_ITUT_T35 = 4,
581  OBU_METADATA_TYPE_TIMECODE = 5,
583 
588 const char *aom_obu_type_to_string(OBU_TYPE type);
589 
591 #ifdef __cplusplus
592 }
593 #endif
594 #endif // AOM_AOM_AOM_CODEC_H_
union aom_codec_ctx::@0 config
Operation completed without error.
Definition: aom_codec.h:157
Encoded bitstream uses an unsupported feature.
Definition: aom_codec.h:185
The coded data for this stream is corrupt or incomplete.
Definition: aom_codec.h:195
Encoder configuration structure.
Definition: aom_encoder.h:387
aom_codec_err_t err
Definition: aom_codec.h:318
const char * name
Definition: aom_codec.h:316
Describes the aom image descriptor and associated operations.
aom_codec_iface_t * iface
Definition: aom_codec.h:317
Codec context structure.
Definition: aom_codec.h:315
aom_codec_caps_t aom_codec_get_caps(aom_codec_iface_t *iface)
Get the capabilities of an algorithm.
const char * err_detail
Definition: aom_codec.h:319
OBU_METADATA_TYPE
OBU metadata types.
Definition: aom_codec.h:576
Definition: aom_codec.h:336
const struct aom_codec_iface aom_codec_iface_t
Codec interface structure.
Definition: aom_codec.h:271
const char * aom_codec_iface_name(aom_codec_iface_t *iface)
Return the name for a given interface.
aom_codec_priv_t * priv
Definition: aom_codec.h:328
aom_codec_err_t aom_codec_destroy(aom_codec_ctx_t *ctx)
Destroy a codec instance.
const char * aom_codec_err_to_string(aom_codec_err_t err)
Convert error number to printable string.
Algorithm does not have required capability.
Definition: aom_codec.h:169
Memory operation failed.
Definition: aom_codec.h:163
Definition: aom_codec.h:338
enum aom_superblock_size aom_superblock_size_t
Superblock size selection.
ABI version mismatch.
Definition: aom_codec.h:166
const char * aom_obu_type_to_string(OBU_TYPE type)
Returns string representation of OBU_TYPE.
Unspecified error.
Definition: aom_codec.h:160
aom_superblock_size
Superblock size selection.
Definition: aom_codec.h:347
Initialization Configurations.
Definition: aom_decoder.h:91
An iterator reached the end of list.
Definition: aom_codec.h:205
const char * aom_codec_error_detail(const aom_codec_ctx_t *ctx)
Retrieve detailed error information for codec context.
OBU_TYPE
OBU types.
Definition: aom_codec.h:563
int aom_codec_version(void)
Return the version information (as an integer)
const char * aom_codec_build_config(void)
Return the build configuration.
The given bitstream is not supported.
Definition: aom_codec.h:176
struct aom_codec_ctx aom_codec_ctx_t
Codec context structure.
uint32_t aom_codec_frame_flags_t
Compressed Frame Flags.
Definition: aom_codec.h:287
const char * aom_codec_version_str(void)
Return the version information (as a string)
aom_codec_err_t aom_codec_set_option(aom_codec_ctx_t *ctx, const char *name, const char *value)
Key & Value API.
Definition: aom_codec.h:348
#define ATTRIBUTE_PACKED
Decorator indicating that given struct/union/enum is packed.
Definition: aom_codec.h:140
const void * aom_codec_iter_t
Iterator.
Definition: aom_codec.h:305
const char * aom_codec_error(const aom_codec_ctx_t *ctx)
Retrieve error synopsis for codec context.
long aom_codec_flags_t
Initialization-time Feature Enabling.
Definition: aom_codec.h:232
enum aom_bit_depth aom_bit_depth_t
Bit depth for codecThis enumeration determines the bit depth of the codec.
Definition: aom_codec.h:349
aom_codec_err_t
Algorithm return codes.
Definition: aom_codec.h:155
struct aom_codec_priv aom_codec_priv_t
Codec private data structure.
Definition: aom_codec.h:278
aom_codec_flags_t init_flags
Definition: aom_codec.h:320
const struct aom_codec_dec_cfg * dec
Definition: aom_codec.h:323
Definition: aom_codec.h:337
An application-supplied parameter is not valid.
Definition: aom_codec.h:200
long aom_codec_caps_t
Codec capabilities bitfield.
Definition: aom_codec.h:217
Definition: aom_codec.h:350
const char * aom_codec_version_extra_str(void)
Return the version information (as a string)
aom_bit_depth
Bit depth for codecThis enumeration determines the bit depth of the codec.
Definition: aom_codec.h:335
aom_codec_err_t aom_codec_control(aom_codec_ctx_t *ctx, int ctrl_id,...)
Algorithm Control.