Crate videoframe

Expand description

videoframe

A common vocabulary of pixel-format and color-metadata types for video processing pipelines.

LoC

§Overview

A common vocabulary of pixel-format and color-metadata types for video processing pipelines. Pure data types: no SIMD, no decoder, no codec, no math — just the shared spine that a color-conversion library, a decoder backend, and a frame consumer can all speak to without agreeing on anything heavier.

§What it provides

color — ITU-T H.273 color metadata enums (ColorMatrix, ColorPrimaries, ColorTransfer, ColorRange, ChromaLocation) bundled into ColorInfo. Plus DcpTargetGamut for DCI-XYZ pipelines.
cfa — Bayer color-filter-array description (BayerPattern).
pixel_format — single PixelFormat enum covering every pixel format in FFmpeg n8.1’s AVPixelFormat (254 variants excluding GPU-resident HW formats) plus cinema-RAW additions. Coverage is verified by cargo xtask check against vendored pixfmt.h slugs — see xtask.
frame — structural primitives (Dimensions, Rect, Plane<B>), the runtime-tagged VideoFrame<P, B>, and the orthogonal TimestampedFrame<F> wrapper bundling mediatime::Timestamp PTS + duration around any inner frame shape. Plus per-format typed *Frame<'a, BE> zero-copy borrow views + *FrameError validation (feature-gated).
source — per-format marker ZSTs (Yuv420p, Nv12, Rgb24, …), *Row<'a> borrows, *Sink subtraits, and *_to walker fns that iterate Frame → Row → PixelSink. The walker macro generates the marker / Row / Sink / walker quartet uniformly. Marker construction is Foo::new() (private () field locks shape evolution to additive changes).
PixelSink + SourceFormat sealed traits re-exported at the crate root.

§Installation

[dependencies]
# Lean — color + pixel_format + frame primitives.
# Adds `mediatime` + `derive_more`. ~600 LoC compiled.
videoframe = "0.2"

Opt into typed *Frame<'a> borrow views + the per-format source::* walker quartet per family:

videoframe = { version = "0.1", features = ["yuv-planar", "rgb"] }

Or take everything via the umbrella:

videoframe = { version = "0.1", features = ["frame"] }

§Per-family feature flags

Enable only the families your pipeline actually consumes — each flag pulls in just the matching *Frame validators, *Row borrow types, marker ZSTs, walker fn, and Sink subtraits. The frame umbrella enables all of them at once.

Feature	Formats
`yuv-planar`	`Yuv420p` / `422p` / `444p` / `440p` / `411p` / `410p` + 9-16 bit
`yuv-semi-planar`	`Nv12` / `16` / `21` / `24` / `42`, `P010` / `210` / `410` family
`yuva`	YUVA planar 8-bit + 9-16 bit
`yuv-packed`	`Yuyv422`, `Uyvy422`, `Yvyu422`, `Uyyvyy411`
`yuv-444-packed`	`V410`, `Xv30`, `Xv36`, `Ayuv64`, `Vuya`, `Vuyx`, `V30X`
`y2xx`	`Y210` / `Y212` / `Y216`
`v210`	`V210`
`rgb`	`Rgb24` / `Bgr24` / `Rgba` / `Bgra` + 10-bit + 16-bit
`rgb-float`	`Rgbf32` / `Rgbf16` + `Rgbaf16`/`f32`
`rgb-legacy`	`Rgb444` / `555` / `565` + Bgr counterparts
`gbr`	`Gbrp` / `Gbrap` + 9-16 bit + float
`gray`	`Gray8` / 9-16 bit / f32, `Ya8` / `Ya16`
`bayer`	Bayer 8 / 10 / 12 / 14 / 16-bit × 4 patterns
`xyz`	`Xyz12` (DCI-XYZ)
`mono`	`Monoblack` / `Monowhite` / `Pal8`
`frame`	umbrella — enables every sub-feature above

Deps pulled in by family features:

thiserror — every per-family feature (for *FrameError).
half — rgb-float, gbr, gray (for half::f16).
derive_more try_unwrap / unwrap — yuv-444-packed, y2xx.

§`no_std`

# Pure no_std — just enums, marker ZSTs, structural primitives.
videoframe = { version = "0.1", default-features = false }

# no_std + alloc — adds Vec-using helpers and tests.
videoframe = { version = "0.1", default-features = false, features = ["alloc"] }

The color, cfa, and pixel_format modules work without alloc (pure enums / Copy types). Per-family frame / source features work under no_std + alloc.

§xtask

cargo xtask sync fetches FFmpeg’s libavutil/pixfmt.h from the pinned release tag (currently n8.1), extracts every AV_PIX_FMT_<NAME> identifier, and writes the lowercase slug list to xtask/vendor/ffmpeg-pixfmts.txt.

cargo xtask check diffs the vendored slug list against PixelFormat::as_str() and fails on any missing variant. CI runs this so the PixelFormat enum stays exhaustive against the pinned FFmpeg version.

Vendoring only the slug list (not the LGPL pixfmt.h verbatim) sidesteps the license question.

§License

videoframe is under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE, LICENSE-MIT for details.

Re-exports§

pub use source::PixelSink;
pub use source::SourceFormat;

Modules§

color: Color metadata: enums for matrix, primaries, transfer, range, and chroma location — all closed-form per ITU-T H.273.
frame: Frame primitives + the typed source-format *Frame<'a, BE> borrow types.
pixel_format: Pixel format identifier — comprehensive coverage of FFmpeg’s AVPixelFormat enum plus Bayer mosaic and cinema-RAW formats.
source: Source pixel-format kernels — marker ZSTs, per-row borrow types (*Row<'a>), per-format Sink subtraits, and walker fns that iterate crate::frame::*Frame<'a, BE> row-by-row dispatching to a PixelSink.

Macros§

marker: Generates the canonical marker quartet (struct + new() + Sealed + SourceFormat) for a source-format marker type.