#[non_exhaustive]pub struct SampleTransform {
pub version: u8,
pub bit_depth: u8,
pub tokens: Vec<Token>,
}Expand description
Parsed sato Sample Transform Derived Image Item descriptor
(av1-avif v1.2.0 §4.2.3). The wire format is one header byte
(version:2 | reserved:4 | bit_depth:2), then token_count: u8,
then token_count tokens (each one byte plus an optional
constant-value payload).
The reconstructed image’s samples come from evaluating this
expression once per channel per (x, y) coordinate, drawing input
samples from the input image items named in the parallel dimg
iref’s to_ids list (reference_count items in declaration order).
The result is the single value left on the stack after the last
token; it is clamped to fit the reconstructed item’s
PixelInformationProperty bit depth.
Use Self::parse to decode the descriptor with strict
spec-conformance — reserved token values, version mismatches, and
stack-discipline violations all error. The descriptor stores the
fully decoded token list so callers can either evaluate the
expression themselves (via Self::evaluate on a per-sample input
vector) or hand the parsed structure to a future composition layer
when an AV1 decoder is available to produce the input items.
Caveat: composition is not implemented in oxideav yet — the
oxideav-av1 decoder is the bottleneck (see crate README). This
parser unblocks structural inspection, validation, and any future
composition work that lands on top.
Fields (Non-exhaustive)§
This struct is marked as non-exhaustive
Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.version: u8version field. Spec mandates 0; readers shall ignore items
with an unrecognised version. Self::parse errors on any
non-zero version (callers that prefer “ignore” semantics can
match on the error and skip the item).
bit_depth: u8bit_depth field — selector for the intermediate precision.
0..=3 map to 8 / 16 / 32 / 64 bits via Self::num_bits.
Self::parse errors on any value outside that range (the
wire format reserves only 2 bits so a strict reader can never
observe an out-of-range value, but a relaxed parser fed garbled
bytes might).
tokens: Vec<Token>Decoded token list. The first token’s evaluation happens first.
Implementations§
Source§impl SampleTransform
impl SampleTransform
Sourcepub fn num_bits(&self) -> u32
pub fn num_bits(&self) -> u32
Intermediate bit depth keyed by Self::bit_depth (av1-avif
Table 1). 0 → 8, 1 → 16, 2 → 32, 3 → 64.
Sourcepub fn min_value(&self) -> i64
pub fn min_value(&self) -> i64
Minimum value representable at Self::num_bits precision
(-2^(num_bits-1)). Computed underflows clamp to this value
per spec.
Sourcepub fn max_value(&self) -> i64
pub fn max_value(&self) -> i64
Maximum value representable at Self::num_bits precision
(2^(num_bits-1) - 1). Computed overflows clamp to this value
per spec.
Sourcepub fn parse(payload: &[u8], reference_count: u32) -> Result<Self>
pub fn parse(payload: &[u8], reference_count: u32) -> Result<Self>
Parse a sato payload strictly per av1-avif v1.2.0 §4.2.3.2 /
§4.2.3.4:
versionmust be0.token_countmust be>= 1.- Each sample-operand token (
1..=token_count_max) must be<= reference_countper §4.2.3.4. Pass thedimgiref’s reference count for the item. - Reserved token values cause an error.
- The expression must evaluate without stack underflow and leave exactly one element on the stack.
Sourcepub fn parse_relaxed(payload: &[u8]) -> Result<Self>
pub fn parse_relaxed(payload: &[u8]) -> Result<Self>
Parse a sato payload structurally without rejecting reserved
tokens or unrecognised versions. Useful for diagnostic dumps of
experimental files. Stack discipline is still enforced (a
malformed expression can’t be round-tripped).
Sourcepub fn evaluate(&self, inputs: &[i64]) -> Result<i64>
pub fn evaluate(&self, inputs: &[i64]) -> Result<i64>
Evaluate this expression for one output sample, given the input
sample values from the parallel dimg iref’s to_ids list (in
the same order). Returns the single value left on the stack,
already clamped to the intermediate precision via the
underflow / overflow rules of av1-avif §4.2.3.3.
inputs[i] is the sample from input image item i + 1 (the
spec’s token values for sample operands are 1-based; this
helper translates them to 0-based vector indices).
The caller is responsible for the final clamp into the
reconstructed item’s PixelInformationProperty bit depth, since
that depth lives outside the sato descriptor itself.
Returns an error if the expression dereferences an out-of-range
sample or trips a stack underflow that wasn’t caught by
Self::parse’s validation (the only path is a caller passing
inputs.len() < max_sample_index_used or a parse_relaxed
expression that bypassed validation).