Library guide · API index and notation
This page is generated from the bundled library in this checkout. Signatures and adjacent source comments are reproduced below; the linked guide explains usage, storage, failures, and platform support.
import "std/image/jxl/encode"
Names used in signatures
Unqualified names denote this package’s types (including other source files in the same package), language built-ins, or generic parameters such as T. Qualified names use the import aliases below. These aliases belong to the library source; import a dependency yourself to use its alias in your program.
| Alias | Package | Source file |
|---|---|---|
binary |
std/image/shared/binary |
encode.dodo, headers.dodo, vd_frame.dodo |
color |
std/image/color |
encode.dodo, headers.dodo, vd_color.dodo, vd_frame.dodo |
convert |
std/image/convert |
vd_aq.dodo, vd_color.dodo, vd_icc.dodo, vd_tables.dodo |
math |
std/math |
vd_color.dodo, vd_tables.dodo |
pixels |
std/image/pixels |
analyze.dodo, encode.dodo, icc.dodo, image.dodo, palette.dodo, vd_block.dodo, vd_color.dodo, vd_frame.dodo, vd_group.dodo, vd_icc.dodo, vd_tables.dodo |
scratch |
std/image/shared/scratch |
encode.dodo, vd_frame.dodo |
slice |
core/slice |
encode.dodo, vd_frame.dodo |
trig |
std/math/trig |
vd_tables.dodo |
DEFAULT_EFFORT
Constant · Source
Default effort for EncodeOptions.new().
pub const DEFAULT_EFFORT: u32 = 2
DEFAULT_DISTANCE
Constant · Source
Default Butteraugli distance of lossy encoding (cjxl’s default, about quality 90).
pub const DEFAULT_DISTANCE: f32 = 1.0
EncodeOptions
Struct · Source
Encoder settings.
pub struct EncodeOptions {
// 1 (fastest) to 9. Lossless: values above 3 currently behave like 3,
// 0 like 1. Lossy: 1 DCT8 with uniform quantization; 2 adds adaptive
// quantization, inverse Gaborish and chroma-from-luma; 3-6 add the
// varblock search (DCT8 to DCT32 and rectangles) and per-block quant
// adjustment; 7-9 also try 64x64 varblocks.
pub effort: u32
// Lossless modular coding (the default). When false, a lossy VarDCT
// frame in XYB is written at `distance`; alpha stays lossless.
pub lossless: bool
// Target Butteraugli distance of lossy coding: 1.0 is visually
// lossless, 0.5 very high quality, 3 to 8 small files. Clamped to
// 0.05..25; zero or less means lossless. distance_from_quality() maps
// a 0..100 quality the way cjxl does.
pub distance: f32
// Wrap the codestream in the ISOBMFF container. Implied when metadata
// is attached (encode_with_metadata).
pub container: bool
// Color description written as the JPEG XL color encoding: CICP
// primaries and transfer (sRGB, linear, BT.709/601/2020 curves, PQ, HLG,
// DCI, power-law gamma; BT.709, BT.2020, Display P3, DCI-P3 or custom
// chromaticities). Unrepresentable values fall back to sRGB. Ignored
// when an ICC profile is embedded (Metadata.icc).
pub color: color.ColorInfo
pub orientation: color.Orientation
}
EncodeOptions.new
Function · Source
pub fn new() -> EncodeOptions
EncodeOptions.lossy
Function · Source
Lossy settings at Butteraugli distance
distance.
pub fn lossy(distance: f32) -> EncodeOptions
Metadata
Struct · Source
Metadata stored with the image: EXIF and XMP in container boxes, the ICC profile in the codestream. Kept apart from EncodeOptions so the options hold no borrows.
pub struct Metadata {
// EXIF payload starting at the TIFF header ("II*\0" or "MM\0*"), or
// with a leading "Exif\0\0"; stored in an "Exif" box. Empty for none.
pub exif: &[u8]
// XMP packet, stored in an "xml " box. Empty for none.
pub xmp: &[u8]
// ICC profile embedded in the image header (entropy coded, see
// icc.dodo); it then describes the colors instead of
// EncodeOptions.color. Must be an RGB profile for RGB(A) images and a
// gray one for gray(+alpha) images (else Unsupported). Lossy encoding
// converts the samples to XYB through the profile, which must then be
// a matrix/TRC profile (colorants and rTRC/gTRC/bTRC) or a gray kTRC
// profile with the XYZ connection space (else Unsupported; profiles
// that only have lookup tables are not supported); see vd_icc.dodo.
// icc_usable() checks both. Empty for none; it does not need the
// container.
pub icc: &[u8]
}
Metadata.new
Function · Source
pub fn new(exif: &[u8], xmp: &[u8]) -> Metadata from(exif, xmp)
Metadata.with_icc
Function · Source
pub fn with_icc(exif: &[u8], xmp: &[u8], icc: &[u8]) -> Metadata from(exif, xmp, icc)
icc_bound
Function · Source
An upper bound on the bytes an embedded ICC profile of
lengthbytes adds to the output: the predicted stream has at most 2 * length + 64 bytes, each coded in at most 22 bits (LZ77 copies cost less per byte), plus the code spec.
pub fn icc_bound(length: usize) -> usize!pixels.Error
max_encoded_size
Function · Source
An upper bound on the bytes encode() writes for this image and options. It is a worst case (about 3 bytes per 8-bit sample); typical output is far smaller, and encode() reports BufferTooSmall rather than overrunning a smaller buffer.
pub fn max_encoded_size(width: u32, height: u32, layout: &pixels.Layout, options: &EncodeOptions) -> usize!pixels.Error
max_encoded_size_with_metadata
Function · Source
max_encoded_size() including the metadata boxes and the ICC profile.
pub fn max_encoded_size_with_metadata(width: u32, height: u32, layout: &pixels.Layout, options: &EncodeOptions, metadata: &Metadata) -> usize!pixels.Error
icc_fits
Function · Source
Whether
icccan be embedded for an image inlayout: an RGB profile for RGB(A), a gray one for gray(+alpha) (see Metadata.icc).
pub fn icc_fits(icc: &[u8], layout: &pixels.Layout) -> bool
icc_usable
Function · Source
Whether encode_with_metadata() accepts
iccfor an image inlayoutwith these options: icc_fits(), and for lossy encoding a matrix/TRC or gray TRC profile (see Metadata.icc).
pub fn icc_usable(icc: &[u8], layout: &pixels.Layout, options: &EncodeOptions) -> bool
encode_scratch_size
Function · Source
Bytes of scratch encode() needs for this image and options.
pub fn encode_scratch_size(width: u32, height: u32, layout: &pixels.Layout, options: &EncodeOptions) -> usize!pixels.Error
encode
Function · Source
Encode
sourceas a lossless JPEG XL file intooutput, returning the byte count. Fails with BufferTooSmall whenscratchis shorter than encode_scratch_size() or the output does not fit, and Malformed for an empty image.
pub fn encode(source: &pixels.View, options: &EncodeOptions, output: &mut[u8], scratch_bytes: &mut[u8]) -> usize!pixels.Error
encode_with_metadata
Function · Source
encode() with EXIF and/or XMP boxes and/or an ICC profile; the output uses the container when EXIF or XMP is present. Size the output with max_encoded_size_with_metadata(). An ICC profile that does not match the image’s color channels (RGB or gray), or that lossy encoding cannot convert from, gives Unsupported (see icc_usable()).
pub fn encode_with_metadata(source: &pixels.View, options: &EncodeOptions, metadata: &Metadata, output: &mut[u8], scratch_bytes: &mut[u8]) -> usize!pixels.Error
distance_from_quality
Function · Source
cjxl’s mapping from a 0..100 quality to a Butteraugli distance.
pub fn distance_from_quality(quality: f32) -> f32