Data Structures
struct	_codec_state

struct	_codec_state::_picture_aspect_ratio
	Picture aspect ratio read from the encoded sample. More...

struct	_codec
	Fields that are common to the encoder and decoder. More...

Typedefs
typedef enum _codec_tag	CODEC_TAG
	Tags that define elements in the bitstream. More...

typedef enum _image_format	IMAGE_FORMAT
	Format of the encoded sample. More...

typedef enum _section_number	SECTION_NUMBER

typedef uint32_t	ENABLED_SECTIONS

typedef struct _codec_state	CODEC_STATE

typedef struct _codec	CODEC
	Fields that are common to the encoder and decoder.

Enumerations
enum	_codec_tag { CODEC_TAG_ImageWidth = 20, CODEC_TAG_ImageHeight = 21, CODEC_TAG_BitsPerComponent = 101, CODEC_TAG_ChannelCount = 12, CODEC_TAG_SubbandCount = 14, CODEC_TAG_ChannelNumber = 62, CODEC_TAG_SubbandNumber = 48, CODEC_TAG_LowpassPrecision = 35, CODEC_TAG_Quantization = 53, CODEC_TAG_PrescaleShift = 109, CODEC_TAG_ChannelWidth = 104, CODEC_TAG_ChannelHeight = 105, CODEC_TAG_PixelFormat = 1001, CODEC_TAG_LargeCodeblock = 0x6000, CODEC_TAG_SMALL_CHUNK = 0x4000, CODEC_TAG_LARGE_CHUNK = 0x2000, CODEC_TAG_CHUNK_MASK = (CODEC_TAG_SMALL_CHUNK \| CODEC_TAG_LARGE_CHUNK), CODEC_TAG_PatternWidth = 106, CODEC_TAG_PatternHeight = 107, CODEC_TAG_ComponentsPerSample = 108, CODEC_TAG_ImageFormat = 84, CODEC_TAG_MaxBitsPerComponent = 102, CODEC_TAG_VendorSpecificData = 0x4000, CODEC_TAG_InversePermutation = 0x4001, CODEC_TAG_InverseTransform = 0x4002, CODEC_TAG_InverseTransform16 = 0x4003, CODEC_TAG_UniqueImageIdentifier = 0x4004, CODEC_TAG_LayerCount = 120, CODEC_TAG_LayerNumber = 121, CODEC_TAG_LayerPattern = 122, CODEC_TAG_ImageCount = 130, CODEC_TAG_ImageNumber = 131, CODEC_TAG_ImageSectionTag = 0x2700, CODEC_TAG_HeaderSectionTag = 0x2500, CODEC_TAG_LayerSectionTag = 0x2600, CODEC_TAG_ChannelSectionTag = 0x2400, CODEC_TAG_WaveletSectionTag = 0x2100, CODEC_TAG_SubbandSectionTag = 0x2000, CODEC_TAG_SmallMetadata = 0x4010, CODEC_TAG_LargeMetadata = 0x6100 }
	Tags that define elements in the bitstream. More...

enum	_image_format { IMAGE_FORMAT_UNKNOWN = 0, IMAGE_FORMAT_RGBA, IMAGE_FORMAT_YCbCrA, IMAGE_FORMAT_BAYER, IMAGE_FORMAT_CFA, IMAGE_FORMAT_COUNT }
	Format of the encoded sample. More...

enum	_section_number { SECTION_NUMBER_IMAGE = 1, SECTION_NUMBER_HEADER = 2, SECTION_NUMBER_LAYER = 3, SECTION_NUMBER_CHANNEL = 4, SECTION_NUMBER_WAVELET = 5, SECTION_NUMBER_SUBBAND = 6, SECTION_NUMBER_MINIMUM = SECTION_NUMBER_IMAGE, SECTION_NUMBER_MAXIMUM = SECTION_NUMBER_SUBBAND }

enum	band_encoding { BAND_ENCODING_ZEROTREE = 1, BAND_ENCODING_CODEBOOK, BAND_ENCODING_RUNLENGTHS, BAND_ENCODING_16BIT, BAND_ENCODING_LOSSLESS }
	Band encoding method. More...

Functions
CODEC_ERROR	PrepareCodecState (CODEC_STATE *codec)
	Initialize the codec state to before encoding or decoding the bitstream. More...

uint32_t	EncoderVersion (uint32_t value)
	Reformat a segment value into the encoder version. More...

uint32_t	RepackedEncoderVersion (uint32_t value)

void	SetCodecVersion (uint8_t version[3], uint16_t value)
	Unpack the version tag value into its components.

IMAGE_FORMAT	DefaultImageFormat (PIXEL_FORMAT pixel_format)
	Set the image format using the pixel format.

int	EncodedPrecision (PIXEL_FORMAT format)
	Return the encoded precision for an input pixel format. More...

int	InputPrecision (PIXEL_FORMAT format)
	Return the precision of a pixel format. More...

CODEC_ERROR	UpdatePrescaleTable (CODEC_STATE *codec, TAGWORD value)
	Unpack the tag value into the prescale table. More...

CODEC_ERROR	UpdateSampleFlags (CODEC_STATE *codec, TAGWORD value)

CODEC_ERROR	UpdateCodecFlags (CODEC_STATE *codec, TAGWORD value)

CODEC_ERROR	UpdateFrameStructureFlags (CODEC_STATE *codec, TAGWORD value)
	Update the flags that describe the frame structure. More...

int	LowpassChannelOffset (CODEC_STATE *codec, PIXEL_FORMAT output_format)
	Compute the channel offset added to each lowpass pixel value. More...

CODEC_ERROR	SetBandCoding (CODEC_STATE *codec, TAGWORD value)
	Set the flags that determine the band coding. More...

const char *	ImageFormatString (IMAGE_FORMAT image_format)
	Return a string for the name of the image format.

bool	IsPartEnabled (ENABLED_PARTS enabled_parts, int part_number)
	Return true if the specified part is enabled at runtime. More...

bool	IsSectionEnabled (ENABLED_SECTIONS enabled_sections, SECTION_NUMBER section_number)
	Return true if the specified type of section is enabled.

bool	IsImageSectionEnabled (ENABLED_PARTS enabled_parts, ENABLED_SECTIONS enabled_sections)
	Return true if image sections are enabled.

Detailed Description

State of the decoder while decoding a sample.

The codec state contains information about the current state of the decoding process. The codec state is updated as the bitstream is decoded.

The encoder process maintains the codec state during encoding to mimic the codec state in the decoder. It is not necessary to encode parameters into the bitstream if the decoding process will automatically determine the same information. For example, after decoding a subband, the decoder will increment the subband number, so the encoder does not have to write the next subband number in the bitstream if the subbands are transmitted in numerical order.

Typedef Documentation

◆ CODEC_STATE

typedef struct _codec_state CODEC_STATE

The codec state contains information about the decoding process obtained as a sample is decoded. The information is transient and is only used while decoding a sample. The decoder data structure contains information that should persist from onen sample to the next.

The codec state is initialized using information in the decoder data structure at the start of decoding a sample.

The intent is that the encoder can operate the same state machine during encoding and any information available in the state machine does not have to be encoded into the sample as it is assumed that the decoder can and will derive the same information. For example, the dimensions of the first subband can be computed from the encoded dimensions and the number of wavelet levels, so it is not necessary to encode this information. Likewise, after the last band in a wavelet is decoded the dimensions of the bands in the wavelet at the next level can be deduced and it is not necessary to encode this information into the sample.

◆ CODEC_TAG

typedef enum _codec_tag CODEC_TAG

Tags that define elements in the bitstream.

All syntax elements in the encoded bitstream begin with a 16-bit tag that specifies the type of element. The 16-bit tag is followed by a 16-bit value, forming a tag-value pair.

If the tag is a negative number, then the actual tag is the negation of the tag value and the negative sign indicates that the tag and its value are an optional tag value pair. If the tag is a positive value, then the segment is required. A decoder must be able to decode all required tag-value pairs, but can skip tag-value pairs that are optional.

In a VC-5 Part 1 bitstream, the image width and height are an upper bound on the dimensions of each channel represented in the bitstream. In a VC-5 Part 3 bitstream, the image width and height are the actual dimensions of the image represented in the bitstream. The width and height of the image and each pattern element is sufficient to determine the width and height of each component array.

A range of tags is reserved for chunks and the value is the size of the chunk.

◆ IMAGE_FORMAT

typedef enum _image_format IMAGE_FORMAT

Format of the encoded sample.

The VC-5 Part 3 can support four bitstream representations of the encoded image.

The image format must be specified for any VC-5 Part 3 bitstream.

Enumeration Type Documentation

◆ _codec_tag

enum _codec_tag

Tags that define elements in the bitstream.

All syntax elements in the encoded bitstream begin with a 16-bit tag that specifies the type of element. The 16-bit tag is followed by a 16-bit value, forming a tag-value pair.

If the tag is a negative number, then the actual tag is the negation of the tag value and the negative sign indicates that the tag and its value are an optional tag value pair. If the tag is a positive value, then the segment is required. A decoder must be able to decode all required tag-value pairs, but can skip tag-value pairs that are optional.

In a VC-5 Part 1 bitstream, the image width and height are an upper bound on the dimensions of each channel represented in the bitstream. In a VC-5 Part 3 bitstream, the image width and height are the actual dimensions of the image represented in the bitstream. The width and height of the image and each pattern element is sufficient to determine the width and height of each component array.

A range of tags is reserved for chunks and the value is the size of the chunk.

Enumerator
CODEC_TAG_ImageWidth	Upper bound on the width of the image.
CODEC_TAG_ImageHeight	Upper bound on the height of the image.
CODEC_TAG_BitsPerComponent	Number of bits in the source image.
CODEC_TAG_ChannelCount	Number of channels in the transform.
CODEC_TAG_SubbandCount	Number of encoded subbands.
CODEC_TAG_ChannelNumber	Channel number.
CODEC_TAG_SubbandNumber	Subband number of this wavelet band.
CODEC_TAG_LowpassPrecision	Number of bits per lowpass coefficient.
CODEC_TAG_Quantization	Quantization applied to band.
CODEC_TAG_PrescaleShift	Packed prescale shift for each wavelet level.
CODEC_TAG_ChannelWidth	Width of the next channel in the bitstream.
CODEC_TAG_ChannelHeight	Height of the next channel in the bitstream.
CODEC_TAG_PixelFormat	Pixel fomrat of the packed input image.
CODEC_TAG_LargeCodeblock	Large chunk that contains a codeblock.
CODEC_TAG_SMALL_CHUNK	Small chunk with a 16-bit payload size (in segments)
CODEC_TAG_LARGE_CHUNK	Large chunk with a 24-bit payload size (in segments)
CODEC_TAG_CHUNK_MASK	Mask for detecting the tag for a small or large chunk (including codeblocks)
CODEC_TAG_PatternWidth	Number of samples per row in each pattern element.
CODEC_TAG_PatternHeight	Number of rows of samples in each pattern element.
CODEC_TAG_ComponentsPerSample	Number of components in each sample in the pattern element.
CODEC_TAG_ImageFormat	Format of the image represented by the bitstream.
CODEC_TAG_MaxBitsPerComponent	Upper bound on the number of bits per component.
CODEC_TAG_VendorSpecificData	Small chunk containing vendor-specific data.
CODEC_TAG_InversePermutation	Small chunk containing the inverse component permutation.
CODEC_TAG_InverseTransform	Small chunk containing the inverse component transform (8 bit representation)
CODEC_TAG_InverseTransform16	Small chunk containing the inverse component transform (16 bit representation)
CODEC_TAG_UniqueImageIdentifier	Small chunk containing the identifier and sequence number for the image.
CODEC_TAG_LayerCount	Number of layers in the bitstream.
CODEC_TAG_LayerNumber	Number of the next layer in the bitstream.
CODEC_TAG_LayerPattern	Mask indicating the use cases in the bitstream.
CODEC_TAG_ImageCount	Number of image bitstream sections in the bitstream.
CODEC_TAG_ImageNumber	Unique number assigned to an image bitstream section.
CODEC_TAG_ImageSectionTag	Section that contains a single image.
CODEC_TAG_HeaderSectionTag	Section that contains the bitstream header.
CODEC_TAG_LayerSectionTag	Section that contains a single layer.
CODEC_TAG_ChannelSectionTag	Section that contains a single channel.
CODEC_TAG_WaveletSectionTag	Section that contains all subbands for one wavelet.
CODEC_TAG_SubbandSectionTag	Section that contains a single subband.
CODEC_TAG_SmallMetadata	Small chunk containing metadata tuples (VC-5 Part 7)
CODEC_TAG_LargeMetadata	Large chunk containing metadata tuples (VC-5 Part 7)

◆ _image_format

enum _image_format

Format of the encoded sample.

The VC-5 Part 3 can support four bitstream representations of the encoded image.

The image format must be specified for any VC-5 Part 3 bitstream.

Enumerator
IMAGE_FORMAT_UNKNOWN	The image format has not been specified.
IMAGE_FORMAT_RGBA	RGB image with optional alpha channel.
IMAGE_FORMAT_YCbCrA	YCbCr image with optional alpha channel.
IMAGE_FORMAT_BAYER	Bayer image format (special case of CFA)
IMAGE_FORMAT_CFA	Generic color filter array (CFA) image.
IMAGE_FORMAT_COUNT	Number of image formats that have been defined.

◆ _section_number

enum _section_number

Enumerator
SECTION_NUMBER_IMAGE	Image section.
SECTION_NUMBER_HEADER	Bitstream header section.
SECTION_NUMBER_LAYER	Layer section.
SECTION_NUMBER_CHANNEL	Channel section.
SECTION_NUMBER_WAVELET	Wavelet section.
SECTION_NUMBER_SUBBAND	Subband section.
SECTION_NUMBER_MINIMUM	Modify the smallest and largest section numbers as more sections are added.

◆ band_encoding

enum band_encoding

Band encoding method.

Several different schemes have been tried for entropy coding the highpass bands. The baseline profile only supports the run lengths encoding method.

The run lengths encoding method using a Huffman code to encode runs of zeros and highpass coefficient magnitudes (unsigned). Runs of zeros can extend across row boundaries, so large sections of a highpass band that are mostly zeros can be encoded very efficiently.

Todo:: Need to cull this list as many band encoding methods are no longer supported.

Function Documentation

◆ EncodedPrecision()

int EncodedPrecision ( PIXEL_FORMAT format )

Return the encoded precision for an input pixel format.

This routine computes the encoded precision that should be used for an input frame with the specified pixel format.

This routine is not currently used since all input formats are encoded using 12 bits of precision.

◆ EncoderVersion()

uint32_t EncoderVersion ( uint32_t value )

Reformat a segment value into the encoder version.

The version of the encoder that created the clip may be encoded into every sample.

Todo:: Document the encoder version number format

◆ InputPrecision()

int InputPrecision ( PIXEL_FORMAT format )

Return the precision of a pixel format.

This routine returns the actual precision of a pixel format.

◆ IsPartEnabled()

bool IsPartEnabled	(	ENABLED_PARTS	enabled_parts,
		int	part_number
	)

Return true if the specified part is enabled at runtime.

This predicate is used to test whether a specific part in the VC-5 standard is enabled at runtime by this codec implementation.

Here is the caller graph for this function:

◆ LowpassChannelOffset()

int LowpassChannelOffset	(	CODEC_STATE *	codec,
		PIXEL_FORMAT	output_format
	)

Compute the channel offset added to each lowpass pixel value.

The channel offset is added to each pixel value when decoding the lowpass band. It corrects for rounding errors that occur during encoding and depends on the output format since the rounding errors are not present at higher output bit depths.

◆ PrepareCodecState()

CODEC_ERROR PrepareCodecState ( CODEC_STATE * codec )

Initialize the codec state to before encoding or decoding the bitstream.

Most of the codec state can be deduced from the decoding parameters. For example, the dimensions of the first wavelet band in the bitstream can be deduced from the encoded frame dimensions and the structure of the wavelet tree.

The encoder will not insert parameters into the bitstream if the values of the parameters are the same as in the codec state. This routine should initialize the codec state with correct values if those values can be inferred by the decoder, otherwise the use incorrect or default values.

Note that the default encoded format is YUV 4:2:2, but this format is not supported by the baseline profile encoder so the encoded format must be explicitly written into the bitstream.

Todo:: Add more default values required to properly initialize the codec state.

Here is the caller graph for this function:

◆ SetBandCoding()

CODEC_ERROR SetBandCoding	(	CODEC_STATE *	codec,
		TAGWORD	value
	)

Set the flags that determine the band coding.

There can be up to 15 different codebooks as specified by the lower four bigs in the band coding flags. Use the default codebook if the active codebook is zero.

The baseline profile does not allow difference coding or alternative codebooks.

◆ UpdateFrameStructureFlags()

CODEC_ERROR UpdateFrameStructureFlags	(	CODEC_STATE *	codec,
		TAGWORD	value
	)

Update the flags that describe the frame structure.

The frame structure includes characteristics such as interlaced versus progressive and top or bottom field first.

◆ UpdatePrescaleTable()

CODEC_ERROR UpdatePrescaleTable	(	CODEC_STATE *	codec,
		TAGWORD	value
	)

Unpack the tag value into the prescale table.

The prescale table contains the prescale value for each wavelet in the transform. The prescale value is a right shift that is applied to the input data before the wavelet is computed.

The prescale table is used for all transforms and does not depend on the channel number.

Data Structures

Typedefs

Enumerations

Functions