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
databy its signature and read its dimensions without decoding.
pub fn info(data: &[u8]) -> Info!Error
decode
Function · Source
Decode
datainto a new canvas overpixels, sized like the image and stored informat.pixelsneeds 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
dataonto 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
datainto a new canvas overpixels, like decode, usingscratchof 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
dataontocanvaslike draw, usingscratchof 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
canvasas 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
canvasas 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
canvasas 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
canvasas 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
canvasas a compressed 8-bit RGBA PNG and return its length. Each row gets the adaptive filter that suits it;levelis the deflate level, 0 through 9. The compressor borrowsbufferof deflate.ENCODER_BUFFER_LEN bytes andwordsof 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