Crate otf_pixels_codec_avif

Expand description

AVIF codec for otf-pixels, implemented from scratch.

AVIF is two specifications stacked: an ISOBMFF/HEIF container (ISO/IEC 23008-12) holding one or more items, and an AV1 bitstream (AOM AV1) coding the pixels. This crate owns both — see ADR-0013, which reverses ADR-0004’s decision to wrap the dav1d/rav1e family.

§Scope

Still images only: an AVIF still is an AV1 key frame, which removes inter prediction, reference frame management, motion vectors and compound modes — well over half of AV1’s decoder surface. AVIF image sequences (the avis brand, carrying moov/trak) are animation and therefore v2 per ROADMAP §v2; a sequence decodes its primary item and nothing else, matching what GIF and WebP already do.

§Encoding

AvifEncoder writes an 8-bit 4:2:0 (or monochrome) key frame, with an auxiliary alpha item for transparency. It is the tile decoder driven by decisions: every symbol site asks a coder, which either reads the stream or decides and writes it, so prediction, reconstruction and probability adaptation are the decoder’s own and cannot drift from it.

§Memory

Internally buffered, as SPEC §Formats says. The container addresses its payload by absolute file offset through iloc, so the bytes must be resident before any of them can be interpreted — there is no prefix of an AVIF that yields a finished row. The external contract stays streaming (ADR-0005): the codec buffers, the caller does not.

§Safety

Every parser here reads attacker-controlled bytes. Malformed input is a value, never a panic: unsafe_code = "forbid" and the workspace ban on unwrap/expect/panic! mean the classic container failures — a box declaring more bytes than its parent holds, an item extent pointing outside the file, a grid whose tiles do not tile — are rejected rather than trusted.

Modules§

cdf: Default CDF tables for the AV1 symbol decoder.

Structs§

Association: One item’s association with a property.
Av1Config: The av1C AV1 codec configuration.
AvifCodec: The AVIF entry in a sniffing registry.
AvifDecoder: Decodes an AVIF stream.
AvifEncoder: Encodes an AVIF still.
AvifInfo: What the container says about the primary image.
BitReader: A most-significant-bit-first reader over an AV1 byte slice.
BoxHeader: A box’s type and the extent of its payload within the file.
Cdef: CDEF parameters (cdef_params, §5.9.19).
CoeffBlock: The result of decoding one transform block’s coefficients.
CoeffCdfs: The mutable coefficient CDFs for one tile, cloned from the defaults for the frame’s quantiser context. The spec’s Tile*Cdf are the frame defaults pre-indexed by the quantiser context (get_qctx), then adapted per symbol as the tile decodes.
ColorConfig: The colour configuration (color_config, §5.5.2).
DecodedFrame: A decoded frame’s sample planes, in coded order (Y, U, V). Each plane covers whole superblocks (in its own subsampled grid); only the top-left display-sized region is the picture.
Dequant: The dequantised coefficient block Dequant[i][j], raster order over the populated tw by th region (tw = min(32,w), th = min(32,h)).
Extent: One contiguous run of an item’s bytes.
Extents: The ispe image spatial extents — an item’s dimensions in pixels.
FilmGrain: Film-grain parameters (film_grain_params, §5.9.30), stored raw so synthesis can apply them later without re-parsing.
FourCc: A four-character box or brand identifier.
FrameHeader: A fully parsed intra frame header.
IntraTxTypeCdfs: The adapting intra_tx_type CDFs for one tile, cloned from the defaults.
Item: One entry of the file’s item table.
LoopFilter: Loop-filter parameters (loop_filter_params, §5.9.11).
LoopRestoration: Loop-restoration parameters (lr_params, §5.9.20).
Meta: The parsed meta box.
Neighbours: The neighbour samples a 4x4 intra predictor reads: the row above and the column to the left, each w + h = 8 samples long, plus the shared top-left corner. Assembled by the tile driver per §7.11.2 general process.
Obu: A single OBU: its header and a borrow of its payload bytes.
ObuHeader: A parsed OBU header (§5.3.2).
OperatingPoint: One operating point (§5.5.1). A still image has exactly one and decodes it.
PixelInfo: The pixi pixel information — bit depth per channel.
Plane: One component’s reconstructed samples.
PredBlock: One intra block’s assembled neighbours and geometry: the row above, the column to the left, the shared top-left corner (AboveRow[-1]), the availability flags, and the block size w x h in samples. above must hold at least w entries and left at least h.
Properties: The parsed contents of iprp.
Quantization: Dequant deltas from quantization_params (§5.9.12).
Reader: A checked cursor over a byte range of the file.
Reference: One iref entry: a typed link from one item to others.
Residual: A reconstructed residual block, width by height samples in raster order. Values are pre-flip: the caller applies flip_ud/flip_lr when adding to the prediction (§7.12.3 step 3).
Segmentation: Segmentation parameters (segmentation_params, §5.9.14).
SequenceHeader: A fully parsed sequence header.
StillPicture: The parsed headers of a still picture, plus a locator for its tile data.
SymbolDecoder: A range decoder over an AV1 tile’s symbol data.
TileInfo: The tile layout (tile_info, §5.9.15).
TxDepthCdfs: The adapting tx_depth CDFs for one tile, one per maximum-transform category.
TxSizeParams: The inputs to read_tx_size other than the decoder and CDFs.
TxTypeCtx: How a coded block’s PlaneTxType is resolved once all_zero shows the block carries coefficients (compute_tx_type / transform_type, §5.11.40–47).

Enums§

Colour: The colr colour information.
Construction: Where an item’s bytes live.
IntraMode: The 13 intra prediction modes (§6.10.2), in their coded order.
IntraTxSet: The intra transform set (get_tx_set on an intra frame, §5.11.48). The inter sets never arise in the still-picture subset.
ObuType: The kind of an OBU (obu_type, §6.2.2).
Property: One entry of the ipco property store.
Subsampling: How the chroma planes are sampled relative to luma.
TxMode: The transform mode (read_tx_mode, §5.9.21).
TxSize: The 19 transform sizes (TX_SIZES_ALL, §6.10.28 order).
TxType: PlaneTxType: the 16 transform types (§6.10.28 order). The first word names the column (vertical) transform, the second the row (horizontal).

Constants§

BLOCK_4X4: BLOCK_4X4 (§6.10.4): the smallest block, index 0 of BLOCK_SIZES.
BRANDS_STILL: Brands that mean “this file holds an AVIF still image”.
BRAND_SEQUENCE: The brand for an AVIF image sequence.
SIGNATURE_FTYP: The box type that identifies a file’s brands, at offset 4 of every ISOBMFF file.
URN_ALPHA: The auxiliary type URN that marks an item as an alpha plane.
URN_ALPHA_LEGACY: An older URN for the same thing, written by encoders that predate the current registration and still found in the wild.

Functions§

ac_q: Ac_Qlookup[(BitDepth-8)>>1][Clip3(0,255,b)] (§7.12.2).
add_residual: Reconstruct a transform block by adding the Residual to the prediction and clipping to the sample range (Clip1, the reconstruct process §7.12.3 step 3), honouring the transform type’s flipUD/flipLR. prediction is row-major residual.width * residual.height; the result is the same shape.
add_residual_4x4: Reconstruct a 4x4 block (§7.12.3 step 3): a thin wrapper over add_residual for the DCT_DCT (no-flip) case the lossless 4x4 tile drives.
block_size_from_4x4: The BLOCK_SIZES index for a block w4 x h4 4-sample units wide/high, or None if that is not a defined block shape.
chroma_tx_type: The chroma transform type (compute_tx_type for a plane > 0 intra block, §5.11.40): the mode-implied type if the set permits it, else DCT_DCT.
dc_q: Dc_Qlookup[(BitDepth-8)>>1][Clip3(0,255,b)] (§7.12.2).
decode_coeffs: Decode the coefficients of one transform block (coeffs, §5.11.39).
decode_still: Decode an intra still frame into its sample planes, from the payloads of its tile groups in order. Handles both lossless and lossy frames, the latter only when film grain is disabled (see unimplemented_filters_off).
dequantize: Dequantise one transform block (§7.12.3 step 1). quant holds Quant[] in raster order over the tw by th region; dc_quant/ac_quant are the plane’s DC/AC quantiser steps. No quantiser matrix is applied.
dequantize_with_matrix: dequantize, with each position’s quantizer first weighted by a quantizer matrix (§7.12.3 step 1b): q2 = Round2(q * matrix[i * tw + j], AOM_QM_BITS). matrix is quantizer_matrix’s slice for the block, or None when no matrix applies.
floor_log2: FloorLog2(x) (§4.7): the index of the most significant set bit. x must be non-zero, which every AV1 call site guarantees.
intra_dir: The intra direction (intraDir) for the intra_tx_type context: the luma mode, or the filter-intra mode’s mapped direction when filter intra is used.
intra_tx_set: get_tx_set(txSz) for an intra frame (§5.11.48). reduced_tx_set is the frame-header flag.
inverse_transform_2d: 2D inverse transform process (§7.13.3). dequant holds the dequantised coefficients Dequant[i][j] in raster order over the min(32,w) by min(32,h) populated region; entries beyond it are treated as zero.
is_tx_type_in_set_intra: is_tx_type_in_set for an intra frame (§5.11.40).
max_tx_depth: Max_Tx_Depth[block].
max_tx_size_rect: Max_Tx_Size_Rect[block].
mode_to_txfm: Mode_To_Txfm[uvMode] (§5.11.40).
predict_intra_4x4: Predict a 4x4 intra block (§7.11.2 for the 4x4 case): a thin wrapper over the size-general predict_intra_block, reshaping the flat result to [[_; 4]; 4].
predict_intra_block: Predict an intra block of any size for the modes that need no edge filtering (§7.11.2): DC, Paeth, the three Smooth variants, and the axis-aligned V/H copies. The result is w * h samples in row-major order.
probe: Whether prefix starts with an ISOBMFF file declaring a brand this decoder recognises.
quantizer_matrix: The quantizer matrix weights for a tx_size block, Min(32, w) x Min(32, h) of them row-major, at level for luma or chroma — or None at level 15, which means no matrix (SegQMLevel, §5.9.12).
read_transform_type: Resolve a luma block’s transform type (transform_type, §5.11.47).
read_tx_size: Resolve a coding block’s luma transform size (read_tx_size, §5.11.15).
sequence_header_from_config: Parse the sequence header out of a run of configuration OBUs.
split_tx_size: Split_Tx_Size[txSz]: one transform-depth step down.
tx_depth_ctx: The tx_depth context (§8.3.2): whether the above/left neighbour transforms are at least as wide/tall as this block’s maximum transform. above_w and left_h are the neighbour transform width/height in samples (0 when the neighbour is unavailable), as get_above_tx_width / get_left_tx_height resolve them for an intra block.