AOMedia Codec SDK: aom/aom_image.h File Reference

AOMedia Codec SDK

Data Structures | Macros | Typedefs | Enumerations | Functions
aom_image.h File Reference

Describes the aom image descriptor and associated operations. More...

`#include "aom/aom_integer.h"`

Go to the source code of this file.

## Data Structures
struct | aom_metadata
| Metadata payload. More...
struct | aom_image
| Image Descriptor. More...
struct | aom_image_rect
| Representation of a rectangle on a surface. More...

## Macros
#define | AOM_IMAGE_ABI_VERSION
| Current ABI version number.
#define | AOM_IMG_FMT_PLANAR 0x100
#define | AOM_IMG_FMT_UV_FLIP 0x200
#define | AOM_IMG_FMT_HIGHBITDEPTH 0x800
#define | AOM_PLANE_PACKED 0
#define | AOM_PLANE_Y 0
#define | AOM_PLANE_U 1
#define | AOM_PLANE_V 2

## Typedefs
typedef enum aom_img_fmt | aom_img_fmt_t
| List of supported image formats. More...
typedef enum aom_color_primaries | aom_color_primaries_t
| List of supported color primaries. More...
typedef enum aom_transfer_characteristics | aom_transfer_characteristics_t
| List of supported transfer functions. More...
typedef enum aom_matrix_coefficients | aom_matrix_coefficients_t
| List of supported matrix coefficients.
typedef enum aom_color_range | aom_color_range_t
| List of supported color range. More...
typedef enum aom_chroma_sample_position | aom_chroma_sample_position_t
| List of chroma sample positions. More...
typedef struct aom_metadata_array | aom_metadata_array_t
| Array of aom_metadata structs for an image.
typedef struct aom_metadata | aom_metadata_t
| Metadata payload.
typedef struct aom_image | aom_image_t
| Image Descriptor. More...
typedef struct aom_image_rect | aom_image_rect_t
| Representation of a rectangle on a surface. More...

## Enumerations
enum | aom_img_fmt { AOM_IMG_FMT_NONE, AOM_IMG_FMT_YV12, AOM_IMG_FMT_I420 = 0x100 | 2, AOM_IMG_FMT_AOMYV12, AOM_IMG_FMT_AOMI420 = 0x100 | 4, AOM_IMG_FMT_I422 = 0x100 | 5, AOM_IMG_FMT_I444 = 0x100 | 6, AOM_IMG_FMT_I42016 = AOM_IMG_FMT_I420 | 0x800, AOM_IMG_FMT_YV1216 = AOM_IMG_FMT_YV12 | 0x800, AOM_IMG_FMT_I42216 = AOM_IMG_FMT_I422 | 0x800, AOM_IMG_FMT_I44416 = AOM_IMG_FMT_I444 | 0x800 }
| List of supported image formats. More...
enum | aom_color_primaries { AOM_CICP_CP_RESERVED_0 = 0, AOM_CICP_CP_BT_709 = 1, AOM_CICP_CP_UNSPECIFIED = 2, AOM_CICP_CP_RESERVED_3 = 3, AOM_CICP_CP_BT_470_M = 4, AOM_CICP_CP_BT_470_B_G = 5, AOM_CICP_CP_BT_601 = 6, AOM_CICP_CP_SMPTE_240 = 7, AOM_CICP_CP_GENERIC_FILM, AOM_CICP_CP_BT_2020 = 9, AOM_CICP_CP_XYZ = 10, AOM_CICP_CP_SMPTE_431 = 11, AOM_CICP_CP_SMPTE_432 = 12, AOM_CICP_CP_RESERVED_13 = 13, AOM_CICP_CP_EBU_3213 = 22, AOM_CICP_CP_RESERVED_23 = 23 }
| List of supported color primaries. More...
enum | aom_transfer_characteristics { AOM_CICP_TC_RESERVED_0 = 0, AOM_CICP_TC_BT_709 = 1, AOM_CICP_TC_UNSPECIFIED = 2, AOM_CICP_TC_RESERVED_3 = 3, AOM_CICP_TC_BT_470_M = 4, AOM_CICP_TC_BT_470_B_G = 5, AOM_CICP_TC_BT_601 = 6, AOM_CICP_TC_SMPTE_240 = 7, AOM_CICP_TC_LINEAR = 8, AOM_CICP_TC_LOG_100 = 9, AOM_CICP_TC_LOG_100_SQRT10, AOM_CICP_TC_IEC_61966 = 11, AOM_CICP_TC_BT_1361 = 12, AOM_CICP_TC_SRGB = 13, AOM_CICP_TC_BT_2020_10_BIT = 14, AOM_CICP_TC_BT_2020_12_BIT = 15, AOM_CICP_TC_SMPTE_2084 = 16, AOM_CICP_TC_SMPTE_428 = 17, AOM_CICP_TC_HLG = 18, AOM_CICP_TC_RESERVED_19 = 19 }
| List of supported transfer functions. More...
enum | aom_matrix_coefficients { AOM_CICP_MC_IDENTITY = 0, AOM_CICP_MC_BT_709 = 1, AOM_CICP_MC_UNSPECIFIED = 2, AOM_CICP_MC_RESERVED_3 = 3, AOM_CICP_MC_FCC = 4, AOM_CICP_MC_BT_470_B_G = 5, AOM_CICP_MC_BT_601 = 6, AOM_CICP_MC_SMPTE_240 = 7, AOM_CICP_MC_SMPTE_YCGCO = 8, AOM_CICP_MC_BT_2020_NCL, AOM_CICP_MC_BT_2020_CL = 10, AOM_CICP_MC_SMPTE_2085 = 11, AOM_CICP_MC_CHROMAT_NCL, AOM_CICP_MC_CHROMAT_CL = 13, AOM_CICP_MC_ICTCP = 14, AOM_CICP_MC_RESERVED_15 = 15 }
| List of supported matrix coefficients. More...
enum | aom_color_range { AOM_CR_STUDIO_RANGE = 0, AOM_CR_FULL_RANGE = 1 }
| List of supported color range. More...
enum | aom_chroma_sample_position { AOM_CSP_UNKNOWN = 0, AOM_CSP_VERTICAL = 1, AOM_CSP_COLOCATED = 2, AOM_CSP_RESERVED = 3 }
| List of chroma sample positions. More...

## Functions
aom_image_t * | aom_img_alloc (aom_image_t *img, aom_img_fmt_t fmt, unsigned int d_w, unsigned int d_h, unsigned int align)
| Open a descriptor, allocating storage for the underlying image. More...
aom_image_t * | aom_img_wrap (aom_image_t *img, aom_img_fmt_t fmt, unsigned int d_w, unsigned int d_h, unsigned int align, unsigned char *img_data)
| Open a descriptor, using existing storage for the underlying image. More...
aom_image_t * | aom_img_alloc_with_border (aom_image_t *img, aom_img_fmt_t fmt, unsigned int d_w, unsigned int d_h, unsigned int align, unsigned int size_align, unsigned int border)
| Open a descriptor, allocating storage for the underlying image with a border. More...
int | aom_img_set_rect (aom_image_t *img, unsigned int x, unsigned int y, unsigned int w, unsigned int h, unsigned int border)
| Set the rectangle identifying the displayed portion of the image. More...
void | aom_img_flip (aom_image_t *img)
| Flip the image vertically (top for bottom) More...
void | aom_img_free (aom_image_t *img)
| Close an image descriptor. More...
int | aom_img_plane_width (const aom_image_t *img, int plane)
| Get the width of a plane. More...
int | aom_img_plane_height (const aom_image_t *img, int plane)
| Get the height of a plane. More...
int | aom_img_add_metadata (aom_image_t *img, uint32_t type, const uint8_t *data, size_t sz)
| Add metadata to image. More...
void | aom_img_remove_metadata (aom_image_t *img)
| Remove metadata from image. More...
aom_metadata_t * | aom_img_metadata_alloc (uint32_t type, const uint8_t *data, size_t sz)
| Allocate memory for aom_metadata struct. More...
void | aom_img_metadata_free (aom_metadata_t *metadata)
| Free metadata struct. More...

## Detailed Description

Describes the aom image descriptor and associated operations.

## Macro Definition Documentation

## ◆ AOM_IMG_FMT_PLANAR

#define AOM_IMG_FMT_PLANAR 0x100

Image is a planar format.

## ◆ AOM_IMG_FMT_UV_FLIP

#define AOM_IMG_FMT_UV_FLIP 0x200

V plane precedes U in memory.

## ◆ AOM_IMG_FMT_HIGHBITDEPTH

#define AOM_IMG_FMT_HIGHBITDEPTH 0x800

0x400 used to signal alpha channel, skipping for backwards compatibility. Image uses 16bit framebuffer.

## ◆ AOM_PLANE_PACKED

#define AOM_PLANE_PACKED 0

To be used for all packed formats

## ◆ AOM_PLANE_Y

#define AOM_PLANE_Y 0

Y (Luminance) plane

## ◆ AOM_PLANE_U

#define AOM_PLANE_U 1

U (Chroma) plane

## ◆ AOM_PLANE_V

#define AOM_PLANE_V 2

V (Chroma) plane

## Typedef Documentation

## ◆ aom_img_fmt_t

typedef enum aom_img_fmt aom_img_fmt_t

List of supported image formats.

alias for enum aom_img_fmt

## ◆ aom_color_primaries_t

typedef enum aom_color_primaries aom_color_primaries_t

List of supported color primaries.

alias for enum aom_color_primaries

## ◆ aom_transfer_characteristics_t

typedef enum aom_transfer_characteristics aom_transfer_characteristics_t

List of supported transfer functions.

alias for enum aom_transfer_function

## ◆ aom_color_range_t

typedef enum aom_color_range aom_color_range_t

List of supported color range.

alias for enum aom_color_range

## ◆ aom_chroma_sample_position_t

typedef enum aom_chroma_sample_position aom_chroma_sample_position_t

List of chroma sample positions.

alias for enum aom_transfer_function

## ◆ aom_image_t

typedef struct aom_image aom_image_t

Image Descriptor.

alias for struct aom_image

## ◆ aom_image_rect_t

typedef struct aom_image_rect aom_image_rect_t

Representation of a rectangle on a surface.

alias for struct aom_image_rect

## Enumeration Type Documentation

## ◆ aom_img_fmt

enum aom_img_fmt

List of supported image formats.

Enumerator
AOM_IMG_FMT_YV12 | Image is a planar format. V plane precedes U in memory. planar YVU
AOM_IMG_FMT_I420 | Image is a planar format.
AOM_IMG_FMT_AOMYV12 | Image is a planar format. V plane precedes U in memory.
AOM_IMG_FMT_AOMI420 | < planar 4:2:0 format with aom color space Image is a planar format.
AOM_IMG_FMT_I422 | Image is a planar format.
AOM_IMG_FMT_I444 | Image is a planar format.
AOM_IMG_FMT_I42016 | Image uses 16bit framebuffer.
AOM_IMG_FMT_YV1216 | Image uses 16bit framebuffer.
AOM_IMG_FMT_I42216 | Image uses 16bit framebuffer.
AOM_IMG_FMT_I44416 | Image uses 16bit framebuffer.

## ◆ aom_color_primaries

enum aom_color_primaries

List of supported color primaries.

Enumerator
AOM_CICP_CP_RESERVED_0 | For future use
AOM_CICP_CP_BT_709 | BT.709
AOM_CICP_CP_UNSPECIFIED | Unspecified
AOM_CICP_CP_RESERVED_3 | For future use
AOM_CICP_CP_BT_470_M | BT.470 System M (historical)
AOM_CICP_CP_BT_470_B_G | BT.470 System B, G (historical)
AOM_CICP_CP_BT_601 | BT.601
AOM_CICP_CP_SMPTE_240 | SMPTE 240
AOM_CICP_CP_GENERIC_FILM | Generic film (color filters using illuminant C)
AOM_CICP_CP_BT_2020 | BT.2020, BT.2100
AOM_CICP_CP_XYZ | SMPTE 428 (CIE 1921 XYZ)
AOM_CICP_CP_SMPTE_431 | SMPTE RP 431-2
AOM_CICP_CP_SMPTE_432 | SMPTE EG 432-1
AOM_CICP_CP_RESERVED_13 | For future use (values 13 - 21)
AOM_CICP_CP_EBU_3213 | EBU Tech. 3213-E
AOM_CICP_CP_RESERVED_23 | For future use (values 23 - 255)

## ◆ aom_transfer_characteristics

enum aom_transfer_characteristics

List of supported transfer functions.

Enumerator
AOM_CICP_TC_RESERVED_0 | For future use
AOM_CICP_TC_BT_709 | BT.709
AOM_CICP_TC_UNSPECIFIED | Unspecified
AOM_CICP_TC_RESERVED_3 | For future use
AOM_CICP_TC_BT_470_M | BT.470 System M (historical)
AOM_CICP_TC_BT_470_B_G | BT.470 System B, G (historical)
AOM_CICP_TC_BT_601 | BT.601
AOM_CICP_TC_SMPTE_240 | SMPTE 240 M
AOM_CICP_TC_LINEAR | Linear
AOM_CICP_TC_LOG_100 | Logarithmic (100 : 1 range)
AOM_CICP_TC_LOG_100_SQRT10 | Logarithmic (100 * Sqrt(10) : 1 range)
AOM_CICP_TC_IEC_61966 | IEC 61966-2-4
AOM_CICP_TC_BT_1361 | BT.1361
AOM_CICP_TC_SRGB | sRGB or sYCC
AOM_CICP_TC_BT_2020_10_BIT | BT.2020 10-bit systems
AOM_CICP_TC_BT_2020_12_BIT | BT.2020 12-bit systems
AOM_CICP_TC_SMPTE_2084 | SMPTE ST 2084, ITU BT.2100 PQ
AOM_CICP_TC_SMPTE_428 | SMPTE ST 428
AOM_CICP_TC_HLG | BT.2100 HLG, ARIB STD-B67
AOM_CICP_TC_RESERVED_19 | For future use (values 19-255)

## ◆ aom_matrix_coefficients

enum aom_matrix_coefficients

List of supported matrix coefficients.

Enumerator
AOM_CICP_MC_IDENTITY | Identity matrix
AOM_CICP_MC_BT_709 | BT.709
AOM_CICP_MC_UNSPECIFIED | Unspecified
AOM_CICP_MC_RESERVED_3 | For future use
AOM_CICP_MC_FCC | US FCC 73.628
AOM_CICP_MC_BT_470_B_G | BT.470 System B, G (historical)
AOM_CICP_MC_BT_601 | BT.601
AOM_CICP_MC_SMPTE_240 | SMPTE 240 M
AOM_CICP_MC_SMPTE_YCGCO | YCgCo
AOM_CICP_MC_BT_2020_NCL | BT.2020 non-constant luminance, BT.2100 YCbCr
AOM_CICP_MC_BT_2020_CL | BT.2020 constant luminance
AOM_CICP_MC_SMPTE_2085 | SMPTE ST 2085 YDzDx
AOM_CICP_MC_CHROMAT_NCL | Chromaticity-derived non-constant luminance
AOM_CICP_MC_CHROMAT_CL | Chromaticity-derived constant luminance
AOM_CICP_MC_ICTCP | BT.2100 ICtCp
AOM_CICP_MC_RESERVED_15 | For future use (values 15-255)

## ◆ aom_color_range

enum aom_color_range

List of supported color range.

Enumerator
AOM_CR_STUDIO_RANGE | Y [16..235], UV [16..240]
AOM_CR_FULL_RANGE | YUV/RGB [0..255]

## ◆ aom_chroma_sample_position

enum aom_chroma_sample_position

List of chroma sample positions.

Enumerator
AOM_CSP_UNKNOWN | Unknown
AOM_CSP_VERTICAL | Horizontally co-located with luma(0, 0) sample, between two vertical samples
AOM_CSP_COLOCATED | Co-located with luma(0, 0) sample
AOM_CSP_RESERVED | Reserved value

## Function Documentation

## ◆ aom_img_alloc()

aom_image_t* aom_img_alloc | ( | aom_image_t * | img,
|  | aom_img_fmt_t | fmt,
|  | unsigned int | d_w,
|  | unsigned int | d_h,
|  | unsigned int | align
| ) |  |

Open a descriptor, allocating storage for the underlying image.

Returns a descriptor for storing an image of the given format. The storage for the image is allocated on the heap.

Parameters

  [in] | img | Pointer to storage for descriptor. If this parameter is NULL, the storage for the descriptor will be allocated on the heap.
  [in] | fmt | Format for the image
  [in] | d_w | Width of the image
  [in] | d_h | Height of the image
  [in] | align | Alignment, in bytes, of the image buffer and each row in the image (stride).

Returns
  Returns a pointer to the initialized image descriptor. If the img parameter is non-null, the value of the img parameter will be returned.

## ◆ aom_img_wrap()

aom_image_t* aom_img_wrap | ( | aom_image_t * | img,
|  | aom_img_fmt_t | fmt,
|  | unsigned int | d_w,
|  | unsigned int | d_h,
|  | unsigned int | align,
|  | unsigned char * | img_data
| ) |  |

Open a descriptor, using existing storage for the underlying image.

Returns a descriptor for storing an image of the given format. The storage for the image has been allocated elsewhere, and a descriptor is desired to "wrap" that storage.

Parameters

  [in] | img | Pointer to storage for descriptor. If this parameter is NULL, the storage for the descriptor will be allocated on the heap.
  [in] | fmt | Format for the image
  [in] | d_w | Width of the image
  [in] | d_h | Height of the image
  [in] | align | Alignment, in bytes, of each row in the image (stride).
  [in] | img_data | Storage to use for the image

Returns
  Returns a pointer to the initialized image descriptor. If the img parameter is non-null, the value of the img parameter will be returned.

## ◆ aom_img_alloc_with_border()

aom_image_t* aom_img_alloc_with_border | ( | aom_image_t * | img,
|  | aom_img_fmt_t | fmt,
|  | unsigned int | d_w,
|  | unsigned int | d_h,
|  | unsigned int | align,
|  | unsigned int | size_align,
|  | unsigned int | border
| ) |  |

Open a descriptor, allocating storage for the underlying image with a border.

Returns a descriptor for storing an image of the given format and its borders. The storage for the image is allocated on the heap.

Parameters

  [in] | img | Pointer to storage for descriptor. If this parameter is NULL, the storage for the descriptor will be allocated on the heap.
  [in] | fmt | Format for the image
  [in] | d_w | Width of the image
  [in] | d_h | Height of the image
  [in] | align | Alignment, in bytes, of the image buffer and each row in the image (stride).
  [in] | size_align | Alignment, in pixels, of the image width and height.
  [in] | border | A border that is padded on four sides of the image.

Returns
  Returns a pointer to the initialized image descriptor. If the img parameter is non-null, the value of the img parameter will be returned.

## ◆ aom_img_set_rect()

int aom_img_set_rect | ( | aom_image_t * | img,
|  | unsigned int | x,
|  | unsigned int | y,
|  | unsigned int | w,
|  | unsigned int | h,
|  | unsigned int | border
| ) |  |

Set the rectangle identifying the displayed portion of the image.

Updates the displayed rectangle (aka viewport) on the image surface to match the specified coordinates and size.

Parameters

  [in] | img | Image descriptor
  [in] | x | leftmost column
  [in] | y | topmost row
  [in] | w | width
  [in] | h | height
  [in] | border | A border that is padded on four sides of the image.

Returns
  0 if the requested rectangle is valid, nonzero otherwise.

## ◆ aom_img_flip()

void aom_img_flip | ( | aom_image_t * | img | ) |

Flip the image vertically (top for bottom)

Adjusts the image descriptor's pointers and strides to make the image be referenced upside-down.

Parameters

  [in] | img | Image descriptor

## ◆ aom_img_free()

void aom_img_free | ( | aom_image_t * | img | ) |

Close an image descriptor.

Frees all allocated storage associated with an image descriptor.

Parameters

  [in] | img | Image descriptor

## ◆ aom_img_plane_width()

int aom_img_plane_width | ( | const aom_image_t * | img,
|  | int | plane
| ) |  |

Get the width of a plane.

Get the width of a plane of an image

Parameters

  [in] | img | Image descriptor
  [in] | plane | Plane index

## ◆ aom_img_plane_height()

int aom_img_plane_height | ( | const aom_image_t * | img,
|  | int | plane
| ) |  |

Get the height of a plane.

Get the height of a plane of an image

Parameters

  [in] | img | Image descriptor
  [in] | plane | Plane index

## ◆ aom_img_add_metadata()

int aom_img_add_metadata | ( | aom_image_t * | img,
|  | uint32_t | type,
|  | const uint8_t * | data,
|  | size_t | sz
| ) |  |

Add metadata to image.

Adds metadata to aom_image_t. Function makes a copy of the provided data parameter. Currently, only ITUT T35 metadata support is implemented.

Parameters

  [in] | img | Image descriptor
  [in] | type | Metadata type
  [in] | data | Metadata contents
  [in] | sz | Metadata contents size

## ◆ aom_img_remove_metadata()

void aom_img_remove_metadata | ( | aom_image_t * | img | ) |

Remove metadata from image.

Removes all metadata in image metadata list and sets metadata list pointer to NULL.

Parameters

  [in] | img | Image descriptor

## ◆ aom_img_metadata_alloc()

aom_metadata_t* aom_img_metadata_alloc | ( | uint32_t | type,
|  | const uint8_t * | data,
|  | size_t | sz
| ) |  |

Allocate memory for aom_metadata struct.

Allocates memory for aom_metadata struct and sets its type. Optionally allocates storage for the metadata payload and copies the payload data into the aom_metadata struct:

- When sz is > 0 and data is NULL, allocates metadata payload buffer of sz.
- When sz is > 0 and data is non-NULL, a metadata payload buffer of sz is allocated and sz bytes are copied from data into the payload buffer.

Parameters

  [in] | type | Metadata type
  [in] | data | Metadata data pointer
  [in] | sz | Metadata size

## ◆ aom_img_metadata_free()

void aom_img_metadata_free | ( | aom_metadata_t * | metadata | ) |

Free metadata struct.

Free metadata struct and its buffer.

Parameters

  [in] | metadata | Metadata struct pointer