Enum PixelFormat 

#[non_exhaustive]
pub enum PixelFormat {
    NV12,
    NV21,
    P010LE,
    P016LE,
    NV16,
    P210LE,
    P216LE,
    P410LE,
    P416LE,
    NV24,
    NV12A,
    YUV420P,
    YUV422P,
    YUV444P,
    YUV420P10LE,
    YUV420P12LE,
    YUV420P14LE,
    YUV420P16LE,
    YUV422P10LE,
    YUV422P12LE,
    YUV422P14LE,
    YUV422P16LE,
    YUV444P10LE,
    YUV444P12LE,
    YUV444P14LE,
    YUV444P16LE,
    YUVA444P10LE,
    YUVA444P12LE,
    UYVY422,
    YUYV422,
    AYUV64LE,
    V216,
    Y210LE,
    RgbaU8,
    BgraU8,
    RgbxU8,
    BgrxU8,
    RgbaU16,
    BgraU16,
    RgbaF16,
    BgraF16,
    RgbaF32,
    BgraF32,
    Rgb10A2,
    RgbU16,
    R16U,
    R32F,
    Rgba16U,
}

Every pixel layout this crate understands.

#[non_exhaustive], so adding a variant is not a breaking change.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

NV12

NV21

P010LE

P016LE

NV16

Biplanar 8-bit 4:2:2 (FFmpeg AV_PIX_FMT_NV16): full-resolution R8 luma plane + half-width full-height RG8 interleaved U/V chroma plane. The 4:2:2 sibling of Self::NV12 and the 8-bit sibling of Self::P210LE — NVDEC’s SDK-13 NV16 output surface for 4:2:2 8-bit H.264/HEVC decode (Blackwell+).

P210LE

P216LE

P410LE

P416LE

NV24

Biplanar 8-bit 4:4:4 (FFmpeg AV_PIX_FMT_NV24): full-resolution R8 luma plane + full-resolution RG8 interleaved U/V chroma plane. The 4:4:4 sibling of Self::NV16 and the 8-bit sibling of Self::P410LE — VideoToolbox’s '444v' /'444f' (kCVPixelFormatType_444YpCbCr8BiPlanar{Video,Full}Range) native decode surface for 8-bit 4:4:4 HEVC RExt.

NV12A

Tri-planar 4:2:0 NV12 plus a full-resolution 8-bit alpha plane (Apple kCVPixelFormatType_420YpCbCr8VideoRange_8A_TriPlanar = 'v0a8'). Three planes: plane 0 full-resolution R8 luma (Y’), plane 1 half-resolution interleaved RG8 chroma (Cb, Cr) exactly like Self::NV12, plane 2 full-resolution R8 alpha. The colour planes are video-range Y’CbCr (BT.601/709/2020 matrix, the VideoRange fourcc suffix); the alpha plane is full-range by definition (code 0..255 maps linearly to 0..1 straight opacity — no limited-range video quantisation, no colour matrix), exactly like the alpha plane of the Self::YUVA444P10LE family and the A lane of Self::AYUV64LE. VideoToolbox’s decoder-native output surface for HEVC-with-alpha (muxa); the 8-bit member of the tri-planar YCbCr+alpha family (the only >8-bit carrier Apple publishes is the 16-bit 444YpCbCr16VideoRange_16A_TriPlanar 's4as' — there is no 10-bit planar alpha format). Imports zero-copy as three Metal textures (R8 + Rg8 + R8 Split(3)); all three plane primitives are core wgpu formats, so it is outside the TEXTURE_FORMAT_16BIT_NORM gate.

YUV420P

YUV422P

YUV444P

YUV420P10LE

YUV420P12LE

YUV420P14LE

YUV420P16LE

YUV422P10LE

YUV422P12LE

YUV422P14LE

YUV422P16LE

YUV444P10LE

YUV444P12LE

YUV444P14LE

YUV444P16LE

YUVA444P10LE

Planar YUV 4:4:4 + alpha (FFmpeg AV_PIX_FMT_YUVA444P10LE): four full-resolution R16 planes — Y, U, V, A — each carrying a 10-bit code LSB-aligned in a 16-bit little-endian word (AVPixFmtDescriptor.shift == 0, exactly like the alpha-less triplanar YUV*P10LE family). The alpha plane is full-range by definition (code 0..1023 maps linearly to 0..1 opacity — no limited-range video quantisation, no colour matrix); every conversion dequantises / requantises it through the full-range luma ladder regardless of the frame’s ColorRange. The alpha-carrying ProRes 4444 / 4444XQ interchange format (the prores_ks ENCODER input).

YUVA444P12LE

12-bit sibling of Self::YUVA444P10LE — the same four-plane LSB-aligned layout at 12 bits per code (alpha full-range, 0..4095 mapping 0..1 opacity). FFmpeg’s ProRes DECODER emits yuva444p12le for alpha-carrying 4444 / 4444XQ streams (the bitstream codes 12-bit), so this is the decode-side twin of the 10-bit encoder input.

UYVY422

YUYV422

AYUV64LE

V216

Packed 4:2:2, 16 bits per component (Apple kCVPixelFormatType_422YpCbCr16 = 'v216'). Single plane: for each horizontal pair of pixels, four 16-bit little-endian components in the order Cb, Y’0, Cr, Y’1 — the 16-bit sibling of the 8-bit '2vuy' / Self::UYVY422 layout (Apple Ice Floe #19). Stored under an Rgba16Unorm texture at half horizontal resolution (size_scale (2, 1)): one texel carries both luma samples plus the shared chroma pair, and the shader reinterprets the RGBA lanes as .r=Cb, .g=Y'0, .b=Cr, .a=Y'1. This is VideoToolbox’s decoder-native output surface for ProRes 422 (WWDC20) — pinning it eliminates the internal v216 → x422 pixel transfer VideoToolbox would otherwise insert on every frame. Video-range Y’CbCr.

Y210LE

Packed 4:2:2, 10 bits per component carried MSB-aligned in a 16-bit little-endian word (Microsoft/DXGI Y210, VAAPI VA_FOURCC_Y210 = 0x30313259). Single plane, 4 bytes/px: for each horizontal pair of pixels, four 16-bit words in the order Y’0, Cb, Y’1, Cr — each holding a 10-bit code in bits [15..6] with the low 6 bits zero (the same MSB-aligned convention as Self::P010LE). Stored under an Rgba16Unorm texture at half horizontal resolution (size_scale (2, 1)): one texel carries both luma samples plus the shared chroma pair, and the shader reinterprets the RGBA lanes as .r=Y'0, .g=Cb, .b=Y'1, .a=Cr — the 10-bit sibling of the 8-bit Self::YUYV422 lane order (whereas Self::V216 carries the 16-bit UYVY lane order). This is the VAAPI decoder-native output surface for HEVC Main 4:2:2 10 (VA_RT_FORMAT_YUV422_10) on Intel Gen11+; VAAPI defines no P210 fourcc, so Y210 is the 4:2:2-10 carrier. Video-range Y’CbCr.

RgbaU8

BgraU8

RgbxU8

Packed 8-bit R, G, B, X — 4 B/px, byte-identical to Self::RgbaU8 except that the fourth lane is padding, not alpha (FFmpeg AV_PIX_FMT_RGB0, DRM XBGR8888, AHardwareBuffer R8G8B8X8_UNORM).

The X contract, stated at the type: Self::alpha_channel answers AlphaChannel::Padding, so Self::has_alpha is false. The stored bits of lane 3 carry NO information — a producer may leave them at anything (a decoded FFV1 bgr0 frame writes 0x00 into all of them, i.e. “fully transparent” if they were ever read as alpha), and every reader MUST substitute full opacity instead of sampling them.

The storage is unchanged, so this costs nothing: the same RGBA8 plane, the same texture, the same zero-copy import. What changes is only what consumers are allowed to conclude from lane 3 — which is why this is a distinct PixelFormat and not a comment on Self::RgbaU8. Aliasing an X format onto its A twin is the one mistake this variant exists to make impossible.

BgrxU8

Packed 8-bit B, G, R, X — the BGRA-ordered twin of Self::RgbxU8, carrying the same opaque-X contract (FFmpeg AV_PIX_FMT_BGR0, DXGI B8G8R8X8_UNORM, DRM XRGB8888). The dominant desktop screen-capture layout: Windows desktop duplication, gdigrab / ddagrab, and X11 capture all hand over BGRX.

RgbaU16

BgraU16

RgbaF16

BgraF16

RgbaF32

BgraF32

Rgb10A2

Packed 10:10:10:2 unsigned-normalized RGBA, 4 B/px — R in bits 0..10, G 10..20, B 20..30, A 30..32 (little-endian; wgpu Rgb10a2Unorm, DXGI R10G10B10A2_UNORM, Vulkan A2B10G10R10_UNORM_PACK32). The HDR10 swapchain / foreign render-target format: lets a host describe a 10-bit PQ render target through the interop import/export path.

RgbU16

3-channel 16-bit unsigned RGB, interleaved, host-order. 6 bytes per pixel — the output shape of GPU RAW debayers such as the R3D SDK’s CUDA / OpenCL paths.

Packed buffer shape — there is no native wgpu texture format (no GPU samples 3-channel 16-bit natively). Consumers MUST check PixelFormat::is_packed_buffer_shape and route through a buffer-shape import path plus an RGB16 → RGBA16 expand pass before sampling.

R16U

Single-channel 16-bit unsigned-integer scalar field: one plane of PlaneFormat::R16Uint, 2 B/px, size_scale (1, 1). The single-channel analogue of Self::RgbaU16 for non-colour host workloads (a raw-sensor CFA mosaic, an index map, a 16-bit depth buffer). Read via textureLoad (texture_2d<u32>) on the GPU — not sampler-filterable. This is the PixelFormat a single-plane CPU surface keyed on R16Uint (or a CPU intermediate typed only by that storage primitive) materialises as, so a single-plane CPU image view covers it exactly like any other single-plane format.

R32F

Single-channel 32-bit float scalar field: one plane of PlaneFormat::R32Float, 4 B/px, size_scale (1, 1). The single-channel analogue of Self::RgbaF32 for non-colour host workloads (a normalized-linear CFA, a scalar coefficient field, a floating depth buffer). The PixelFormat a single-plane CPU surface keyed on R32Float (or a CPU intermediate typed only by that storage primitive) materialises as.

Rgba16U

Four-channel 16-bit unsigned-integer RGBA: one plane of PlaneFormat::RGBA16Uint, 8 B/px, size_scale (1, 1). The 4-channel integer analogue of Self::R16U for non-colour host workloads that carry several already-separated 16-bit channels per pixel (an already-colour multi-plane raw frame packed interleaved — Foveon’s 3 stacked layers, a pixel-shift RGBG quad, a linear-RGB DNG). Read via textureLoad (texture_2d<u32>) on the GPU — not sampler-filterable (the integer channels carry raw sensor counts that must not be normalised). The PixelFormat a single-plane CPU surface keyed on RGBA16Uint materialises as, so a single-plane CPU image view covers it exactly like any other single-plane format.

Implementations

impl PixelFormat

pub const ALL: &'static [PixelFormat]

Every PixelFormat, indexed by its shader_id — the single canonical roster to enumerate over.

Hand-written copies of this list drift: a gate that keeps its own copy silently stops checking the newest variants. One list, in the crate that owns the enum, is the only arrangement that cannot drift silently.

Adding a variant. Six exhaustive matches already fail to compile (plane_layout, bits_per_sample, shader_id, color_family, alpha_channel and packed_expand_depth). Adding the new ordinal to shader_id then trips Self::COUNT, which is what forces the entry here — so the roster stays complete without relying on anyone remembering it.

Order is shader_id order, and ALL[i].shader_id() == i is asserted at compile time below.

pub const COUNT: usize = 48

Number of PixelFormat variants — PixelFormat::ALL.len(), and one past the highest shader_id.

This constant is the tripwire that keeps Self::ALL complete: a new variant gets a new ordinal in the (compile-enforced) shader_id match, and the const assertion below then refuses to build until both this number and the roster entry follow. State it as a literal so the bump is a deliberate act.

pub const fn plane_layout(self) -> PlaneLayout

Immutable plane descriptor. Single source of truth for every backend’s upload / readback / shader.

pub const fn for_single_plane(plane: PlaneFormat) -> Option<PixelFormat>

The canonical single-plane PixelFormat whose only plane stores plane, or None when no single-plane PixelFormat represents that storage primitive (the sub-channel YUV plane primitives R8 / R16 / RG8 / RG16, which only exist as members of a multi-plane layout). The inverse of plane_layout().plane0.format restricted to the single-plane (count() == 1) formats.

This is the bridge a CPU backend uses to bind an intermediate buffer typed only by a PlaneFormat as a strided single-plane CPU image. BGRA8 resolves to Self::BgraU8; every other multi-channel primitive to its Rgba* form. The packed-buffer-shape RgbU16 is intentionally NOT produced here (it has no native single-plane sampling path).

pub const fn bytes_per_pixel(self) -> u32

Tight (unpadded) bytes per pixel of a single-plane format — plane0.format.bytes_per_sample(). For multi-plane formats this is the bytes-per-texel of plane 0 only; callers handling multi-plane layouts must use Self::plane_size + per-plane PlaneFormat::bytes_per_sample instead. A single-plane CPU image view derives its tight row stride as width * bytes_per_pixel().

pub fn plane_size(self, frame_w: u32, frame_h: u32, plane: u8) -> (u32, u32)

(width, height) of plane in pixels, given the frame’s nominal frame_w × frame_h. Panics on an out-of-range plane index.

A subsampled plane’s dimension is the frame dimension divided by the per-axis size_scale, rounded up — exactly matching FFmpeg’s av_image_fill_pointers / av_image_fill_plane_sizes (AV_CEIL_RSHIFT(dim, log2_chroma), i.e. (dim + s - 1) / s). At an odd frame dimension a 4:2:0 / 4:2:2 chroma plane therefore keeps its trailing half-covered row/column (e.g. 4:2:0 at 321×241 → chroma 161×121, not 160×120). This is the row/column count every FFmpeg-allocated source plane actually carries, so allocation sizing, stride recovery, and copy bounds must all agree with it. For even dimensions (the common case) the result is identical to a truncating divide.

pub const fn bits_per_sample(self) -> u8

Bits per sample in a single channel. For float formats, returns the width of the float (16 or 32).

pub const fn shader_id(self) -> u32

Stable ordinal for the format as GPU shaders see it.

Hard-coded literal match, NOT self as u32 — future variant insertion-order changes must not silently re-order the ordinals the GPU shaders depend on. Despite #[non_exhaustive], this match is exhaustive within the defining crate; any future variant added without a matching arm here will fail to compile.

pub const fn is_packed_buffer_shape(self) -> bool

True for packed multi-channel layouts that do not map to a native wgpu texture format. The decoded GpuResource for these formats MUST be a buffer-shape variant (CudaBufferHandle / OpenClMem of cl_mem buffer type / etc.) and consumers MUST run an expand pass before sampling.

The only such format is RgbU16 (6 B/px interleaved 16-bit RGB). (Rgb10A2 is NOT one of these — it maps natively to wgpu::TextureFormat::Rgb10a2Unorm.)

pub const fn is_hdr_native(self) -> bool

True if the format’s underlying precision is ≥10 bits and the layout is plausibly HDR. SDR 8-bit RGB/NV12/YUV420P are excluded.

pub const fn color_family(self) -> ColorFamily

The ColorFamily this format encodes its samples in — the coarse classification a colour-neutral-vs-colour-changing repack decision keys on (Yuv ↔ Yuv and Rgb ↔ Rgb are layout/bit-depth repacks within one colourspace; a family crossing is a real matrix transform). Hard-coded literal match — exhaustive within the defining crate, so a future variant must add an arm here.

pub const fn packed_expand_depth(self, range: ResolvedRange) -> u32

The bit depth at which a packed source carried on this format must have its limited swing decoded to full swing, or 0 when nothing is owed.

The ONE derivation of that answer — every route that ingests a packed RGB source (an encoder’s RGB plan, a still-image conversion, a render chain’s RGB input stage) should call it rather than derive its own. A second derivation is precisely how one route ends up right and another silently wrong, which is the failure the tri-state exists to remove.

It takes the resolved swing because that is what it consumes: “this source is narrow AND its carrier has an integer code space”. Callers holding a wire tag resolve it first — range.resolve(fmt.color_family()) — and callers that already hold a resolved value must not re-derive it.

This crate does not call it itself: it exists for the conversion code built on top of it.

0 (nothing owed) is returned for four genuinely different reasons, and all four are correct:

• the range resolves full — an explicit Full, or an unsignalled RGB source, which pl_color_levels_guess reads as full;
• the carrier is float (RgbaF16 / RgbaF32 / BGRA twins) — a narrow swing is a property of an integer code space and a float edge has none, so there is nothing to decode even if a caller insisted on the tag;
• the carrier is a scalar raw-channel field (R16U / R32F / Rgba16U) — no luma pedestal, and reachable only via an explicit Limited tag that does not describe a sensor mosaic or an index map;
• the carrier is YUV — its swing belongs to the YUV conversion path (luma / chroma dequantisation, which has its own chroma pedestal and its own MSB-aligned storage convention). Answering a depth here would invite a second, wrong decode on top of the right one.

The 0 sentinel suits a GPU-side config field that takes this depth directly with the same “0 = no expand” convention, so there is one convention end to end rather than an Option that every caller unwraps to 0.

Depths are the natural normalisation (code / (2^d − 1)), which is how a sampler reads a packed texture — NOT the MSB-aligned-in-16-bit convention a YUV dequantiser uses for a ≥10-bit plane. The two agree at 8 and 16 bits and differ by ~0.1% at 10/12/14, which is why a packed path needs its own affine rather than reusing the YUV one.

pub const fn alpha_channel(self) -> AlphaChannel

What this format’s fourth component means — the single source of truth for every alpha decision. See AlphaChannel for why the answer cannot be derived from the plane layout: an X-padded layout and its alpha-carrying twin are identical bytes.

Hard-coded literal match, exhaustive within the defining crate — a future variant must state its answer here rather than inherit one.

pub const fn has_alpha(self) -> bool

True when the format carries a dedicated alpha channel/plane — the single source of truth a compositor keys on to decide whether a decoded frame needs alpha compositing (opaque formats are blitted directly). Exactly AlphaChannel::Straight: an X-padded layout (Self::RgbxU8 / Self::BgrxU8) has four channels but no alpha, and answers false here, so a compositor gate that reads this predicate treats it as opaque.

pub const fn is_biplanar(self) -> bool

True for biplanar YUV layouts (one luma plane + one interleaved chroma plane). Covers NV12/NV21 (4:2:0 8-bit), NV16 (4:2:2 8-bit), NV24 (4:4:4 8-bit), P010/P016 (4:2:0 10/16-bit), P210/P216 (4:2:2 10/16-bit), P410/P416 (4:4:4 10/16-bit).

pub const fn requires_16bit_norm(self) -> bool

True when zero-copy importing / sampling this format needs the wgpu::Features::TEXTURE_FORMAT_16BIT_NORM adapter feature — i.e. any plane rides a 16-bit normalized storage primitive (PlaneFormat::requires_16bit_norm). The 10-/16-bit biplanar YUV families (P010/P210/P410/P016/P216/P416), the packed 16-bit AYUV64LE, and the 16-bit-unorm RGBA packings return true; the 8-bit families (NV12/NV16/NV24/…), the integer scalar fields (R16U, Rgba16U — R16Uint/Rgba16Uint storage), and the float formats return false. Derived from Self::plane_layout, so a new variant is classified automatically.

A decode backend can probe this against the device’s feature set to fail fast at construction (a clear error) instead of surfacing a late, less-readable HAL validation failure at import time.

pub const fn is_planar(self) -> bool

True for any multi-plane layout whose planes are all bare channel planes (R8 / R16 / RG8 / RG16) — the structural requirement for packing a frame into one linear per-plane-footprint allocation (e.g. one CUDA buffer carrying every plane of a frame). Covers every Self::is_biplanar format plus the triplanar YUV*P* family and the alpha-planar YUVA444P* quad layouts; packed formats (UYVY422 / AYUV64LE / RGB) are single-plane and excluded. Derived from Self::plane_layout, so a new planar variant is covered automatically.

pub const fn is_msb_aligned_storage(self) -> bool

FFmpeg sub-byte storage convention: for sub-16-bit YUV planar formats the 10/12/14-bit active code sits in one of two halves of the 16-bit storage word.

• MSB-aligned (u16 = code << (16 - bit_depth)): biplanar P010 / P016 / P210 / P216 / P410 / P416 (FFmpeg AVPixFmtDescriptor.shift = 16 - depth).
• LSB-aligned (u16 = code): triplanar YUV{420,422,444}P{10,12,14}LE plus the alpha-planar YUVA444P{10,12}LE (FFmpeg AVPixFmtDescriptor.shift = 0).

8-bit (R8) and 16-bit (R16 w/ depth=16) formats have no shift ambiguity and return true. RGB / packed YUV formats also return true (they have no half-word slack).

pub const fn storage_sample_scale(self) -> f32

Storage-alignment bridge factor between a normalised storage sample (code / 65535) and an MSB-aligned dequant / quant ladder — the per-format constant a GPU shader reading such a sample must apply too, so CPU and GPU paths agree exactly. Returns 2^(16 - bit_depth) for FFmpeg’s LSB-aligned triplanar YUV*P{10,12,14}LE family + YUVA444P{10,12}LE (AVPixFmtDescriptor.shift == 0) and 1.0 for every other layout (8-bit, true 16-bit P16LE, MSB-aligned biplanar, packed, RGB) — the bridge collapses to a no-op there.

Apply on the read side: multiply the storage-normalised sample to lift an LSB-aligned value into the MSB domain. The write side divides by this (or multiplies by storage_sample_scale_inv).

pub const fn storage_sample_scale_inv(self) -> f32

Write-side reciprocal of storage_sample_scale: multiply an MSB-aligned quantised sample by this to land it in this format’s storage convention. For a converter that multiplies on the write side; dividing by storage_sample_scale directly is equivalent (the factor is a power of two, so both are exact).

Trait Implementations

impl Clone for PixelFormat

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for PixelFormat

impl Debug for PixelFormat

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for PixelFormat

Available on crate feature serde only.

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for PixelFormat

impl Hash for PixelFormat

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

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 PixelFormat

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for PixelFormat

Available on crate feature serde only.

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for PixelFormat