Struct Basic 

pub struct Basic {
    pub color_model: Option<ColorModel>,
    pub color_primaries: Option<ColorPrimaries>,
    pub transfer_function: Option<TransferFunction>,
    pub flags: DataFormatFlags,
    pub texel_block_dimensions: [NonZeroU8; 4],
    pub bytes_planes: [u8; 8],
    pub sample_information: Vec<SampleInformation>,
}

“Basic” DFD block, containing information about texture-like data.

This is the most common type of DFD block found in KTX2 files.

Fields

color_model: Option<ColorModel>

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 colorModel be present.

See the DFD specification for more information on this than you’d ever need.

None means unknown/unspecified.

color_primaries: Option<ColorPrimaries>

The color primaries used by the data.

See the DFD specification for more information than you can shake a stick at.

None means unknown/unspecified.

transfer_function: Option<TransferFunction>

The function converting the encoded data to a linear color space.

See the DFD specification for more information.

None means unknown/unspecified.

flags: DataFormatFlags

Boolean flags modifying properties of the data. In practice, this is only used to indicate if the alpha channel is premultiplied.

See the DFD specification for more information.

texel_block_dimensions: [NonZeroU8; 4]

The dimensions of each “block” of texels in the image. For uncompressed formats, this is always 1x1x1x1. For compressed formats, this represents the dimensions of the compression block (e.g. 4x4x1x1 for BCn formats).

The dfd stores this as one less than the actual dimension. See the DFD specification for more information.

bytes_planes: [u8; 8]

The number of bytes in each plane of the data.

See the DFD specification for more information.

sample_information: Vec<SampleInformation>

Information about each “sample” within the data, describing how to interpret their bits of the data as color or other information.

Implementations

impl Basic

pub const FIXED_LENGTH: usize = 16

Number of bytes in the constant-size prefix of a Basic block, before the variable-length sample information.

pub fn from_format(format: Format) -> Result<(Self, u32), BuildError>

Creates a Basic DFD block for the given Format, using the format’s default transfer function, color primaries, color model, and straight (non-premultiplied) alpha.

Returns the DFD block and the crate::Header::type_size that corresponds to the provided format.

This is a convenience wrapper around from_format_with that uses the standard defaults for every parameter. If you need to customize any of these, use from_format_with instead.

Errors

Returns BuildError::UnsupportedFormat if the format is not recognized by the DFD generation table.

pub fn from_format_with( format: Format, alpha_premultiplied: bool, transfer_function: Option<TransferFunction>, color_primaries: Option<ColorPrimaries>, color_model: Option<ColorModel>, ) -> Result<(Self, u32), BuildError>

Creates a Basic DFD block for the given Format, with optional overrides for transfer function, color primaries, color model, and alpha premultiplication.

Returns the DFD block and the crate::Header::type_size that corresponds to the provided format and overrides.

Parameters set to None use the format’s natural defaults:

• alpha_premultiplied — when true, sets the ALPHA_PREMULTIPLIED flag, indicating that color channel values have already been scaled by the alpha channel. When false (the default), alpha is straight (non-premultiplied).

• transfer_function — overrides how encoded sample values are converted to linear light. The default depends on the format: sRGB format variants (e.g. R8G8B8A8_SRGB) default to TransferFunction::SRGB; all others default to TransferFunction::Linear. When you override the default transfer function, unlike with srgb-variant formats, the “alpha” channel is not automatically marked as linear by DFD generation, due to an ambiguity in the specification. See this issue. However, conventionally, the alpha channel of these formats is still expected to be linear.

• color_primaries — overrides the color primaries of the data. Defaults to ColorPrimaries::BT709 (the sRGB/Rec. 709 primaries used by most consumer content).

• color_model — overrides the color model. Defaults to ColorModel::RGBSDA for most formats, ColorModel::YUVSDA for 4:2:2 subsampled formats, or the intrinsic model for compressed formats. If this is changed from the default for the format, the dfd will be formally invalid, but this may be useful for some applications.

Format-specific restrictions

Not all overrides are valid for all formats. The following restrictions are enforced and will return an error if violated:

Depth-stencil formats (e.g. D16_UNORM_S8_UINT, D32_SFLOAT_S8_UINT)

Depth-stencil formats have a fixed DFD layout. No overrides are permitted: alpha_premultiplied must be false, and transfer_function, color_primaries, and color_model must all be None.

Compressed formats (e.g. BC7_UNORM_BLOCK, ASTC_4x4_SRGB_BLOCK)

Compressed formats must use their intrinsic color model (e.g. ColorModel::BC7, ColorModel::ASTC). The color_model parameter must be None.

sRGB variant rules

Formats that exist in both UNORM and SRGB variants (e.g. R8G8B8A8_UNORM / R8G8B8A8_SRGB, ASTC_4x4_UNORM_BLOCK / ASTC_4x4_SRGB_BLOCK) have strict transfer function requirements:

• UNORM variant (e.g. R8G8B8A8_UNORM): the transfer function must not be set to TransferFunction::SRGB. If you want sRGB encoding, use the SRGB variant of the format instead.

• SRGB variant (e.g. R8G8B8A8_SRGB): the transfer function must be TransferFunction::SRGB (or None to use the default). Overriding it to any other value is an error.

Formats without an sRGB counterpart (e.g. R16_UNORM, R32_SFLOAT, ASTC_4x4_SFLOAT_BLOCK) have no transfer function restrictions.

Errors

Returns a BuildError describing which constraint was violated. See the variant documentation for details.

pub fn parse(bytes: &[u8]) -> Result<Self, ParseError>

Parses a Basic block from the start of bytes.

pub fn serialized_length(&self) -> usize

Number of bytes the serialized form of this block will take up.

pub fn to_bytes(&self, output: &mut [u8])

Serializes this block to a given slice of bytes. The slice must be at least serialized_length bytes long.

pub fn to_vec(&self) -> Vec<u8>

Serializes this block to a vector of bytes.

Trait Implementations

impl Clone for Basic

fn clone(&self) -> Basic

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Basic

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for Basic

impl PartialEq for Basic

fn eq(&self, other: &Basic) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for Basic