| 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)
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 {
157 AOM_CODEC_OK,
158
160 AOM_CODEC_ERROR,
161
163 AOM_CODEC_MEM_ERROR,
164
166 AOM_CODEC_ABI_MISMATCH,
167
169 AOM_CODEC_INCAPABLE,
170
176 AOM_CODEC_UNSUP_BITSTREAM,
177
185 AOM_CODEC_UNSUP_FEATURE,
186
195 AOM_CODEC_CORRUPT_FRAME,
196
200 AOM_CODEC_INVALID_PARAM,
201
205 AOM_CODEC_LIST_END
206
207} aom_codec_err_t;
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
293#define AOM_FRAME_IS_INTRAONLY 0x10u
295#define AOM_FRAME_IS_SWITCH 0x20u
297#define AOM_FRAME_IS_ERROR_RESILIENT 0x40u
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;
317 aom_codec_iface_t *iface;
318 aom_codec_err_t err;
319 const char *err_detail;
320 aom_codec_flags_t init_flags;
321 union {
323 const struct aom_codec_dec_cfg *dec;
325 const struct aom_codec_enc_cfg *enc;
326 const void *raw;
327 } config;
328 aom_codec_priv_t *priv;
329} aom_codec_ctx_t;
330
335 typedef enum aom_bit_depth {
336 AOM_BITS_8 = 8,
337 AOM_BITS_10 = 10,
338 AOM_BITS_12 = 12,
339} aom_bit_depth_t;
340
347 typedef enum aom_superblock_size {
348 AOM_SUPERBLOCK_SIZE_64X64,
349 AOM_SUPERBLOCK_SIZE_128X128,
350 AOM_SUPERBLOCK_SIZE_DYNAMIC
351} aom_superblock_size_t;
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
413 const char *aom_codec_iface_name(aom_codec_iface_t *iface);
414
425 const char *aom_codec_err_to_string(aom_codec_err_t err);
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
472 aom_codec_err_t aom_codec_destroy(aom_codec_ctx_t *ctx);
473
481 aom_codec_caps_t aom_codec_get_caps(aom_codec_iface_t *iface);
482
513 aom_codec_err_t aom_codec_control(aom_codec_ctx_t *ctx, int ctrl_id, ...);
514
532 aom_codec_err_t aom_codec_set_option(aom_codec_ctx_t *ctx, const char *name,
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;
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,
582} OBU_METADATA_TYPE;
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_
aom_image.h
Describes the aom image descriptor and associated operations.
aom_codec_caps_t
long aom_codec_caps_t
Codec capabilities bitfield.
Definition aom_codec.h:217
aom_codec_iface_name
const char * aom_codec_iface_name(aom_codec_iface_t *iface)
Return the name for a given interface.
aom_bit_depth_t
enum aom_bit_depth aom_bit_depth_t
Bit depth for codecThis enumeration determines the bit depth of the codec.
aom_codec_control
aom_codec_err_t aom_codec_control(aom_codec_ctx_t *ctx, int ctrl_id,...)
Algorithm Control.
aom_codec_flags_t
long aom_codec_flags_t
Initialization-time Feature Enabling.
Definition aom_codec.h:232
aom_codec_ctx_t
struct aom_codec_ctx aom_codec_ctx_t
Codec context structure.
aom_codec_priv_t
struct aom_codec_priv aom_codec_priv_t
Codec private data structure.
Definition aom_codec.h:278
aom_codec_iface_t
const struct aom_codec_iface aom_codec_iface_t
Codec interface structure.
Definition aom_codec.h:271
aom_codec_version_str
const char * aom_codec_version_str(void)
Return the version information (as a string)
aom_codec_get_caps
aom_codec_caps_t aom_codec_get_caps(aom_codec_iface_t *iface)
Get the capabilities of an algorithm.
aom_bit_depth
aom_bit_depth
Bit depth for codecThis enumeration determines the bit depth of the codec.
Definition aom_codec.h:335
OBU_TYPE
OBU_TYPE
OBU types.
Definition aom_codec.h:562
aom_codec_build_config
const char * aom_codec_build_config(void)
Return the build configuration.
aom_codec_set_option
aom_codec_err_t aom_codec_set_option(aom_codec_ctx_t *ctx, const char *name, const char *value)
Key & Value API.
aom_codec_error
const char * aom_codec_error(const aom_codec_ctx_t *ctx)
Retrieve error synopsis for codec context.
aom_codec_pts_t
int64_t aom_codec_pts_t
Time Stamp Type.
Definition aom_codec.h:252
aom_superblock_size_t
enum aom_superblock_size aom_superblock_size_t
Superblock size selection.
aom_codec_destroy
aom_codec_err_t aom_codec_destroy(aom_codec_ctx_t *ctx)
Destroy a codec instance.
aom_codec_err_to_string
const char * aom_codec_err_to_string(aom_codec_err_t err)
Convert error number to printable string.
aom_codec_err_t
aom_codec_err_t
Algorithm return codes.
Definition aom_codec.h:155
OBU_METADATA_TYPE
OBU_METADATA_TYPE
OBU metadata types.
Definition aom_codec.h:575
aom_codec_version
int aom_codec_version(void)
Return the version information (as an integer)
aom_superblock_size
aom_superblock_size
Superblock size selection.
Definition aom_codec.h:347
ATTRIBUTE_PACKED
#define ATTRIBUTE_PACKED
Decorator indicating that given struct/union/enum is packed.
Definition aom_codec.h:140
aom_codec_error_detail
const char * aom_codec_error_detail(const aom_codec_ctx_t *ctx)
Retrieve detailed error information for codec context.
aom_codec_iter_t
const void * aom_codec_iter_t
Iterator.
Definition aom_codec.h:305
aom_obu_type_to_string
const char * aom_obu_type_to_string(OBU_TYPE type)
Returns string representation of OBU_TYPE.
aom_codec_frame_flags_t
uint32_t aom_codec_frame_flags_t
Compressed Frame Flags.
Definition aom_codec.h:287
aom_codec_version_extra_str
const char * aom_codec_version_extra_str(void)
Return the version information (as a string)
AOM_BITS_12
@ AOM_BITS_12
Definition aom_codec.h:338
AOM_BITS_8
@ AOM_BITS_8
Definition aom_codec.h:336
AOM_BITS_10
@ AOM_BITS_10
Definition aom_codec.h:337
AOM_CODEC_INVALID_PARAM
@ AOM_CODEC_INVALID_PARAM
An application-supplied parameter is not valid.
Definition aom_codec.h:200
AOM_CODEC_ERROR
@ AOM_CODEC_ERROR
Unspecified error.
Definition aom_codec.h:160
AOM_CODEC_UNSUP_BITSTREAM
@ AOM_CODEC_UNSUP_BITSTREAM
The given bitstream is not supported.
Definition aom_codec.h:176
AOM_CODEC_LIST_END
@ AOM_CODEC_LIST_END
An iterator reached the end of list.
Definition aom_codec.h:205
AOM_CODEC_ABI_MISMATCH
@ AOM_CODEC_ABI_MISMATCH
ABI version mismatch.
Definition aom_codec.h:166
AOM_CODEC_CORRUPT_FRAME
@ AOM_CODEC_CORRUPT_FRAME
The coded data for this stream is corrupt or incomplete.
Definition aom_codec.h:195
AOM_CODEC_UNSUP_FEATURE
@ AOM_CODEC_UNSUP_FEATURE
Encoded bitstream uses an unsupported feature.
Definition aom_codec.h:185
AOM_CODEC_MEM_ERROR
@ AOM_CODEC_MEM_ERROR
Memory operation failed.
Definition aom_codec.h:163
AOM_CODEC_INCAPABLE
@ AOM_CODEC_INCAPABLE
Algorithm does not have required capability.
Definition aom_codec.h:169
AOM_CODEC_OK
@ AOM_CODEC_OK
Operation completed without error.
Definition aom_codec.h:157
AOM_SUPERBLOCK_SIZE_128X128
@ AOM_SUPERBLOCK_SIZE_128X128
Definition aom_codec.h:349
AOM_SUPERBLOCK_SIZE_64X64
@ AOM_SUPERBLOCK_SIZE_64X64
Definition aom_codec.h:348
AOM_SUPERBLOCK_SIZE_DYNAMIC
@ AOM_SUPERBLOCK_SIZE_DYNAMIC
Definition aom_codec.h:350
aom_codec_ctx
Codec context structure.
Definition aom_codec.h:315
aom_codec_ctx::name
const char * name
Definition aom_codec.h:316
aom_codec_ctx::iface
aom_codec_iface_t * iface
Definition aom_codec.h:317
aom_codec_ctx::dec
const struct aom_codec_dec_cfg * dec
Definition aom_codec.h:323
aom_codec_ctx::err
aom_codec_err_t err
Definition aom_codec.h:318
aom_codec_ctx::priv
aom_codec_priv_t * priv
Definition aom_codec.h:328
aom_codec_ctx::config
union aom_codec_ctx::@0 config
aom_codec_ctx::init_flags
aom_codec_flags_t init_flags
Definition aom_codec.h:320
aom_codec_ctx::err_detail
const char * err_detail
Definition aom_codec.h:319
aom_codec_dec_cfg
Initialization Configurations.
Definition aom_decoder.h:91
aom_codec_enc_cfg
Encoder configuration structure.
Definition aom_encoder.h:387