AOMedia Codec SDK
Modules | Files | Data Structures | Macros | Typedefs | Enumerations | Functions
Common Algorithm Interface

Modules

 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...
 
struct  cfg_options
 Config Options. More...
 

Macros

#define AOM_DEPRECATED
 Decorator indicating a function is deprecated.
 
#define AOM_DECLSPEC_DEPRECATED
 Decorator indicating a function is deprecated. More...
 
#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_VERSION_MAJOR(v)   ((v >> 16) & 0xff)
 
#define AOM_VERSION_MINOR(v)   ((v >> 8) & 0xff)
 
#define AOM_VERSION_PATCH(v)   ((v >> 0) & 0xff)
 
#define aom_codec_version_major()   ((aom_codec_version() >> 16) & 0xff)
 Return the version major number.
 
#define aom_codec_version_minor()   ((aom_codec_version() >> 8) & 0xff)
 Return the version minor number.
 
#define aom_codec_version_patch()   ((aom_codec_version() >> 0) & 0xff)
 Return the version patch number.
 
#define aom_codec_control(ctx, id, data)
 aom_codec_control wrapper macro More...
 
#define AOM_CTRL_USE_TYPE(id, typ)
 aom_codec_control type definition macro More...
 
#define AOM_CTRL_USE_TYPE_DEPRECATED(id, typ)
 aom_codec_control deprecated type definition macro More...
 
#define AOM_CTRL_VOID(id)
 aom_codec_control void type definition macro More...
 

Typedefs

typedef long aom_codec_caps_t
 Codec capabilities bitfield. More...
 
typedef long aom_codec_flags_t
 Initialization-time Feature Enabling. More...
 
typedef const struct
aom_codec_iface 
aom_codec_iface_t
 Codec interface structure. More...
 
typedef struct aom_codec_priv aom_codec_priv_t
 Codec private data structure. More...
 
typedef const void * aom_codec_iter_t
 Iterator. More...
 
typedef struct aom_codec_ctx aom_codec_ctx_t
 Codec context structure. More...
 
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. More...
 
typedef struct cfg_options cfg_options_t
 Config Options. More...
 

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) More...
 
const char * aom_codec_version_str (void)
 Return the version information (as a string) More...
 
const char * aom_codec_version_extra_str (void)
 Return the version information (as a string) More...
 
const char * aom_codec_build_config (void)
 Return the build configuration. More...
 
const char * aom_codec_iface_name (aom_codec_iface_t *iface)
 Return the name for a given interface. More...
 
const char * aom_codec_err_to_string (aom_codec_err_t err)
 Convert error number to printable string. More...
 
const char * aom_codec_error (aom_codec_ctx_t *ctx)
 Retrieve error synopsis for codec context. More...
 
const char * aom_codec_error_detail (aom_codec_ctx_t *ctx)
 Retrieve detailed error information for codec context. More...
 
aom_codec_err_t aom_codec_destroy (aom_codec_ctx_t *ctx)
 Destroy a codec instance. More...
 
aom_codec_caps_t aom_codec_get_caps (aom_codec_iface_t *iface)
 Get the capabilities of an algorithm. More...
 
aom_codec_err_t aom_codec_control_ (aom_codec_ctx_t *ctx, int ctrl_id,...)
 Control algorithm. More...
 
const char * aom_obu_type_to_string (OBU_TYPE type)
 Returns string representation of OBU_TYPE. More...
 

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

#define AOM_DECLSPEC_DEPRECATED

Decorator indicating a function is deprecated.

#define AOM_CODEC_CAP_DECODER   0x1

Is a decoder

#define AOM_CODEC_CAP_ENCODER   0x2

Is an encoder

#define AOM_VERSION_MAJOR (   v)    ((v >> 16) & 0xff)

extract major from packed version

#define AOM_VERSION_MINOR (   v)    ((v >> 8) & 0xff)

extract minor from packed version

#define AOM_VERSION_PATCH (   v)    ((v >> 0) & 0xff)

extract patch from packed version

#define aom_codec_control (   ctx,
  id,
  data 
)

aom_codec_control wrapper macro

This macro allows for type safe conversions across the variadic parameter to aom_codec_control_().

#define AOM_CTRL_USE_TYPE (   id,
  typ 
)

aom_codec_control type definition macro

This macro allows for type safe conversions across the variadic parameter to aom_codec_control_(). It defines the type of the argument for a given control identifier.

#define AOM_CTRL_USE_TYPE_DEPRECATED (   id,
  typ 
)

aom_codec_control deprecated type definition macro

Like AOM_CTRL_USE_TYPE, but indicates that the specified control is deprecated and should not be used. Consult the documentation for your codec for more information.

#define AOM_CTRL_VOID (   id)

aom_codec_control void type definition macro

This macro allows for type safe conversions across the variadic parameter to aom_codec_control_(). It indicates that a given control identifier takes no argument.

Typedef Documentation

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.

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.

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.

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.

typedef const void* aom_codec_iter_t

Iterator.

Opaque storage used for iterating over lists.

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.

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.

typedef struct cfg_options cfg_options_t

Config Options.

This type allows to enumerate and control options defined for control via config file at runtime.

Enumeration Type Documentation

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.

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

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

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.

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, prerelease versions, etc.

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.

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.

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]ifaceInterface pointer
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]errError number.
const char* aom_codec_error ( 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]ctxPointer to this instance's context.
const char* aom_codec_error_detail ( aom_codec_ctx_t ctx)

Retrieve detailed error information for codec context.

Returns a human readable string providing detailed information about the last error.

Parameters
[in]ctxPointer to this instance's context.
Return values
NULLNo detailed information is available.
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]ctxPointer to this instance's context
Return values
AOM_CODEC_OKThe codec algorithm initialized.
AOM_CODEC_MEM_ERRORMemory allocation failed.
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]ifacePointer to the algorithm interface
aom_codec_err_t aom_codec_control_ ( aom_codec_ctx_t ctx,
int  ctrl_id,
  ... 
)

Control algorithm.

This function is used to exchange algorithm specific data with the codec instance. This can be used to implement features specific to a particular algorithm.

This wrapper function dispatches the request to the helper function associated with the given ctrl_id. It tries to call this function transparently, but will return AOM_CODEC_ERROR if the request could not be dispatched.

Note that this function should not be used directly. Call the aom_codec_control wrapper macro instead.

Parameters
[in]ctxPointer to this instance's context
[in]ctrl_idAlgorithm specific control identifier
Return values
AOM_CODEC_OKThe control request was processed.
AOM_CODEC_ERRORThe control request was not processed.
AOM_CODEC_INVALID_PARAMThe data was not valid.
const char* aom_obu_type_to_string ( OBU_TYPE  type)

Returns string representation of OBU_TYPE.

Parameters
[in]typeThe OBU_TYPE to convert to string.