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

## 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 enum aom_metadata_insert_flags | aom_metadata_insert_flags_t
| List of insert flags for Metadata. 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...

## 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...
enum | aom_metadata_insert_flags { AOM_MIF_NON_KEY_FRAME = 0 , AOM_MIF_KEY_FRAME = 1 , AOM_MIF_ANY_FRAME = 2 }
| 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. 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, aom_metadata_insert_flags_t insert_flag)
| Add metadata to image. More...
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. More...
size_t | aom_img_num_metadata (const aom_image_t *img)
| Return the number of metadata blocks within the 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, aom_metadata_insert_flags_t insert_flag)
| 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_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. Metadata will be emitted into the output stream within the next temporal unit if it satisfies the specified insertion flag.

During decoding, when the library encounters a metadata OBU, it is always flagged as AOM_MIF_ANY_FRAME and emitted with the next output aom_image.

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

## ◆ 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. Metadata will be emitted into the output stream within the next temporal unit if it satisfies the specified insertion flag.

During decoding, when the library encounters a metadata OBU, it is always flagged as AOM_MIF_ANY_FRAME and emitted with the next output aom_image.

Enumerator
AOM_MIF_NON_KEY_FRAME | Adds metadata if it's not keyframe
AOM_MIF_KEY_FRAME | Adds metadata only if it's a keyframe
AOM_MIF_ANY_FRAME | Adds 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
  [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,
|  | 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

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

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