API referencestd/image

std/image/png

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

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/png"

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 apng.dodo, chunks.dodo, decode.dodo, encode.dodo
checksum std/checksum chunks.dodo, encode.dodo
color std/image/color chunks.dodo
convert std/image/convert apng.dodo
deflate std/compress/deflate decode.dodo, encode.dodo
meta std/image/meta chunks.dodo
pixels std/image/pixels apng.dodo, chunks.dodo, decode.dodo, encode.dodo, filter.dodo
sink std/image/sink apng.dodo, decode.dodo, encode.dodo
slice core/slice apng.dodo, encode.dodo
storage std/image/shared/scratch apng.dodo, encode.dodo
zlib std/compress/zlib decode.dodo, encode.dodo

frame_info

Function · Source

Timing of frame index: delay_num / delay_den seconds, a zero denominator meaning 100. A still image has one frame of zero duration.

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

frame_scratch_size

Function · Source

Bytes of scratch decode_frame() needs: the rows of scratch_size() plus two 16-bit RGBA canvases. For a still image, scratch_size().

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

decode_frame

Function · Source

Render animation frame index (see above) into output as one Rgba16 rect covering the canvas, using frame_scratch_size(data) bytes of work. For a still image, frame 0 is decode().

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

matches

Function · Source

True when data starts with the PNG signature.

pub fn matches(data: &[u8]) -> bool

info

Function · Source

Read the header without decoding: size, native layout, color, EXIF orientation and animation.

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

metadata

Function · Source

The file’s EXIF (eXIf, raw), XMP (iTXt “XML:com.adobe.xmp”, zlib when compressed) and ICC profile (iCCP, zlib), before or after the image data.

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

scratch_size

Function · Source

Bytes of scratch decode() needs for data: two rows of raw image data, each with its filter byte.

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

decode

Function · Source

Decode the default image (IDAT) into output in the header’s native layout, using scratch_size(data) bytes of scratch. For an animation this is the image shown by viewers without APNG support, which may or may not be frame 0; see decode_frame.

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

EncodeOptions

Struct · Source

pub struct EncodeOptions {
    // 0 writes stored (uncompressed) deflate blocks and needs no scratch;
    // 1 to 9 compress at that deflate level.
    pub level: u32
    // FILTER_NONE through FILTER_PAETH for every row, or FILTER_ADAPTIVE
    // (which uses FILTER_NONE for indexed and sub-byte rows).
    pub filter: u32
    // Write Adam7-interlaced rows.
    pub interlace: bool
    // Write an indexed PNG when the 8-bit source has <= 256 RGBA colors.
    pub palette: bool
    // Write an sRGB chunk (perceptual intent), unless an ICC profile is
    // given.
    pub srgb_chunk: bool
}

EncodeOptions.new

Function · Source

pub fn new() -> EncodeOptions

metadata_size

Function · Source

Bytes the optional eXIf and iCCP chunks add for payloads of these sizes; add it to max_encoded_size() when passing metadata.

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

max_encoded_size

Function · Source

An upper bound on the encoded size of a width x height image from a source in layout, without metadata (see metadata_size). Level 0 gives the exact size of a truecolor file.

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

encode_scratch_size

Function · Source

Bytes of scratch encode() needs: none for level 0, else the deflate encoder’s buffer and workspace.

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

encode

Function · Source

Encode source (any layout) and return the byte count.

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

encode_from

Function · Source

pub fn encode_from<S: sink.Source>(source: &S, options: &EncodeOptions, output: &mut[u8], scratch: &mut[u8]) -> usize!pixels.Error

encode_with_metadata

Function · Source

Encode with an eXIf chunk holding exif (a TIFF-structured payload, “II*\0” or “MM\0*”) and an iCCP chunk holding the ICC profile icc, each skipped when empty. The output needs max_encoded_size() + metadata_size(exif.len, icc.len) bytes at most.

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

encode_with_metadata_from

Function · Source

pub fn encode_with_metadata_from<S: sink.Source>(source: &S, options: &EncodeOptions, exif: &[u8], icc: &[u8], output: &mut[u8], work: &mut[u8]) -> usize!pixels.Error

encode_with_buffers

Function · Source

Encode with the deflate encoder at options.level (0 through 9; 0 writes deflate’s own stored blocks) using caller storage of at least deflate.ENCODER_BUFFER_LEN bytes and deflate.WORKSPACE_LEN words. All compressed data goes into one IDAT chunk.

pub fn encode_with_buffers<S: sink.Source>(source: &S, options: &EncodeOptions, exif: &[u8], icc: &[u8], output: &mut[u8], buffer: &mut[u8], words: &mut[u32]) -> usize!pixels.Error

FILTER_NONE

Constant · Source

pub const FILTER_NONE: u32 = 0

FILTER_SUB

Constant · Source

pub const FILTER_SUB: u32 = 1

FILTER_UP

Constant · Source

pub const FILTER_UP: u32 = 2

FILTER_AVERAGE

Constant · Source

pub const FILTER_AVERAGE: u32 = 3

FILTER_PAETH

Constant · Source

pub const FILTER_PAETH: u32 = 4

FILTER_ADAPTIVE

Constant · Source

Pick the filter per row by the smallest sum of filtered bytes taken as signed magnitudes, the usual heuristic.

pub const FILTER_ADAPTIVE: u32 = 5

Search every guide, reference page, and API declaration.