856f865cf98d
lib.rs
//! Sparse, copy-on-write tiled surfaces in any [`PixelFormat`].
//!
//! A [`Surface`] is an infinite plane of 256×256 tiles. Missing tiles read as the surface's
//! default pixel (transparent for layers, white for "reveal all" masks). Tiles are `Arc`-shared,
//! so cloning a surface is O(tiles) and mutation copies only the touched tiles. That makes
//! undo snapshots, background jobs and autosave cheap.
#![forbid(unsafe_code)]
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
pub mod headroom;
mod interrupt;
pub use interrupt::{Cancelled, Interrupt};
pub mod scratch;
mod shift;
pub use shift::TranslateSteps;
use std::collections::BTreeMap;
use std::fmt;
use std::ops::{Bound, Deref, DerefMut};
use std::sync::{Arc, RwLockReadGuard, RwLockWriteGuard};
use photocraft_color::{ColorMode, PixelFormat, SampleType, read_sample, read_samples, write_sample};
use photocraft_geom::{Rect, TILE_SIZE, TileCoord};
/// The bytes a surface in `fmt` keeps for pixels written over `rect`: every tile the rect
/// touches, whole. Importers admit decoded pixels by their logical size; a narrow or scattered
/// rect stores up to `TILE_SIZE` times more, so admission charges this instead.
pub fn tile_storage_bytes(rect: Rect, fmt: &PixelFormat) -> u64 {
stored_tiles_bytes(rect.tile_count(), fmt)
}
/// The bytes `tiles` whole tiles take in `fmt`.
pub fn stored_tiles_bytes(tiles: u64, fmt: &PixelFormat) -> u64 {
tiles.saturating_mul((TILE_SIZE as u64).pow(2)).saturating_mul(fmt.bytes_per_pixel() as u64)
}
/// A checked surface allocation could not be represented or reserved.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum AllocationError {
ScratchRead(String),
SizeOverflow,
NotEnoughMemory {
bytes: usize,
},
/// The pixels given don't fill the region they are written to.
LengthMismatch {
expected: usize,
got: usize,
},
}
impl fmt::Display for AllocationError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::ScratchRead(error) => write!(f, "scratch tile could not be read: {error}"),
Self::SizeOverflow => f.write_str("requested surface allocation is too large"),
Self::NotEnoughMemory { bytes } => write!(f, "not enough memory to allocate {} bytes", bytes),
Self::LengthMismatch { expected, got } => write!(f, "{got} bytes of pixels given for a region that takes {expected}"),
}
}
}
impl std::error::Error for AllocationError {}
/// Failure to prepare an interruptible row write.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum RowWriteError {
Allocation(AllocationError),
Cancelled(Cancelled),
}
impl From<AllocationError> for RowWriteError {
fn from(error: AllocationError) -> Self {
Self::Allocation(error)
}
}
impl fmt::Display for RowWriteError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Allocation(error) => write!(f, "{error}"),
Self::Cancelled(error) => write!(f, "{error}"),
}
}
}
impl std::error::Error for RowWriteError {}
pub mod memory;
mod scratch_file;
pub mod spill;
pub mod stage_file;
/// One shared tile per pixel value (and tile size), for [`Surface::share_uniform_tiles`].
#[derive(Debug, Default)]
pub struct TileInterner {
tiles: std::collections::HashMap<usize, std::collections::HashMap<Vec<u8>, Arc<Tile>>>,
}
impl TileInterner {
/// Number of distinct uniform tiles held.
pub fn len(&self) -> usize {
self.tiles.values().map(|m| m.len()).sum()
}
/// `true` when no tile is held.
pub fn is_empty(&self) -> bool {
self.len() == 0
}
}
/// Pixel storage for one tile: `TILE_SIZE² × bytes_per_pixel`, row-major, interleaved channels.
///
/// The bytes may live on the scratch disk ([`spill`]); [`Tile::bytes`] and [`Tile::bytes_mut`]
/// bring them back and keep them in memory while the returned guard lives. Take one guard per
/// tile, not per pixel, in hot loops.
pub struct Tile {
cell: Arc<spill::Cell>,
}
impl Tile {
/// Fill a new tile with one encoded pixel, reporting size or allocation failures.
fn try_filled(format: &PixelFormat, pixel: &[u8]) -> Result<Self, AllocationError> {
let n = (TILE_SIZE * TILE_SIZE) as usize;
let bytes = n.checked_mul(format.bytes_per_pixel()).ok_or(AllocationError::SizeOverflow)?;
let mut data = scratch::try_take_exact(bytes, 0u8).ok_or(AllocationError::NotEnoughMemory { bytes })?;
if pixel.iter().any(|&b| b != 0) {
// Fill the first row, then copy it to the other rows without another allocation.
let row_len = TILE_SIZE as usize * format.bytes_per_pixel();
let (row, rest) = data.split_at_mut(row_len);
for px in row.chunks_exact_mut(pixel.len()) {
px.copy_from_slice(pixel);
}
for dst in rest.chunks_exact_mut(row_len) {
dst.copy_from_slice(row);
}
}
Ok(Tile::from_vec(data))
}
/// Clone this tile's pixel buffer with a fallible reservation.
pub fn try_clone(&self) -> Result<Self, AllocationError> {
let source = self.try_bytes().map_err(AllocationError::ScratchRead)?;
let bytes = source.len();
let mut data = scratch::try_take_exact(bytes, 0u8).ok_or(AllocationError::NotEnoughMemory { bytes })?;
data.copy_from_slice(&source);
Ok(Tile::from_vec(data))
}
fn filled(format: &PixelFormat, pixel: &[u8]) -> Self {
let row_len = TILE_SIZE as usize * format.bytes_per_pixel();
let mut data = scratch::take_exact(row_len * TILE_SIZE as usize, 0u8);
if pixel.iter().any(|&b| b != 0) {
// One prebuilt row copied per tile row: 256 bulk copies instead of one
// copy_from_slice per pixel.
let mut row = Vec::with_capacity(row_len);
for _ in 0..TILE_SIZE {
row.extend_from_slice(pixel);
}
for out in data.chunks_mut(row_len) {
out.copy_from_slice(&row);
}
}
Tile::from_vec(data)
}
fn from_vec(data: Vec<u8>) -> Self {
Tile { cell: spill::Cell::new(data) }
}
/// The tile's bytes (read back from the scratch disk if needed).
pub fn bytes(&self) -> TileBytes<'_> {
let guard = self.cell.read();
let placeholder = if guard.is_none() { vec![0; self.len()] } else { Vec::new() };
TileBytes(guard, placeholder)
}
pub fn bytes_mut(&mut self) -> TileBytesMut<'_> {
let guard = self.cell.write();
let placeholder = if guard.is_none() { vec![0; self.len()] } else { Vec::new() };
TileBytesMut(guard, placeholder)
}
/// `Err` while this tile's scratch copy is unreadable (its bytes read as a placeholder).
/// Free when no tile in the process has failed.
pub fn scratch_health(&self) -> Result<(), String> {
if !spill::any_failed() {
return Ok(());
}
self.cell.read_error().map_or(Ok(()), Err)
}
/// Fallible pixel access for callers that can propagate a scratch read failure.
pub fn try_bytes(&self) -> Result<TileBytes<'_>, String> {
let bytes = self.bytes();
match self.cell.read_error() {
Some(error) => Err(error),
None => Ok(bytes),
}
}
/// Tile-local half-open bounds `(x0, y0, x1, y1)` of the pixels that differ from the encoded
/// pixel `dp` (one pixel of the tile's format), or `None` when every pixel equals it (or `dp`
/// is empty).
pub fn content_bounds(&self, dp: &[u8]) -> Option<(u16, u16, u16, u16)> {
let bpp = dp.len();
if bpp == 0 {
return None;
}
let ts = TILE_SIZE as usize;
// A row of `dp`, compared block by block: an untouched row (most rows of a soft brush
// stroke's tiles) costs a few slice compares instead of one per pixel. A pixel differs
// where any of its bytes does, so the first and last differing bytes give the first and
// last differing pixels.
let blank = dp.repeat(ts);
let (mut x0, mut y0, mut x1, mut y1) = (usize::MAX, usize::MAX, 0usize, 0usize);
for (y, row) in self.bytes().chunks_exact(ts * bpp).enumerate() {
let Some(first) = first_difference(row, &blank) else { continue };
let Some(last) = last_difference(row, &blank) else { continue };
x0 = x0.min(first / bpp);
x1 = x1.max(last / bpp + 1);
y0 = y0.min(y);
y1 = y + 1;
}
(x0 != usize::MAX).then_some((x0 as u16, y0 as u16, x1 as u16, y1 as u16))
}
/// Byte length, without touching the pixels (they may be on disk).
pub fn len(&self) -> usize {
self.cell.len()
}
pub fn is_empty(&self) -> bool {
self.cell.len() == 0
}
}
impl Clone for Tile {
fn clone(&self) -> Self {
match self.try_bytes() {
Ok(bytes) => {
let mut data = scratch::take_exact(bytes.len(), 0u8);
data.copy_from_slice(&bytes);
Tile::from_vec(data)
}
// Preserve the original backing; the transaction will reject this poisoned tile.
Err(_) => Tile { cell: self.cell.clone() },
}
}
}
impl PartialEq for Tile {
fn eq(&self, other: &Self) -> bool {
Arc::ptr_eq(&self.cell, &other.cell) || (self.len() == other.len() && *self.bytes() == *other.bytes())
}
}
impl Eq for Tile {}
impl std::fmt::Debug for Tile {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Tile").field("len", &self.len()).finish_non_exhaustive()
}
}
/// Read guard over a tile's bytes; derefs to `[u8]`.
pub struct TileBytes<'a>(RwLockReadGuard<'a, Option<Vec<u8>>>, Vec<u8>);
impl Deref for TileBytes<'_> {
type Target = [u8];
fn deref(&self) -> &[u8] {
self.0.as_deref().unwrap_or(&self.1)
}
}
/// Write guard over a tile's bytes; derefs to `[u8]`.
pub struct TileBytesMut<'a>(RwLockWriteGuard<'a, Option<Vec<u8>>>, Vec<u8>);
impl Deref for TileBytesMut<'_> {
type Target = [u8];
fn deref(&self) -> &[u8] {
self.0.as_deref().unwrap_or(&self.1)
}
}
impl DerefMut for TileBytesMut<'_> {
fn deref_mut(&mut self) -> &mut [u8] {
self.0.as_deref_mut().unwrap_or(&mut self.1)
}
}
/// Bytes compared at once while looking for a difference in a tile row.
const DIFF_BLOCK: usize = 64;
/// Index of the first byte where `a` and `b` (the same length) differ.
fn first_difference(a: &[u8], b: &[u8]) -> Option<usize> {
let (k, (x, y)) = a.chunks(DIFF_BLOCK).zip(b.chunks(DIFF_BLOCK)).enumerate().find(|(_, (x, y))| x != y)?;
x.iter().zip(y).position(|(p, q)| p != q).map(|i| k * DIFF_BLOCK + i)
}
/// Index of the last byte where `a` and `b` (the same length) differ.
fn last_difference(a: &[u8], b: &[u8]) -> Option<usize> {
let (k, (x, y)) = a.chunks(DIFF_BLOCK).zip(b.chunks(DIFF_BLOCK)).enumerate().rfind(|(_, (x, y))| x != y)?;
x.iter().zip(y).rposition(|(p, q)| p != q).map(|i| k * DIFF_BLOCK + i)
}
/// Where [`Surface::prune_batch`] resumes: after the last tile it visited.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct PruneCursor {
after: Option<TileCoord>,
done: bool,
}
impl PruneCursor {
/// True once every tile has been visited.
pub fn is_done(&self) -> bool {
self.done
}
}
#[derive(Clone, Debug)]
pub struct Surface {
format: PixelFormat,
default_pixel: Box<[u8]>,
tiles: BTreeMap<TileCoord, Arc<Tile>>,
}
/// Use stack storage when it fits, otherwise reuse a dynamically sized sample buffer.
fn sample_buffer<'a>(channels: usize, stack: &'a mut [f32], heap: &'a mut Vec<f32>) -> &'a mut [f32] {
if let Some(samples) = stack.get_mut(..channels) {
samples
} else {
heap.resize(channels, 0.0);
heap
}
}
/// Tiles of one pixel value met while moving a surface ([`Surface::translated`]): each scanned
/// once, and one tile kept per value so the targets share it.
#[derive(Default)]
struct UniformTiles {
/// Per source tile (by address): the index of its value's tile in `canonical`, or `None`.
of: std::collections::HashMap<usize, Option<usize>>,
canonical: Vec<Arc<Tile>>,
}
impl UniformTiles {
/// The tile to share for a target reading window `r` of `s`, when every tile under it holds
/// one and the same pixel value (`r` must lie on existing tiles).
fn window(&self, s: &Surface, r: Rect) -> Option<Arc<Tile>> {
let mut found = None;
for c in r.tiles() {
let t = s.tiles.get(&c)?;
let k = (*self.of.get(&(Arc::as_ptr(t) as usize))?)?;
if found.is_some_and(|f| f != k) {
return None;
}
found = Some(k);
}
self.canonical.get(found?).cloned()
}
fn value_of(&mut self, t: &Arc<Tile>, bpp: usize) -> Option<usize> {
let key = Arc::as_ptr(t) as usize;
if let Some(k) = self.of.get(&key) {
return *k;
}
let bytes = t.try_bytes().ok()?;
let mut px = bytes.chunks_exact(bpp);
let k = px.next().filter(|p0| px.all(|p| p == *p0)).map(|p0| {
match self.canonical.iter().position(|c| c.try_bytes().is_ok_and(|bytes| bytes.get(..bpp) == Some(p0))) {
Some(k) => k,
None => {
self.canonical.push(t.clone());
self.canonical.len() - 1
}
}
});
self.of.insert(key, k);
k
}
}
impl PartialEq for Surface {
fn eq(&self, other: &Self) -> bool {
self.format == other.format && self.default_pixel == other.default_pixel && self.tiles == other.tiles
}
}
/// Converts the `data` span covering one tile into that tile's bytes.
fn write_tile(t: &mut Tile, tc: TileCoord, r: Rect, data: &[f32], w: usize, n: usize, sample: SampleType) {
let tr = tc.rect().intersect(&r);
// Convert contiguous channel samples a row at a time. Dispatching on depth here removes the
// per-pixel channel loop and lets the compiler vectorise conversion.
let span = tr.width() as usize * n;
let mut target = t.bytes_mut();
for y in tr.y0..tr.y1 {
let o = (((y - r.y0) as usize) * w + (tr.x0 - r.x0) as usize) * n;
let base = (((y - tc.ty * TILE_SIZE) as usize) * TILE_SIZE as usize + (tr.x0 - tc.tx * TILE_SIZE) as usize) * n;
let src = &data[o..o + span];
let bytes = sample.bytes();
let dst = &mut target[base * bytes..(base + span) * bytes];
match sample {
SampleType::U8 => {
for (d, v) in dst.iter_mut().zip(src) {
*d = (v.clamp(0.0, 1.0) * 255.0 + 0.5) as u8;
}
}
SampleType::U16 => {
for (d, v) in dst.as_chunks_mut::<2>().0.iter_mut().zip(src) {
let q = (v.clamp(0.0, 1.0) * 65535.0 + 0.5) as u16;
d.copy_from_slice(&q.to_ne_bytes());
}
}
SampleType::F32 => {
for (d, v) in dst.as_chunks_mut::<4>().0.iter_mut().zip(src) {
d.copy_from_slice(&v.to_ne_bytes());
}
}
}
}
}
/// Converts the tiles of a region write. A tile holds no state another tile reads, so the tiles
/// are converted on all cores; each writes only its own bytes, in the same arithmetic.
#[cfg(not(target_arch = "wasm32"))]
fn convert_tiles(tiles: &mut [(TileCoord, Arc<Tile>)], r: Rect, data: &[f32], w: usize, n: usize, sample: SampleType) {
use rayon::prelude::*;
tiles.par_iter_mut().for_each(|(tc, t)| write_tile(Arc::make_mut(t), *tc, r, data, w, n, sample));
}
/// Serial counterpart, for the web build (there are no threads to spread tiles over).
#[cfg(target_arch = "wasm32")]
fn convert_tiles(tiles: &mut [(TileCoord, Arc<Tile>)], r: Rect, data: &[f32], w: usize, n: usize, sample: SampleType) {
for (tc, t) in tiles.iter_mut() {
write_tile(Arc::make_mut(t), *tc, r, data, w, n, sample);
}
}
/// Copies the rows of `r` (interleaved `bytes`, `w` px wide, `bpp` bytes per pixel) into one
/// tile, first copying it fallibly when an undo snapshot still shares it.
fn copy_tile(tc: TileCoord, t: &mut Arc<Tile>, r: Rect, bytes: &[u8], w: usize, bpp: usize) -> Result<(), AllocationError> {
if Arc::get_mut(t).is_none() {
*t = Arc::new(t.try_clone()?);
}
let t = Arc::get_mut(t).ok_or(AllocationError::SizeOverflow)?;
let mut target = t.bytes_mut();
let tr = tc.rect().intersect(&r);
let span = tr.width() as usize * bpp;
for y in tr.y0..tr.y1 {
let src = (((y - r.y0) as usize) * w + (tr.x0 - r.x0) as usize) * bpp;
let dst = (((y - tc.ty * TILE_SIZE) as usize) * TILE_SIZE as usize + (tr.x0 - tc.tx * TILE_SIZE) as usize) * bpp;
let (Some(d), Some(s)) = (target.get_mut(dst..dst + span), bytes.get(src..src + span)) else { return Err(AllocationError::SizeOverflow) };
d.copy_from_slice(s);
}
Ok(())
}
/// The tiles of an interleaved write, on all cores: each writes only its own bytes.
#[cfg(not(target_arch = "wasm32"))]
fn copy_tiles(tiles: &mut [(TileCoord, Arc<Tile>)], r: Rect, bytes: &[u8], w: usize, bpp: usize) -> Result<(), AllocationError> {
use rayon::prelude::*;
tiles.par_iter_mut().try_for_each(|(tc, t)| copy_tile(*tc, t, r, bytes, w, bpp))
}
/// Serial counterpart, for the web build.
#[cfg(target_arch = "wasm32")]
fn copy_tiles(tiles: &mut [(TileCoord, Arc<Tile>)], r: Rect, bytes: &[u8], w: usize, bpp: usize) -> Result<(), AllocationError> {
tiles.iter_mut().try_for_each(|(tc, t)| copy_tile(*tc, t, r, bytes, w, bpp))
}
/// Fills one tile of [`Surface::try_write_rows_with`]: makes it writable, then calls `fill` for
/// each row of `r` inside it.
fn fill_tile<F, C, E>(slot: &mut (TileCoord, Option<Arc<Tile>>), r: Rect, format: &PixelFormat, default_pixel: &[u8], fill: &F, check: &C) -> Result<(), E>
where
F: Fn(i32, i32, &mut [u8]) + Sync,
C: Fn() -> Result<(), E> + Sync,
E: From<AllocationError> + Send,
{
check()?;
let (tc, tile) = slot;
match tile {
None => *tile = Some(Arc::new(Tile::try_filled(format, default_pixel)?)),
Some(t) => {
if Arc::get_mut(t).is_none() {
*t = Arc::new(t.try_clone()?);
}
}
}
let data = tile.as_mut().and_then(Arc::get_mut).ok_or(AllocationError::SizeOverflow)?;
let mut data = data.bytes_mut();
let bpp = format.bytes_per_pixel();
let tr = tc.rect().intersect(&r);
let span = tr.width() as usize * bpp;
for y in tr.y0..tr.y1 {
check()?;
let row = (y - tc.ty * TILE_SIZE) as usize * TILE_SIZE as usize + (tr.x0 - tc.tx * TILE_SIZE) as usize;
if let Some(dst) = row.checked_mul(bpp).and_then(|o| data.get_mut(o..o.checked_add(span)?)) {
fill(y, tr.x0, dst);
}
}
Ok(())
}
#[cfg(not(target_arch = "wasm32"))]
fn fill_tiles<F, C, E>(tiles: &mut [(TileCoord, Option<Arc<Tile>>)], r: Rect, format: &PixelFormat, default_pixel: &[u8], fill: &F, check: &C) -> Result<(), E>
where
F: Fn(i32, i32, &mut [u8]) + Sync,
C: Fn() -> Result<(), E> + Sync,
E: From<AllocationError> + Send,
{
use rayon::prelude::*;
tiles.par_iter_mut().try_for_each(|slot| fill_tile(slot, r, format, default_pixel, fill, check))
}
/// Serial counterpart, for the web build.
#[cfg(target_arch = "wasm32")]
fn fill_tiles<F, C, E>(tiles: &mut [(TileCoord, Option<Arc<Tile>>)], r: Rect, format: &PixelFormat, default_pixel: &[u8], fill: &F, check: &C) -> Result<(), E>
where
F: Fn(i32, i32, &mut [u8]) + Sync,
C: Fn() -> Result<(), E> + Sync,
E: From<AllocationError> + Send,
{
tiles.iter_mut().try_for_each(|slot| fill_tile(slot, r, format, default_pixel, fill, check))
}
fn decode_tile_row_rgba(fmt: &PixelFormat, t: &[u8], base: usize, dst: &mut [[f32; 4]], row: &mut Vec<f32>) {
let n = fmt.channels();
match (fmt.mode, fmt.sample, fmt.alpha) {
(ColorMode::Rgb, SampleType::U8, true) => {
let src = &t[base..base + dst.len() * 4];
for (d, s) in dst.iter_mut().zip(src.as_chunks::<4>().0) {
*d = [s[0] as f32 / 255.0, s[1] as f32 / 255.0, s[2] as f32 / 255.0, s[3] as f32 / 255.0];
}
}
(ColorMode::Grayscale, SampleType::U8, true) => {
let src = &t[base..base + dst.len() * 2];
for (d, s) in dst.iter_mut().zip(src.as_chunks::<2>().0) {
let g = s[0] as f32 / 255.0;
*d = [g, g, g, s[1] as f32 / 255.0];
}
}
(ColorMode::Rgb, SampleType::U16, true) => {
let byte_base = base * 2;
let src = &t[byte_base..byte_base + dst.len() * 8];
for (d, s) in dst.iter_mut().zip(src.as_chunks::<8>().0) {
*d = [
u16::from_ne_bytes([s[0], s[1]]) as f32 / 65535.0,
u16::from_ne_bytes([s[2], s[3]]) as f32 / 65535.0,
u16::from_ne_bytes([s[4], s[5]]) as f32 / 65535.0,
u16::from_ne_bytes([s[6], s[7]]) as f32 / 65535.0,
];
}
}
(ColorMode::Grayscale, SampleType::U16, true) => {
let byte_base = base * 2;
let src = &t[byte_base..byte_base + dst.len() * 4];
for (d, s) in dst.iter_mut().zip(src.as_chunks::<4>().0) {
let g = u16::from_ne_bytes([s[0], s[1]]) as f32 / 65535.0;
*d = [g, g, g, u16::from_ne_bytes([s[2], s[3]]) as f32 / 65535.0];
}
}
(ColorMode::Cmyk, SampleType::U8, _) => {
// Identical ink bytes share the exact ICC result; alpha is independent.
let mut previous: Option<([u8; 4], [f32; 3])> = None;
let src = &t[base..base + dst.len() * n];
for (d, s) in dst.iter_mut().zip(src.chunks_exact(n)) {
let ink = [s[0], s[1], s[2], s[3]];
let rgb = match previous {
Some((key, rgb)) if key == ink => rgb,
_ => {
let rgb = photocraft_color::convert::cmyk_to_rgb(ink.map(|v| v as f32 / 255.0));
previous = Some((ink, rgb));
rgb
}
};
*d = [rgb[0], rgb[1], rgb[2], s.get(4).map_or(1.0, |v| *v as f32 / 255.0)];
}
}
_ => {
// The row's samples in one pass, then its colour model resolved once:
// RGB and grey take their channels as `to_rgba` does, other models go
// through it.
row.resize(dst.len() * n, 0.0);
read_samples(t, fmt.sample, base, row);
let a = |s: &[f32], i: usize| if fmt.alpha { s[i] } else { 1.0 };
let pixels = dst.iter_mut().zip(row.chunks_exact(n));
match fmt.mode {
ColorMode::Rgb => pixels.for_each(|(d, s)| *d = [s[0], s[1], s[2], a(s, 3)]),
ColorMode::Grayscale | ColorMode::Bitmap | ColorMode::Duotone => pixels.for_each(|(d, s)| *d = [s[0], s[0], s[0], a(s, 1)]),
_ => pixels.for_each(|(d, s)| *d = to_rgba(fmt, s)),
}
}
}
}
impl Surface {
/// Reads a region into a newly allocated buffer, returning an error instead of aborting if
/// the requested pixel buffer cannot be represented or reserved.
pub fn try_read_region(&self, r: Rect) -> Result<Vec<f32>, AllocationError> {
let len = (r.width() as usize).checked_mul(r.height() as usize).and_then(|n| n.checked_mul(self.channels())).ok_or(AllocationError::SizeOverflow)?;
let bytes = len.checked_mul(std::mem::size_of::<f32>()).ok_or(AllocationError::SizeOverflow)?;
let mut out = scratch::try_take_exact(len, 0.0f32).ok_or(AllocationError::NotEnoughMemory { bytes })?;
let generation = spill::read_error_generation();
self.read_region_into(r, &mut out);
spill::check_since(generation).map_err(AllocationError::ScratchRead)?;
self.region_health(r).map_err(AllocationError::ScratchRead)?;
Ok(out)
}
/// `Err` if any stored tile of this surface is unreadable. Free when no tile in the
/// process has failed.
pub fn scratch_health(&self) -> Result<(), String> {
if !spill::any_failed() {
return Ok(());
}
self.tiles.values().try_for_each(|t| t.scratch_health())
}
/// [`Surface::scratch_health`] for the tiles overlapping `r` only.
pub fn region_health(&self, r: Rect) -> Result<(), String> {
if !spill::any_failed() {
return Ok(());
}
r.tiles().filter_map(|c| self.tiles.get(&c)).try_for_each(|t| t.scratch_health())
}
/// Reads a region as encoded interleaved bytes with fallible allocation.
pub fn try_to_interleaved(&self, r: Rect) -> Result<Vec<u8>, AllocationError> {
let bpp = self.format.bytes_per_pixel();
let len = (r.width() as usize).checked_mul(r.height() as usize).and_then(|n| n.checked_mul(bpp)).ok_or(AllocationError::SizeOverflow)?;
let mut out = Vec::new();
out.try_reserve_exact(len).map_err(|_| AllocationError::NotEnoughMemory { bytes: len })?;
out.resize(len, 0);
let w = r.width() as usize;
for tc in r.tiles() {
let tr = tc.rect().intersect(&r);
let span = tr.width() as usize * bpp;
for y in tr.y0..tr.y1 {
let dst = (((y - r.y0) as usize) * w + (tr.x0 - r.x0) as usize) * bpp;
match self.tiles.get(&tc) {
Some(t) => {
let src = (((y - tc.ty * TILE_SIZE) as usize) * TILE_SIZE as usize + (tr.x0 - tc.tx * TILE_SIZE) as usize) * bpp;
out[dst..dst + span].copy_from_slice(&t.try_bytes().map_err(AllocationError::ScratchRead)?[src..src + span]);
}
None => {
for px in out[dst..dst + span].chunks_exact_mut(bpp) {
px.copy_from_slice(&self.default_pixel);
}
}
}
}
}
Ok(out)
}
/// Transparent/zero surface.
pub fn new(format: PixelFormat) -> Self {
Self { format, default_pixel: vec![0u8; format.bytes_per_pixel()].into_boxed_slice(), tiles: BTreeMap::new() }
}
/// Surface whose untouched pixels read as `pixel` (normalised channel values).
pub fn with_default(format: PixelFormat, pixel: &[f32]) -> Self {
let mut s = Self::new(format);
encode_pixel(&format, pixel, &mut s.default_pixel);
s
}
pub fn format(&self) -> PixelFormat {
self.format
}
pub fn channels(&self) -> usize {
self.format.channels()
}
pub fn tile_count(&self) -> usize {
self.tiles.len()
}
pub fn tiles(&self) -> impl Iterator<Item = (&TileCoord, &Arc<Tile>)> {
self.tiles.iter()
}
pub fn tile(&self, c: TileCoord) -> Option<&Arc<Tile>> {
self.tiles.get(&c)
}
pub fn default_pixel(&self) -> Vec<f32> {
decode_pixel(&self.format, &self.default_pixel)
}
/// Decode the default pixel, using dynamic storage only when the stack buffer is too small.
fn default_samples<'a>(&self, stack: &'a mut [f32], heap: &'a mut Vec<f32>) -> &'a mut [f32] {
let px = sample_buffer(self.channels(), stack, heap);
for (i, v) in px.iter_mut().enumerate() {
*v = read_sample(&self.default_pixel, self.format.sample, i);
}
px
}
/// Mutable access to a tile, allocating it (filled with the default pixel) or un-sharing it.
pub fn tile_mut(&mut self, c: TileCoord) -> &mut Tile {
let fmt = self.format;
let dp = &self.default_pixel;
let arc = self.tiles.entry(c).or_insert_with(|| Arc::new(Tile::filled(&fmt, dp)));
Arc::make_mut(arc)
}
/// Fallible counterpart to [`Surface::tile_mut`]. Pixel storage is reserved before changing
/// the surface, and a shared tile is copied only after its replacement has been allocated.
pub fn try_tile_mut(&mut self, c: TileCoord) -> Result<&mut Tile, AllocationError> {
if let Some(tile) = self.tiles.get(&c) {
drop(tile.try_bytes().map_err(AllocationError::ScratchRead)?);
}
if !self.tiles.contains_key(&c) {
let tile = Arc::new(Tile::try_filled(&self.format, &self.default_pixel)?);
self.tiles.insert(c, tile);
} else if self.tiles.get_mut(&c).is_some_and(|t| Arc::get_mut(t).is_none()) {
let original = self.tiles.remove(&c).ok_or(AllocationError::SizeOverflow)?;
let tile = match Arc::try_unwrap(original) {
// Weak cache references must not force a pixel-buffer copy.
Ok(tile) => tile,
Err(original) => match original.try_clone() {
Ok(tile) => tile,
Err(error) => {
self.tiles.insert(c, original);
return Err(error);
}
},
};
self.tiles.insert(c, Arc::new(tile));
}
self.tiles.get_mut(&c).and_then(Arc::get_mut).ok_or(AllocationError::SizeOverflow)
}
/// Writes a region using fallible pixel-tile allocations. Callers that need transactional
/// document updates should perform this on their staged document copy and commit on success.
pub fn try_write_region(&mut self, r: Rect, data: &[f32]) -> Result<(), AllocationError> {
let n = self.channels();
let sample = self.format.sample;
let expected = (r.width() as usize).checked_mul(r.height() as usize).and_then(|v| v.checked_mul(n)).ok_or(AllocationError::SizeOverflow)?;
if data.len() != expected {
return Err(AllocationError::SizeOverflow);
}
for tc in r.tiles() {
let tr = tc.rect().intersect(&r);
let t = self.try_tile_mut(tc)?;
let mut target = t.bytes_mut();
let span = tr.width() as usize * n;
for y in tr.y0..tr.y1 {
let src = (((y - r.y0) as usize) * r.width() as usize + (tr.x0 - r.x0) as usize) * n;
let dst = (((y - tc.ty * TILE_SIZE) as usize) * TILE_SIZE as usize + (tr.x0 - tc.tx * TILE_SIZE) as usize) * n;
for (i, v) in data[src..src + span].iter().enumerate() {
write_sample(&mut target, sample, dst + i, *v);
}
}
}
Ok(())
}
/// Tile rects that differ between `self` and `other`: tiles present in only one, or holding
/// a different (copied-on-write) tile. Compares pointers, never pixels, so it is cheap and
/// never reads spilled tiles back. `None` when the format or default pixel differ (every
/// pixel may read differently).
pub fn changed_rect(&self, other: &Surface) -> Option<Rect> {
if self.format != other.format || self.default_pixel != other.default_pixel {
return None;
}
let mut r = Rect::EMPTY;
for (c, t) in &self.tiles {
if other.tiles.get(c).is_none_or(|o| !Arc::ptr_eq(t, o)) {
r = r.union(&c.rect());
}
}
for c in other.tiles.keys() {
if !self.tiles.contains_key(c) {
r = r.union(&c.rect());
}
}
Some(r)
}
/// Coarse bounds: union of allocated tile rects.
pub fn tile_bounds(&self) -> Rect {
self.tiles.keys().fold(Rect::EMPTY, |r, c| r.union(&c.rect()))
}
/// Exact bounds of pixels that differ from the default pixel.
pub fn content_bounds(&self) -> Rect {
if self.tiles.is_empty() {
return Rect::EMPTY;
}
// Scan tiles from the outside of the tile grid inwards; a tile lying entirely inside the
// bounds found so far cannot extend them and is skipped (so a full-canvas selection scans
// roughly its outer ring of tiles instead of every pixel).
let (mut gx0, mut gy0, mut gx1, mut gy1) = (i32::MAX, i32::MAX, i32::MIN, i32::MIN);
for c in self.tiles.keys() {
(gx0, gy0, gx1, gy1) = (gx0.min(c.tx), gy0.min(c.ty), gx1.max(c.tx), gy1.max(c.ty));
}
let mut order: Vec<(&TileCoord, &Arc<Tile>)> = self.tiles.iter().collect();
order.sort_by_key(|(c, _)| (c.tx - gx0).min(gx1 - c.tx).min(c.ty - gy0).min(gy1 - c.ty));
let mut out = Rect::EMPTY;
for (c, t) in order {
let origin = c.rect();
if !out.is_empty() && out.contains_rect(&origin) {
continue;
}
if let Some((x0, y0, x1, y1)) = t.content_bounds(&self.default_pixel) {
out = out.union(&Rect::new(x0.into(), y0.into(), x1.into(), y1.into()).translate(origin.x0, origin.y0));
}
}
out
}
/// Makes every tile that holds one pixel value throughout share the interner's tile for that
/// value: a white background, an opaque mask or a solid fill then costs one tile however
/// large it is, and across every surface that shares `interner`. Tiles are copy-on-write, so
/// editing one splits it off again. Returns the bytes no longer held by this surface alone.
pub fn share_uniform_tiles(&mut self, interner: &mut TileInterner) -> usize {
let bpp = self.format.bytes_per_pixel();
let mut saved = 0;
for t in self.tiles.values_mut() {
let Ok(bytes) = t.try_bytes() else { continue };
let mut px = bytes.chunks_exact(bpp);
let Some(p0) = px.next() else { continue };
if !px.all(|p| p == p0) {
continue;
}
let p0 = p0.to_vec();
drop(bytes);
let shared = interner.tiles.entry(t.len()).or_default().entry(p0).or_insert_with(|| t.clone());
if !Arc::ptr_eq(shared, t) {
saved += t.len();
*t = shared.clone();
}
}
saved
}
/// Drop tiles that are entirely the default pixel.
pub fn prune(&mut self) {
let dp = self.default_pixel.as_ref();
let bpp = dp.len();
self.tiles.retain(|_, t| t.bytes().chunks_exact(bpp).any(|px| px != dp));
}
/// A [`PruneCursor`] for [`Surface::prune_batch`], which drops the same tiles as [`Surface::prune`]
/// a batch at a time (for a caller that must not block: the web build has no threads).
pub fn prune_cursor(&self) -> PruneCursor {
PruneCursor::default()
}
/// Drops the tiles that are entirely the default pixel, visiting at most `max` tiles in
/// coordinate order and resuming after them on the next call; returns true when every tile
/// has been visited (and so [`Surface::prune`] has nothing left to drop). A `max` of zero
/// visits one tile. The scan reads the live tile map from the cursor on: a tile inserted at or
/// before the last visited coordinate is not visited, one inserted after it is (and dropped
/// when it holds only the default pixel, which reads the same as an absent tile).
pub fn prune_batch(&mut self, cursor: &mut PruneCursor, max: usize) -> bool {
if cursor.done {
return true;
}
let dp = self.default_pixel.as_ref();
let bpp = dp.len();
let max = max.max(1);
let keys: Vec<TileCoord> = match cursor.after {
None => self.tiles.keys().take(max).copied().collect(),
Some(after) => self.tiles.range((Bound::Excluded(after), Bound::Unbounded)).take(max).map(|(c, _)| *c).collect(),
};
for c in &keys {
if self.tiles.get(c).is_some_and(|t| !t.bytes().chunks_exact(bpp).any(|px| px != dp)) {
self.tiles.remove(c);
}
}
let Some(last) = keys.last().copied() else {
cursor.done = true;
return true;
};
cursor.after = Some(last);
cursor.done = keys.len() < max || self.tiles.range((Bound::Excluded(last), Bound::Unbounded)).next().is_none();
cursor.done
}
#[inline]
fn locate(&self, x: i32, y: i32) -> (TileCoord, usize) {
let c = TileCoord::containing(x, y);
let lx = x.rem_euclid(TILE_SIZE) as usize;
let ly = y.rem_euclid(TILE_SIZE) as usize;
(c, (ly * TILE_SIZE as usize + lx) * self.format.channels())
}
/// Read one pixel as normalised channel values (`channels()` floats).
pub fn pixel(&self, x: i32, y: i32) -> Vec<f32> {
let mut out = vec![0.0; self.channels()];
self.read_pixel(x, y, &mut out);
out
}
pub fn read_pixel(&self, x: i32, y: i32, out: &mut [f32]) {
let (c, base) = self.locate(x, y);
let n = self.channels();
match self.tiles.get(&c) {
Some(t) => {
let data = t.bytes();
for (i, o) in out.iter_mut().enumerate().take(n) {
*o = read_sample(&data, self.format.sample, base + i);
}
}
None => {
for (i, o) in out.iter_mut().enumerate().take(n) {
*o = read_sample(&self.default_pixel, self.format.sample, i);
}
}
}
}
pub fn write_pixel(&mut self, x: i32, y: i32, px: &[f32]) {
let (c, base) = self.locate(x, y);
let n = self.channels();
let sample = self.format.sample;
let mut t = self.tile_mut(c).bytes_mut();
for (i, v) in px.iter().enumerate().take(n) {
write_sample(&mut t, sample, base + i, *v);
}
}
/// One channel of one pixel, without allocating.
#[inline]
pub fn sample_channel(&self, x: i32, y: i32, c: usize) -> f32 {
let (tc, base) = self.locate(x, y);
match self.tiles.get(&tc) {
Some(t) => read_sample(&t.bytes(), self.format.sample, base + c),
None => read_sample(&self.default_pixel, self.format.sample, c),
}
}
/// Channel `c` at `(x0 + i·step, y)` for `i in 0..out.len()`, looking each tile up once per run
/// (much faster than per-sample [`Surface::sample_channel`] for strided scans).
/// Steps below 1 read consecutive pixels; positions beyond `i32::MAX` read the default pixel.
pub fn sample_row_strided(&self, y: i32, x0: i32, step: i32, c: usize, out: &mut [f32]) {
let step = i64::from(step.max(1));
let dp = read_sample(&self.default_pixel, self.format.sample, c);
let n = self.format.channels();
let ty = y.div_euclid(TILE_SIZE);
let ly = y.rem_euclid(TILE_SIZE) as usize;
let mut i = 0;
let mut x = i64::from(x0);
while i < out.len() {
if x > i64::from(i32::MAX) {
out[i..].fill(dp);
break;
}
let tx = x.div_euclid(i64::from(TILE_SIZE));
// Samples that fall in this tile.
let tile_end = (tx + 1) * i64::from(TILE_SIZE);
let count = (((tile_end - x) + step - 1) / step).max(1) as usize;
let count = count.min(out.len() - i);
let end = i + count;
match self.tiles.get(&TileCoord { tx: tx as i32, ty }) {
None => out[i..end].fill(dp),
Some(t) => {
let data = t.bytes();
for (k, o) in out[i..end].iter_mut().enumerate() {
let lx = (x + k as i64 * step - tx * i64::from(TILE_SIZE)) as usize;
*o = read_sample(&data, self.format.sample, (ly * TILE_SIZE as usize + lx) * n + c);
}
}
}
i = end;
x += count as i64 * step;
}
}
/// [`Surface::read_region`] into a reusable buffer (resized to fit).
pub fn read_region_into(&self, r: Rect, out: &mut Vec<f32>) {
let n = self.channels();
let w = r.width() as usize;
out.clear();
out.resize(w * r.height() as usize * n, 0.0);
self.read_samples_into(r, out);
}
/// Copy samples into a zero-initialized buffer sized for `r`.
fn read_samples_into(&self, r: Rect, out: &mut [f32]) {
let n = self.channels();
let w = r.width() as usize;
let mut stack = [0.0; 8];
let mut heap = Vec::new();
let dp = self.default_samples(&mut stack, &mut heap);
let zero = self.default_pixel.iter().all(|&b| b == 0);
for tc in r.tiles() {
let tr = tc.rect().intersect(&r);
let guard = self.tiles.get(&tc).map(|t| t.bytes());
if guard.is_none() && zero {
continue;
}
let tile = guard.as_deref();
for y in tr.y0..tr.y1 {
let o = (((y - r.y0) as usize) * w + (tr.x0 - r.x0) as usize) * n;
let span = tr.width() as usize * n;
let Some(dst) = out.get_mut(o..o + span) else { continue };
match tile {
Some(t) => {
let base = (((y - tc.ty * TILE_SIZE) as usize) * TILE_SIZE as usize + (tr.x0 - tc.tx * TILE_SIZE) as usize) * n;
read_samples(t, self.format.sample, base, dst);
}
None if n == 1 => dst.fill(dp[0]),
None => {
for px in dst.chunks_exact_mut(n) {
px.copy_from_slice(dp);
}
}
}
}
}
}
/// Reads `r` as straight RGBA floats (converting from the surface's
/// model) into `out` (`w*h` entries), without per-pixel allocation.
/// Fast paths for RGB(A) and gray(A) at 8/16/32 bits read tile bytes
/// directly; missing tiles are filled with the default pixel.
pub fn read_rgba_into(&self, r: Rect, out: &mut [[f32; 4]]) {
let w = r.width() as usize;
debug_assert_eq!(out.len(), w * r.height() as usize);
let fmt = self.format;
let n = fmt.channels();
let mut stack = [0.0; 8];
let mut heap = Vec::new();
let dp = to_rgba(&fmt, self.default_samples(&mut stack, &mut heap));
let mut row = Vec::new();
for tc in r.tiles() {
let tr = tc.rect().intersect(&r);
let guard = self.tiles.get(&tc).map(|t| t.bytes());
let tile = guard.as_deref();
for y in tr.y0..tr.y1 {
let o = ((y - r.y0) as usize) * w + (tr.x0 - r.x0) as usize;
let dst = &mut out[o..o + tr.width() as usize];
let Some(t) = tile else {
dst.fill(dp);
continue;
};
let base = (((y - tc.ty * TILE_SIZE) as usize) * TILE_SIZE as usize + (tr.x0 - tc.tx * TILE_SIZE) as usize) * n;
decode_tile_row_rgba(&fmt, t, base, dst, &mut row);
}
}
}
/// Reads `r` as straight 8-bit RGBA into `out` (`w*h` entries). RGBA8 surfaces copy tile bytes
/// directly; other formats convert while holding the same tile read guard.
pub fn read_rgba8_into(&self, r: Rect, out: &mut [[u8; 4]]) {
let w = r.width() as usize;
debug_assert_eq!(out.len(), w * r.height() as usize);
let fmt = self.format;
let rgba8 = matches!((fmt.mode, fmt.sample, fmt.alpha), (ColorMode::Rgb, SampleType::U8, true));
let q = |v: f32| (v.clamp(0.0, 1.0) * 255.0 + 0.5) as u8;
let mut stack = [0.0; 8];
let mut heap = Vec::new();
let dp = to_rgba(&fmt, self.default_samples(&mut stack, &mut heap));
let dp8 = [q(dp[0]), q(dp[1]), q(dp[2]), q(dp[3])];
let mut px = [0.0f32; 8];
for tc in r.tiles() {
let tr = tc.rect().intersect(&r);
let guard = self.tiles.get(&tc).map(|t| t.bytes());
let tile = guard.as_deref();
for y in tr.y0..tr.y1 {
let o = ((y - r.y0) as usize) * w + (tr.x0 - r.x0) as usize;
let dst = &mut out[o..o + tr.width() as usize];
match tile {
None => dst.fill(dp8),
Some(t) if rgba8 => {
let base = (((y - tc.ty * TILE_SIZE) as usize) * TILE_SIZE as usize + (tr.x0 - tc.tx * TILE_SIZE) as usize) * 4;
let len = dst.len();
for (d, s) in dst.iter_mut().zip(t[base..base + len * 4].as_chunks::<4>().0) {
*d = [s[0], s[1], s[2], s[3]];
}
}
Some(t) => {
// A second read lock could deadlock behind an eviction writer.
let n = fmt.channels();
let base = (((y - tc.ty * TILE_SIZE) as usize) * TILE_SIZE as usize + (tr.x0 - tc.tx * TILE_SIZE) as usize) * n;
for (i, d) in dst.iter_mut().enumerate() {
for (c, v) in px.iter_mut().enumerate().take(n) {
*v = read_sample(t, fmt.sample, base + i * n + c);
}
let p = to_rgba(&fmt, &px[..n]);
*d = [q(p[0]), q(p[1]), q(p[2]), q(p[3])];
}
}
}
}
}
}
/// `true` if any allocated tile intersects `r` (else `r` reads as the
/// default pixel everywhere).
pub fn has_tiles_in(&self, r: Rect) -> bool {
r.tiles().any(|tc| self.tiles.contains_key(&tc))
}
/// Read a rectangle as interleaved normalised floats (`w*h*channels`).
pub fn read_region(&self, r: Rect) -> Vec<f32> {
let n = self.channels();
let w = r.width() as usize;
let mut out = scratch::take(w * r.height() as usize * n, 0.0f32);
self.read_samples_into(r, &mut out);
out
}
/// Write interleaved normalised floats into a rectangle, on the calling thread.
///
/// This never enters Rayon, so it is safe inside a `OnceLock` initializer or any other
/// section that must not run another Rayon job on its stack. [`Surface::write_region_par`]
/// writes the same bytes on all cores.
pub fn write_region(&mut self, r: Rect, data: &[f32]) {
let n = self.channels();
let w = r.width() as usize;
assert_eq!(data.len(), w * r.height() as usize * n, "region data length mismatch");
let sample = self.format.sample;
for tc in r.tiles() {
write_tile(self.tile_mut(tc), tc, r, data, w, n, sample);
}
}
/// [`Surface::write_region`] with the tiles converted on all cores (serially on the web).
///
/// This enters Rayon: while it waits for its tiles, the calling worker may run any other
/// queued Rayon job. Callers inside a `OnceLock` initializer or another section that must
/// not do that use [`Surface::write_region`].
pub fn write_region_par(&mut self, r: Rect, data: &[f32]) {
let n = self.channels();
let w = r.width() as usize;
assert_eq!(data.len(), w * r.height() as usize * n, "region data length mismatch");
let sample = self.format.sample;
// The tiles are disjoint, so converting them in any order (and on any thread) writes
// exactly the same bytes. `take_tiles` gives the missing tiles as one shared
// default-filled tile, copied per tile by `Arc::make_mut` in `convert_tiles`.
let mut tiles = self.take_tiles(r);
convert_tiles(&mut tiles, r, data, w, n, sample);
self.put_tiles(tiles);
}
/// Take the tiles covering `r` out of the surface (missing ones filled with the default
/// pixel), so they can be edited elsewhere, e.g. in parallel: `Arc::unwrap_or_clone` copies a
/// tile only if an undo snapshot still shares it. Give them back with [`Surface::put_tiles`].
pub fn take_tiles(&mut self, r: Rect) -> Vec<(TileCoord, Arc<Tile>)> {
let fmt = self.format;
let mut blank: Option<Arc<Tile>> = None;
r.tiles()
.map(|c| {
let t = self.tiles.remove(&c).unwrap_or_else(|| blank.get_or_insert_with(|| Arc::new(Tile::filled(&fmt, &self.default_pixel))).clone());
(c, t)
})
.collect()
}
/// Fallible counterpart to [`Surface::take_tiles`]. Reserves the complete result and any
/// default tile before removing a tile, so a reservation failure leaves the surface intact.
pub fn try_take_tiles(&mut self, r: Rect) -> Result<Vec<(TileCoord, Arc<Tile>)>, AllocationError> {
// Counted in u64 and checked before narrowing: on 32-bit targets the grid of a sparse
// surface's bounds can pass `usize` (and visiting it to count it takes just as long).
let count = usize::try_from(r.tile_count()).map_err(|_| AllocationError::SizeOverflow)?;
let bytes = count.checked_mul(std::mem::size_of::<(TileCoord, Arc<Tile>)>()).ok_or(AllocationError::SizeOverflow)?;
let mut out = Vec::new();
out.try_reserve_exact(count).map_err(|_| AllocationError::NotEnoughMemory { bytes })?;
let has_missing = r.tiles().any(|c| !self.tiles.contains_key(&c));
let blank = if has_missing { Some(Arc::new(Tile::try_filled(&self.format, &self.default_pixel)?)) } else { None };
for c in r.tiles() {
let tile = self.tiles.remove(&c).or_else(|| blank.clone());
if let Some(tile) = tile {
out.push((c, tile));
}
}
Ok(out)
}
/// Put tiles back (see [`Surface::take_tiles`]); each replaces the tile at its coordinate.
pub fn put_tiles(&mut self, tiles: impl IntoIterator<Item = (TileCoord, Arc<Tile>)>) {
for (c, t) in tiles {
self.tiles.insert(c, t);
}
}
/// A tile filled with the default pixel (what a missing tile reads as), allocated fallibly.
pub fn try_default_tile(&self) -> Result<Tile, AllocationError> {
Tile::try_filled(&self.format, &self.default_pixel)
}
/// A tile of this surface's format filled with `px` (normalised channel values). Sharing one
/// across many coordinates fills them without copying (tiles are copy-on-write).
pub fn solid_tile(&self, px: &[f32]) -> Arc<Tile> {
let mut enc = vec![0u8; self.format.bytes_per_pixel()];
encode_pixel(&self.format, px, &mut enc);
Arc::new(Tile::filled(&self.format, &enc))
}
/// The default pixel's encoded bytes.
pub fn default_bytes(&self) -> &[u8] {
&self.default_pixel
}
/// Fill a rectangle with one pixel value.
pub fn fill_rect(&mut self, r: Rect, px: &[f32]) {
let n = self.channels();
let mut enc = vec![0u8; self.format.bytes_per_pixel()];
encode_pixel(&self.format, &px[..n], &mut enc);
let bpp = enc.len();
// Fully covered tiles share one Arc: a solid fill costs one tile however large `r` is,
// and copy-on-write splits a tile off when it is edited (#705).
let mut full: Option<Arc<Tile>> = None;
for tc in r.tiles() {
let tr = tc.rect().intersect(&r);
if tr == tc.rect() {
let fmt = self.format;
let t = full.get_or_insert_with(|| Arc::new(Tile::filled(&fmt, &enc)));
self.tiles.insert(tc, t.clone());
continue;
}
let mut t = self.tile_mut(tc).bytes_mut();
for y in tr.y0..tr.y1 {
let ly = (y - tc.ty * TILE_SIZE) as usize;
let lx0 = (tr.x0 - tc.tx * TILE_SIZE) as usize;
let lx1 = (tr.x1 - tc.tx * TILE_SIZE) as usize;
let row = &mut t[(ly * TILE_SIZE as usize + lx0) * bpp..(ly * TILE_SIZE as usize + lx1) * bpp];
for p in row.chunks_exact_mut(bpp) {
p.copy_from_slice(&enc);
}
}
}
}
/// Build from interleaved *encoded* bytes of `format` covering `r`.
pub fn from_interleaved(format: PixelFormat, r: Rect, bytes: &[u8]) -> Self {
let mut s = Surface::new(format);
s.write_interleaved(r, bytes);
s
}
/// Write interleaved encoded bytes (same format as the surface) into `r`.
pub fn write_interleaved(&mut self, r: Rect, bytes: &[u8]) {
let bpp = self.format.bytes_per_pixel();
let w = r.width() as usize;
assert_eq!(bytes.len(), w * r.height() as usize * bpp, "interleaved length mismatch");
for tc in r.tiles() {
let tr = tc.rect().intersect(&r);
let mut t = self.tile_mut(tc).bytes_mut();
let span = tr.width() as usize * bpp;
for y in tr.y0..tr.y1 {
let src = (((y - r.y0) as usize) * w + (tr.x0 - r.x0) as usize) * bpp;
let dst = (((y - tc.ty * TILE_SIZE) as usize) * TILE_SIZE as usize + (tr.x0 - tc.tx * TILE_SIZE) as usize) * bpp;
t[dst..dst + span].copy_from_slice(&bytes[src..src + span]);
}
}
}
/// Fallible counterpart to [`Surface::write_interleaved`], writing the tiles on all cores
/// (native targets): a length that doesn't match `r` is [`AllocationError::LengthMismatch`],
/// not a panic, and a tile that can't be allocated stops the write with
/// [`AllocationError::NotEnoughMemory`] (the tiles written so far keep their new pixels).
///
/// This enters Rayon, as [`Surface::write_region_par`] does.
pub fn try_write_interleaved(&mut self, r: Rect, bytes: &[u8]) -> Result<(), AllocationError> {
let bpp = self.format.bytes_per_pixel();
let w = r.width() as usize;
let expected = w.checked_mul(r.height() as usize).and_then(|v| v.checked_mul(bpp)).ok_or(AllocationError::SizeOverflow)?;
if bytes.len() != expected {
return Err(AllocationError::LengthMismatch { expected, got: bytes.len() });
}
let mut tiles = self.try_take_tiles(r)?;
let written = copy_tiles(&mut tiles, r, bytes, w, bpp);
self.put_tiles(tiles);
written
}
/// Fills `r` row by row, straight into the tiles: `fill(y, x0, dst)` writes the pixels of row
/// `y` from column `x0` into `dst`, the tile's bytes for that span (`dst.len()` is a whole
/// number of pixels in the surface's format). Lets a caller convert from its own buffer
/// without staging a copy of the region first.
///
/// Tiles are filled on all cores (serially on the web), so `fill` must not depend on call
/// order. Missing tiles start as the default pixel; existing tiles are copied fallibly so
/// the surface is unchanged if preparation fails. An empty `r` writes nothing.
///
/// Like [`Surface::write_region_par`] this enters Rayon, so don't call it from a `OnceLock`
/// initializer.
pub fn try_write_rows_with<F>(&mut self, r: Rect, fill: F) -> Result<(), AllocationError>
where
F: Fn(i32, i32, &mut [u8]) + Sync,
{
self.try_prepare_rows(r, |tiles, format, default_pixel| fill_tiles(tiles, r, format, default_pixel, &fill, &|| Ok(())))
}
/// Interruptible row write. Cancellation or allocation failure leaves the surface unchanged.
/// Checks run before each tile and row; already running callbacks may finish after cancellation.
pub fn try_write_rows_with_interrupt<F>(&mut self, r: Rect, ctl: &Interrupt, fill: F) -> Result<(), RowWriteError>
where
F: Fn(i32, i32, &mut [u8]) + Sync,
{
self.try_prepare_rows(r, |tiles, format, default_pixel| {
fill_tiles(tiles, r, format, default_pixel, &fill, &|| ctl.check().map_err(RowWriteError::Cancelled))
})
}
fn try_prepare_rows<F, E>(&mut self, r: Rect, prepare: F) -> Result<(), E>
where
F: FnOnce(&mut [(TileCoord, Option<Arc<Tile>>)], &PixelFormat, &[u8]) -> Result<(), E>,
E: From<AllocationError>,
{
if r.is_empty() {
return Ok(());
}
let count = usize::try_from(r.tile_count()).map_err(|_| AllocationError::SizeOverflow)?;
let bytes = count.checked_mul(std::mem::size_of::<(TileCoord, Option<Arc<Tile>>)>()).ok_or(AllocationError::SizeOverflow)?;
let mut tiles: Vec<(TileCoord, Option<Arc<Tile>>)> = Vec::new();
tiles.try_reserve_exact(count).map_err(|_| AllocationError::NotEnoughMemory { bytes })?;
tiles.extend(r.tiles().map(|c| (c, self.tiles.get(&c).cloned())));
prepare(&mut tiles, &self.format, &self.default_pixel)?;
for (c, tile) in tiles {
if let Some(tile) = tile {
if let Some(existing) = self.tiles.get_mut(&c) {
*existing = tile;
} else {
self.tiles.insert(c, tile);
}
}
}
Ok(())
}
/// Read `r` as interleaved encoded bytes in the surface's format.
pub fn to_interleaved(&self, r: Rect) -> Vec<u8> {
let bpp = self.format.bytes_per_pixel();
let w = r.width() as usize;
let mut out = scratch::take(w * r.height() as usize * bpp, 0u8);
for tc in r.tiles() {
let tr = tc.rect().intersect(&r);
let span = tr.width() as usize * bpp;
for y in tr.y0..tr.y1 {
let dst = (((y - r.y0) as usize) * w + (tr.x0 - r.x0) as usize) * bpp;
match self.tiles.get(&tc).map(|t| t.bytes()) {
Some(t) => {
let src = (((y - tc.ty * TILE_SIZE) as usize) * TILE_SIZE as usize + (tr.x0 - tc.tx * TILE_SIZE) as usize) * bpp;
out[dst..dst + span].copy_from_slice(&t[src..src + span]);
}
None => {
for p in out[dst..dst + span].chunks_exact_mut(bpp) {
p.copy_from_slice(&self.default_pixel);
}
}
}
}
}
out
}
/// The surface moved by whole pixels: its encoded samples copied tile to tile (no float
/// round trip, no intermediate buffer); moves by whole tiles share the tiles themselves, and
/// a target tile read entirely from tiles of one single pixel value shares one such tile (the
/// inside of a solid fill stays one copy-on-write tile however often it moves). A tile it
/// copies that ends up holding only the default pixel isn't stored.
/// `content` must hold every pixel that isn't the default one (`content_bounds`, say): only
/// tiles it reaches are kept.
pub fn translated(&self, dx: i32, dy: i32, content: Rect) -> Surface {
let mut out = Surface { format: self.format, default_pixel: self.default_pixel.clone(), tiles: BTreeMap::new() };
let sources = || self.tiles.iter().filter(move |(c, _)| !c.rect().intersect(&content).is_empty());
if dx % TILE_SIZE == 0 && dy % TILE_SIZE == 0 {
let (tx, ty) = (dx / TILE_SIZE, dy / TILE_SIZE);
out.tiles = sources().map(|(c, t)| (TileCoord::new(c.tx.saturating_add(tx), c.ty.saturating_add(ty)), t.clone())).collect();
return out;
}
let mut builder = shift::ShiftBuilder::new(self, dx, dy, content);
for (_, t) in sources() {
builder.scan(t);
}
let targets = builder.targets(self);
let build_target = |dc: TileCoord| builder.build(self, dc);
#[cfg(not(target_arch = "wasm32"))]
{
use rayon::prelude::*;
out.tiles = targets.into_par_iter().filter_map(build_target).collect();
}
#[cfg(target_arch = "wasm32")]
{
out.tiles = targets.into_iter().filter_map(build_target).collect();
}
out
}
/// Applies `f` to every colour sample (not alpha), including the default pixel: a tone-curve
/// change such as linearising when a document becomes 32-bit.
pub fn map_color(&mut self, f: impl Fn(f32) -> f32) {
let format = self.format;
let color = format.mode.color_channels();
let n = format.channels();
let mut dp = decode_pixel(&format, &self.default_pixel);
for v in dp.iter_mut().take(color) {
*v = f(*v);
}
encode_pixel(&format, &dp, &mut self.default_pixel);
let coords: Vec<TileCoord> = self.tiles.keys().copied().collect();
let px_count = (TILE_SIZE * TILE_SIZE) as usize;
// A tile shared by several coordinates (a filled background) is mapped once and stays
// shared (#4531). Keys are the original tiles, all alive until their coordinates are
// reached, so a freed address can't be mistaken for another original.
let mut done: std::collections::HashMap<*const Tile, Arc<Tile>> = std::collections::HashMap::new();
for c in coords {
let Some(key) = self.tiles.get(&c).map(Arc::as_ptr) else { continue };
if let Some(mapped) = done.get(&key) {
self.tiles.insert(c, mapped.clone());
continue;
}
let tile = self.tile_mut(c);
let mut bytes = tile.bytes_mut();
for i in 0..px_count {
for k in 0..color {
let at = i * n + k;
let v = read_sample(&bytes, format.sample, at);
write_sample(&mut bytes, format.sample, at, f(v));
}
}
drop(bytes);
if let Some(mapped) = self.tiles.get(&c) {
done.insert(key, mapped.clone());
}
}
}
/// Convert to another pixel format (depth and/or model; colour models via [`convert_pixel`]).
pub fn convert(&self, to: PixelFormat) -> Surface {
let mut out = Surface::with_default(to, &convert_pixel(&self.format, &to, &self.default_pixel()));
let from_n = self.channels();
let mut src = vec![0.0f32; from_n];
// Each distinct tile converts once; coordinates sharing it share the result (#4531).
let mut done: std::collections::HashMap<*const Tile, Arc<Tile>> = std::collections::HashMap::new();
for (c, t) in &self.tiles {
if let Some(converted) = done.get(&Arc::as_ptr(t)) {
out.tiles.insert(*c, converted.clone());
continue;
}
let source = t.bytes();
let mut dst = out.tile_mut(*c).bytes_mut();
let px_count = (TILE_SIZE * TILE_SIZE) as usize;
for i in 0..px_count {
for (k, v) in src.iter_mut().enumerate() {
*v = read_sample(&source, self.format.sample, i * from_n + k);
}
let px = convert_pixel(&self.format, &to, &src);
for (k, v) in px.iter().enumerate() {
write_sample(&mut dst, to.sample, i * to.channels() + k, *v);
}
}
drop(dst);
if let Some(converted) = out.tiles.get(c) {
done.insert(Arc::as_ptr(t), converted.clone());
}
}
out
}
/// Convert a surface while reserving each replacement tile fallibly.
pub fn try_convert(&self, to: PixelFormat) -> Result<Surface, AllocationError> {
let mut out = Surface::with_default(to, &convert_pixel(&self.format, &to, &self.default_pixel()));
let from_n = self.channels();
let mut src = Vec::new();
src.try_reserve_exact(from_n).map_err(|_| AllocationError::NotEnoughMemory { bytes: from_n * std::mem::size_of::<f32>() })?;
src.resize(from_n, 0.0f32);
let mut done: std::collections::HashMap<*const Tile, Arc<Tile>> = std::collections::HashMap::new();
for (c, t) in &self.tiles {
if let Some(converted) = done.get(&Arc::as_ptr(t)) {
out.tiles.insert(*c, converted.clone());
continue;
}
let dst = out.try_tile_mut(*c)?;
let source_bytes = t.try_bytes().map_err(AllocationError::ScratchRead)?;
let mut dest_bytes = dst.bytes_mut();
let px_count = (TILE_SIZE * TILE_SIZE) as usize;
for i in 0..px_count {
for (k, v) in src.iter_mut().enumerate() {
*v = read_sample(&source_bytes, self.format.sample, i * from_n + k);
}
let px = convert_pixel(&self.format, &to, &src);
for (k, v) in px.iter().enumerate() {
write_sample(&mut dest_bytes, to.sample, i * to.channels() + k, *v);
}
}
drop(dest_bytes);
if let Some(converted) = out.tiles.get(c) {
done.insert(Arc::as_ptr(t), converted.clone());
}
}
Ok(out)
}
/// Composite-friendly RGBA read (converts from the surface's model).
pub fn rgba(&self, x: i32, y: i32) -> [f32; 4] {
let mut p = [0.0f32; 5];
self.read_pixel(x, y, &mut p);
to_rgba(&self.format, &p)
}
}
/// Encode normalised floats into one pixel's bytes.
pub fn encode_pixel(format: &PixelFormat, px: &[f32], out: &mut [u8]) {
for (i, v) in px.iter().enumerate().take(format.channels()) {
write_sample(out, format.sample, i, *v);
}
}
pub fn decode_pixel(format: &PixelFormat, bytes: &[u8]) -> Vec<f32> {
(0..format.channels()).map(|i| read_sample(bytes, format.sample, i)).collect()
}
/// Convert one pixel between formats via sRGB RGBA (CMYK through the built-in CMYK profile;
/// the engine's mode conversions use the document's profiles instead).
pub fn convert_pixel(from: &PixelFormat, to: &PixelFormat, px: &[f32]) -> Vec<f32> {
if from.mode == to.mode {
let n = from.mode.color_channels();
let mut out: Vec<f32> = px[..n].to_vec();
if to.alpha {
out.push(if from.alpha { px[n] } else { 1.0 });
}
return out;
}
let rgba = to_rgba(from, px);
from_rgba(to, rgba)
}
pub fn to_rgba(format: &PixelFormat, px: &[f32]) -> [f32; 4] {
let n = format.mode.color_channels();
let a = if format.alpha { px[n] } else { 1.0 };
let rgb = match format.mode {
ColorMode::Grayscale | ColorMode::Bitmap | ColorMode::Duotone => [px[0]; 3],
ColorMode::Cmyk => photocraft_color::convert::cmyk_to_rgb([px[0], px[1], px[2], px[3]]),
ColorMode::Lab => photocraft_color::convert::lab_to_srgb([px[0] * 100.0, px[1] * 255.0 - 128.0, px[2] * 255.0 - 128.0]),
_ => [px[0], px[1], px[2]],
};
[rgb[0], rgb[1], rgb[2], a]
}
pub fn from_rgba(format: &PixelFormat, rgba: [f32; 4]) -> Vec<f32> {
let rgb = [rgba[0], rgba[1], rgba[2]];
let mut out: Vec<f32> = match format.mode {
ColorMode::Grayscale | ColorMode::Bitmap | ColorMode::Duotone => vec![photocraft_color::convert::rgb_to_gray(rgb)],
ColorMode::Cmyk => photocraft_color::convert::rgb_to_cmyk(rgb).to_vec(),
ColorMode::Lab => {
let l = photocraft_color::convert::srgb_to_lab(rgb);
vec![l[0] / 100.0, (l[1] + 128.0) / 255.0, (l[2] + 128.0) / 255.0]
}
_ => rgb.to_vec(),
};
if format.alpha {
out.push(rgba[3]);
}
out
}
/// [`from_rgba`] without allocating: writes `format.channels()` values into
/// `out` and returns how many were written.
#[inline]
pub fn from_rgba_into(format: &PixelFormat, rgba: [f32; 4], out: &mut [f32]) -> usize {
let rgb = [rgba[0], rgba[1], rgba[2]];
let n = match format.mode {
ColorMode::Grayscale | ColorMode::Bitmap | ColorMode::Duotone => {
out[0] = photocraft_color::convert::rgb_to_gray(rgb);
1
}
ColorMode::Cmyk => {
out[..4].copy_from_slice(&photocraft_color::convert::rgb_to_cmyk(rgb));
4
}
ColorMode::Lab => {
let l = photocraft_color::convert::srgb_to_lab(rgb);
out[..3].copy_from_slice(&[l[0] / 100.0, (l[1] + 128.0) / 255.0, (l[2] + 128.0) / 255.0]);
3
}
_ => {
out[..3].copy_from_slice(&rgb);
3
}
};
if format.alpha {
out[n] = rgba[3];
n + 1
} else {
n
}
}
/// A simple owned RGBA8 image, used for display and thumbnails.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Rgba8Image {
pub width: u32,
pub height: u32,
pub pixels: Vec<u8>,
}
impl Rgba8Image {
pub fn new(width: u32, height: u32) -> Self {
Self { width, height, pixels: vec![0; width as usize * height as usize * 4] }
}
}
/// Is this sample type able to hold values above 1.0 (HDR)?
pub fn is_hdr(sample: SampleType) -> bool {
matches!(sample, SampleType::F32)
}
#[cfg(test)]
mod tests;
#[cfg(test)]
mod echelon_case {
use super::*;
#[test]
fn sparse_missing_tiles_read_the_default_after_a_shift() {
let mut s = Surface::with_default(PixelFormat::GRAY8, &[1.0]);
s.fill_rect(Rect::new(0, 0, 10, 10), &[0.0]);
s.fill_rect(Rect::new(600, 0, 610, 10), &[0.0]);
let t = s.translated(5, 0, Rect::new(0, 0, 768, 256));
assert_eq!(t.pixel(305, 20), vec![1.0]);
}
/// The rewrite must not change output: the misaligned path is compared against a
/// straightforward reference gather (read each pixel, write it shifted) over randomized
/// formats, default pixels, sparse tiles and shifts that cross tile boundaries.
#[test]
fn randomized_shifts_match_a_reference_gather() {
let mut rng: u64 = 0x1234_5678_9abc_def0;
let mut next = move || {
rng ^= rng << 13;
rng ^= rng >> 7;
rng ^= rng << 17;
rng
};
for case in 0..200u32 {
let fmt = [PixelFormat::RGBA8, PixelFormat::RGBA16, PixelFormat::RGBA32F, PixelFormat::GRAY8, PixelFormat::GRAYA8][(next() % 5) as usize];
let def: Vec<f32> = (0..fmt.channels()).map(|i| if case % 3 == 0 { 0.0 } else { ((i + case as usize) % 7) as f32 / 6.0 }).collect();
let mut s = Surface::with_default(fmt, &def);
// Sparse content: a few small patches at random positions.
for _ in 0..(1 + next() % 4) {
let x = (next() % 1600) as i32 - 800;
let y = (next() % 1200) as i32 - 600;
let w = 1 + (next() % 90) as i32;
let h = 1 + (next() % 70) as i32;
let v: Vec<f32> = (0..fmt.channels()).map(|i| ((i as u64 + next()) % 251) as f32 / 250.0).collect();
s.fill_rect(Rect::new(x, y, x + w, y + h), &v);
}
let content = Rect::new(-900, -700, 1700, 1300);
let (dx, dy) = ((next() % 1200) as i32 - 600, (next() % 900) as i32 - 450);
let t = s.translated(dx, dy, content);
// Reference: every pixel of the moved extent reads the source at (x-dx, y-dy),
// inside the content, through the surface's default-aware reader.
for _ in 0..64 {
let x = (next() % 1500) as i32 - 750 + dx;
let y = (next() % 1100) as i32 - 550 + dy;
if !content.translate(dx, dy).contains(x, y) {
continue;
}
let want = if content.contains(x - dx, y - dy) { s.pixel(x - dx, y - dy) } else { s.default_pixel() };
let got = t.pixel(x, y);
assert_eq!(got, want, "case {case} fmt {fmt:?} shift ({dx},{dy}) at ({x},{y})");
}
}
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.