API referencestd/graphics

std/graphics/image

Public declarations, types, methods, and source contracts for std/graphics/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/graphics/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
graphics std/graphics 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 std/image: Truncated, Malformed, Unsupported (a valid file using something not implemented, such as ASCII PPM), TooLarge (a dimension exceeds graphics.MAX_DIMENSION or a size overflows) and BufferTooSmall.

pub type Error = pixels.Error

error_name

Function · Source

pub fn error_name(error: Error) -> &str from(static)

Format

Enum · Source

pub enum Format {
    // Netpbm binary PPM (P6), PGM (P5), PAM (P7) or PFM.
    Ppm,
    Qoi,
    Bmp,
    Png
}

Info

Struct · Source

pub struct Info {
    pub format: Format
    pub width: u32
    pub height: u32
    // True when the file stores an alpha channel (QOI RGBA, BMP alpha mask,
    // PNG gray or RGB with alpha, PAM with alpha) or a PNG transparency
    // (tRNS) chunk.
    pub has_alpha: bool
}

info

Function · Source

Identify data by its signature and read its dimensions without decoding.

pub fn info(data: &[u8]) -> Info!Error

decode

Function · Source

Decode data into a new canvas over pixels, sized like the image and stored in format. pixels needs graphics.bytes_needed(width, height, format) bytes. The returned canvas’s dirty rectangle covers the image. PNG rows are unfiltered in PNG_SCRATCH_LEN bytes of stack; an image whose rows need more fails with BufferTooSmall, so use decode_png for it.

pub fn decode(data: &[u8], pixels: &mut[u8], format: graphics.PixelFormat) -> graphics.Canvas!Error from(pixels)

draw

Function · Source

Decode data onto an existing canvas with the image’s top-left corner at (x, y). Pixels outside the canvas or its clip are skipped; colors are stored, not blended. A decoding error can leave a partly drawn image.

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

PNG_SCRATCH_LEN

Constant · Source

Bytes of stack the generic decode() and draw() use for PNG rows; see png_scratch_size.

pub const PNG_SCRATCH_LEN: usize = 16384

png_scratch_size

Function · Source

Bytes of scratch storage draw_png and decode_png need for data: two rows of raw image data, each with its filter byte.

pub fn png_scratch_size(data: &[u8]) -> usize!Error

decode_png

Function · Source

Decode PNG data into a new canvas over pixels, like decode, using scratch of at least png_scratch_size(data) bytes for its rows.

pub fn decode_png(data: &[u8], pixels: &mut[u8], format: graphics.PixelFormat, scratch: &mut[u8]) -> graphics.Canvas!Error from(pixels)

draw_png

Function · Source

Draw PNG data onto canvas like draw, using scratch of at least png_scratch_size(data) bytes for its rows.

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

ppm_size

Function · Source

Bytes encode_ppm writes for a width x height canvas.

pub fn ppm_size(width: u32, height: u32) -> usize!Error

encode_ppm

Function · Source

Write canvas as binary PPM (P6, maxval 255; alpha is dropped) and return the byte count, ppm_size(width, height).

pub fn encode_ppm(canvas: &graphics.Canvas, output: &mut[u8]) -> usize!Error

qoi_max_size

Function · Source

The largest size encode_qoi can produce for a width x height canvas.

pub fn qoi_max_size(width: u32, height: u32) -> usize!Error

encode_qoi

Function · Source

Write canvas as a 4-channel sRGB QOI file and return its length. The output needs at most qoi_max_size(width, height) bytes; a smaller buffer works when the image compresses well, else fails with BufferTooSmall.

pub fn encode_qoi(canvas: &graphics.Canvas, output: &mut[u8]) -> usize!Error

bmp_size

Function · Source

Bytes encode_bmp writes for a width x height canvas.

pub fn bmp_size(width: u32, height: u32) -> usize!Error

encode_bmp

Function · Source

Write canvas as an uncompressed, bottom-up 24-bit BMP (alpha is dropped) and return the byte count, bmp_size(width, height).

pub fn encode_bmp(canvas: &graphics.Canvas, output: &mut[u8]) -> usize!Error

png_size

Function · Source

Bytes encode_png writes for a width x height canvas. Fails with Unsupported for an empty canvas, which PNG cannot store.

pub fn png_size(width: u32, height: u32) -> usize!Error

encode_png

Function · Source

Write canvas as an 8-bit RGBA PNG without compression (stored deflate blocks, no row filters) and return the byte count, png_size(width, height).

pub fn encode_png(canvas: &graphics.Canvas, output: &mut[u8]) -> usize!Error

png_compressed_max_size

Function · Source

An upper bound on what encode_png_compressed writes for a width x height canvas at any level.

pub fn png_compressed_max_size(width: u32, height: u32) -> usize!Error

encode_png_compressed

Function · Source

Write canvas as a compressed 8-bit RGBA PNG and return its length. Each row gets the adaptive filter that suits it; level is the deflate level, 0 through 9. The compressor borrows buffer of deflate.ENCODER_BUFFER_LEN bytes and words of deflate.WORKSPACE_LEN words (about 350 KiB together; static storage suits small stacks). The output needs at most png_compressed_max_size(width, height) bytes; a smaller buffer works when the image compresses well, else fails with BufferTooSmall.

pub fn encode_png_compressed(canvas: &graphics.Canvas, output: &mut[u8], level: usize, buffer: &mut[u8], words: &mut[u32]) -> usize!Error

Search every guide, reference page, and API declaration.