API referencestd/image_alloc

std/image_alloc

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

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_alloc"

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
block alloc/block image_alloc.dodo
color std/image/color image_alloc.dodo
convert std/image/convert image_alloc.dodo
error alloc/error image_alloc.dodo
fs std/fs image_alloc.dodo
image std/image image_alloc.dodo
layout alloc/layout image_alloc.dodo
mem core/mem image_alloc.dodo
meta std/image/meta image_alloc.dodo
ops std/image/ops image_alloc.dodo
pixels std/image/pixels image_alloc.dodo
platform std/platform image_alloc.dodo
platform_error std/platform/error image_alloc.dodo
ptr core/ptr image_alloc.dodo
shared_arena alloc/shared_arena image_alloc.dodo

Error

Enum · Source

pub enum Error {
    Image(pixels.Error), Allocation(error.AllocError), File(fs.FileError)
}

error_name

Function · Source

A short fixed description of failure for messages.

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

MAX_FILE_SIZE

Constant · Source

The largest file load() and read_file() accept: 1 GiB.

pub const MAX_FILE_SIZE: u64 = 1073741824

Bytes

Struct · Source

An owned byte buffer: file contents or an encoded image.

pub struct Bytes<A> {
    // Private implementation fields omitted.
}

Bytes.len

Function · Source

pub fn len(&self) -> usize

Bytes.is_empty

Function · Source

pub fn is_empty(&self) -> bool

Bytes.as_slice

Function · Source

pub fn as_slice(&self) -> &[u8] from(self)

Bytes.as_mut_slice

Function · Source

pub fn as_mut_slice(&mut self) -> &mut[u8] from(self)

Bytes.truncate

Function · Source

Shorten to length bytes; the storage is kept until the buffer drops.

pub fn truncate(&mut self, length: usize)

bytes_in

Function · Source

SAFETY: A meets the allocator contract described at the top of this file.

pub unsafe fn bytes_in<A>(size: usize, allocator: A) -> Bytes<A>!Error from(allocator)

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

bytes

Function · Source

size zeroed bytes from a shared arena.

pub fn bytes(size: usize, allocator: shared_arena.Handle) -> Bytes<shared_arena.Handle>!Error from(allocator)

read_file_in

Function · Source

SAFETY: A meets the allocator contract described at the top of this file.

pub unsafe fn read_file_in<A>(path: &str, allocator: A) -> Bytes<A>!Error from(allocator)

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

read_file

Function · Source

The whole file at path (UTF-8), at most MAX_FILE_SIZE bytes.

pub fn read_file(path: &str, allocator: shared_arena.Handle) -> Bytes<shared_arena.Handle>!Error from(allocator)

write_file

Function · Source

Create or truncate the file at path and write data to it.

pub fn write_file(path: &str, data: &[u8]) -> void!Error

Image

Struct · Source

Owned pixels: width x height tightly packed rows in layout, plus what the file they were decoded from said about them.

pub struct Image<A> {
    // Private implementation fields omitted.
}

Image.width

Function · Source

pub fn width(&self) -> u32

Image.height

Function · Source

pub fn height(&self) -> u32

Image.layout

Function · Source

pub fn layout(&self) -> &pixels.Layout

Image.stride

Function · Source

Bytes between rows: rows are tightly packed.

pub fn stride(&self) -> usize

Image.bytes

Function · Source

Every pixel, row after row.

pub fn bytes(&self) -> &[u8] from(self)

Image.bytes_mut

Function · Source

pub fn bytes_mut(&mut self) -> &mut[u8] from(self)

Image.view

Function · Source

pub fn view(&self) -> pixels.View from(self)

Image.view_mut

Function · Source

pub fn view_mut(&mut self) -> pixels.ViewMut from(self)

Image.header

Function · Source

The header of the file this image was decoded from: its format, size and native layout as stored, bit depth, color description and animation. Images made with new() have a placeholder header and decoded() is false. Transforms do not change it, except that orient() resets the orientation.

pub fn header(&self) -> &pixels.Header

Image.decoded

Function · Source

pub fn decoded(&self) -> bool

Image.format

Function · Source

The format of the file this image came from, if any.

pub fn format(&self) -> Option<pixels.Format>

Image.color

Function · Source

pub fn color(&self) -> &color.ColorInfo

Image.orientation

Function · Source

How the pixels must be transformed for display; Identity once orient() has applied it.

pub fn orientation(&self) -> &color.Orientation

Image.bit_depth

Function · Source

pub fn bit_depth(&self) -> u32

Image.exif

Function · Source

The EXIF payload (TIFF structure) copied from the file, or empty.

pub fn exif(&self) -> &[u8] from(self)

Image.icc

Function · Source

The decoded ICC profile copied from the file, or empty.

pub fn icc(&self) -> &[u8] from(self)

Image.set_exif

Function · Source

pub fn set_exif(&mut self, payload: &[u8]) -> void!Error

Image.set_icc

Function · Source

pub fn set_icc(&mut self, profile: &[u8]) -> void!Error

Image.clear_metadata

Function · Source

Drop the EXIF and ICC payloads, so nothing is written with the pixels.

pub fn clear_metadata(&mut self) -> void!Error

Image.copy

Function · Source

A copy of this image (pixels, header and metadata) in allocator.

pub fn copy(&self, allocator: A) -> Image<A>!Error from(allocator)

Image.converted

Function · Source

A copy converted to target, in allocator.

pub fn converted(&self, target: pixels.Layout, allocator: A) -> Image<A>!Error from(allocator)

Image.convert

Function · Source

Convert the pixels to target (see std/image/convert: 8 to 16 bits multiplies by 257, 16 to 8 rounds, color to gray uses BT.709 luma, a missing alpha is opaque).

pub fn convert(&mut self, target: pixels.Layout) -> void!Error

Image.orient

Function · Source

Apply the header’s orientation, so the pixels are as displayed; the orientation becomes Identity and an EXIF orientation tag is reset to 1.

pub fn orient(&mut self) -> void!Error

Image.transform

Function · Source

Transform the pixels by orientation (flips, quarter turns, transposes); the header is unchanged.

pub fn transform(&mut self, orientation: &color.Orientation) -> void!Error

Image.rotate

Function · Source

Rotate clockwise by 90, 180 or 270 degrees (0 does nothing); other angles fail with Malformed.

pub fn rotate(&mut self, degrees: u32) -> void!Error

Image.flip_horizontal

Function · Source

Mirror left-right.

pub fn flip_horizontal(&mut self)

Image.flip_vertical

Function · Source

Mirror top-bottom.

pub fn flip_vertical(&mut self)

Image.crop

Function · Source

Keep the width x height rectangle at (x, y); Malformed when it does not fit.

pub fn crop(&mut self, x: u32, y: u32, width: u32, height: u32) -> void!Error

Image.resize

Function · Source

Resample to width x height with std/image/ops resize (any filter, in linear light with options.linear); the layout is kept.

pub fn resize(&mut self, width: u32, height: u32, options: &ops.ResizeOptions) -> void!Error

Image.quantize

Function · Source

Reduce the image to at most colors (1 to 256) colors with a median cut palette and the given dithering; the pixels become 8-bit RGBA using only palette colors, so a PNG written with EncodeOptions.palette is indexed. Returns the palette size.

pub fn quantize(&mut self, colors: usize, dither: ops.Dither) -> usize!Error

Image.max_encoded_size

Function · Source

An upper bound on the bytes encode() and save() write.

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

Image.encode_into

Function · Source

Encode into output (at least max_encoded_size() bytes) and return the byte count. With options.keep_metadata the EXIF and ICC payloads are written where the format stores them.

pub fn encode_into(&self, format: pixels.Format, options: &image.EncodeOptions, output: &mut[u8]) -> usize!Error

Image.encode

Function · Source

The encoded file in a new buffer from allocator.

pub fn encode(&self, format: pixels.Format, options: &image.EncodeOptions, allocator: A) -> Bytes<A>!Error from(allocator)

Image.save

Function · Source

Encode as format and write the file at path.

pub fn save(&self, path: &str, format: pixels.Format, options: &image.EncodeOptions) -> void!Error

Image.save_auto

Function · Source

save() with the format named by the path’s extension (see image.format_from_extension) and default options.

pub fn save_auto(&self, path: &str) -> void!Error

Image.decode_from

Function · Source

Decode the default image of data into this image, replacing its pixels, header and metadata. With native the file’s native layout is used, otherwise target. After a failure the pixels are unspecified (the size may already be the file’s) and the header and metadata are the previous ones.

pub fn decode_from(&mut self, data: &[u8], target: pixels.Layout, native: bool) -> void!Error

Image.decode_frame_from

Function · Source

Render animation frame index of data into this image (see image.decode_frame), reusing the pixel buffer when its size matches.

pub fn decode_frame_from(&mut self, data: &[u8], index: u32, target: pixels.Layout, native: bool) -> void!Error

new_in

Function · Source

pub unsafe fn new_in<A>(width: u32, height: u32, shape: pixels.Layout, allocator: A) -> Image<A>!Error from(allocator)

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

decode_in

Function · Source

pub unsafe fn decode_in<A>(data: &[u8], allocator: A) -> Image<A>!Error from(allocator)

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

decode_as_in

Function · Source

pub unsafe fn decode_as_in<A>(data: &[u8], target: pixels.Layout, allocator: A) -> Image<A>!Error from(allocator)

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

decode_frame_in

Function · Source

pub unsafe fn decode_frame_in<A>(data: &[u8], index: u32, target: pixels.Layout, native: bool, allocator: A) -> Image<A>!Error from(allocator)

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

load_in

Function · Source

pub unsafe fn load_in<A>(path: &str, allocator: A) -> Image<A>!Error from(allocator)

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

load_as_in

Function · Source

pub unsafe fn load_as_in<A>(path: &str, target: pixels.Layout, allocator: A) -> Image<A>!Error from(allocator)

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

new

Function · Source

A width x height image of zeroed pixels in shape.

pub fn new(width: u32, height: u32, shape: pixels.Layout, allocator: shared_arena.Handle) -> Image<shared_arena.Handle>!Error from(allocator)

decode

Function · Source

Decode the default image of data in the file’s native layout.

pub fn decode(data: &[u8], allocator: shared_arena.Handle) -> Image<shared_arena.Handle>!Error from(allocator)

decode_as

Function · Source

Decode the default image of data converted to target.

pub fn decode_as(data: &[u8], target: pixels.Layout, allocator: shared_arena.Handle) -> Image<shared_arena.Handle>!Error from(allocator)

decode_frame

Function · Source

Render animation frame index of data (see image.decode_frame), in the native layout when native is set, otherwise in target.

pub fn decode_frame(data: &[u8], index: u32, target: pixels.Layout, native: bool, allocator: shared_arena.Handle) -> Image<shared_arena.Handle>!Error from(allocator)

load

Function · Source

Read and decode the file at path in its native layout.

pub fn load(path: &str, allocator: shared_arena.Handle) -> Image<shared_arena.Handle>!Error from(allocator)

load_as

Function · Source

Read and decode the file at path, converted to target.

pub fn load_as(path: &str, target: pixels.Layout, allocator: shared_arena.Handle) -> Image<shared_arena.Handle>!Error from(allocator)

Search every guide, reference page, and API declaration.