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::HevcEncoderimplementation backed by this crate’s Rust-native still-picture HEVC encoder (crate::encoder::encode).- encoder
- Still-image HEVC intra encoder facade.
Structs§
- Decode
Output - Decoded
Frame - Decoded video frame
- Decoder
Config - Encoder
Tuning - 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 inbpg-hevc. A failure (bad x265 param name or value) surfaces asEncodeError::Backend, never a corrupt bitstream. - Heic
Encode Options - Optional data associated with a HEIC primary image.
- Heic
Image Info - Metadata extracted from a HEIC/HEIF file without full decode.
- Hevc
Backend Caps - Declared capabilities of a
HevcEncoderbackend, 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_stillstill returnsEncodeError::Unsupportedfor anything outside these bounds, butcaps()lets callers fail fast with a clear message. - Hevc
Encode Params - 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/heightare the luma (pre-padding) dimensions; chroma plane dimensions follow fromchroma_format. Samples are stored asu16regardless ofbit_depth, matchingbpgenc.c’s internaltypedef uint16_t PIXELrepresentation; values are bounded by(1 << bit_depth) - 1. - Image
Info - Limits
- Still
Hevc Config - Still-picture HEVC encoder configuration.
- Still
Hevc Encoder - 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).Offis uniform QP — the default for every tier; AQ is an explicit opt-in. The two*Probevariants are experiment/control modes, not user-quality features. - Chroma
Format - Chroma subsampling format. Only
Yuv444andYuv420are exercised by the M1 pipeline;Gray/Yuv422are included so the type doesn’t need to change when those are implemented. - Color
Space - Output color space.
- Container
Kind - Deblock
Mode - In-loop deblocking filter mode (placeholder; Phase 3 emits
slice_deblocking_filter_disabled_flag = 1regardless). - Decode
Error - Effort
- How much search work the still encoder spends.
- Encode
Error - Errors from the encode pipeline.
- Image
Orientation - Display orientation copied from source metadata and represented with HEIF transformative properties.
- Pixel
Layout - SaoMode
- Sample Adaptive Offset mode (placeholder; Phase 3 emits
sao_enabled_flag = 0regardless).
Traits§
- Hevc
Encoder - 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 emittedcu_qp_delta_enabled_flagand 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--aqflag and external library callers (so the API exposes exactly the same options as the command line). ReturnsNonefor an unknown name. Names use hyphens, e.g.perceptual-chroma-mild.two-passis 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
imageas a complete BPG file with standard tuning. - encode_
heic - Encode
imageas 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::recommendedlets applications opt in without duplicating the CLI’s tested strength and clamp. - resolve_
aq - Resolve
(mode, strength, clamp)for an encode, honouring theBPG_PLACEBO_AQ/BPG_PLACEBO_AQ_STRENGTHenv override on Placebo and theconfig.aq_*fields otherwise. - resolve_
aq_ mode - Resolve the effective
AqModefor an encode. Resolution order: - resolve_
aq_ qg_ log2 - Resolve the effective quantization-group size (log2, luma samples) for an
encode:
5(32x32, the default) or4(16x16,aq_qg = 16opt-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 emitssign_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.