API referencestd/image

std/image/jxl/encode

Public declarations, types, methods, and source contracts for std/image/jxl/encode.

On this page

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 length bytes 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 icc can be embedded for an image in layout: 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 icc for an image in layout with 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 source as a lossless JPEG XL file into output, returning the byte count. Fails with BufferTooSmall when scratch is 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

Search every guide, reference page, and API declaration.