Struct PixelDescriptor 

#[non_exhaustive]
pub struct PixelDescriptor {
    pub format: PixelFormat,
    pub transfer: TransferFunction,
    pub alpha: Option<AlphaMode>,
    pub primaries: ColorPrimaries,
    pub signal_range: SignalRange,
}

Compact pixel format descriptor.

Combines a PixelFormat (physical pixel layout) with transfer function, alpha mode, color primaries, and signal range.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

format: PixelFormat

Physical pixel format (channel type + layout as a flat enum).

transfer: TransferFunction

Electro-optical transfer function.

alpha: Option<AlphaMode>

Alpha interpretation. None = no alpha channel.

primaries: ColorPrimaries

Color primaries (gamut). Defaults to BT.709/sRGB.

signal_range: SignalRange

Signal range (full vs narrow/limited). See SignalRange for the exact ITU anchor definition, bit-depth scaling, and the no-relabeling conversion rule.

Implementations

impl PixelDescriptor

pub const RGB8_SRGB: PixelDescriptor

8-bit sRGB RGB.

pub const RGBA8_SRGB: PixelDescriptor

8-bit sRGB RGBA with straight alpha.

pub const RGB16_SRGB: PixelDescriptor

16-bit sRGB RGB.

pub const RGBA16_SRGB: PixelDescriptor

16-bit sRGB RGBA with straight alpha.

pub const RGBF32_LINEAR: PixelDescriptor

Linear-light f32 RGB.

pub const RGBAF32_LINEAR: PixelDescriptor

Linear-light f32 RGBA with straight alpha.

pub const GRAY8_SRGB: PixelDescriptor

8-bit sRGB grayscale.

pub const GRAY16_SRGB: PixelDescriptor

16-bit sRGB grayscale.

pub const GRAYF32_LINEAR: PixelDescriptor

Linear-light f32 grayscale.

pub const GRAYA8_SRGB: PixelDescriptor

8-bit sRGB grayscale with straight alpha.

pub const GRAYA16_SRGB: PixelDescriptor

16-bit sRGB grayscale with straight alpha.

pub const GRAYAF32_LINEAR: PixelDescriptor

Linear-light f32 grayscale with straight alpha.

pub const BGRA8_SRGB: PixelDescriptor

8-bit sRGB BGRA with straight alpha.

pub const RGBX8_SRGB: PixelDescriptor

8-bit sRGB RGBX (padding byte, not alpha).

pub const BGRX8_SRGB: PixelDescriptor

8-bit sRGB BGRX (padding byte, not alpha).

pub const RGB16_BT2100_PQ: PixelDescriptor

16-bit BT.2100 PQ RGB (BT.2020 primaries, PQ transfer, full range) — CICP (9, 16, 0, full). The common interchange form for HDR10-style stills decoded to u16.

Use new_full for other channel types or layouts in this color space.

pub const RGB16_BT2100_HLG: PixelDescriptor

16-bit BT.2100 HLG RGB (BT.2020 primaries, HLG transfer, full range) — CICP (9, 18, 0, full).

Use new_full for other channel types or layouts in this color space.

pub const RGB8: PixelDescriptor

8-bit RGB, transfer unknown.

pub const RGBA8: PixelDescriptor

8-bit RGBA, transfer unknown.

pub const RGB16: PixelDescriptor

16-bit RGB, transfer unknown.

pub const RGBA16: PixelDescriptor

16-bit RGBA, transfer unknown.

pub const RGBF32: PixelDescriptor

f32 RGB, transfer unknown.

pub const RGBAF32: PixelDescriptor

f32 RGBA, transfer unknown.

pub const GRAY8: PixelDescriptor

8-bit grayscale, transfer unknown.

pub const GRAY16: PixelDescriptor

16-bit grayscale, transfer unknown.

pub const GRAYF32: PixelDescriptor

f32 grayscale, transfer unknown.

pub const GRAYA8: PixelDescriptor

8-bit grayscale with alpha, transfer unknown.

pub const GRAYA16: PixelDescriptor

16-bit grayscale with alpha, transfer unknown.

pub const GRAYAF32: PixelDescriptor

f32 grayscale with alpha, transfer unknown.

pub const BGRA8: PixelDescriptor

8-bit BGRA, transfer unknown.

pub const RGBX8: PixelDescriptor

8-bit RGBX, transfer unknown.

pub const BGRX8: PixelDescriptor

8-bit BGRX, transfer unknown.

pub const OKLABF32: PixelDescriptor

Oklab f32 (L, a, b), transfer unknown.

pub const OKLABAF32: PixelDescriptor

Oklab+alpha f32 (L, a, b, alpha), transfer unknown.

pub const CMYK8: PixelDescriptor

8-bit CMYK, no transfer function or primaries.

pub const fn pixel_format(&self) -> PixelFormat

The pixel format variant (layout + depth, no transfer or alpha semantics).

pub const fn channel_type(&self) -> ChannelType

Channel storage type.

pub const fn alpha(&self) -> Option<AlphaMode>

Alpha interpretation. None = no alpha channel.

pub const fn transfer(&self) -> TransferFunction

Transfer function.

pub const fn color_profile_source(&self) -> ColorProfileSource<'static>

Extract the color encoding as a crate::ColorProfileSource::PrimariesTransferPair.

pub const fn byte_order(&self) -> ByteOrder

Byte order.

pub const fn color_model(&self) -> ColorModel

Color model.

pub const fn layout(&self) -> ChannelLayout

Channel layout (derived from the PixelFormat variant).

pub const fn new( channel_type: ChannelType, layout: ChannelLayout, alpha: Option<AlphaMode>, transfer: TransferFunction, ) -> PixelDescriptor

Create a descriptor with default primaries (BT.709) and full range.

See also

• new_full — same constructor with an explicit ColorPrimaries argument, for anything that isn’t BT.709/sRGB gamut (BT.2020 HDR, Display P3, …).
• The HDR presets RGB16_BT2100_PQ / RGB16_BT2100_HLG — common BT.2100 combinations without spelling out the enums.

Panics

Panics if the (channel_type, layout, alpha) combination has no corresponding PixelFormat variant (e.g. (U16, Bgra, _)).

pub const fn new_full( channel_type: ChannelType, layout: ChannelLayout, alpha: Option<AlphaMode>, transfer: TransferFunction, primaries: ColorPrimaries, ) -> PixelDescriptor

Create a descriptor with explicit primaries.

See also

• new — the four-argument form when BT.709/sRGB primaries (the default) are what you want.
• RGB16_BT2100_PQ / RGB16_BT2100_HLG — ready-made BT.2100 HDR presets built on this constructor.

Panics

Panics if the (channel_type, layout, alpha) combination has no corresponding PixelFormat variant.

pub const fn from_pixel_format(format: PixelFormat) -> PixelDescriptor

Create from a PixelFormat with default alpha, unknown transfer, BT.709 primaries, and full range.

pub const fn channels(self) -> usize

Number of channels.

pub const fn bytes_per_pixel(self) -> usize

Bytes per pixel.

pub const fn bytes_per_channel(self) -> usize

Bytes per channel (1 for U8, 2 for U16/F16, 4 for F32).

Shorthand for self.channel_type().byte_size() — the per-sample width, as opposed to bytes_per_pixel (all channels of one pixel). The usual “do I need a high-bit-depth path?” check is bytes_per_channel() > 1.

pub const fn has_alpha(self) -> bool

Whether this descriptor has meaningful alpha data.

pub const fn is_grayscale(self) -> bool

Whether this descriptor is grayscale.

pub const fn is_bgr(self) -> bool

Whether this descriptor uses BGR byte order.

pub const fn with_transfer(self, transfer: TransferFunction) -> PixelDescriptor

Return a copy of this descriptor relabeled with a different transfer function. Does not touch any pixel bytes.

Use when the source data was mistagged (e.g., a codec decoded a profile-less image and you know its true TF from another source) or when you want to assert a particular TF for downstream planning without round-tripping through EOTF/OETF kernels.

This is metadata-only. To actually re-encode pixel bytes from one transfer function into another, pass a source buffer and a destination descriptor with the new TF into RowConverter::new — that builds a plan with the appropriate EOTF/OETF kernels.

pub const fn with_primaries(self, primaries: ColorPrimaries) -> PixelDescriptor

Return a copy of this descriptor relabeled with different primaries. Does not touch any pixel bytes or apply a gamut matrix.

Use when you know the true primaries of the source data independent of whatever upstream tagging said, or to assert a particular primary set for downstream planning.

This is metadata-only. To actually apply a gamut conversion (e.g., BT.709 → Display P3), pass the new descriptor as the destination to RowConverter::new — that inserts the appropriate gamut matrix in linear light.

pub const fn with_alpha(self, alpha: Option<AlphaMode>) -> PixelDescriptor

Return a copy of this descriptor relabeled with a different alpha mode. Does not touch any pixel bytes or apply (un)premultiply.

Use when the source alpha mode was mistagged or when you want to assert straight/premultiplied without round-tripping through the premul kernels.

This is metadata-only. To actually premultiply or un-premultiply pixel values, pass the new descriptor as the destination to RowConverter::new — that inserts a StraightToPremul or PremulToStraight step. (Note: the built-in premul kernels operate in the source byte space — “encoded premul”, per Canvas 2D semantics — not in linear light.)

pub const fn with_alpha_mode(self, alpha: Option<AlphaMode>) -> PixelDescriptor

Alias for with_alpha.

pub const fn with_signal_range( self, signal_range: SignalRange, ) -> PixelDescriptor

Return a copy with a different signal range.

This relabels the descriptor — it does not rescale any pixel values. Only use it to describe what the data already is (e.g. tagging broadcast HDR that is genuinely studio-swing as SignalRange::Narrow). Mislabeling lifts or crushes blacks; see SignalRange for the anchor definition and conversion rules.

pub const fn is_opaque(self) -> bool

Whether this format is fully opaque (no transparency possible).

Returns true when there is no alpha channel (None), the alpha bytes are undefined padding (Undefined), or alpha is all-255 (Opaque).

pub const fn may_have_transparency(self) -> bool

Whether this format may contain transparent pixels.

Returns true for Straight and Premultiplied.

pub const fn is_linear(self) -> bool

Whether the transfer function is Linear.

pub const fn is_unknown_transfer(self) -> bool

Whether the transfer function is Unknown.

pub const fn min_alignment(self) -> usize

Minimum byte alignment required for the channel type (1, 2, or 4).

pub const fn aligned_stride(self, width: u32) -> usize

Tightly-packed byte stride for a given width.

pub const fn simd_aligned_stride(self, width: u32, simd_align: usize) -> usize

SIMD-friendly byte stride for a given width.

The stride is a multiple of lcm(bytes_per_pixel, simd_align), ensuring every row start is both pixel-aligned and SIMD-aligned. simd_align must be a power of 2.

pub const fn layout_compatible(self, other: PixelDescriptor) -> bool

Whether this descriptor’s channel type and layout are compatible with other.

“Compatible” means the raw bytes can be reinterpreted as other without any pixel transformation — same channel type, same layout.

Trait Implementations

impl Clone for PixelDescriptor

fn clone(&self) -> PixelDescriptor

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for PixelDescriptor

impl Debug for PixelDescriptor

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

Formats the value using the given formatter.

impl Display for PixelDescriptor

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

Formats the value using the given formatter.

impl Eq for PixelDescriptor

impl From<PixelDescriptor> for FormatOption

fn from(descriptor: PixelDescriptor) -> Self

Converts to this type from the input type.

impl Hash for PixelDescriptor

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for PixelDescriptor

fn eq(&self, other: &PixelDescriptor) -> 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 PixelDescriptor