#![deny(unsafe_op_in_unsafe_fn)]
#[cfg(hwdec_backend = "vaapi")]
mod vaapi;
#[cfg(all(
feature = "videotoolbox",
not(any(target_os = "macos", target_os = "ios"))
))]
compile_error!(
"rawshift-hwdec: the `videotoolbox` feature requires an Apple target \
(macOS or iOS). Use the portable `hw` feature to select the native \
backend for the compile target, or see docs/SUPPORT.md."
);
#[cfg(all(feature = "vaapi", not(all(target_os = "linux", target_env = "gnu"))))]
compile_error!(
"rawshift-hwdec: the `vaapi` feature requires a linux-gnu target (VAAPI \
is dlopen'd; musl has no dlopen deployment story — see docs/SUPPORT.md). \
Use the portable `hw` feature to select the native backend for the \
compile target."
);
#[cfg(all(feature = "mediacodec", not(target_os = "android")))]
compile_error!(
"rawshift-hwdec: the `mediacodec` feature requires an Android target \
(NDK MediaCodec). Use the portable `hw` feature to select the native \
backend for the compile target, or see docs/SUPPORT.md."
);
use thiserror::Error;
pub use gamut_color::{ChromaSubsampling, ColorRange};
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum HwCodec {
Hevc,
Av1,
}
impl HwCodec {
#[must_use]
pub fn name(self) -> &'static str {
match self {
HwCodec::Hevc => "HEVC",
HwCodec::Av1 => "AV1",
}
}
}
impl std::fmt::Display for HwCodec {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(self.name())
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum HwBackend {
VideoToolbox,
Vaapi,
MediaCodec,
}
impl HwBackend {
#[must_use]
pub fn name(self) -> &'static str {
match self {
HwBackend::VideoToolbox => "VideoToolbox",
HwBackend::Vaapi => "VAAPI",
HwBackend::MediaCodec => "MediaCodec",
}
}
}
impl std::fmt::Display for HwBackend {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(self.name())
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CodecConfig<'a> {
Hvcc(&'a [u8]),
Av1c(&'a [u8]),
}
impl<'a> CodecConfig<'a> {
#[must_use]
pub fn codec(&self) -> HwCodec {
match self {
CodecConfig::Hvcc(_) => HwCodec::Hevc,
CodecConfig::Av1c(_) => HwCodec::Av1,
}
}
#[must_use]
pub fn bytes(&self) -> &'a [u8] {
match self {
CodecConfig::Hvcc(bytes) | CodecConfig::Av1c(bytes) => bytes,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct StillDecodeRequest<'a> {
pub config: CodecConfig<'a>,
pub payload: &'a [u8],
pub width: u32,
pub height: u32,
pub bit_depth: u8,
pub chroma: ChromaSubsampling,
}
impl StillDecodeRequest<'_> {
#[must_use]
pub fn codec(&self) -> HwCodec {
self.config.codec()
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum PixelFormat {
Nv12,
P010,
I420,
I010,
}
impl PixelFormat {
#[must_use]
pub fn plane_count(self) -> usize {
match self {
PixelFormat::Nv12 | PixelFormat::P010 => 2,
PixelFormat::I420 | PixelFormat::I010 => 3,
}
}
#[must_use]
pub fn bytes_per_sample(self) -> usize {
match self {
PixelFormat::Nv12 | PixelFormat::I420 => 1,
PixelFormat::P010 | PixelFormat::I010 => 2,
}
}
#[must_use]
pub fn supports_bit_depth(self, bit_depth: u8) -> bool {
match self {
PixelFormat::Nv12 | PixelFormat::I420 => bit_depth == 8,
PixelFormat::P010 | PixelFormat::I010 => (9..=16).contains(&bit_depth),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Plane {
pub data: Vec<u8>,
pub stride: usize,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DecodedFrame {
format: PixelFormat,
width: u32,
height: u32,
bit_depth: u8,
range: ColorRange,
planes: Vec<Plane>,
}
impl DecodedFrame {
pub fn new(
format: PixelFormat,
width: u32,
height: u32,
bit_depth: u8,
range: ColorRange,
planes: Vec<Plane>,
) -> Result<Self, HwDecodeError> {
let invalid = |message: &str| HwDecodeError::InvalidFrame {
message: message.to_string(),
};
if width == 0 || height == 0 {
return Err(invalid("frame dimensions must be non-zero"));
}
if !format.supports_bit_depth(bit_depth) {
return Err(invalid(
"bit depth is not representable in the pixel format",
));
}
if planes.len() != format.plane_count() {
return Err(invalid("plane count does not match the pixel format"));
}
let bps = format.bytes_per_sample();
let (cw, ch) = (width.div_ceil(2) as usize, height.div_ceil(2) as usize);
for (index, plane) in planes.iter().enumerate() {
let (row_samples, rows) = match (format.plane_count(), index) {
(_, 0) => (width as usize, height as usize),
(2, 1) => (cw * 2, ch),
(3, 1 | 2) => (cw, ch),
_ => unreachable!("plane index out of range for format"),
};
let row_bytes = row_samples
.checked_mul(bps)
.ok_or_else(|| invalid("plane row size overflows"))?;
if plane.stride < row_bytes {
return Err(invalid("plane stride is smaller than the row width"));
}
let required = plane
.stride
.checked_mul(rows - 1)
.and_then(|n| n.checked_add(row_bytes))
.ok_or_else(|| invalid("plane size overflows"))?;
if plane.data.len() < required {
return Err(invalid("plane buffer is shorter than its rows"));
}
}
Ok(Self {
format,
width,
height,
bit_depth,
range,
planes,
})
}
#[must_use]
pub fn format(&self) -> PixelFormat {
self.format
}
#[must_use]
pub fn width(&self) -> u32 {
self.width
}
#[must_use]
pub fn height(&self) -> u32 {
self.height
}
#[must_use]
pub fn bit_depth(&self) -> u8 {
self.bit_depth
}
#[must_use]
pub fn range(&self) -> ColorRange {
self.range
}
#[must_use]
pub fn planes(&self) -> &[Plane] {
&self.planes
}
}
pub trait HwStillDecoder: Send {
fn decode_still(
&mut self,
request: &StillDecodeRequest<'_>,
) -> Result<DecodedFrame, HwDecodeError>;
}
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum HwDecodeError {
#[error("no hardware decoder available for {codec}: {reason}")]
Unavailable {
codec: HwCodec,
reason: String,
},
#[error("hardware {codec} decode failed: {message}")]
Decode {
codec: HwCodec,
message: String,
},
#[error("invalid decoded frame: {message}")]
InvalidFrame {
message: String,
},
}
#[must_use]
pub fn decoder(codec: HwCodec) -> Option<Box<dyn HwStillDecoder>> {
#[cfg(hwdec_backend = "vaapi")]
{
vaapi::decoder(codec)
}
#[cfg(not(hwdec_backend = "vaapi"))]
{
let _ = codec;
None
}
}
#[must_use]
pub fn backend() -> Option<HwBackend> {
#[cfg(hwdec_backend = "vaapi")]
{
vaapi::backend()
}
#[cfg(not(hwdec_backend = "vaapi"))]
{
None
}
}
#[must_use]
pub fn available_codecs() -> &'static [HwCodec] {
#[cfg(hwdec_backend = "vaapi")]
{
vaapi::available_codecs()
}
#[cfg(not(hwdec_backend = "vaapi"))]
{
&[]
}
}
#[cfg(test)]
mod tests {
use super::*;
#[cfg(not(hwdec_backend = "vaapi"))]
#[test]
fn stub_has_no_decoder_for_any_codec() {
assert!(decoder(HwCodec::Hevc).is_none());
assert!(decoder(HwCodec::Av1).is_none());
}
#[cfg(not(hwdec_backend = "vaapi"))]
#[test]
fn stub_reports_no_backend_and_no_codecs() {
assert_eq!(backend(), None);
assert!(available_codecs().is_empty());
}
#[test]
fn discovery_entry_points_are_consistent() {
let codecs = available_codecs();
assert_eq!(backend().is_some(), !codecs.is_empty());
for codec in [HwCodec::Hevc, HwCodec::Av1] {
assert_eq!(
decoder(codec).is_some(),
codecs.contains(&codec),
"decoder({codec}) must match available_codecs()"
);
}
}
#[test]
fn codec_is_implied_by_the_config_variant() {
let hvcc = [0x01u8, 0x02];
let av1c = [0x81u8];
assert_eq!(CodecConfig::Hvcc(&hvcc).codec(), HwCodec::Hevc);
assert_eq!(CodecConfig::Av1c(&av1c).codec(), HwCodec::Av1);
assert_eq!(CodecConfig::Hvcc(&hvcc).bytes(), &hvcc);
let request = StillDecodeRequest {
config: CodecConfig::Hvcc(&hvcc),
payload: &[0, 0, 0, 1, 0x26],
width: 64,
height: 48,
bit_depth: 8,
chroma: ChromaSubsampling::Cs420,
};
assert_eq!(request.codec(), HwCodec::Hevc);
}
fn plane(len: usize, stride: usize) -> Plane {
Plane {
data: vec![0u8; len],
stride,
}
}
#[test]
fn i420_frame_validates() {
let frame = DecodedFrame::new(
PixelFormat::I420,
5,
3,
8,
ColorRange::Limited,
vec![plane(15, 5), plane(6, 3), plane(6, 3)],
)
.expect("valid I420 frame");
assert_eq!(frame.format(), PixelFormat::I420);
assert_eq!((frame.width(), frame.height()), (5, 3));
assert_eq!(frame.planes().len(), 3);
}
#[test]
fn nv12_frame_validates_with_padded_stride() {
let frame = DecodedFrame::new(
PixelFormat::Nv12,
4,
4,
8,
ColorRange::Full,
vec![plane(8 * 3 + 4, 8), plane(4 * 2, 4)],
)
.expect("valid NV12 frame");
assert_eq!(frame.range(), ColorRange::Full);
assert_eq!(frame.planes()[0].stride, 8);
}
#[test]
fn p010_requires_high_bit_depth_and_i420_requires_8() {
let err = DecodedFrame::new(
PixelFormat::P010,
2,
2,
8,
ColorRange::Limited,
vec![plane(8, 4), plane(4, 4)],
)
.unwrap_err();
assert!(matches!(err, HwDecodeError::InvalidFrame { .. }));
assert!(
DecodedFrame::new(
PixelFormat::I420,
2,
2,
10,
ColorRange::Limited,
vec![plane(4, 2), plane(1, 1), plane(1, 1)],
)
.is_err()
);
assert!(
DecodedFrame::new(
PixelFormat::P010,
2,
2,
10,
ColorRange::Limited,
vec![plane(8, 4), plane(4, 4)],
)
.is_ok()
);
}
#[test]
fn frame_rejects_wrong_plane_count_and_short_planes() {
assert!(
DecodedFrame::new(
PixelFormat::I420,
2,
2,
8,
ColorRange::Limited,
vec![plane(4, 2), plane(1, 1)],
)
.is_err()
);
assert!(
DecodedFrame::new(
PixelFormat::I420,
2,
2,
8,
ColorRange::Limited,
vec![plane(3, 2), plane(1, 1), plane(1, 1)],
)
.is_err()
);
assert!(
DecodedFrame::new(
PixelFormat::I420,
4,
2,
8,
ColorRange::Limited,
vec![plane(8, 3), plane(2, 2), plane(2, 2)],
)
.is_err()
);
assert!(
DecodedFrame::new(
PixelFormat::I420,
0,
2,
8,
ColorRange::Limited,
vec![plane(0, 0), plane(0, 0), plane(0, 0)],
)
.is_err()
);
}
#[test]
fn errors_name_the_codec() {
let err = HwDecodeError::Unavailable {
codec: HwCodec::Hevc,
reason: "no backend compiled in".to_string(),
};
let text = err.to_string();
assert!(text.contains("HEVC"), "{text}");
assert!(text.contains("no backend compiled in"), "{text}");
assert_eq!(HwCodec::Av1.to_string(), "AV1");
assert_eq!(HwBackend::Vaapi.to_string(), "VAAPI");
}
}