API referencestd/image

std/image/pixels

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

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

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
color std/image/color pixels.dodo
num core/num pixels.dodo

Error

Enum · Source

pub enum Error {
    // The data ended before the image did.
    Truncated,
    // The data is not a valid file of its format.
    Malformed,
    // A valid file using something this package does not implement.
    Unsupported,
    // A dimension exceeds MAX_DIMENSION or a size overflows.
    TooLarge,
    // The pixel storage, scratch or output buffer is shorter than required.
    BufferTooSmall
}

error_name

Function · Source

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

MAX_DIMENSION

Constant · Source

The largest width or height any codec accepts, as in std/graphics.

pub const MAX_DIMENSION: u32 = 16777216

Format

Enum · Source

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

format_name

Function · Source

pub fn format_name(format: &Format) -> &str from(static)

clone_format

Function · Source

pub fn clone_format(format: &Format) -> Format

Channels

Enum · Source

pub enum Channels {
    Gray,
    GrayAlpha,
    Rgb,
    Rgba
}

Sample

Enum · Source

pub enum Sample {
    U8,
    U16,
    // IEEE 754 binary16.
    F16,
    // IEEE 754 binary32.
    F32
}

SAMPLE_U8

Constant · Source

Sample codes for code that dispatches on a scalar; see Layout.sample_code.

pub const SAMPLE_U8: u32 = 0

SAMPLE_U16

Constant · Source

pub const SAMPLE_U16: u32 = 1

SAMPLE_F16

Constant · Source

pub const SAMPLE_F16: u32 = 2

SAMPLE_F32

Constant · Source

pub const SAMPLE_F32: u32 = 3

Layout

Struct · Source

pub struct Layout {
    pub channels: Channels
    pub sample: Sample
    // Color samples are multiplied by alpha. Only meaningful with alpha.
    pub premultiplied: bool
}

Layout.new

Function · Source

pub fn new(channels: Channels, sample: Sample) -> Layout

Layout.from_codes

Function · Source

A layout from channel count (1 to 4) and sample code, the inverse of channel_count() and sample_code().

pub fn from_codes(channels: usize, sample: u32, premultiplied: bool) -> Layout

Layout.rgba8

Function · Source

pub fn rgba8() -> Layout

Layout.rgb8

Function · Source

pub fn rgb8() -> Layout

Layout.gray8

Function · Source

pub fn gray8() -> Layout

Layout.gray_alpha8

Function · Source

pub fn gray_alpha8() -> Layout

Layout.rgba16

Function · Source

pub fn rgba16() -> Layout

Layout.rgb16

Function · Source

pub fn rgb16() -> Layout

Layout.gray16

Function · Source

pub fn gray16() -> Layout

Layout.rgba_f32

Function · Source

pub fn rgba_f32() -> Layout

Layout.rgb_f32

Function · Source

pub fn rgb_f32() -> Layout

Layout.clone

Function · Source

pub fn clone(&self) -> Layout

Layout.equals

Function · Source

pub fn equals(&self, other: &Layout) -> bool

Layout.channel_count

Function · Source

1 to 4.

pub fn channel_count(&self) -> usize

Layout.sample_code

Function · Source

SAMPLE_U8, SAMPLE_U16, SAMPLE_F16 or SAMPLE_F32.

pub fn sample_code(&self) -> u32

Layout.sample_bytes

Function · Source

pub fn sample_bytes(&self) -> usize

Layout.bytes_per_pixel

Function · Source

pub fn bytes_per_pixel(&self) -> usize

Layout.has_alpha

Function · Source

pub fn has_alpha(&self) -> bool

Layout.is_gray

Function · Source

pub fn is_gray(&self) -> bool

Layout.is_float

Function · Source

pub fn is_float(&self) -> bool

Layout.with_alpha

Function · Source

This layout with an alpha channel added or removed.

pub fn with_alpha(&self, alpha: bool) -> Layout

Layout.with_sample

Function · Source

This layout with another sample type.

pub fn with_sample(&self, sample: u32) -> Layout

row_bytes

Function · Source

Bytes in one tightly packed row.

pub fn row_bytes(width: u32, layout: &Layout) -> usize!Error

bytes_needed

Function · Source

Bytes a tightly packed width x height image needs.

pub fn bytes_needed(width: u32, height: u32, layout: &Layout) -> usize!Error

checked

Function · Source

count * per + extra, or TooLarge.

pub fn checked(count: usize, per: usize, extra: usize) -> usize!Error

get16

Function · Source

pub fn get16(data: &[u8], offset: usize) -> u16

put16

Function · Source

pub fn put16(data: &mut[u8], offset: usize, value: u16)

get32

Function · Source

pub fn get32(data: &[u8], offset: usize) -> u32

put32

Function · Source

pub fn put32(data: &mut[u8], offset: usize, value: u32)

View

Struct · Source

Borrowed, read-only pixels: row y starts at byte y * stride.

pub struct View {
    // Private implementation fields omitted.
}

View.new

Function · Source

A view of tightly packed rows. Fails with BufferTooSmall when data is shorter than bytes_needed(width, height, layout).

pub fn new(data: &[u8], width: u32, height: u32, layout: Layout) -> View!Error from(data)

View.with_stride

Function · Source

A view whose rows are stride bytes apart; the last row needs only its own pixels.

pub fn with_stride(data: &[u8], width: u32, height: u32, stride: usize, layout: Layout) -> View!Error from(data)

View.width

Function · Source

pub fn width(&self) -> u32

View.height

Function · Source

pub fn height(&self) -> u32

View.stride

Function · Source

pub fn stride(&self) -> usize

View.layout

Function · Source

pub fn layout(&self) -> &Layout

View.bytes_per_pixel

Function · Source

pub fn bytes_per_pixel(&self) -> usize

View.row

Function · Source

The bytes of row y, exactly width * bytes_per_pixel long. Panics when y >= height.

pub fn row(&self, y: u32) -> &[u8] from(self)

View.pixel

Function · Source

The bytes of pixel (x, y).

pub fn pixel(&self, x: u32, y: u32) -> &[u8] from(self)

View.bytes

Function · Source

The underlying bytes from the first pixel to the end of the last row.

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

View.is_packed

Function · Source

True when rows are tightly packed, so bytes() is the whole image.

pub fn is_packed(&self) -> bool

View.sub

Function · Source

The width x height rectangle at (x, y), sharing these pixels. Fails with Malformed when it does not fit.

pub fn sub(&self, x: u32, y: u32, width: u32, height: u32) -> View!Error from(self)

ViewMut

Struct · Source

Borrowed, writable pixels.

pub struct ViewMut {
    // Private implementation fields omitted.
}

ViewMut.new

Function · Source

pub fn new(data: &mut[u8], width: u32, height: u32, layout: Layout) -> ViewMut!Error from(data)

ViewMut.with_stride

Function · Source

pub fn with_stride(data: &mut[u8], width: u32, height: u32, stride: usize, layout: Layout) -> ViewMut!Error from(data)

ViewMut.width

Function · Source

pub fn width(&self) -> u32

ViewMut.height

Function · Source

pub fn height(&self) -> u32

ViewMut.stride

Function · Source

pub fn stride(&self) -> usize

ViewMut.layout

Function · Source

pub fn layout(&self) -> &Layout

ViewMut.bytes_per_pixel

Function · Source

pub fn bytes_per_pixel(&self) -> usize

ViewMut.row

Function · Source

pub fn row(&self, y: u32) -> &[u8] from(self)

ViewMut.row_mut

Function · Source

pub fn row_mut(&mut self, y: u32) -> &mut[u8] from(self)

ViewMut.pixel

Function · Source

pub fn pixel(&self, x: u32, y: u32) -> &[u8] from(self)

ViewMut.pixel_mut

Function · Source

pub fn pixel_mut(&mut self, x: u32, y: u32) -> &mut[u8] from(self)

ViewMut.bytes

Function · Source

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

ViewMut.bytes_mut

Function · Source

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

ViewMut.is_packed

Function · Source

pub fn is_packed(&self) -> bool

ViewMut.as_view

Function · Source

A read-only view of the same pixels.

pub fn as_view(&self) -> View from(self)

ViewMut.sub_mut

Function · Source

A writable width x height rectangle at (x, y).

pub fn sub_mut(&mut self, x: u32, y: u32, width: u32, height: u32) -> ViewMut!Error from(self)

ViewMut.relabel

Function · Source

Reinterpret the pixels with another layout of the same pixel size, such as after premultiplying in place.

pub fn relabel(&mut self, layout: Layout) -> void!Error

ViewMut.clear

Function · Source

Set every byte of every pixel to zero: transparent black, or black.

pub fn clear(&mut self)

Struct · Source

What a decoder reports about a file before decoding it.

pub struct Header {
    pub format: Format
    pub width: u32
    pub height: u32
    // The layout that holds the file's samples without loss: palettes expand
    // to RGB or RGBA, gray below 8 bits widens to 8.
    pub native: Layout
    // Significant bits per sample as stored: 1 to 16 for integers, 16 or 32
    // for floats.
    pub bit_depth: u32
    pub color: color.ColorInfo
    pub orientation: color.Orientation
    // 1 unless the file is animated.
    pub frames: u32
    // How often an animation plays; 0 means forever.
    pub loops: u32
    pub animated: bool
    pub lossy: bool
    // Interlaced PNG, progressive JPEG XL.
    pub progressive: bool
}

Header.new

Function · Source

A header with the defaults for a single, lossless, untagged sRGB frame.

pub fn new(format: Format, width: u32, height: u32, native: Layout, bit_depth: u32) -> Header

Header.clone

Function · Source

pub fn clone(&self) -> Header

Header.has_alpha

Function · Source

pub fn has_alpha(&self) -> bool

Header.display_width

Function · Source

Width and height once the orientation is applied.

pub fn display_width(&self) -> u32

Header.display_height

Function · Source

pub fn display_height(&self) -> u32

FrameInfo

Struct · Source

Timing of one animation frame: it shows for numerator / denominator seconds.

pub struct FrameInfo {
    pub numerator: u32
    pub denominator: u32
}

FrameInfo.milliseconds

Function · Source

The duration rounded to milliseconds, saturating at 0xffffffff (frame timing comes from the file: 2^32 - 1 seconds fit a FrameInfo).

pub fn milliseconds(&self) -> u32

Search every guide, reference page, and API declaration.