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...

## 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_HAVE_IMG_FMT_NV12 1
| Allows detection of the presence of AOM_IMG_FMT_NV12 at compile time.
#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.
typedef enum aom_color_primaries | aom_color_primaries_t
| List of supported color primaries.
typedef enum aom_transfer_characteristics | aom_transfer_characteristics_t
| List of supported transfer functions.
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.
typedef enum aom_chroma_sample_position | aom_chroma_sample_position_t
| List of chroma sample positions.
typedef enum aom_metadata_insert_flags | aom_metadata_insert_flags_t
| List of insert flags for Metadata.
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.

## Enumerations

enum

aom_img_fmt {
AOM_IMG_FMT_NONE , AOM_IMG_FMT_YV12 , AOM_IMG_FMT_I420 = 0x100 | 2 , AOM_IMG_FMT_AOMYV12 = 0x100 | 0x200 | 3 ,
AOM_IMG_FMT_AOMI420 = 0x100 | 4 , AOM_IMG_FMT_I422 = 0x100 | 5 , AOM_IMG_FMT_I444 = 0x100 | 6 , AOM_IMG_FMT_NV12 ,
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 ,
AOM_CICP_MC_IPT_C2 = 15 , AOM_CICP_MC_YCGCO_RE = 16 , AOM_CICP_MC_YCGCO_RO = 17
}

| 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...
enum | aom_metadata_insert_flags { AOM_MIF_NON_KEY_FRAME = 0 , AOM_MIF_KEY_FRAME = 1 , AOM_MIF_ANY_FRAME = 2 , AOM_MIF_NON_KEY_FRAME_LAYER_SPECIFIC = 16 , AOM_MIF_KEY_FRAME_LAYER_SPECIFIC = 17 , AOM_MIF_ANY_FRAME_LAYER_SPECIFIC = 18 }
| List of insert flags for Metadata. 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.
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 stride_align, unsigned char *img_data)
| Open a descriptor, using existing storage for the underlying image.
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.
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.
void | aom_img_flip (aom_image_t *img)
| Flip the image vertically (top for bottom).
void | aom_img_free (aom_image_t *img)
| Close an image descriptor.
int | aom_img_plane_width (const aom_image_t *img, int plane)
| Get the width of a plane.
int | aom_img_plane_height (const aom_image_t *img, int plane)
| Get the height of a plane.
int | aom_img_add_metadata (aom_image_t *img, uint32_t type, const uint8_t *data, size_t sz, aom_metadata_insert_flags_t insert_flag)
| Add metadata to image.
const aom_metadata_t * | aom_img_get_metadata (const aom_image_t *img, size_t index)
| Return a metadata payload stored within the image metadata array.
size_t | aom_img_num_metadata (const aom_image_t *img)
| Return the number of metadata blocks within the image.
void | aom_img_remove_metadata (aom_image_t *img)
| Remove metadata from image.
aom_metadata_t * | aom_img_metadata_alloc (uint32_t type, const uint8_t *data, size_t sz, aom_metadata_insert_flags_t insert_flag)
| Allocate memory for aom_metadata struct.
void | aom_img_metadata_free (aom_metadata_t *metadata)
| Free metadata struct.

## 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

Referenced by av1_apply_temporal_filter_c(), av1_interpolation_filter_search(), av1_nonrd_pick_inter_mode_sb(), av1_nonrd_pick_intra_mode(), av1_rd_pick_intra_sbuv_mode(), av1_rd_pick_intra_sby_mode(), av1_rd_pick_partition(), av1_receive_raw_frame(), fast_interp_search(), handle_inter_mode(), pick_sb_modes(), pick_sb_modes_nonrd(), prune_zero_mv_with_sse(), search_filter_ref(), and tf_setup_filtering_buffer().

## AOM_PLANE_U

#define AOM_PLANE_U 1

U (Chroma) plane

Referenced by av1_apply_temporal_filter_c(), av1_interpolation_filter_search(), av1_nonrd_pick_inter_mode_sb(), av1_rd_pick_intra_mode_sb(), av1_rd_pick_intra_sbuv_mode(), av1_search_intra_uv_modes_in_interframe(), av1_search_palette_mode(), fast_interp_search(), handle_inter_mode(), pick_sb_modes_nonrd(), and process_compound_inter_mode().

## AOM_PLANE_V

#define AOM_PLANE_V 2

V (Chroma) plane

Referenced by av1_interpolation_filter_search(), av1_nonrd_pick_inter_mode_sb(), fast_interp_search(), and pick_sb_modes_nonrd().

## 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_characteristics

## aom_matrix_coefficients_t

typedef enum aom_matrix_coefficients aom_matrix_coefficients_t

List of supported matrix coefficients.

alias for enum aom_matrix_coefficients

## 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_chroma_sample_position

## aom_metadata_insert_flags_t

typedef enum aom_metadata_insert_flags aom_metadata_insert_flags_t

List of insert flags for Metadata.

These flags control how the library treats metadata during encode.

While encoding, when metadata is added to an aom_image via aom_img_add_metadata(), the flag passed along with the metadata will determine where the metadata OBU will be placed in the encoded OBU stream, and whether it's layer-specific. Metadata will be emitted into the output stream within the next temporal unit if it satisfies the specified insertion flag.

If the video contains multiple spatial and/or temporal layers, a layer-specific metadata OBU only applies to the current frame's layer, as determined by the frame's temporal_id and spatial_id. Some metadata types cannot be layer-specific, as listed in Section 6.7.1 of the draft AV1 specification as of 2025-03-06.

During decoding, when the library encounters a metadata OBU, it is emitted with the next output aom_image. Its insert_flag is set to either AOM_MIF_ANY_FRAME, or AOM_MIF_ANY_FRAME_LAYER_SPECIFIC if the OBU contains an OBU header extension (i.e. the video contains multiple layers AND the metadata was added using *_LAYER_SPECIFIC insert flag if using libaom).

## aom_image_t

typedef struct aom_image aom_image_t

Image Descriptor.

alias for struct aom_image

## 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

Planar 4:2:0 format with aom color space

Deprecated
  This value is unsupported and will be removed in a future release.

Image is a planar format. V plane precedes U in memory.

AOM_IMG_FMT_AOMI420

Planar 4:2:0 format with aom color space

Deprecated
  This value is unsupported and will be removed in a future release.

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_NV12 | Image is a planar format. 4:2:0 with U and V interleaved
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 backward compatibility
AOM_CICP_MC_IPT_C2 | IPT-C2
AOM_CICP_MC_YCGCO_RE | YCgCo-Re
AOM_CICP_MC_YCGCO_RO | YCgCo-Ro For future use (values 18-255)

## aom_color_range

enum aom_color_range

List of supported color range.

Enumerator

AOM_CR_STUDIO_RANGE

- Y [16..235], UV [16..240] (bit depth 8)
- Y [64..940], UV [64..960] (bit depth 10)
- Y [256..3760], UV [256..3840] (bit depth 12)

AOM_CR_FULL_RANGE

- YUV/RGB [0..255] (bit depth 8)
- YUV/RGB [0..1023] (bit depth 10)
- YUV/RGB [0..4095] (bit depth 12)

## 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

## aom_metadata_insert_flags

enum aom_metadata_insert_flags

List of insert flags for Metadata.

These flags control how the library treats metadata during encode.

While encoding, when metadata is added to an aom_image via aom_img_add_metadata(), the flag passed along with the metadata will determine where the metadata OBU will be placed in the encoded OBU stream, and whether it's layer-specific. Metadata will be emitted into the output stream within the next temporal unit if it satisfies the specified insertion flag.

If the video contains multiple spatial and/or temporal layers, a layer-specific metadata OBU only applies to the current frame's layer, as determined by the frame's temporal_id and spatial_id. Some metadata types cannot be layer-specific, as listed in Section 6.7.1 of the draft AV1 specification as of 2025-03-06.

During decoding, when the library encounters a metadata OBU, it is emitted with the next output aom_image. Its insert_flag is set to either AOM_MIF_ANY_FRAME, or AOM_MIF_ANY_FRAME_LAYER_SPECIFIC if the OBU contains an OBU header extension (i.e. the video contains multiple layers AND the metadata was added using *_LAYER_SPECIFIC insert flag if using libaom).

Enumerator
AOM_MIF_NON_KEY_FRAME | Adds metadata if it's not a keyframe
AOM_MIF_KEY_FRAME | Adds metadata only if it's a keyframe
AOM_MIF_ANY_FRAME | Adds metadata to any type of frame
AOM_MIF_NON_KEY_FRAME_LAYER_SPECIFIC | Adds layer-specific metadata if it's not a keyframe
AOM_MIF_KEY_FRAME_LAYER_SPECIFIC | Adds layer-specific metadata only if it's a keyframe
AOM_MIF_ANY_FRAME_LAYER_SPECIFIC | Adds layer-specific metadata to any type of frame

## 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. Must not exceed 0x08000000 (2^27).
  [in] | d_h | Height of the image. Must not exceed 0x08000000 (2^27).
  [in] | align | Alignment, in bytes, of the image buffer and each row in the image (stride). Must not exceed 65536.

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 | stride_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. Must not exceed 0x08000000 (2^27).
  [in] | d_h | Height of the image. Must not exceed 0x08000000 (2^27).
  [in] | stride_align | Alignment, in bytes, of each row in the image (stride). Must not exceed 65536.
  [in] | img_data | Storage to use for the image. The storage must outlive the returned image descriptor; it can be disposed of after calling aom_img_free().

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.

Note
  img_data is required to have a minimum allocation size that satisfies the requirements of the fmt, d_w, d_h and stride_align parameters. This size can be calculated as follows (see `img_alloc_helper` in the aom_image.c file in the libaom source tree for more detail):
  align = (1 << x_chroma_shift) - 1;
  w = (d_w + align) & ~align;
  align = (1 << y_chroma_shift) - 1;
  h = (d_h + align) & ~align;
  s = (fmt & AOM_IMG_FMT_PLANAR) ? w : (uint64_t)bps * w / 8;
  s = (fmt & AOM_IMG_FMT_HIGHBITDEPTH) ? s * 2 : s;
  s = (s + stride_align - 1) & ~((uint64_t)stride_align - 1);
  s = (fmt & AOM_IMG_FMT_HIGHBITDEPTH) ? s / 2 : s;
  alloc_size = (fmt & AOM_IMG_FMT_PLANAR) ? (uint64_t)h * s * bps / 8
  : (uint64_t)h * s;
  AOM_IMG_FMT_HIGHBITDEPTH
  #define AOM_IMG_FMT_HIGHBITDEPTH
  Definition aom_image.h:38
  AOM_IMG_FMT_PLANAR
  #define AOM_IMG_FMT_PLANAR
  Definition aom_image.h:35
  x_chroma_shift, y_chroma_shift and bps can be obtained by calling aom_img_wrap with a non-`NULL` img_data parameter. The `aom_image_t` pointer should not be used in other API calls until after a successful call to aom_img_wrap with a valid image buffer. For example:
  aom_img_wrap(img, fmt, d_w, d_h, stride_align, (unsigned char *)1);
  ... calculate buffer size and allocate buffer as described earlier
  aom_img_wrap(img, fmt, d_w, d_h, stride_align, img_data);
  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 stride_align, unsigned char *img_data)
  Open a descriptor, using existing storage for the underlying image.

## 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. Must not exceed 0x08000000 (2^27).
  [in] | d_h | Height of the image. Must not exceed 0x08000000 (2^27).
  [in] | align | Alignment, in bytes, of the image buffer and each row in the image (stride). Must not exceed 65536.
  [in] | size_align | Alignment, in pixels, of the image width and height. Must not exceed 65536.
  [in] | border | A border that is padded on four sides of the image. Must not exceed 65536.

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. Specifically, sets img->d_w, img->d_h, and elements of the img->planes[] array.

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 (-1) 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,
|  | aom_metadata_insert_flags_t | insert_flag )

Add metadata to image.

Adds metadata to aom_image_t. Function makes a copy of the provided data parameter. Metadata insertion point is controlled by insert_flag.

Parameters

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

Returns
  Returns 0 on success. If img or data is NULL, sz is 0, or memory allocation fails, it returns -1.

## aom_img_get_metadata()

const aom_metadata_t * aom_img_get_metadata | ( | const aom_image_t * | img,
|  | size_t | index )

Return a metadata payload stored within the image metadata array.

Gets the metadata (aom_metadata_t) at the indicated index in the image metadata array.

Parameters

  [in] | img | Pointer to image descriptor to get metadata from
  [in] | index | Metadata index to get from metadata array

Returns
  Returns a const pointer to the selected metadata, if img and/or index is invalid, it returns NULL.

## aom_img_num_metadata()

size_t aom_img_num_metadata | ( | const aom_image_t * | img | ) |

Return the number of metadata blocks within the image.

Gets the number of metadata blocks contained within the provided image metadata array.

Parameters

  [in] | img | Pointer to image descriptor to get metadata number from.

Returns
  Returns the size of the metadata array. If img or metadata is NULL, it returns 0.

## 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,
|  | aom_metadata_insert_flags_t | insert_flag )

Allocate memory for aom_metadata struct.

Allocates storage for the metadata payload, sets its type and copies the payload data into the aom_metadata struct. A metadata payload buffer of size 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
  [in] | insert_flag | Metadata insert flag

Returns
  Returns the newly allocated aom_metadata struct. If data is NULL, sz is 0, or memory allocation fails, it returns NULL.

## 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