API referencestd/image

std/image

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

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"

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
bmp std/image/bmp image.dodo
color std/image/color image.dodo
graphics std/graphics image.dodo
jxl std/image/jxl image.dodo
jxl_encode std/image/jxl/encode image.dodo
mem core/mem image.dodo
meta std/image/meta image.dodo
pixels std/image/pixels image.dodo
png std/image/png image.dodo
ppm std/image/ppm image.dodo
qoi std/image/qoi image.dodo
sink std/image/sink image.dodo

Error

Type alias · Source

The errors of every codec: Truncated, Malformed, Unsupported, TooLarge, BufferTooSmall.

pub type Error = pixels.Error

Format

Type alias · Source

pub type Format = pixels.Format

detect

Function · Source

The format of data from its signature, without validating the rest. Unknown data fails with Unsupported.

pub fn detect(data: &[u8]) -> pixels.Format!pixels.Error

info

Function · Source

The file’s header: size, native layout, bit depth, color description, orientation and animation.

pub fn info(data: &[u8]) -> pixels.Header!pixels.Error

metadata

Function · Source

Where the file’s EXIF, XMP and ICC payloads are (see meta.Item).

pub fn metadata(data: &[u8]) -> meta.Metadata!pixels.Error

icc

Function · Source

The embedded ICC profile, decoded into output (PNG iCCP is inflated, BMP profiles are copied, JPEG XL profiles are entropy-decoded); returns its length, 0 when there is none. scratch needs icc_scratch_size(data) bytes (zero except for JPEG XL). The profile is the one describing the decoded pixels (info().color): lossy (XYB) JPEG XL files decode to sRGB, so this returns 0 for them; jxl.icc() extracts their embedded profile.

pub fn icc(data: &[u8], output: &mut[u8], scratch: &mut[u8]) -> usize!pixels.Error

scratch_size

Function · Source

Bytes of scratch decode() and decode_into() need for data. target is the layout decode() will write; the current codecs convert row by row and need the same scratch for every target.

pub fn scratch_size(data: &[u8], target: &pixels.Layout) -> usize!pixels.Error

decode

Function · Source

Decode data into target, converting to its layout. The target must be at least as large as the image; the image’s top-left pixel lands at the target’s. An animation decodes to its default image.

pub fn decode(data: &[u8], target: &mut pixels.ViewMut, scratch: &mut[u8]) -> void!pixels.Error

decode_into

Function · Source

Decode data into any sink, in the native layout of info(data).

pub fn decode_into<S: sink.Sink>(data: &[u8], output: &mut S, scratch: &mut[u8]) -> void!pixels.Error

draw

Function · Source

Decode data onto a canvas with the image’s top-left corner at (x, y), converted to straight 8-bit RGBA and stored (not blended); pixels outside the canvas or its clip are skipped.

pub fn draw(data: &[u8], canvas: &mut graphics.Canvas, x: i32, y: i32, scratch: &mut[u8]) -> void!pixels.Error

icc_scratch_size

Function · Source

Bytes of scratch icc() needs for data.

pub fn icc_scratch_size(data: &[u8]) -> usize!pixels.Error

frame_count

Function · Source

pub fn frame_count(data: &[u8]) -> u32!pixels.Error

frame_info

Function · Source

How long frame index shows.

pub fn frame_info(data: &[u8], index: u32) -> pixels.FrameInfo!pixels.Error

frame_scratch_size

Function · Source

Bytes of scratch decode_frame() needs.

pub fn frame_scratch_size(data: &[u8]) -> usize!pixels.Error

decode_frame

Function · Source

Render frame index as a viewer shows it (earlier frames composited underneath) into target, converting to its layout.

pub fn decode_frame(data: &[u8], index: u32, target: &mut pixels.ViewMut, scratch: &mut[u8]) -> void!pixels.Error

decode_frame_into

Function · Source

Render frame index into a sink. Animated PNG frames arrive as one Rgba16 rect covering the canvas; frame 0 of a still image is decode_into().

pub fn decode_frame_into<S: sink.Sink>(data: &[u8], index: u32, output: &mut S, scratch: &mut[u8]) -> void!pixels.Error

EncodeOptions

Struct · Source

Format-independent encoder settings, mapped onto each codec’s options. JPEG XL is the one format with both: lossless (the default) or, with lossless = false, lossy at quality. The other formats are lossless and ignore quality and lossless.

pub struct EncodeOptions {
    // 0 to 100 for lossy encoding; higher is better (JPEG XL maps it to a
    // Butteraugli distance like cjxl: 90 is distance 1).
    pub quality: u32
    // Prefer a lossless encoding where the format offers both.
    pub lossless: bool
    // JPEG XL lossy: the Butteraugli distance itself, overriding quality
    // when above zero.
    pub distance: f32
    // 1 (fastest) to 9 (smallest); PNG uses it as the deflate level, and 0
    // writes stored PNG blocks.
    pub effort: u32
    // Write the EXIF and ICC payloads given to encode_with_metadata.
    pub keep_metadata: bool
    // PNG: write an indexed PNG when an 8-bit source has at most 256 RGBA
    // colors (see ops.palette and ops.remap to reduce it that far).
    pub palette: bool
}

EncodeOptions.new

Function · Source

pub fn new() -> EncodeOptions

max_encoded_size

Function · Source

An upper bound on the bytes encode() writes for source.

pub fn max_encoded_size(format: pixels.Format, source: &pixels.View, options: &EncodeOptions) -> usize!pixels.Error

max_encoded_size_for

Function · Source

The same for a width x height source in layout.

pub fn max_encoded_size_for(format: pixels.Format, width: u32, height: u32, layout: &pixels.Layout, options: &EncodeOptions) -> usize!pixels.Error

metadata_size

Function · Source

Bytes encode_with_metadata() may add for EXIF and ICC payloads of these sizes (zero for formats that do not store them).

pub fn metadata_size(format: pixels.Format, exif_len: usize, icc_len: usize) -> usize!pixels.Error

encode_scratch_size

Function · Source

Bytes of scratch encode() needs for source.

pub fn encode_scratch_size(format: pixels.Format, source: &pixels.View, options: &EncodeOptions) -> usize!pixels.Error

encode

Function · Source

Encode source (any layout) as format into output and return the byte count. Each codec picks the closest stored form: PNG writes gray, gray+alpha, RGB or RGBA at 8 or 16 bits; PPM writes P5, P6, P7 or PFM; QOI writes RGB or RGBA; BMP writes 24 or 32-bit.

pub fn encode(format: pixels.Format, source: &pixels.View, options: &EncodeOptions, output: &mut[u8], scratch: &mut[u8]) -> usize!pixels.Error

encode_with_metadata

Function · Source

encode() with an EXIF payload (TIFF-structured) and an ICC profile, each written when not empty, options.keep_metadata is set and the format can store it (PNG: eXIf and iCCP; JPEG XL: an Exif box and the embedded, entropy-coded profile, which must be an RGB or gray profile matching the image, else it is left out). The output may need metadata_size() more bytes than max_encoded_size().

pub fn encode_with_metadata(format: pixels.Format, source: &pixels.View, options: &EncodeOptions, exif: &[u8], icc: &[u8], output: &mut[u8], scratch: &mut[u8]) -> usize!pixels.Error

encode_canvas

Function · Source

Encode a canvas, read from its top-left pixel as 8-bit RGBA; size the output with max_encoded_size_for(format, width, height, pixels.Layout.rgba8(), options).

pub fn encode_canvas(format: pixels.Format, canvas: &graphics.Canvas, options: &EncodeOptions, output: &mut[u8], scratch: &mut[u8]) -> usize!pixels.Error

format_from_extension

Function · Source

The format for a file name’s extension, or a bare extension such as extension() returns, compared without case: png and apng; qoi; bmp and dib; ppm, pgm, pnm, pam and pfm; jxl.

pub fn format_from_extension(name: &str) -> pixels.Format!pixels.Error

extension

Function · Source

The usual file extension for format, without the dot.

pub fn extension(format: &pixels.Format) -> &str from(static)

Search every guide, reference page, and API declaration.