Skip to main content

Crate rawshift_hwdec

Crate rawshift_hwdec 

Source
Expand description

§rawshift-hwdec

Hardware still-frame codestream decode for rawshift: HEVC (HEIC) and AV1 (AVIF) intra pictures through the platform decode APIs fixed in docs/SUPPORT.md — VideoToolbox (macOS/iOS), VAAPI (linux-gnu, dlopen’d at runtime), and NDK MediaCodec (Android).

§Safety boundary

Per PRINCIPLES.md, all platform FFI for hardware decode lives in this crate and nowhere else: #![deny(unsafe_op_in_unsafe_fn)], every public item is safe, and every unsafe block documents its invariants inside the platform backend module that owns it. The VAAPI backend (linux-gnu, dlopen’d libva — see the vaapi module) is implemented; VideoToolbox and MediaCodec land as separate issues. On targets/builds with no backend every entry point reports “no decoder” — decoder returns None, backend returns None, and available_codecs is empty.

On NVIDIA GPUs the VAAPI backend works through the maintained nvidia-vaapi-driver translation layer over NVDEC (see docs/SUPPORT.md).

§Verified feature flags

  • hw — portable: selects the native backend for the compile target via the build script; on a target with no hardware decode API (windows-msvc, linux-musl, wasm — see the SUPPORT.md matrix) it emits a build warning and compiles this stub. Valid everywhere.

  • videotoolbox / vaapi / mediacodec — pin one explicit backend; compile_error! on any other target. For example, this fails to compile anywhere but Apple platforms (a compile-fail test matrix in CI is tracked separately):

    cargo check -p rawshift-hwdec --features videotoolbox   # non-Apple host
    error: rawshift-hwdec: the `videotoolbox` feature requires an Apple target ...

§Request/response contract

The request is misuse-resistant by construction: the codec is implied by the CodecConfig variant (an hvcC config with an OBU payload, or an av1C config claiming to be HEVC, is unrepresentable), and DecodedFrame::new validates plane geometry against the pixel format so an internally inconsistent frame cannot be constructed.

Structs§

DecodedFrame
The validated output of a HwStillDecoder: a decoded 4:2:0 (or monochrome-in-4:2:0) picture in one of the four platform surface layouts.
Plane
One image plane of a DecodedFrame: raw bytes plus the row stride.
StillDecodeRequest
One still-frame decode request: the codec configuration (which implies the codec), the coded payload, and the caller’s advisory picture description.

Enums§

ChromaSubsampling
Chroma subsampling of the coded planes (AV1 subsampling_x / subsampling_y, §5.5.2).
CodecConfig
The codec configuration record of a still-decode request. The variant is the codec: an Hvcc request is an HEVC request and an Av1c request is an AV1 request, so a mismatched codec/config pair is unrepresentable.
ColorRange
Sample value range (CICP VideoFullRangeFlag; AV1 color_range).
HwBackend
A platform hardware-decode API — the fixed set from docs/SUPPORT.md.
HwCodec
A codec this crate can decode still frames of.
HwDecodeError
Errors reported by hardware still-frame decode.
PixelFormat
The pixel layout of a DecodedFrame — the four surface formats the platform decoders emit for 4:2:0 content.

Traits§

HwStillDecoder
A hardware still-frame decoder for one codec, obtained from decoder.

Functions§

available_codecs
The codecs decoder can currently return a decoder for, per the runtime probe (e.g. vaQueryConfigProfiles for VAAPI).
backend
The platform backend compiled into this build and usable at runtime, or None.
decoder
Returns a decoder for codec, or None when no compiled-in backend can decode it at runtime.