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_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_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.

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

pub fn height(&self) -> u32

pub fn format(&self) -> PixelFormat

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 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.