Skip to main content

Crate still265

Crate still265 

Source
Expand description

Pure-Rust HEVC/H.265 still-image encoding, plus BPG and HEIC helpers.

RustStillHevcEncoder encodes one all-intra HEVC picture. encode_bpg and encode_heic wrap the raw HEVC stream in BPG and HEIC containers; decode_heic and decode_bpg expose the corresponding still-image decoders. The normal entry point is the encoder builder plus one of the container helpers. Advanced callers can use encoder to supply planar YCbCr samples and obtain the raw Annex-B HEVC stream.

This is a still-image codec, not a video codec. It supports one lossy, intra-only 8-, 10-, or 12-bit image in gray, 4:2:0, 4:2:2, or 4:4:4. It does not encode alpha, lossless HEVC, animation, inter frames, or any bitrate-targeted rate-control mode.

Re-exports§

pub use backend::LastEncodeStats;
pub use backend::RustStillHevcEncoder;

Modules§

backend
crate::internal::bpg_encode::HevcEncoder implementation backed by this crate’s Rust-native still-picture HEVC encoder (crate::encoder::encode).
encoder
Still-image HEVC intra encoder facade.

Structs§

DecodeOutput
DecodedFrame
Decoded video frame
DecoderConfig
EncoderTuning
Encoder-tuning knobs resolved from a bpg-tune::EncodePlan. These are the soft parameters a tune is allowed to set; the mandatory BPG/structural params (intra-only, AMP, CQP, csp, bit depth, repeat-headers) are always re-asserted by the backend AFTER these, so a tune can never violate the modified-SPS preconditions in bpg-hevc. A failure (bad x265 param name or value) surfaces as EncodeError::Backend, never a corrupt bitstream.
HeicEncodeOptions
Optional data associated with a HEIC primary image.
HeicImageInfo
Metadata extracted from a HEIC/HEIF file without full decode.
HevcBackendCaps
Declared capabilities of a HevcEncoder backend, used by callers (e.g. bpg-tools) to validate a request before doing any expensive work (image loading, color conversion, CTU padding) and to keep CLI help/README claims honest. A backend must not silently downgrade or ignore an unsupported request: HevcEncoder::encode_still still returns EncodeError::Unsupported for anything outside these bounds, but caps() lets callers fail fast with a clear message.
HevcEncodeParams
Parameters for one HEVC encode, mirroring the subset of HEVCEncodeParams (bpgenc.h) that the M1 x265 path uses. The backend is responsible for translating these into x265 params (x265_glue.c).
Image
A decoded/converted image ready for encoding: width/height are the luma (pre-padding) dimensions; chroma plane dimensions follow from chroma_format. Samples are stored as u16 regardless of bit_depth, matching bpgenc.c’s internal typedef uint16_t PIXEL representation; values are bounded by (1 << bit_depth) - 1.
ImageInfo
Limits
StillHevcConfig
Still-picture HEVC encoder configuration.
StillHevcEncoder
Rust-native still-picture HEVC intra encoder.

Enums§

AqMode
Adaptive-quantization map selection. The per-QG QP offset is derived from one of these strategies (see [crate::preanalysis] for the offset math). Off is uniform QP — the default for every tier; AQ is an explicit opt-in. The two *Probe variants are experiment/control modes, not user-quality features.
ChromaFormat
Chroma subsampling format. Only Yuv444 and Yuv420 are exercised by the M1 pipeline; Gray/Yuv422 are included so the type doesn’t need to change when those are implemented.
ColorSpace
Output color space.
ContainerKind
DeblockMode
In-loop deblocking filter mode (placeholder; Phase 3 emits slice_deblocking_filter_disabled_flag = 1 regardless).
DecodeError
Effort
How much search work the still encoder spends.
EncodeError
Errors from the encode pipeline.
ImageOrientation
Display orientation copied from source metadata and represented with HEIF transformative properties.
PixelLayout
SaoMode
Sample Adaptive Offset mode (placeholder; Phase 3 emits sao_enabled_flag = 0 regardless).

Traits§

HevcEncoder
A HEVC backend that encodes a single intra still frame and returns its raw Annex-B elementary stream. Implemented by still265.

Functions§

aq_active
Whether adaptive quantization (per-CU cu_qp_delta) is active for a config. This is the single gate consulted by both the PPS writer ([params::write_pps]) and the encoder, so the emitted cu_qp_delta_enabled_flag and the per-CU QP plan can never disagree.
aq_preset
Resolve a named adaptive-quantization preset to (mode, strength, clamp) — the single source of truth shared by the CLI --aq flag and external library callers (so the API exposes exactly the same options as the command line). Returns None for an unknown name. Names use hyphens, e.g. perceptual-chroma-mild. two-pass is the recommended measured mode.
chroma_qp_offset
Experimental PPS chroma QP offset for rate-allocation diagnostics. Defaults to x265/libbpg parity (0).
decode_bpg
Decode a complete BPG file to pixels in layout.
decode_heic
Decode a HEIC/HEIF file to interleaved pixel data.
decode_heic_thumbnail
Decode the embedded thumbnail from a HEIC/HEIF file, if present.
decode_heic_to_frame
Decode a HEIC/HEIF file to a raw planar YCbCr frame.
encode_bpg
Encode image as a complete BPG file with standard tuning.
encode_heic
Encode image as a complete HEIC file with standard tuning.
get_heic_image_info
Parse HEIC/HEIF metadata without decoding pixel data.
is_reference_tier
Whether an effort is the inert high-quality comparison tier.
recommended_aq_preset
Tunables for the recommended measured two-pass AQ mode. Keeping this named API next to AqMode::recommended lets applications opt in without duplicating the CLI’s tested strength and clamp.
resolve_aq
Resolve (mode, strength, clamp) for an encode, honouring the BPG_PLACEBO_AQ / BPG_PLACEBO_AQ_STRENGTH env override on Placebo and the config.aq_* fields otherwise.
resolve_aq_mode
Resolve the effective AqMode for an encode. Resolution order:
resolve_aq_qg_log2
Resolve the effective quantization-group size (log2, luma samples) for an encode: 5 (32x32, the default) or 4 (16x16, aq_qg = 16 opt-in). The single source of truth shared by the PPS writer (diff_cu_qp_delta_depth = CTB_LOG2 − qg_log2) and the encoder’s QP-prediction mirror, so the bitstream and the per-CU QP plan can never disagree on the QG grid.
sdh_active
Whether HEVC sign-data-hiding is applied for a config. Single source of truth consulted by both the PPS writer ([params::write_pps], which emits sign_data_hiding_enabled_flag) and the encoder (which makes each coding group’s hidden sign parity-consistent), so the flag and the coded levels can never disagree.