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

Enumerations
enum	VkSuffix { s_UNORM , s_SNORM , s_USCALED , s_SSCALED , s_UINT , s_SINT , s_SFLOAT , s_UFLOAT , s_SRGB }

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_FLOAT_FORMAT_BIT = 1u << 5u , i_COMPRESSED_FORMAT_BIT = 1u << 6u , i_YUVSDA_FORMAT_BIT = 1u << 7u , i_UNSUPPORTED_ERROR_BIT = 1u << 8u , 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.

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 *	createDFDPackedPadded (int bigEndian, int numChannels, int bits[], int paddings[], 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.

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.

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

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, Edgewise Consulting.

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.

◆ createDFDPackedPadded()

uint32_t * createDFDPackedPadded	(	int	bigEndian,
		int	numChannels,
		int	bits[],
		int	paddings[],
		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.
paddings[]	An array of length numChannels. Each entry is the number of padding bits after each channel.
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.

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

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

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.
R	Information about the decoded red channel or the depth channel, if any.
G	Information about the decoded green channel or the stencil channel, if any.
B	Information about the decoded blue channel, if any.
A	Information about the decoded alpha channel, if any.
wordBytes	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.

◆ 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

◆ 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

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ InterpretDFDResult

◆ VkCompScheme

◆ VkSuffix

Function Documentation

◆ createDFDAlpha()

◆ createDFDCompressed()

◆ createDFDDepthStencil()

◆ createDFDPacked()

◆ createDFDPackedPadded()

◆ createDFDUnpacked()

◆ findMapping()

◆ getPrimaries()

◆ interpretDFD()

◆ printDFD()

◆ printDFDJSON()

◆ vk2dfd()