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
datafrom 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.scratchneeds 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.targetis 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
dataintotarget, 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
datainto 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
dataonto 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
indexshows.
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
indexas a viewer shows it (earlier frames composited underneath) intotarget, 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
indexinto 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) asformatintooutputand 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)