7. Khronos Basic Data Format Descriptor Block

One basic descriptor block is intended to cover a large amount of metadata that is typically associated with common bulk data — most notably image or texture data. While this descriptor contains more information about the data interpretation than is needed by many applications, having a relatively comprehensive descriptor reduces the risk that metadata needed by different APIs will be lost in translation.

The format is described in terms of a repeating axis-aligned texel block composed of of samples. Each sample contains a single channel of information with a single spatial offset within the texel block, and consists of an amount of contiguous data. This descriptor block consists of information about the interpretation of the texel block as a whole, supplemented by a description of a number of samples taken from one or more planes of contiguous memory. For example, a 24-bit red/green/blue format may be described as a 1×1 pixel region, containing three samples, one of each color, in one plane. A YUV 4:2:0 format may consist of a repeating 2×2 region consisting of four Y samples and one sample each of U and V.

Table 11. Basic Data Format Descriptor layout

Byte 0 (LSB) Byte 1 Byte 2 Byte 3 (MSB)

0 (vendor_id)

0 (descriptor_type)

0 (version number)

24 + 16 times number of samples (descriptor_block_size)

color_model

color_primaries

transfer_function

flags

texel_block_dimension_0

texel_block_dimension_1

texel_block_dimension_2

texel_block_dimension_3

bytes_plane_0

bytes_plane_1

bytes_plane_2

bytes_plane_3

bytes_plane_4

bytes_plane_5

bytes_plane_6

bytes_plane_7

Sample information for first sample

Sample information for second sample (optional), etc.


The fields of the Basic Data Format Descriptor Block are described in the following sections.

7.1. vendor_id

The vendor_id for the Basic Data Format Descriptor Block is 0, defined as KHR_DF_VENDORID_KHRONOS in khr_df_vendorid_e.

7.2. descriptor_type

The descriptor_type for the Basic Data Format Descriptor Block is 0, a value reserved in khr_df_khr_descriptortype_e (the enumeration of Khronos-specific descriptor types) as KHR_DF_KHR_DESCRIPTORTYPE_BASICFORMAT.

7.3. version_number

The version_number relating to the Basic Data Format Descriptor Block as described in this specification is 0.

7.4. descriptor_block_size

The size of the Basic Data Format Descriptor Block depends on the number of samples contained within it. The memory requirements for this format are 24 bytes of shared data plus 16 bytes per sample. The descriptor_block_size is measured in bytes.

7.5. color_model

The color_model determines the set of color (or other data) channels which may be encoded within the data, though there is no requirement that all of the possible channels from the color_model be present. Most data fits into a small number of common color models, but compressed texture formats each have their own color model enumeration. Note that the data need not actually represent a color — this is just the most common type of content using this descriptor.

The available color models are described in the khr_df_model_e enumeration, and are represented as an unsigned 8-bit value.

Note that the numbering of the component channels is chosen such that those channel types which are common across multiple color models have the same enumeration value. That is, alpha is always encoded as channel ID 15, depth is always encoded as channel ID 14, and stencil is always encoded as channel ID 13. Luma/Luminance is always in channel ID 0. This numbering convention is intended to simplify code which can process a range of color models. Note that there is no guarantee that models which do not support these channels will not use this channel ID. Particularly, RGB formats do not have luma in channel 0, and a 16-channel undefined format is not obligated to represent alpha in any way in channel number 15.

KHR_DF_MODEL_UNSPECIFIED

When the data format is unknown or does not fall into a predefined category, utilities which perform automatic conversion based on an interpretation of the data cannot operate on it. This format should be used when there is no expectation of portable interpretation of the data using only the basic descriptor block.

For portability reasons, it is recommended that pixel-like formats with up to sixteen channels, but which cannot have those channels described in the basic block, be represented with a basic descriptor block with the appropriate number of samples from UNSPECIFIED channels, and then for the channel description to be stored in an extension block. This allows software which understands only the basic descriptor to be able to perform operations that depend only on channel location, not channel interpretation (such as image cropping). For example, a camera may store a raw format taken with a modified Bayer sensor, with “RGBW” (red, green, blue and white) sensor sites, or “RGBE” (red, green, blue and “emerald”). Rather than trying to encode the exact color coordinates of each sample in the basic descriptor, these formats could be represented by a four-channel “UNSPECIFIED” model, with an extension block describing the interpretation of each channel.

KHR_DF_MODEL_RGBSDA

This color model represents additive colors of three channels, nominally red, green and blue, supplemented by channels for alpha, depth and stencil. Note that in many formats, depth and stencil are stored in a completely independent buffer, but there are formats for which integrating depth and stencil with color data makes sense.

Table 12. Basic Data Format RGBSDA channels

Channel number Name Description

0

KHR_DF_CHANNEL_RGBSDA_RED

Red

1

KHR_DF_CHANNEL_RGBSDA_GREEN

Green

2

KHR_DF_CHANNEL_RGBSDA_BLUE

Blue

13

KHR_DF_CHANNEL_RGBSDA_STENCIL

Stencil

14

KHR_DF_CHANNEL_RGBSDA_DEPTH

Depth

15

KHR_DF_CHANNEL_RGBSDA_ALPHA

Alpha (transparency)


Portable representation of additive colors with more than three primaries requires an extension to describe the full color space of the channels present. There is no practical way to do this portably without taking significantly more space.

KHR_DF_MODEL_YUVSDA

This color model represents color differences with three channels, nominally luma (Y) and two color-difference chroma channels, U (Cb) and V (Cr), supplemented by channels for alpha, depth and stencil. These formats are distinguished by U and V being a delta between the Y channel and the blue and red channels respectively, rather than requiring a full color matrix. The conversion between YUV and RGB color spaces is defined in this case by the choice of value in the color_primaries field.

Note: Most single-channel luma data formats should select KHR_DF_MODEL_YUVSDA and use only the Y channel, unless there is a reason to do otherwise.

Table 13. Basic Data Format YUVSDA channels

Channel number Name Description

0

KHR_DF_CHANNEL_YUVSDA_Y

Y (luma/luminance)

1

KHR_DF_CHANNEL_YUVSDA_CB

U (Cb)

2

KHR_DF_CHANNEL_YUVSDA_CR

V (Cr)

13

KHR_DF_CHANNEL_YUVSDA_STENCIL

Stencil

14

KHR_DF_CHANNEL_YUVSDA_DEPTH

Depth

15

KHR_DF_CHANNEL_YUVSDA_ALPHA

Alpha (transparency)


KHR_DF_MODEL_YIQSDA

This color model represents color differences with three channels, nominally luma (Y) and two color-difference chroma channels, I and Q, supplemented by channels for alpha, depth and stencil. This format is distinguished by I and Q each requiring all three additive channels to evaluate.

Table 14. Basic Data Format YIQSDA channels

Channel number Name Description

0

KHR_DF_CHANNEL_YIQSDA_Y

Y (luma)

1

KHR_DF_CHANNEL_YIQSDA_I

I (in-phase)

2

KHR_DF_CHANNEL_YIQSDA_Q

Q (quadrature)

13

KHR_DF_CHANNEL_YIQSDA_STENCIL

Stencil

14

KHR_DF_CHANNEL_YIQSDA_DEPTH

Depth

15

KHR_DF_CHANNEL_YIQSDA_ALPHA

Alpha (transparency)


KHR_DF_MODEL_LABSDA

This color model represents the ICC perceptually-uniform L*a*b* color space, combined with the option of an alpha channel.

Table 15. Basic Data Format LABSDA channels

Channel number Name Description

0

KHR_DF_CHANNEL_LABSDA_L

L* (luma)

1

KHR_DF_CHANNEL_LABSDA_A

a*

2

KHR_DF_CHANNEL_LABSDA_B

b*

13

KHR_DF_CHANNEL_LABSDA_STENCIL

Stencil

14

KHR_DF_CHANNEL_LABSDA_DEPTH

Depth

15

KHR_DF_CHANNEL_LABSDA_ALPHA

Alpha (transparency)


KHR_DF_MODEL_CMYKA

This color model represents secondary (subtractive) colors and the combined key (black) channel, along with alpha.

Table 16. Basic Data Format CMYKA channels

Channel number Name Description

0

KHR_DF_CHANNEL_CMYKA_CYAN

Cyan

1

KHR_DF_CHANNEL_CMYKA_MAGENTA

Magenta

2

KHR_DF_CHANNEL_CMYKA_YELLOW

Yellow

3

KHR_DF_CHANNEL_CMYKA_KEY

Key/Black

15

KHR_DF_CHANNEL_CMYKA_ALPHA

Alpha (transparency)


KHR_DF_MODEL_XYZW

This “color model” represents channel data used for coordinate values — for example, as a representation of the surface normal in a bump map. Additional channels for higher-dimensional coordinates can be used by extending the channel number within the 4-bit limit of the channel_type field.

Table 17. Basic Data Format XYZW channels

Channel number Name Description

0

KHR_DF_CHANNEL_XYZW_X

X

1

KHR_DF_CHANNEL_XYZW_Y

Y

2

KHR_DF_CHANNEL_XYZW_Z

Z

3

KHR_DF_CHANNEL_XYZW_W

W


KHR_DF_MODEL_HSVA_ANG

This color model represents color differences with three channels, value (luminance or luma), saturation (distance from monochrome) and hue (dominant wavelength), supplemented by an alpha channel. In this model, the hue relates to the angular offset on a color wheel.

Table 18. Basic Data Format HSVA_ANG channels

Channel number Name Description

0

KHR_DF_CHANNEL_HSVA_ANG_VALUE

V (value)

1

KHR_DF_CHANNEL_HSVA_ANG_SATURATION

S (saturation)

2

KHR_DF_CHANNEL_HSVA_ANG_HUE

H (hue)

15

KHR_DF_CHANNEL_HSVA_ANG_ALPHA

Alpha (transparency)


KHR_DF_MODEL_HSLA_ANG

This color model represents color differences with three channels, lightness (maximum intensity), saturation (distance from monochrome) and hue (dominant wavelength), supplemented by an alpha channel. In this model, the hue relates to the angular offset on a color wheel.

Table 19. Basic Data Format HSLA_ANG channels

Channel number Name Description

0

KHR_DF_CHANNEL_HSLA_ANG_LIGHTNESS

L (lightness)

1

KHR_DF_CHANNEL_HSLA_ANG_SATURATION

S (saturation)

2

KHR_DF_CHANNEL_HSLA_ANG_HUE

H (hue)

15

KHR_DF_CHANNEL_HSLA_ANG_ALPHA

Alpha (transparency)


KHR_DF_MODEL_HSVA_HEX

This color model represents color differences with three channels, value (luminance or luma), saturation (distance from monochrome) and hue (dominant wavelength), supplemented by an alpha channel. In this model, the hue is generated by interpolation between extremes on a color hexagon.

Table 20. Basic Data Format HSVA_HEX channels

Channel number Name Description

0

KHR_DF_CHANNEL_HSVA_HEX_VALUE

V (value)

1

KHR_DF_CHANNEL_HSVA_HEX_SATURATION

S (saturation)

2

KHR_DF_CHANNEL_HSVA_HEX_HUE

H (hue)

15

KHR_DF_CHANNEL_HSVA_HEX_ALPHA

Alpha (transparency)


KHR_DF_MODEL_HSLA_HEX

This color model represents color differences with three channels, lightness (maximum intensity), saturation (distance from monochrome) and hue (dominant wavelength), supplemented by an alpha channel. In this model, the hue is generated by interpolation between extremes on a color hexagon.

Table 21. Basic Data Format HSLA_HEX channels

Channel number Name Description

0

KHR_DF_CHANNEL_HSLA_HEX_LIGHTNESS

L (lightness)

1

KHR_DF_CHANNEL_HSLA_HEX_SATURATION

S (saturation)

2

KHR_DF_CHANNEL_HSLA_HEX_HUE

H (hue)

15

KHR_DF_CHANNEL_HSLA_HEX_ALPHA

Alpha (transparency)


KHR_DF_MODEL_YCGCOA

This color model represents low-cost approximate color differences with three channels, nominally luma (Y) and two color-difference chroma channels, Cg (green/purple color difference) and Co (orange/cyan color difference), supplemented by a channel for alpha.

Table 22. Basic Data Format YCoCgA channels

Channel number Name Description

0

KHR_DF_CHANNEL_YCGCOA_Y

Y

1

KHR_DF_CHANNEL_YCGCOA_CG

Cg

2

KHR_DF_CHANNEL_YCGCOA_CO

Co

15

KHR_DF_CHANNEL_YCGCOA_ALPHA

Alpha (transparency)


Compressed formats

A number of compressed formats are supported as part of khr_df_model_e. In general, these formats will have a texel block dimension of the compression block size. Most contain a single sample of channel type 0 at offset 0,0 — where further samples are required, they should also be sited at 0,0. By convention, models which have multiple channels that are disjoint in memory have these channel locations described accurately.

The ASTC family of formats have a number of possible channels, and are distinguished by samples which reference some set of these channels. The texel_block_dimensions field determines the compression ratio for ASTC.

Floating-point compressed formats have lower and upper limits specified in floating point format. Integer compressed formats with a lower and upper of 0 and UINT32_MAX (for unsigned formats) or INT32_MIN and INT32_MAX (for signed formats) are assumed to map the full representable range to the 0..1 or -1..1 respectively.

KHR_DF_MODEL_DXT1A/KHR_DF_MODEL_BC1A

This model represents the DXT1 or BC1 format. Channel 0 indicates color. If a second sample is present it should use channel 1 to indicate that the “special value” of the format should represent transparency — otherwise the “special value” represents opaque black.

KHR_DF_MODEL_DXT2/3/KHR_DF_MODEL_BC2

This model represents the DXT2/3 format, also described as BC2. The alpha premultiplication state (the distinction between DXT2 and DXT3) is recorded separately in the descriptor. This model has two channels: ID 0 contains the color information and ID 15 contains the alpha information. The alpha channel is 64 bits and at offset 0; the color channel is 64 bits and at offset 64. No attempt is made to describe the 16 alpha samples for this position independently, since understanding the other channels for any pixel requires the whole texel block.

KHR_DF_MODEL_DXT4/5/KHR_DF_MODEL_BC3

This model represents the DXT4/5 format, also described as BC3. The alpha premultiplication state (the distinction between DXT4 and DXT5) is recorded separately in the descriptor. This model has two channels: ID 0 contains the color information and ID 15 contains the alpha information. The alpha channel is 64 bits and at offset 0; the color channel is 64 bits and at offset 64.

KHR_DF_MODEL_BC4

This model represents the Direct3D BC4 format for single-channel interpolated 8-bit data. The model has a single channel of id 0 with offset 0 and length 64 bits.

KHR_DF_MODEL_BC5

This model represents the Direct3D BC5 format for dual-channel interpolated 8-bit data. The model has two channels, 0 (red) and 1 (green), which should have their bit depths and offsets independently described: the red channel has offset 0 and length 64 bits and the green channel has offset 64 and length 64 bits.

KHR_DF_MODEL_BC6H

This model represents the Direct3D BC6H format for RGB floating-point data. The model has a single channel 0, representing all three channels, and occupying 128 bits.

KHR_DF_MODEL_BC7

This model represents the Direct3D BC7 format for RGBA data. This model has a single channel 0 of 128 bits.

KHR_DF_MODEL_ETC1

This model represents the original Ericsson Texture Compression format, with a guarantee that the format does not rely on ETC2 extensions. It contains a single channel of RGB data.

KHR_DF_MODEL_ETC2

This model represents the updated Ericsson Texture Compression format, ETC2. Channel 0 represents red, and is used for the R11 EAC format. Channel 1 represents green, and both red and green should be present for the RG11 EAC format. Channel 2 represents RGB combined content. Channel 15 indicates the presence of alpha. If the texel block size is 8 bytes and the RGB and alpha channels are co-sited, “punch through” alpha is supported. If the texel block size is 16 bytes and the alpha channel appears in the first 8 bytes, followed by 8 bytes for the RGB channel, 8-bit separate alpha is supported.

KHR_DF_MODEL_ASTC

This model represents Adaptive Scalable Texture Compression as a single channel in a texel block of 16 bytes. ASTC HDR (high dynamic range) and LDR (low dynamic range) modes are distinguished by the channel_id containing the flag KHR_DF_SAMPLE_DATATYPE_FLOAT: an ASTC texture that is guaranteed by the user to contain only LDR-encoded blocks should have the channel_id KHR_DF_SAMPLE_DATATYPE_FLOAT bit clear, and an ASTC texture that may include HDR-encoded blocks should have the channel_id KHR_DF_SAMPLE_DATATYPE_FLOAT bit set to 1. ASTC supports a number of compression ratios defined by different texel block sizes; these are selected by changing the texel block size fields in the data format. The single sample has a size of 128 bits.

7.6. color_primaries

It is not sufficient to define a buffer as containing, for example, additive primaries. Additional information is required to define what “red” is provided by the “red” channel. A full definition of primaries requires an extension which provides the full color space of the data, but a subset of common primary spaces can be identified by the khr_df_primaries_e enumeration, represented as an unsigned 8-bit integer value.

KHR_DF_PRIMARIES_UNSPECIFIED

This “set of primaries” identifies a data representation whose color representation is unknown or which does not fit into this list of common primaries. Having an “unspecified” value here precludes users of this data format from being able to perform automatic color conversion unless the primaries are defined in another way. Formats which require a proprietary color space — for example, raw data from a Bayer sensor that records the direct response of each filtered sample — can still indicate that samples represent “red”, “green” and “blue”, but should mark the primaries here as “unspecified” and provide a detailed description in an extension block.

KHR_DF_PRIMARIES_BT709

This value represents the Color Primaries defined by the ITU-R BT.709 specification, which is also shared by sRGB. RGB data is distinguished between BT.709 and sRGB by the Transfer Function. Conversion to and from BT.709 Y’CbCr (YUV) representation uses the color conversion matrix defined in the BT.709 specification. This is the preferred set of color primaries used by HDTV, and likely a sensible default set of color primaries for common rendering operations.

KHR_DF_PRIMARIES_SRGB is provided as a synonym for KHR_DF_PRIMARIES_BT709.

KHR_DF_PRIMARIES_BT601_EBU

This value represents the Color Primaries defined in the ITU-R BT.601 specification for standard-definition television, particularly for 625-line signals. Conversion to and from BT.601 Y’CbCr (YUV) uses the color conversion matrix defined in the BT.601 specification.

KHR_DF_PRIMARIES_BT601_SMPTE

This value represents the Color Primaries defined in the ITU-R BT.601 specification for standard-definition television, particularly for 525-line signals. Conversion to and from BT.601 Y’CbCr (YUV) uses the color conversion matrix defined in the BT.601 specification.

KHR_DF_PRIMARIES_BT2020

This value represents the Color Primaries defined in the ITU-R BT.2020 specification for ultra-high-definition television. Conversion to and from BT.2020 Y’CbCr (YUV) uses the color conversion matrix defined in the BT.2020 specification.

KHR_DF_PRIMARIES_CIEXYZ

This value represents the theoretical Color Primaries defined by the International Color Consortium for the ICC XYZ linear color space.

KHR_DF_PRIMARIES_ACES

This value represents the Color Primaries defined for the Academy Color Encoding System.

7.7. transfer_function

Many color representations contain a nonlinear transfer function which maps between a linear (intensity-based) representation and a more perceptually-uniform encoding. Common Transfer Functions are encoded in the khr_df_transfer_e enumeration and represented as an unsigned 8-bit integer. A fully-flexible transfer function requires an extension with a full color space definition. Where the Transfer Function can be described as a simple power curve, applying the function is commonly known as “gamma correction”. The transfer function is applied to a sample only when the sample’s KHR_DF_SAMPLE_DATATYPE_LINEAR bit is 0; if this bit is 1, the sample is represented linearly irrespective of the transfer_function.

When a color model contains more than one channel in a sample and the transfer function should be applied only to a subset of those channels, the convention of that model should be used when applying the transfer function. For example, ASTC stores both alpha and RGB data but is represented by a single sample; in ASTC, the transfer function is not conventionally applied to the alpha channel of the ASTC texture. In this case, the KHR_DF_SAMPLE_DATATYPE_LINEAR bit being zero means that the transfer function is “applied” to the ASTC sample in a way that only affects the RGB channels. This is not a concern for most color models, which explicitly store different channels in each sample.

If all the samples are linear, KHR_DF_TRANSFER_LINEAR should be used. In this case, no sample should have the KHR_DF_SAMPLE_DATATYPE_LINEAR bit set.

KHR_DF_TRANSFER_UNSPECIFIED

This value should be used when the Transfer Function is unknown, or specified only in an extension block, precluding conversion of color spaces and correct filtering of the data values using only the information in the basic descriptor block.

KHR_DF_TRANSFER_LINEAR

This value represents a linear Transfer Function: for color data, there is a linear relationship between numerical pixel values and the intensity of additive colors. This transfer function allows for blending and filtering operations to be applied directly to the data values.

KHR_DF_TRANSFER_SRGB

This value represents the nonlinear Transfer Function defined in the sRGB specification for mapping between numerical pixel values and intensity.

KHR_DF_TRANSFER_ITU

This value represents the nonlinear Transfer Function defined by the ITU and used in the BT.601, BT.709 and BT.2020 specifications.

KHR_DF_TRANSFER_NTSC

This value represents the nonlinear Transfer Function defined by the original NTSC television broadcast specification.

KHR_DF_TRANSFER_SLOG

This value represents a nonlinear Transfer Function used by some Sony video cameras to represent an increased dynamic range.

KHR_DF_TRANSFER_SLOG2

This value represents a nonlinear Transfer Function used by some Sony video cameras to represent a further increased dynamic range.

7.8. flags

The format supports some configuration options in the form of boolean flags; these are described in the khr_df_flags_e enumeration and represented in an unsigned 8-bit integer value.

In this version of the specification, the only flag defined is KHR_DF_FLAG_ALPHA_PREMULTIPIED. If this bit is set, any color information in the data should be interpreted as having been previously scaled by the alpha channel when performing blending operations. The value KHR_DF_FLAG_ALPHA_STRAIGHT is provided to represent this flag not being set, which indicates that the color values in the data should be interpreted as needing to be scaled by the alpha channel when performing blending operations. This flag has no effect if there is no alpha channel in the format.

7.9. texel_block_dimensions_[0..3]

The texel_block_dimensions define the number of coordinates covered by the repeating block described by the samples. Four separate values, represented as unsigned 8-bit integers, are supported, corresponding to successive dimensions. The Basic Data Format Descriptor Block supports up to four dimensions of encoding within a texel block, supporting, for example, a texture with three spatial dimensions and one temporal dimension. Nothing stops the data structure as a whole from having higher dimensionality: for example, a two-dimensional texel block can be used as an element in a six-dimensional look-up table.

The value held in each of these fields is one fewer than the size of the block in that dimension — that is, a value of 0 represents a size of 1, a value of 1 represents a size of 2, etc. A texel block which covers fewer than four dimensions should have a size of 1 in each dimension that it lacks, and therefore the corresponding fields in the representation should be 0.

For example, a YUV 4:2:0 representation may use a Texel Block of 2×2 pixels in the nominal coordinate space, corresponding to the four Y samples. The texel block dimensions in this case would be 2×2×1×1 (in the X, Y, Z and T dimensions, if the fourth dimension is interpreted as T). The texel_block_dimensions_[0..3] values would therefore be:

Table 23. Example Basic Data Format texel_block_dimensions for YUV 4:2:0

texel_block_dimensions_0

1

texel_block_dimensions_1

1

texel_block_dimensions_2

0

texel_block_dimensions_3

0


7.10. bytes_plane_[0..7]

The Basic Data Format Descriptor divides the image into a number of planes, each consisting of an integer number of consecutive bytes. The requirement that planes consist of consecutive data means that formats with distinct subsampled channels — such as YUV 4:2:0 — may require multiple planes to describe a channel. A typical YUV 4:2:0 image has two planes for the Y channel in this representation, offset by one line vertically.

The use of byte granularity to define planes is a choice to allow large texels (of up to 255 bytes). A consequence of this is that formats which are not byte-aligned on each addressable unit, such as 1-bit-per-pixel formats, need to represent a texel block of multiple samples, contained within a.

A maximum of eight independent planes is supported in the Basic Data Format Descriptor. Formats which require more than eight planes — which are rare — require an extension.

The bytes_plane_[0..7] fields each contain an unsigned 8-bit integer which represents the number of bytes which that plane contributes to the format. The first field which contains the value 0 indicates that only a subset of the 8 possible planes are present; that is, planes which are not present should be given the bytes_plane value of 0, and any bytes_plane values after the first 0 are ignored. If no bytes_plane value is zero, 8 planes are considered to exist.

As an exception, if bytes_plane_0 has the value 0, the first plane is considered to hold indices into a color palette, which is described by one or more additional planes and samples in the normal way. The first sample in this case should describe a 1×1×1×1 texel holding an unsigned integer value. The number of bits used by the index should be encoded in this sample, with a maximum value of the largest palette entry held in sample_upper. Subsequent samples describe the entries in the palette, starting at an offset of bit 0. Note that the texel block in the index plane is not required to be byte-aligned in this case, and will not be for paletted formats which have small palettes. The channel type for the index is irrelevant.

For example, consider a 5-color paletted texture which describes each of these colors using 8 bits of red, green, blue and alpha. The color model would be RGBSDA, and the format would be described with two planes. bytes_plane_0 would be 0, indicating the special case of a palette, and bytes_plane_1 would be 4, representing the size of the palette entry. The first sample would then have a number of bits corresponding to the number of bits for the palette — in this case, three bits, corresponding the requirements of a 5-color palette. The sample_upper value for this sample is 4, indicating only 5 palette entries. Four subsequent samples represent the red, green, blue and alpha channels, starting from bit 0 as though the index value were not present, and describe the contents of the palette. The full data format descriptor for this example is provided as one of the example format descriptors.

7.11. Sample information

The layout and position of the information within each plane is determined by a number of samples, each consisting of a single channel of data and with a single corresponding position within the texel block.

The bytes from the plane data contributing to the format are treated as though they have been concatenated into a bit stream, with the first byte of the lowest-numbered plane providing the lowest bits of the result. Each sample consists of a number of consecutive bits from this bit stream. If the content for a channel cannot be represented in a single sample, for example because the data for a channel is nonconsecutive within this bit stream, additional samples with the same coordinate position and channel number should follow from the first, in order increasing from the least significant bits from the channel data. Note that some native big-endian formats may need to be supported with multiple samples in a channel, since the constituent bits may not be consecutive in a little-endian interpretation. There is an example in the list of format descriptors provided. In this case, the sample_lower and sample_upper fields for the combined sample are taken from the first sample to belong uniquely to this channel/position pair.

By convention, to avoid aliases for formats, samples should be listed in order starting with channels at the lowest bits of this bit stream.

The number of samples present in the format is determined by the descriptor_block_size field. There is no limit on the number of samples which may be present, other than the maximum size of the Data Format Descriptor Block. There is no requirement that samples should access unique parts of the bit-stream (formats such as combined intensity and alpha, or shared exponent formats, require that bits be reused). Nor is there a requirement that all the bits in a plane be used (a format may contain padding).

Table 24. Basic Data Format Descriptor Sample Information

Byte 0 (LSB) Byte 1 Byte 2 Byte 3 (MSB)

bit_offset

bit_length

channel_type

sample_position_0

sample_position_1

sample_position_2

sample_position_3

sample_lower

sample_upper


bit_offset

The bit_offset field describes the offset of the least significant bit of this sample from the least significant bit of the least significant byte of the concatenated bit stream for the format. Typically the bit_offset of the first sample is therefore 0; a sample which begins at an offset of one byte relative to the data format would have a Bit Offset of 8. The Bit Offset is an unsigned 16-bit integer quantity.

bit_length

The bit_length field describes the number of consecutive bits from the concatenated bit stream that contribute to the sample. This field is an unsigned 8-bit integer quantity, and stores the number of bits contributed minus 1; thus a single-byte channel should have a bit_length field value of 7. If a bit_length of more than 256 is required, further samples should be added; the value for the sample is composed in increasing order from least to most significant bit as subsequent samples are processed.

channel_type

The channel_type field is an unsigned 8-bit quantity.

The bottom four bits of the channel_type indicates which channel is being described by this sample. The list of available channels is determined by the color_model field of the Basic Data Format Descriptor Block, and the channel_type field contains the number of the required channel within this list — see the color_model field for the list of channels for each model.

The top four bits of the channel_type are described by the khr_df_sample_datatype_qualifiers_e enumeration:

If the KHR_DF_SAMPLE_DATATYPE_LINEAR bit is not set, the sample value is modified by the transfer function defined in the format’s transfer_function field; if this bit is set, the sample is considered to contain a linearly-encoded value irrespective of the format’s transfer_function.

If the KHR_DF_SAMPLE_DATATYPE_EXPONENT bit is set, this sample holds an exponent (in integer form) for this channel. For example, this would be used to describe the shared exponent location in shared exponent formats (with the exponent bits listed separately under each channel). An exponent is applied to any integer sample of the same type. If this bit is not set, the sample is considered to contain mantissa information. If the KHR_DF_SAMPLE_DATATYPE_SIGNED bit is also set, the exponent is considered to be two’s complement — otherwise it is treated as unsigned. The bias of the exponent can be determined by the sample’s lower and upper values. The presence or absence of an implicit leading digit in the mantissa of a format with an exponent can be determined by the upper value.

If the KHR_DF_SAMPLE_DATATYPE_SIGNED bit is set, the sample holds a signed value in two’s complement form. If this bit is not set, the sample holds an unsigned value. It is possible to represent a sign/magnitude integer value by having a sample of unsigned integer type with the same channel and sample location as a 1-bit signed sample.

If the KHR_DF_SAMPLE_DATATYPE_FLOAT bit is set, the sample holds floating point data in a conventional format of 10, 11, 16, 32, or 64-bits. KHR_DF_SAMPLE_DATATYPE_SIGNED should be set unless a genuine unsigned format is intended. Less common floating point representations can be generated with multiple samples and a combination of signed integer, unsigned integer and exponent fields.

sample_position_[0..3]

The sample has an associated location within the 4-dimensional space of the texel block. Each sample has an offset relative to the 0,0 position of the texel block, determined in units of half a coordinate. This allows the common situation of downsampled channels to have samples conceptually sited at the midpoint between full resolution samples. Support for offsets other than multiples of a half coordinates require an extension. The direction of the sample offsets is determined by the coordinate addressing scheme used by the API. There is no limit on the dimensionality of the data, but if more than four dimensions need to be contained within a single texel block, an extension will be required.

Each sample_position is an 8-bit unsigned integer quantity. sample_position_0 is the X offset of the sample, sample_position_1 is the Y offset of the sample, etc. Formats which use an offset larger than 127.5 in any dimension require an extension.

It is legal, but unusual, to use the same bits to represent multiple samples at different coordinate locations.

sample_lower

Sample_lower, combined with sample_upper, is used to represent the mapping between the numerical value stored in the format and the conceptual numerical interpretation. For unsigned formats, sample_lower typically represents the value which should be interpreted as zero (the black point). For signed formats, sample_lower typically represents “-1”.

If the channel encoding is an integer format, the sample_lower value is represented as a 32-bit integer — signed or unsigned according to whether the channel encoding is signed. If the channel encoding is a floating point value, the sample_lower value is also floating point. If the number of bits in the sample is greater than 32, the lowest representable value for sample_lower is interpreted as the smallest value representable in the channel format.

For example, the BT.709 television broadcast standard dictates that the Y' value stored in an 8-bit encoding should fall between the range 16 and 235. In this case, sample_lower should contain the value 16.

In OpenGL terminology, a “normalized” channel contains an integer value which is mapped to the range 0..1.0. A channel which is not normalized contains an integer value which is mapped to a floating point equivalent of the integer value. Similarly an “snorm” channel is a signed normalized value mapping from -1.0 to 1.0. Setting sample_lower to the minimum signed integer value representable in the channel is equivalent to defining an “snorm” texture.

sample_upper

Sample_upper, combined with sample_lower, is used to represent the mapping between the numerical value stored in the format and the conceptual numerical interpretation. Sample_upper typically represents the value which should be interpreted as “1.0” (the “white point”).

If the channel encoding is an integer format, the sample_upper value is represented as a 32-bit integer — signed or unsigned according to whether the channel encoding is signed. If the channel encoding is a floating point value, the sample_upper value is also floating point. If the number of bits in the sample is greater than 32, the highest representable value for sample_upper is interpreted as the largest value representable in the channel format.

For example, the BT.709 television broadcast standard dictates that the Y' value stored in an 8-bit encoding should fall between the range 16 and 235. In this case, sample_upper should contain the value 235.

In OpenGL terminology, a “normalized” channel contains an integer value which is mapped to the range 0..1.0. A channel which is not normalized contains an integer value which is mapped to a floating point equivalent of the integer value. Similarly an “snorm” channel is a signed normalized value mapping from -1.0 to 1.0. Setting sample_upper to the maximum signed integer value representable in the channel for a signed channel type is equivalent to defining an “snorm” texture. Setting sample_upper to the maximum unsigned value representable in the channel for an unsigned channel type is equivalent to defining a “normalized” texture. Setting sample_upper to “1” is equivalent to defining an “unnormalized” texture.

Sensor data from a camera typically does not cover the full range of the bit depth used to represent it. Sample_upper can be used to specify an upper limit on sensor brightness — or to specify the value which should map to white on the display, which may be less than the full dynamic range of the captured image.

There is no guarantee or expectation that image data be guaranteed to fall between sample_lower and sample_upper unless the users of a format agree that convention.