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§
- Decoded
Frame - 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. - Still
Decode Request - One still-frame decode request: the codec configuration (which implies the codec), the coded payload, and the caller’s advisory picture description.
Enums§
- Chroma
Subsampling - Chroma subsampling of the coded planes (AV1
subsampling_x/subsampling_y, §5.5.2). - Codec
Config - The codec configuration record of a still-decode request. The variant is
the codec: an
Hvccrequest is an HEVC request and anAv1crequest is an AV1 request, so a mismatched codec/config pair is unrepresentable. - Color
Range - Sample value range (CICP
VideoFullRangeFlag; AV1color_range). - HwBackend
- A platform hardware-decode API — the fixed set from
docs/SUPPORT.md. - HwCodec
- A codec this crate can decode still frames of.
- HwDecode
Error - Errors reported by hardware still-frame decode.
- Pixel
Format - The pixel layout of a
DecodedFrame— the four surface formats the platform decoders emit for 4:2:0 content.
Traits§
- HwStill
Decoder - A hardware still-frame decoder for one codec, obtained from
decoder.
Functions§
- available_
codecs - The codecs
decodercan currently return a decoder for, per the runtime probe (e.g.vaQueryConfigProfilesfor VAAPI). - backend
- The platform backend compiled into this build and usable at runtime, or
None. - decoder
- Returns a decoder for
codec, orNonewhen no compiled-in backend can decode it at runtime.