Struct Image 

pub struct Image { /* private fields */ }

A raster image. RGBA pixels (see PixelFormat) tagged with the ColorSpace they were authored in; top-left origin, row-major. Cheap Arc-backed clone; backends key their texture cache off Self::content_hash so two equal Images share a GPU slot.

Implementations

impl Image

pub fn from_rgba8(width: u32, height: u32, pixels: Vec<u8>) -> Self

Build from sRGB-encoded RGBA8 pixels — the common case for decoded PNG/JPEG art. Panics if pixels.len() != width * height * 4. Untagged 8-bit sources should use this (the web’s convention for untagged images is sRGB).

pub fn from_rgba8_in( space: ColorSpace, width: u32, height: u32, pixels: Vec<u8>, ) -> Self

Build from RGBA8 pixels authored in space — e.g. ColorSpace::DISPLAY_P3 for a P3-tagged JPEG. Panics if pixels.len() != width * height * 4.

pub fn from_rgb8(width: u32, height: u32, pixels: Vec<u8>) -> Self

Build from sRGB-encoded RGB8 pixels (no alpha channel — opaque sources like JPEG or RGB PNG). Expands to RGBA internally with alpha = 255; callers don’t need to repack rows by hand. Panics if pixels.len() != width * height * 3.

pub fn from_rgb8_in( space: ColorSpace, width: u32, height: u32, pixels: Vec<u8>, ) -> Self

Build from RGB8 pixels (no alpha channel) authored in space. Expands to RGBA internally with alpha = 255. Panics if pixels.len() != width * height * 3.

pub fn from_rgba16_in( space: ColorSpace, width: u32, height: u32, pixels: Vec<u16>, ) -> Self

Build from 16-bit unsigned-normalized RGBA pixels authored in space — e.g. a 16-bit PNG. Panics if pixels.len() != width * height * 4 (u16 channel values, not bytes).

pub fn from_rgba_f16_in( space: ColorSpace, width: u32, height: u32, pixels: Vec<f16>, ) -> Self

Build from typed half-float RGBA pixels authored in space. The f16 type is re-exported as crate::image::f16 so callers don’t need their own version-matched half dependency. Panics if pixels.len() != width * height * 4.

Sources that hand f16 data as raw bit patterns (most decoders) can skip the typed layer via Self::from_rgba_f16_bits_in.

pub fn from_rgba_f16_bits_in( space: ColorSpace, width: u32, height: u32, bits: Vec<u16>, ) -> Self

Build from half-float RGBA pixels given as raw IEEE 754 bit patterns (the shape most decoders hand f16 data in) authored in space. Panics if bits.len() != width * height * 4. For typed f16 buffers use Self::from_rgba_f16_in.

pub fn from_rgba_f32_in( space: ColorSpace, width: u32, height: u32, pixels: Vec<f32>, ) -> Self

Build from f32 RGBA pixels authored in space — e.g. a decoded EXR in ColorSpace::SCRGB_LINEAR. Panics if pixels.len() != width * height * 4.

pub fn width(&self) -> u32

Image width in pixels.

pub fn height(&self) -> u32

Image height in pixels.

pub fn format(&self) -> PixelFormat

Channel encoding of the pixel buffer.

pub fn color_space(&self) -> ColorSpace

The color space the pixel values were authored in.

pub fn pixels(&self) -> &[u8]

Raw pixel bytes, length width * height * format().bytes_per_pixel(), native-endian. Top-left origin.

pub fn is_srgb8(&self) -> bool

True when the pixel buffer can upload directly to an 8-bit sRGB texture and let the sampler decode — RGBA8 in the default ColorSpace::SRGB. Everything else goes through Self::to_scrgb_f16.

pub fn to_scrgb_f16(&self) -> Vec<u16>

Convert to linear sRGB-primaries extended-range (“scRGB”) half-float pixels for GPU upload: RGBA interleaved, width * height * 4 raw f16 bit patterns, alpha unchanged (straight, not premultiplied — the image shader premultiplies at blend).

This is the working-space representation every renderer composites in, so sampling needs no further conversion. Wide-gamut primaries land outside [0, 1] and HDR brights above 1.0; both survive on float textures.

Luminance contract

Working-space 1.0 displays at the output’s reference white (the renderer scales to the swapchain’s encoding, e.g. white_scale on scRGB). Relative transfers (sRGB, gamma, linear) already encode 1.0 = reference white and convert as-is. PQ is absolute (signal 1.0 = 10000 nits), so this conversion anchors it: a pixel at the source’s reference_luminance_nits (203 for ColorSpace::BT2020_PQ, per BT.2408) converts to working-space 1.0, and a 1000-nit highlight lands at ~4.9× — HDR headroom the per-image remaster grades into the panel’s volume (see DynamicRangeLimit). HLG is scene-referred and currently decodes without an OOTF or anchoring — its contract is still open. Note crate::color::Color conversion does not anchor PQ (UI colors stay encoding-literal); the anchor is an image-pipeline behavior.

pub fn to_scrgb_f16_with_peak(&self) -> (Vec<u16>, f32)

Self::to_scrgb_f16 plus the image’s measured content peak: the maximum linear RGB channel value over all pixels, in working-space units (1.0 = reference white). For a still image this is its effective MaxCLL — backends cache it per texture and feed it to the luminance remaster (see DynamicRangeLimit and docs/COLOR_MANAGEMENT.md). Alpha is ignored (the remaster runs on straight rgb before the blend premultiply). Non-finite channel values are skipped.

pub fn downscaled_to_fit(&self, max_dim: u32) -> Image

Return this image downscaled so its larger side fits max_dim, or a cheap (Arc-bump) clone when it already fits. An image larger than the device’s max_*_dimension_2d (8192 by default; 4096 on some adapters) would fail GPU texture creation and panic the process — content the user merely clicked on. Every backend calls this with its device limit before upload (issue #78).

When it downscales, the resample runs in linear scRGB f16 working space (box-average, each source pixel read once) so colour averages correctly and HDR brights >1.0 survive; the result is an RgbaF16 / ColorSpace::SCRGB_LINEAR image regardless of source format, so an oversized 8-bit sRGB source uploads through the f16 path — the memory-for-simplicity trade of a single resampler. Aspect ratio is preserved, so a source oversized on one axis shrinks on both. Logs a warn on the downscale; the fit case is silent.

pub fn content_hash(&self) -> u64

Stable hash of (width, height, format, color_space, pixels). Backends use this as the key into their per-image texture cache.

pub fn label(&self) -> String

Short hex label for inspection / dump output, e.g. "image:1a2b3c4d".

Trait Implementations

impl Clone for Image

fn clone(&self) -> Image

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Image

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for Image

impl PartialEq for Image

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.