Topics
	Decoder Algorithm Interface

	Encoder Algorithm Interface

Files
file	aom_codec.h
	Describes the codec algorithm interface to applications.

Data Structures
struct	aom_codec_ctx
	Codec context structure. More...

Macros
#define	AOM_DEPRECATED
	Decorator indicating a function is deprecated.

#define	AOM_DECLSPEC_DEPRECATED
	Decorator indicating a function is deprecated.

#define	AOM_UNUSED
	Decorator indicating a function is potentially unused.

#define	ATTRIBUTE_PACKED
	Decorator indicating that given struct/union/enum is packed.

#define	AOM_CODEC_ABI_VERSION
	Current ABI version number.

#define	AOM_CODEC_CAP_DECODER 0x1

#define	AOM_CODEC_CAP_ENCODER 0x2

#define	AOM_CODEC_USE_EXPERIMENTAL 0x1

#define	AOM_FRAME_IS_KEY 0x1u

#define	AOM_FRAME_IS_DROPPABLE 0x2u
	frame can be dropped without affecting the stream (no future frame depends on this one)

#define	AOM_FRAME_IS_INTRAONLY 0x10u
	this is an INTRA_ONLY frame

#define	AOM_FRAME_IS_SWITCH 0x20u
	this is an S-frame

#define	AOM_FRAME_IS_ERROR_RESILIENT 0x40u
	this is an error-resilient frame

#define	AOM_FRAME_IS_DELAYED_RANDOM_ACCESS_POINT 0x80u
	this is a key-frame dependent recovery-point frame

#define	aom_codec_version_major()
	Return the major version number.

#define	aom_codec_version_minor()
	Return the minor version number.

#define	aom_codec_version_patch()
	Return the patch version number.

Typedefs
typedef long	aom_codec_caps_t
	Codec capabilities bitfield.

typedef long	aom_codec_flags_t
	Initialization-time Feature Enabling.

typedef int64_t	aom_codec_pts_t
	Time Stamp Type.

typedef const struct aom_codec_iface	aom_codec_iface_t
	Codec interface structure.

typedef struct aom_codec_priv	aom_codec_priv_t
	Codec private data structure.

typedef uint32_t	aom_codec_frame_flags_t
	Compressed Frame Flags.

typedef const void *	aom_codec_iter_t
	Iterator.

typedef struct aom_codec_ctx	aom_codec_ctx_t
	Codec context structure.

typedef enum aom_bit_depth	aom_bit_depth_t
	Bit depth for codec This enumeration determines the bit depth of the codec.

typedef enum aom_superblock_size	aom_superblock_size_t
	Superblock size selection.

Enumerations
enum	aom_codec_err_t { AOM_CODEC_OK , AOM_CODEC_ERROR , AOM_CODEC_MEM_ERROR , AOM_CODEC_ABI_MISMATCH , AOM_CODEC_INCAPABLE , AOM_CODEC_UNSUP_BITSTREAM , AOM_CODEC_UNSUP_FEATURE , AOM_CODEC_CORRUPT_FRAME , AOM_CODEC_INVALID_PARAM , AOM_CODEC_LIST_END }
	Algorithm return codes. More...

enum	aom_bit_depth { AOM_BITS_8 = 8 , AOM_BITS_10 = 10 , AOM_BITS_12 = 12 }
	Bit depth for codec This enumeration determines the bit depth of the codec. More...

enum	aom_superblock_size { AOM_SUPERBLOCK_SIZE_64X64 , AOM_SUPERBLOCK_SIZE_128X128 , AOM_SUPERBLOCK_SIZE_DYNAMIC }
	Superblock size selection. More...

enum	OBU_TYPE { OBU_SEQUENCE_HEADER = 1 , OBU_TEMPORAL_DELIMITER = 2 , OBU_FRAME_HEADER = 3 , OBU_TILE_GROUP = 4 , OBU_METADATA = 5 , OBU_FRAME = 6 , OBU_REDUNDANT_FRAME_HEADER = 7 , OBU_TILE_LIST = 8 , OBU_PADDING = 15 }
	OBU types.

enum	OBU_METADATA_TYPE { OBU_METADATA_TYPE_AOM_RESERVED_0 = 0 , OBU_METADATA_TYPE_HDR_CLL = 1 , OBU_METADATA_TYPE_HDR_MDCV = 2 , OBU_METADATA_TYPE_SCALABILITY = 3 , OBU_METADATA_TYPE_ITUT_T35 = 4 , OBU_METADATA_TYPE_TIMECODE = 5 }
	OBU metadata types.

Functions
int	aom_codec_version (void)
	Return the version information (as an integer)

const char *	aom_codec_version_str (void)
	Return the version information (as a string)

const char *	aom_codec_version_extra_str (void)
	Return the version information (as a string)

const char *	aom_codec_build_config (void)
	Return the build configuration.

const char *	aom_codec_iface_name (aom_codec_iface_t *iface)
	Return the name for a given interface.

const char *	aom_codec_err_to_string (aom_codec_err_t err)
	Convert error number to printable string.

const char *	aom_codec_error (const aom_codec_ctx_t *ctx)
	Retrieve error synopsis for codec context.

const char *	aom_codec_error_detail (const aom_codec_ctx_t *ctx)
	Retrieve detailed error information for codec context.

aom_codec_err_t	aom_codec_destroy (aom_codec_ctx_t *ctx)
	Destroy a codec instance.

aom_codec_caps_t	aom_codec_get_caps (aom_codec_iface_t *iface)
	Get the capabilities of an algorithm.

const char *	aom_obu_type_to_string (OBU_TYPE type)
	Returns string representation of OBU_TYPE.

Codec Control
The aom_codec_control function exchanges algorithm specific data with the codec instance. Additionally, the macro AOM_CODEC_CONTROL_TYPECHECKED is provided, which will type-check the parameter against the control ID before calling aom_codec_control - note that this macro requires the control ID to be directly encoded in it, e.g., AOM_CODEC_CONTROL_TYPECHECKED(&ctx, AOME_SET_CPUUSED, 8). The codec control IDs can be found in aom.h, aomcx.h, and aomdx.h (defined as aom_com_control_id, aome_enc_control_id, and aom_dec_control_id).
aom_codec_err_t	aom_codec_control (aom_codec_ctx_t *ctx, int ctrl_id,...)
	Algorithm Control.

aom_codec_err_t	aom_codec_set_option (aom_codec_ctx_t ctx, const char name, const char *value)
	Key & Value API.

#define	AOM_CODEC_CONTROL_TYPECHECKED(ctx, id, data)
	aom_codec_control wrapper macro (adds type-checking, less flexible)

#define	AOM_CTRL_USE_TYPE(id, typ)
	Creates type checking mechanisms for aom_codec_control.

Detailed Description

This abstraction allows applications to easily support multiple video formats with minimal code duplication. This section describes the interface common to all codecs (both encoders and decoders).

Macro Definition Documentation

◆ AOM_DECLSPEC_DEPRECATED

#define AOM_DECLSPEC_DEPRECATED

Decorator indicating a function is deprecated.

◆ AOM_CODEC_CAP_DECODER

#define AOM_CODEC_CAP_DECODER 0x1

Is a decoder

◆ AOM_CODEC_CAP_ENCODER

#define AOM_CODEC_CAP_ENCODER 0x2

Is an encoder

◆ AOM_CODEC_USE_EXPERIMENTAL

#define AOM_CODEC_USE_EXPERIMENTAL 0x1

Enables experimental features

◆ AOM_FRAME_IS_KEY

#define AOM_FRAME_IS_KEY 0x1u

frame is the start of a GOP

◆ aom_codec_version_major

#define aom_codec_version_major ( )

Value:

((aom_codec_version() >> 16) & 0xff)

aom_codec_version

int aom_codec_version(void)

Return the version information (as an integer)

Return the major version number.

◆ aom_codec_version_minor

#define aom_codec_version_minor ( )

Value:

((aom_codec_version() >> 8) & 0xff)

Return the minor version number.

◆ aom_codec_version_patch

#define aom_codec_version_patch ( )

Value:

((aom_codec_version() >> 0) & 0xff)

Return the patch version number.

◆ AOM_CODEC_CONTROL_TYPECHECKED

#define AOM_CODEC_CONTROL_TYPECHECKED	(	ctx,
		id,
		data )

aom_codec_control wrapper macro (adds type-checking, less flexible)

This macro allows for type safe conversions across the variadic parameter to aom_codec_control(). However, it requires the explicit control ID be passed in (it cannot be passed in via a variable) – otherwise a compiler error will occur. After the type checking, it calls aom_codec_control.

◆ AOM_CTRL_USE_TYPE

#define AOM_CTRL_USE_TYPE	(		id,
			typ )

Value:

  static aom_codec_err_t aom_codec_control_typechecked_##id( \
      aom_codec_ctx_t *, int, typ) AOM_UNUSED;               \
  static aom_codec_err_t aom_codec_control_typechecked_##id( \
      aom_codec_ctx_t *ctx, int ctrl, typ data) {            \
    return aom_codec_control(ctx, ctrl, data);               \
  }                                    \
  typedef typ aom_codec_control_type_##id;

Creates type checking mechanisms for aom_codec_control.

It defines a static function with the correctly typed arguments as a wrapper to the type-unsafe aom_codec_control function. It also creates a typedef for each type.

Typedef Documentation

◆ aom_codec_caps_t

typedef long aom_codec_caps_t

Codec capabilities bitfield.

Each codec advertises the capabilities it supports as part of its aom_codec_iface_t interface structure. Capabilities are extra interfaces or functionality, and are not required to be supported.

The available flags are specified by AOM_CODEC_CAP_* defines.

◆ aom_codec_flags_t

typedef long aom_codec_flags_t

Initialization-time Feature Enabling.

Certain codec features must be known at initialization time, to allow for proper memory allocation.

The available flags are specified by AOM_CODEC_USE_* defines. The bits are allocated as follows: 0x1 - 0x80: codec (common to decoder and encoder) 0x100 - 0x8000: decoder 0x10000 - 0x800000: encoder

◆ aom_codec_pts_t

typedef int64_t aom_codec_pts_t

Time Stamp Type.

An integer, which when multiplied by the stream's time base, provides the absolute time of a sample.

◆ aom_codec_iface_t

typedef const struct aom_codec_iface aom_codec_iface_t

Codec interface structure.

Contains function pointers and other data private to the codec implementation. This structure is opaque to the application. Common functions used with this structure:

aom_codec_iface_name(aom_codec_iface_t *iface): get the name of the codec
aom_codec_get_caps(aom_codec_iface_t *iface): returns the capabilities of the codec
aom_codec_enc_config_default: generate the default config for initializing the encoder (see documentation in aom_encoder.h)
aom_codec_dec_init, aom_codec_enc_init: initialize the codec context structure (see documentation on aom_codec_ctx).

To get access to the AV1 encoder and decoder, use aom_codec_av1_cx() and aom_codec_av1_dx().

◆ aom_codec_priv_t

typedef struct aom_codec_priv aom_codec_priv_t

Codec private data structure.

Contains data private to the codec implementation. This structure is opaque to the application.

◆ aom_codec_frame_flags_t

typedef uint32_t aom_codec_frame_flags_t

Compressed Frame Flags.

This type represents a bitfield containing information about a compressed frame that may be useful to an application. The most significant 16 bits can be used by an algorithm to provide additional detail, for example to support frame types that are codec specific (MPEG-1 D-frames for example)

◆ aom_codec_iter_t

typedef const void* aom_codec_iter_t

Iterator.

Opaque storage used for iterating over lists.

◆ aom_codec_ctx_t

typedef struct aom_codec_ctx aom_codec_ctx_t

Codec context structure.

All codecs MUST support this context structure fully. In general, this data should be considered private to the codec algorithm, and not be manipulated or examined by the calling application. Applications may reference the 'name' member to get a printable description of the algorithm.

◆ aom_superblock_size_t

typedef enum aom_superblock_size aom_superblock_size_t

Superblock size selection.

Defines the superblock size used for encoding. The superblock size can either be fixed at 64x64 or 128x128 pixels, or it can be dynamically selected by the encoder for each frame.

Enumeration Type Documentation

◆ aom_codec_err_t

enum aom_codec_err_t

Algorithm return codes.

Enumerator
AOM_CODEC_OK	Operation completed without error.
AOM_CODEC_ERROR	Unspecified error.
AOM_CODEC_MEM_ERROR	Memory operation failed.
AOM_CODEC_ABI_MISMATCH	ABI version mismatch.
AOM_CODEC_INCAPABLE	Algorithm does not have required capability.
AOM_CODEC_UNSUP_BITSTREAM	The given bitstream is not supported. The bitstream was unable to be parsed at the highest level. The decoder is unable to proceed. This error SHOULD be treated as fatal to the stream.
AOM_CODEC_UNSUP_FEATURE	Encoded bitstream uses an unsupported feature. The decoder does not implement a feature required by the encoder. This return code should only be used for features that prevent future pictures from being properly decoded. This error MAY be treated as fatal to the stream or MAY be treated as fatal to the current GOP.
AOM_CODEC_CORRUPT_FRAME	The coded data for this stream is corrupt or incomplete. There was a problem decoding the current frame. This return code should only be used for failures that prevent future pictures from being properly decoded. This error MAY be treated as fatal to the stream or MAY be treated as fatal to the current GOP. If decoding is continued for the current GOP, artifacts may be present.
AOM_CODEC_INVALID_PARAM	An application-supplied parameter is not valid.
AOM_CODEC_LIST_END	An iterator reached the end of list.

◆ aom_bit_depth

enum aom_bit_depth

Bit depth for codec

This enumeration determines the bit depth of the codec.

Enumerator
AOM_BITS_8	8 bits
AOM_BITS_10	10 bits
AOM_BITS_12	12 bits

◆ aom_superblock_size

enum aom_superblock_size

Superblock size selection.

Defines the superblock size used for encoding. The superblock size can either be fixed at 64x64 or 128x128 pixels, or it can be dynamically selected by the encoder for each frame.

Enumerator
AOM_SUPERBLOCK_SIZE_64X64	Always use 64x64 superblocks.
AOM_SUPERBLOCK_SIZE_128X128	Always use 128x128 superblocks.
AOM_SUPERBLOCK_SIZE_DYNAMIC	Select superblock size dynamically.

Function Documentation

◆ aom_codec_version()

int aom_codec_version ( void )

Return the version information (as an integer)

Returns a packed encoding of the library version number. This will only include the major.minor.patch component of the version number. Note that this encoded value should be accessed through the macros provided, as the encoding may change in the future.

◆ aom_codec_version_str()

const char * aom_codec_version_str ( void )

Return the version information (as a string)

Returns a printable string containing the full library version number. This may contain additional text following the three digit version number, as to indicate release candidates, pre-release versions, etc.

◆ aom_codec_version_extra_str()

const char * aom_codec_version_extra_str ( void )

Return the version information (as a string)

Returns a printable "extra string". This is the component of the string returned by aom_codec_version_str() following the three digit version number.

◆ aom_codec_build_config()

const char * aom_codec_build_config ( void )

Return the build configuration.

Returns a printable string containing an encoded version of the build configuration. This may be useful to aom support.

◆ aom_codec_iface_name()

const char * aom_codec_iface_name ( aom_codec_iface_t * iface )

Return the name for a given interface.

Returns a human readable string for name of the given codec interface.

Parameters

[in] iface Interface pointer

◆ aom_codec_err_to_string()

const char * aom_codec_err_to_string ( aom_codec_err_t err )

Convert error number to printable string.

Returns a human readable string for the last error returned by the algorithm. The returned error will be one line and will not contain any newline characters.

Parameters

[in] err Error number.

◆ aom_codec_error()

const char * aom_codec_error ( const aom_codec_ctx_t * ctx )

Retrieve error synopsis for codec context.

Returns a human readable string for the last error returned by the algorithm. The returned error will be one line and will not contain any newline characters.

Parameters

[in] ctx Pointer to this instance's context.

◆ aom_codec_error_detail()

const char * aom_codec_error_detail ( const aom_codec_ctx_t * ctx )

Retrieve detailed error information for codec context.

Returns a human readable string providing detailed information about the last error. The returned string is only valid until the next aom_codec_* function call (except aom_codec_error and aom_codec_error_detail) on the codec context.

Parameters

[in] ctx Pointer to this instance's context.

Return values

NULL	No detailed information is available.

◆ aom_codec_destroy()

aom_codec_err_t aom_codec_destroy ( aom_codec_ctx_t * ctx )

Destroy a codec instance.

Destroys a codec context, freeing any associated memory buffers.

Parameters

[in] ctx Pointer to this instance's context

Return values

AOM_CODEC_OK	The codec instance has been destroyed.
AOM_CODEC_INVALID_PARAM	ctx is a null pointer.
AOM_CODEC_ERROR	Codec context not initialized.

◆ aom_codec_get_caps()

aom_codec_caps_t aom_codec_get_caps ( aom_codec_iface_t * iface )

Get the capabilities of an algorithm.

Retrieves the capabilities bitfield from the algorithm's interface.

Parameters

[in] iface Pointer to the algorithm interface

◆ aom_codec_control()

aom_codec_err_t aom_codec_control	(	aom_codec_ctx_t *	ctx,
		int	ctrl_id,
			... )

Algorithm Control.

aom_codec_control takes a context, a control ID, and a third parameter (with varying type). If the context is non-null and an error occurs, ctx->err will be set to the same value as the return value.

Parameters

[in]	ctx	Pointer to this instance's context
[in]	ctrl_id	Algorithm specific control identifier. Must be nonzero.

Return values

AOM_CODEC_OK	The control request was processed.
AOM_CODEC_ERROR	The control request was not processed.
AOM_CODEC_INVALID_PARAM	The control ID was zero, or the data was not valid.

◆ 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_set_option() takes a context, a key (option name) and a value. If the context is non-null and an error occurs, ctx->err will be set to the same value as the return value.

Parameters

[in]	ctx	Pointer to this instance's context
[in]	name	The name of the option (key)
[in]	value	The value of the option

Return values

AOM_CODEC_OK	The value of the option was set.
AOM_CODEC_INVALID_PARAM	The data was not valid.
AOM_CODEC_ERROR	The option was not successfully set.

◆ aom_obu_type_to_string()

const char * aom_obu_type_to_string ( OBU_TYPE type )

Returns string representation of OBU_TYPE.

Parameters

[in] type The OBU_TYPE to convert to string.

Topics

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Codec Control

Detailed Description

Macro Definition Documentation

◆ AOM_DECLSPEC_DEPRECATED

◆ AOM_CODEC_CAP_DECODER

◆ AOM_CODEC_CAP_ENCODER

◆ AOM_CODEC_USE_EXPERIMENTAL

◆ AOM_FRAME_IS_KEY

◆ aom_codec_version_major

◆ aom_codec_version_minor

◆ aom_codec_version_patch

◆ AOM_CODEC_CONTROL_TYPECHECKED

◆ AOM_CTRL_USE_TYPE

Typedef Documentation

◆ aom_codec_caps_t

◆ aom_codec_flags_t

◆ aom_codec_pts_t

◆ aom_codec_iface_t

◆ aom_codec_priv_t

◆ aom_codec_frame_flags_t

◆ aom_codec_iter_t

◆ aom_codec_ctx_t

◆ aom_superblock_size_t

Enumeration Type Documentation

◆ aom_codec_err_t

◆ aom_bit_depth

◆ aom_superblock_size

Function Documentation

◆ aom_codec_version()

◆ aom_codec_version_str()

◆ aom_codec_version_extra_str()

◆ aom_codec_build_config()

◆ aom_codec_iface_name()

◆ aom_codec_err_to_string()

◆ aom_codec_error()

◆ aom_codec_error_detail()

◆ aom_codec_destroy()

◆ aom_codec_get_caps()

◆ aom_codec_control()

◆ aom_codec_set_option()

◆ aom_obu_type_to_string()