Enum PixelFormat 

#[non_exhaustive]
#[repr(u8)]
pub enum PixelFormat {
    Rgb = 1,
    Rgba = 2,
    Bgra = 3,
    Grey = 4,
    Yuyv = 5,
    Vyuy = 6,
    Nv12 = 7,
    Nv16 = 8,
    PlanarRgb = 9,
    PlanarRgba = 10,
    Nv24 = 11,
}

Pixel format identifier.

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.

Rgb = 1

Packed RGB [H, W, 3]

Rgba = 2

Packed RGBA [H, W, 4]

Bgra = 3

Packed BGRA [H, W, 4]

Grey = 4

Grayscale [H, W, 1]

Yuyv = 5

Packed YUV 4:2:2, YUYV byte order [H, W, 2]

Vyuy = 6

Packed YUV 4:2:2, VYUY byte order [H, W, 2]

Nv12 = 7

Semi-planar YUV 4:2:0 [H*3/2, W] or multiplane [H, W] + [H/2, W]

Nv16 = 8

Semi-planar YUV 4:2:2 [H*2, W] or multiplane [H, W] + [H, W]

PlanarRgb = 9

Planar RGB, channels-first [3, H, W]

PlanarRgba = 10

Planar RGBA, channels-first [4, H, W]

Nv24 = 11

Semi-planar YUV 4:4:4, contiguous shape [H*3, W]. Full-resolution chroma: Y plane (H rows of W bytes) + interleaved Cb/Cr plane (H image rows of W pairs = 2W bytes/row, laid out as 2H rows of W) → 3H rows total. Multiplane NV24 is not yet supported (see from_planes). Added last to keep the existing #[repr(u8)] discriminants (and any serialized values) stable.

Implementations

impl PixelFormat

pub const fn channels(&self) -> usize

Returns the number of channels for this pixel format.

For semi-planar formats (NV12, NV16), this returns 1 (the luma channel count for the primary plane). For packed formats, this is the total number of interleaved components per pixel.

pub const fn layout(&self) -> PixelLayout

Returns the memory layout category for this pixel format.

pub fn image_shape(&self, width: usize, height: usize) -> Option<Vec<usize>>

The tensor shape for this format at width×height, or None if the dimensions are invalid for the format, or the format is an unsupported semi-planar variant (any SemiPlanar variant other than Nv12, Nv16, and Nv24).

Odd dimensions are fully supported. The combined-plane height for NV12 is height + ceil(height / 2) (luma rows + chroma rows), which equals the classic height * 3 / 2 for even heights and stays exact for odd ones — e.g. 483 → 725 rows (483 luma + 242 chroma).

For semi-planar formats the shape carries the logical width as-is (odd widths are preserved, e.g. [720, 789] for a 789×384 NV12). The row stride recorded separately on the tensor is >= even(width) and 64-byte aligned; it may exceed the logical width. Use effective_row_stride() to determine the true byte pitch for mapping and allocation. Allocation byte size = total_h * row_stride, NOT the shape product.

pub const fn combined_plane_height(&self, height: usize) -> Option<usize>

Combined-plane height in physical (stride-wide) rows for a semi-planar format: the Y rows plus the interleaved-UV rows.

• NV12 (4:2:0): H + ceil(H/2) — exact for odd heights (e.g. 483 → 725 = 483 luma + 242 chroma), equals the classic H*3/2 for even.
• NV16 (4:2:2): 2H (one full-height chroma row per luma row).
• NV24 (4:4:4): 3H (a full-width 2W-byte chroma line spans two stride-wide buffer rows, so 2H chroma rows).

Returns None for non-semi-planar formats (and unsupported SemiPlanar variants). This is the single source of truth for the vertical extent of the contiguous NV* buffer — image_shape, the GL DMA-BUF/IOSurface imports, the PBO allocator, and the gpu-probe all derive from it, so the combined-plane height can never drift between them.

pub const fn chroma_layout(&self) -> Option<ChromaLayout>

Per-format semi-planar chroma addressing parameters, shared by the codec writer (uv_rows_per_luma), the CPU readers, and both GL shaders so the combined-plane chroma geometry has a single source of truth. Returns None for non-semi-planar formats.

pub fn semi_planar_surface_dims( &self, width: usize, height: usize, bpe: usize, ) -> Option<(usize, usize)>

Physical GPU-surface dimensions (pitch_width, total_h) in texels for a semi-planar combined plane bound as one bpe-byte-per-element texture, or None for non-semi-planar formats.

The width is rounded up to the 64-aligned row pitch (== bytes_per_row) rather than left at the even logical width. ANGLE (and tiled GPUs in general) will not address texels beyond a surface’s declared width via texelFetch, so a surface narrower than its padded bytes_per_row leaves the padding columns unreachable. That is fatal for NV24 (4:4:4): its chroma line is 2*W interleaved bytes, which spills past the even width into those padding columns whenever the row is padded (bytes_per_row > even_width). Making the surface width equal the pitch keeps every byte addressable and costs nothing — bytes_per_row is already this value.

Single source of truth for both IOSurface allocators (the tensor crate’s IoSurfaceTensor::new_image and the image crate’s ImageLayout), so they cannot diverge.

pub const fn is_yuv(&self) -> bool

Returns true if this format encodes YUV (luma/chroma) data.

pub const fn has_alpha(&self) -> bool

Returns true if this format includes an alpha channel.

pub const fn to_fourcc(&self) -> u32

Returns the V4L2/DRM FourCC code for this format, or 0 for formats that have no standard FourCC representation (e.g., PlanarRgb).

pub const fn from_fourcc(fourcc: u32) -> Option<Self>

Converts a V4L2/DRM FourCC code to a PixelFormat, returning None for unrecognized or zero codes.

Trait Implementations

impl Clone for PixelFormat

fn clone(&self) -> PixelFormat

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

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for PixelFormat

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

Formats the value using the given formatter.

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: &PixelFormat) -> 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 Serialize for PixelFormat

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