Header file defining the data format descriptor utilities API. More...

#include <KHR/khr_df.h>
#include <stdbool.h>
#include <vulkan/vulkan_core.h>

Data Structures
struct	_InterpretedDFDChannel
	Interpretation of a channel from the data format descriptor. More...
struct	_Primaries
	Colourspace primaries information. More...

Typedefs
typedef struct _InterpretedDFDChannel	InterpretedDFDChannel
	Interpretation of a channel from the data format descriptor.
typedef struct _Primaries	Primaries
	Colourspace primaries information.

Enumerations
enum	VkSuffix { s_UNORM , s_SNORM , s_USCALED , s_SSCALED , s_UINT , s_SINT , s_SFLOAT , s_UFLOAT , s_SRGB , s_SFIXED5 }
enum	VkCompScheme { c_BC1_RGB , c_BC1_RGBA , c_BC2 , c_BC3 , c_BC4 , c_BC5 , c_BC6H , c_BC7 , c_ETC2_R8G8B8 , c_ETC2_R8G8B8A1 , c_ETC2_R8G8B8A8 , c_EAC_R11 , c_EAC_R11G11 , c_ASTC , c_ETC1S , c_PVRTC , c_PVRTC2 }
enum	InterpretDFDResult { i_LITTLE_ENDIAN_FORMAT_BIT = 0 , i_BIG_ENDIAN_FORMAT_BIT = 1u << 0u , i_PACKED_FORMAT_BIT = 1u << 1u , i_SRGB_FORMAT_BIT = 1u << 2u , i_NORMALIZED_FORMAT_BIT = 1u << 3u , i_SIGNED_FORMAT_BIT = 1u << 4u , i_FIXED_FORMAT_BIT = 1u << 5u , i_FLOAT_FORMAT_BIT = 1u << 6u , i_COMPRESSED_FORMAT_BIT = 1u << 7u , i_YUVSDA_FORMAT_BIT = 1u << 8u , i_UNSUPPORTED_ERROR_BIT = 1u << 9u , i_UNSUPPORTED_NONTRIVIAL_ENDIANNESS = i_UNSUPPORTED_ERROR_BIT , i_UNSUPPORTED_MULTIPLE_SAMPLE_LOCATIONS = i_UNSUPPORTED_ERROR_BIT + 1 , i_UNSUPPORTED_MULTIPLE_PLANES = i_UNSUPPORTED_ERROR_BIT + 2 , i_UNSUPPORTED_CHANNEL_TYPES = i_UNSUPPORTED_ERROR_BIT + 3 , i_UNSUPPORTED_MIXED_CHANNELS = i_UNSUPPORTED_ERROR_BIT + 4 , i_UNSUPPORTED_BLOCK_DIMENSIONS = i_UNSUPPORTED_ERROR_BIT + 5 }
	Result of interpreting the data format descriptor. More...

Functions
uint32_t *	vk2dfd (enum VkFormat format)
	Create a DFD matching a VkFormat.
enum VkFormat	dfd2vk (uint32_t *dfd)
	Return a VkFormat matching a DFD.
uint32_t *	createDFDUnpacked (int bigEndian, int numChannels, int bytes, int redBlueSwap, enum VkSuffix suffix)
	Create a Data Format Descriptor for an unpacked format.
uint32_t *	createDFDPackedShifted (int bigEndian, int numChannels, int bits[], int shiftBits[], int channels[], enum VkSuffix suffix)
	Create a Data Format Descriptor for a packed format.
uint32_t *	createDFDPacked (int bigEndian, int numChannels, int bits[], int channels[], enum VkSuffix suffix)
	Create a Data Format Descriptor for a packed format.
uint32_t *	createDFDCompressed (enum VkCompScheme compScheme, int bwidth, int bheight, int bdepth, enum VkSuffix suffix)
	Create a Data Format Descriptor for a compressed format.
uint32_t *	createDFDDepthStencil (int depthBits, int stencilBits, int sizeBytes)
	Create a Data Format Descriptor for a depth-stencil format.
uint32_t *	createDFDAlpha (int bigEndian, int bytes, enum VkSuffix suffix)
	Create a Data Format Descriptor for an alpha-only format.
enum InterpretDFDResult	interpretDFD (const uint32_t DFD, InterpretedDFDChannel R, InterpretedDFDChannel G, InterpretedDFDChannel B, InterpretedDFDChannel A, uint32_t wordBytes)
	Interpret a Data Format Descriptor for a simple format.
void	printDFD (uint32_t *DFD, uint32_t dataSize)
	Print a human-readable interpretation of a data format descriptor.
void	printDFDJSON (uint32_t *DFD, uint32_t dataSize, uint32_t base_indent, uint32_t indent_width, bool minified)
	Print a JSON interpretation of a data format descriptor.
void	getDFDComponentInfoUnpacked (const uint32_t DFD, uint32_t numComponents, uint32_t *componentByteLength)
	Get the number and size of the image components from a DFD.
uint32_t	getDFDNumComponents (const uint32_t *DFD)
	Return the number of "components" in the data.
void	reconstructDFDBytesPlanesFromSamples (uint32_t *DFD)
	Reconstruct the values of bytesPlane[01] from sample info.
uint32_t	reconstructDFDBytesPlane0FromSamples (const uint32_t *DFD)
	Reconstruct the value of bytesPlane0 from sample info.
void	recreateBytesPlane0FromSampleInfo (const uint32_t DFD, uint32_t bytesPlane0)
	Reconstruct the value of bytesPlane0 from sample info.
khr_df_primaries_e	findMapping (const Primaries *p, float latitude)
	Map a set of primaries to a KDFS primaries enum.
bool	getPrimaries (khr_df_primaries_e primaries, Primaries *p)
	Get the primaries corresponding to a KDFS primaries enum.

Detailed Description

Header file defining the data format descriptor utilities API.

Typedef Documentation

◆ Primaries

typedef struct _Primaries Primaries

Colourspace primaries information.

Structure to store the 1931 CIE x,y chromaticities of the red, green, and blue display primaries and the reference white point of a colourspace.

Enumeration Type Documentation

◆ InterpretDFDResult

enum InterpretDFDResult

Result of interpreting the data format descriptor.

Enumerator
i_LITTLE_ENDIAN_FORMAT_BIT	Confirmed little-endian (default for 8bpc).
i_BIG_ENDIAN_FORMAT_BIT	Confirmed big-endian.
i_PACKED_FORMAT_BIT	Packed format.
i_SRGB_FORMAT_BIT	sRGB transfer function.
i_NORMALIZED_FORMAT_BIT	Normalized (UNORM or SNORM).
i_SIGNED_FORMAT_BIT	Format is signed.
i_FIXED_FORMAT_BIT	Format is a fixed-point representation.
i_FLOAT_FORMAT_BIT	Format is floating point.
i_COMPRESSED_FORMAT_BIT	Format is block compressed (422).
i_YUVSDA_FORMAT_BIT	Color model is YUVSDA.
i_UNSUPPORTED_ERROR_BIT	Format not successfully interpreted.
i_UNSUPPORTED_NONTRIVIAL_ENDIANNESS	"NONTRIVIAL_ENDIANNESS" means not big-endian, not little-endian (a channel has bits that are not consecutive in either order).
i_UNSUPPORTED_MULTIPLE_SAMPLE_LOCATIONS	"MULTIPLE_SAMPLE_LOCATIONS" is an error because only single-sample texel blocks (with coordinates 0,0,0,0 for all samples) are supported.
i_UNSUPPORTED_MULTIPLE_PLANES	"MULTIPLE_PLANES" is an error because only contiguous data is supported.
i_UNSUPPORTED_CHANNEL_TYPES	Only channels R, G, B and A are supported.
i_UNSUPPORTED_MIXED_CHANNELS	Only channels with the same flags are supported (e.g. we don't support float red with integer green).
i_UNSUPPORTED_BLOCK_DIMENSIONS	Only 2x1 block is supported for YUVSDA model.

◆ VkCompScheme

enum VkCompScheme

Compression scheme, in Vulkan terms.

Enumerator
c_BC1_RGB	BC1, aka DXT1, no alpha.
c_BC1_RGBA	BC1, aka DXT1, punch-through alpha.
c_BC2	BC2, aka DXT2 and DXT3.
c_BC3	BC3, aka DXT4 and DXT5.
c_BC4	BC4.
c_BC5	BC5.
c_BC6H	BC6h HDR format.
c_BC7	BC7.
c_ETC2_R8G8B8	ETC2 no alpha.
c_ETC2_R8G8B8A1	ETC2 punch-through alpha.
c_ETC2_R8G8B8A8	ETC2 independent alpha.
c_EAC_R11	R11 ETC2 single-channel.
c_EAC_R11G11	R11G11 ETC2 dual-channel.
c_ASTC	ASTC.
c_ETC1S	ETC1S.
c_PVRTC	PVRTC(1).
c_PVRTC2	PVRTC2.

◆ VkSuffix

enum VkSuffix

Qualifier suffix to the format, in Vulkan terms.

Enumerator
s_UNORM	Unsigned normalized format.
s_SNORM	Signed normalized format.
s_USCALED	Unsigned scaled format.
s_SSCALED	Signed scaled format.
s_UINT	Unsigned integer format.
s_SINT	Signed integer format.
s_SFLOAT	Signed float format.
s_UFLOAT	Unsigned float format.
s_SRGB	sRGB normalized format.
s_SFIXED5	2's complement fixed-point; 5 fractional bits.

Function Documentation

◆ createDFDAlpha()

uint32_t * createDFDAlpha	(	int	bigEndian,
		int	bytes,
		enum VkSuffix	suffix )

Create a Data Format Descriptor for an alpha-only format.

Parameters

bigEndian	Set to 1 for big-endian byte ordering and 0 for little-endian byte ordering.
bytes	The number of bytes per channel.
suffix	Indicates the format suffix for the type.

Returns: A data format descriptor in malloc'd data. The caller is responsible for freeing the descriptor.

◆ createDFDCompressed()

uint32_t * createDFDCompressed	(	enum VkCompScheme	compScheme,
		int	bwidth,
		int	bheight,
		int	bdepth,
		enum VkSuffix	suffix )

Create a Data Format Descriptor for a compressed format.

Parameters

compScheme	Vulkan-style compression scheme enumeration.
bwidth	Block width in texel coordinates.
bheight	Block height in texel coordinates.
bdepth	Block depth in texel coordinates.

Author: Mark Callow, github.com/MarkCallow.

Parameters

suffix Indicates the format suffix for the type.

Returns: A data format descriptor in malloc'd data. The caller is responsible for freeing the descriptor.

◆ createDFDDepthStencil()

uint32_t * createDFDDepthStencil	(	int	depthBits,
		int	stencilBits,
		int	sizeBytes )

Create a Data Format Descriptor for a depth-stencil format.

Parameters

depthBits	The numeber of bits in the depth channel.
stencilBits	The numeber of bits in the stencil channel.
sizeBytes	The total byte size of the texel.

Returns: A data format descriptor in malloc'd data. The caller is responsible for freeing the descriptor.

◆ createDFDPacked()

uint32_t * createDFDPacked	(	int	bigEndian,
		int	numChannels,
		int	bits[],
		int	channels[],
		enum VkSuffix	suffix )

Create a Data Format Descriptor for a packed format.

Parameters

bigEndian	Big-endian flag: Set to 1 for big-endian byte ordering and 0 for little-endian byte ordering.
numChannels	The number of color channels.
bits[]	An array of length numChannels. Each entry is the number of bits composing the channel, in order starting at bit 0 of the packed type.
channels[]	An array of length numChannels. Each entry enumerates the channel type: 0 = red, 1 = green, 2 = blue, 15 = alpha, in order starting at bit 0 of the packed type. These values match channel IDs for RGBSDA in the Khronos Data Format header. To simplify iteration through channels, channel id 3 is a synonym for alpha.
suffix	Indicates the format suffix for the type.

Returns: A data format descriptor in malloc'd data. The caller is responsible for freeing the descriptor.

◆ createDFDPackedShifted()

uint32_t * createDFDPackedShifted	(	int	bigEndian,
		int	numChannels,
		int	bits[],
		int	shiftBits[],
		int	channels[],
		enum VkSuffix	suffix )

Create a Data Format Descriptor for a packed format.

Parameters

bigEndian	Big-endian flag: Set to 1 for big-endian byte ordering and 0 for little-endian byte ordering.
numChannels	The number of color channels.
bits[]	An array of length numChannels. Each entry is the number of bits composing the channel, in order starting at bit 0 of the packed type.
shiftBits[]	An array of length numChannels. Each entry is the number of bits each channel is shifted and thus padded with insignificant bits.
channels[]	An array of length numChannels. Each entry enumerates the channel type: 0 = red, 1 = green, 2 = blue, 15 = alpha, in order starting at bit 0 of the packed type. These values match channel IDs for RGBSDA in the Khronos Data Format header. To simplify iteration through channels, channel id 3 is a synonym for alpha.
suffix	Indicates the format suffix for the type.

Returns: A data format descriptor in malloc'd data. The caller is responsible for freeing the descriptor.

◆ createDFDUnpacked()

uint32_t * createDFDUnpacked	(	int	bigEndian,
		int	numChannels,
		int	bytes,
		int	redBlueSwap,
		enum VkSuffix	suffix )

Create a Data Format Descriptor for an unpacked format.

Parameters

bigEndian	Set to 1 for big-endian byte ordering and 0 for little-endian byte ordering.
numChannels	The number of color channels.
bytes	The number of bytes per channel.
redBlueSwap	Normally channels appear in consecutive R, G, B, A order in memory; redBlueSwap inverts red and blue, allowing B, G, R, A.
suffix	Indicates the format suffix for the type.

Returns: A data format descriptor in malloc'd data. The caller is responsible for freeing the descriptor.

◆ dfd2vk()

enum VkFormat dfd2vk ( uint32_t * dfd )

Return a VkFormat matching a DFD.

Parameters

[in] dfd Pointer to the DFD.

Returns: The matching VkFormat enum or VK_FORMAT_UNDEFINED if not matched.

◆ findMapping()

khr_df_primaries_e findMapping	(	const Primaries *	p,
		float	latitude )

Map a set of primaries to a KDFS primaries enum.

Parameters

[in]	p	pointer to a Primaries struct filled in with the primary values.
[in]	latitude	tolerance to use while matching. A suitable value might be 0.002 but it depends on the application.

◆ getDFDComponentInfoUnpacked()

void getDFDComponentInfoUnpacked	(	const uint32_t *	DFD,
		uint32_t *	numComponents,
		uint32_t *	componentByteLength )

Get the number and size of the image components from a DFD.

This simplified function is for use only with the DFDs for unpacked formats which means all components have the same size.

Parameters

DFD	Pointer to a Data Format Descriptor to interpret, described as 32-bit words in native endianness. Note that this is the whole descriptor, not just the basic descriptor block.
numComponents	pointer to a 32-bit word in which the number of components will be written.
componentByteLength	pointer to a 32-bit word in which the size of a component in bytes will be written.

◆ getDFDNumComponents()

uint32_t getDFDNumComponents ( const uint32_t * DFD )

Return the number of "components" in the data.

Calculates the number of uniques samples in the DFD by combining multiple samples for the same channel. For uncompressed colorModels this is the same as the number of components in the image data. For block-compressed color models this is the number of samples in the color model, typically 1 and in a few cases 2.

Parameters

DFD	Pointer to a Data Format Descriptor for which, described as 32-bit words in native endianness. Note that this is the whole descriptor, not just the basic descriptor block.

◆ getPrimaries()

bool getPrimaries	(	khr_df_primaries_e	primaries,
		Primaries *	p )

Get the primaries corresponding to a KDFS primaries enum.

Parameters

[in]	primaries	the enum identifying the KDFS primaries.
[out]	p	pointer to a Primaries struct that will be filled with the primary values.

◆ interpretDFD()

enum InterpretDFDResult interpretDFD	(	const uint32_t *	DFD,
		InterpretedDFDChannel *	R,
		InterpretedDFDChannel *	G,
		InterpretedDFDChannel *	B,
		InterpretedDFDChannel *	A,
		uint32_t *	wordBytes )

Interpret a Data Format Descriptor for a simple format.

Handles "simple" cases that can be translated to things a GPU can access. For simplicity, it ignores the compressed formats, which are generally a single sample (and I believe are all defined to be little-endian in their in-memory layout, even if some documentation confuses this). Focuses on the layout and ignores sRGB except for reporting if that is the transfer function by way of a bit in the returned value.

Parameters

[in]	DFD	Pointer to a Data Format Descriptor to interpret, described as 32-bit words in native endianness. Note that this is the whole descriptor, not just the basic descriptor block.
	R[in,out]	Pointer to struct to receive information about the decoded red channel, the Y channel, if YUV, or the depth channel, if any.
	G[in,out]	Pointer to struct to receive information about the decoded green channel, the U (Cb) channel, if YUV, or the stencil channel, if any.
	B[in,out]	Pointer to struct to receive information about the decoded blue channel, if any or the V (Cr) channel, if YUV.
	A[in,out]	Pointer to struct to receive information about the decoded alpha channel, if any or the second Y channel, if YUV and any.
	wordBytes[in,out]	Pointer to a uint32_t to receive the byte size of the channels (unpacked) or total size (packed).

Returns: An enumerant describing the decoded value, or an error code in case of failure.

The mapping of YUV channels to the parameter names used here is based on the channel ids in khr_df.h and is different from the convention used in format names in the Vulkan specification where G == Y, R = Cr and B = Cb.

◆ printDFD()

void printDFD	(	uint32_t *	DFD,
		uint32_t	dataSize )

Print a human-readable interpretation of a data format descriptor.

Parameters

DFD	Pointer to a data format descriptor.
dataSize	The maximum size that can be considered as part of the DFD.

◆ printDFDJSON()

void printDFDJSON	(	uint32_t *	DFD,
		uint32_t	dataSize,
		uint32_t	base_indent,
		uint32_t	indent_width,
		bool	minified )

Print a JSON interpretation of a data format descriptor.

Parameters

DFD	Pointer to a data format descriptor.
dataSize	The maximum size that can be considered as part of the DFD.
base_indent	The number of indentations to include at the front of every line
indent_width	The number of spaces to add with each nested scope
minified	Specifies whether the JSON output should be minified

Prints an enum as string or number

Prints an enum as string or number if the to string function fails with a trailing comma

Prints an enum as string or number if the to string function fails without a trailing comma

◆ reconstructDFDBytesPlane0FromSamples()

uint32_t reconstructDFDBytesPlane0FromSamples ( const uint32_t * DFD )

Reconstruct the value of bytesPlane0 from sample info.

Deprecated: Use reconstructDFDBytesPlanesFromSamples. This does not handle the possible second plane of the ETC1S model.

Reconstruct the value for data that has been variable-rate compressed and and whose bytesPlane0 value has been set to 0. For DFDs that are valid for KTX files. Little-endian data only and no multi-plane models except ETC1S.

Parameters

DFD	Pointer to the Data Format Descriptor for which to provide the value described as 32-bit words in native endianness. Note that this is the whole descriptor, not just the basic descriptor block.

Returns: The number of bytes a pixel occupies in bytesPlane0.

◆ reconstructDFDBytesPlanesFromSamples()

void reconstructDFDBytesPlanesFromSamples ( uint32_t * DFD )

Reconstruct the values of bytesPlane[01] from sample info.

Reconstruct the values for data that has been variable-rate compressed and whose bytesPlane[01] values have been set to 0 and update the fields of the target DFD. For DFDs that are valid for KTX files. Little-endian data only and no multi-plane models except ETC1S hence only looking at bytesPlane0 abd bytesPlane1.

Parameters

DFD	Pointer to a Data Format Descriptor for which, described as 32-bit words in native endianness. Note that this is the whole descriptor, not just the basic descriptor block.

◆ recreateBytesPlane0FromSampleInfo()

void recreateBytesPlane0FromSampleInfo	(	const uint32_t *	DFD,
		uint32_t *	bytesPlane0 )

Reconstruct the value of bytesPlane0 from sample info.

See also: reconstructDFDBytesPlane0FromSamples for details.

Deprecated: For backward comparibility only. Use reconstructDFDBytesPlanesFromSamples.

Parameters

DFD	Pointer to the Data Format Descriptor for which to provide the value described as 32-bit words in native endianness. Note that this is the whole descriptor, not just the basic descriptor block.
bytesPlane0	pointer to a 32-bit word in which the recreated value of bytesPlane0 will be written.

◆ vk2dfd()

uint32_t * vk2dfd ( enum VkFormat format )

Create a DFD matching a VkFormat.

Parameters

[in] format VkFormat for which to create a DFD.

Returns: pointer to the created DFD or 0 if format not supported or unrecognized. Caller is responsible for freeing the created DFD.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ Primaries

Enumeration Type Documentation

◆ InterpretDFDResult

◆ VkCompScheme

◆ VkSuffix

Function Documentation

◆ createDFDAlpha()

◆ createDFDCompressed()

◆ createDFDDepthStencil()

◆ createDFDPacked()

◆ createDFDPackedShifted()

◆ createDFDUnpacked()

◆ dfd2vk()

◆ findMapping()

◆ getDFDComponentInfoUnpacked()

◆ getDFDNumComponents()

◆ getPrimaries()

◆ interpretDFD()

◆ printDFD()

◆ printDFDJSON()

◆ reconstructDFDBytesPlane0FromSamples()

◆ reconstructDFDBytesPlanesFromSamples()

◆ recreateBytesPlane0FromSampleInfo()

◆ vk2dfd()