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
failurefor 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
lengthbytes; 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
sizezeroed 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
pathand writedatato 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, inallocator.
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
formatand write the file atpath.
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
datainto this image, replacing its pixels, header and metadata. Withnativethe file’s native layout is used, otherwisetarget. 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
indexofdatainto 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
datain 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
dataconverted totarget.
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
indexofdata(see image.decode_frame), in the native layout whennativeis set, otherwise intarget.
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
pathin 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 totarget.
pub fn load_as(path: &str, target: pixels.Layout, allocator: shared_arena.Handle) -> Image<shared_arena.Handle>!Error from(allocator)