Struct EncodingSupport

pub struct EncodingSupport { /* private fields */ }

Describes the extent of support for encoding a format.

Implementations

impl EncodingSupport

pub const fn dithering(&self) -> Dithering

Whether and what type of dithering is supported.

pub const fn split_height(&self) -> Option<NonZeroU8>

The split height for the image format.

Encoding most formats is trivially parallelizable, by splitting the image into chunks by lines, encoding each chunk separately, and writing the encoded chunks to the output stream in order.

This value specifies how many lines need to be grouped together for correct encoding. E.g. BC1_UNORM requires 4 lines to be grouped together, meaning that all chunks (except the last one) must have a height that is a multiple of 4. So e.g. an image with a height of 10 pixels can split into chunks with heights of 4-4-2, 8-2, 4-6, or 10.

crate::SplitSurface will automatically split the image into chunks of the correct height, so this value is only relevant if you are implementing your own encoder/splitter.

Note that most dithering will produce different (but not necessarily incorrect) results if the image is split into chunks. However, all BCn formats implement block-based local dithering, meaning that the dithering is the same whether the image is split or not. See EncodingSupport::local_dithering().

pub const fn local_dithering(&self) -> bool

Whether the format supports local dithering.

Most formats implement global error diffusing dithering for best quality. However, this prevents parallel encoding of the image, as the dithering error of one chunk depends on the dithering error of the previous chunk. It’s still possible to encode the image in parallel, but the dither pattern may reveal the chunk seams.

Local dithering on the other hand will attempt to diffuse the error within a small region of the image. E.g. BC1_UNORM will dither within a 4x4 block. This allows the image to be split into chunks and encoded in parallel without revealing the chunk seams.

self.dithering() == Dithering::None implies self.local_dithering() == false.

pub const fn size_multiple(&self) -> Option<(NonZeroU32, NonZeroU32)>

The size multiple of the encoded image, if any.

Some formats require the image to be a multiple of a certain size. E.g. NV12 requires the image to be a multiple of 2x2 pixels, meaning that the width and height of the image must be even.

Formats that can encode images of any size will return None.

If Some is returned, the width and height of the returned value are both non-zero, and at least one of them is greater than 1.

Use EncodingSupport::supports_size() to check if a given image size is supported by the format.

Example

let format = Format::NV12;
let encoding = format.encoding_support().unwrap();

assert_eq!(
    encoding.size_multiple(),
    Some((NonZeroU32::new(2).unwrap(), NonZeroU32::new(2).unwrap()))
);
assert_eq!(encoding.supports_size(Size::new(2, 2)), true);
assert_eq!(encoding.supports_size(Size::new(3, 2)), false);

pub const fn supports_size(&self, size: Size) -> bool

Whether the given image size is supported for encoding.

This will always return true if EncodingSupport::size_multiple() is None.

Trait Implementations

impl Clone for EncodingSupport

fn clone(&self) -> EncodingSupport

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for EncodingSupport

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

Formats the value using the given formatter.

impl Copy for EncodingSupport