d84914ef1e5a
commit.rs
//! Committing a stroke: premultiplied "over" (paint) or scale-down (erase) of the stroke alpha
//! into a layer's channels or a mask's paint effect. Only touched tiles are un-shared, so the
//! previous state stays intact in undo snapshots. A [`Staging`] does most of that work while
//! the stroke is drawn, so the commit itself is quick even at 8K.
use std::collections::{BTreeMap, BTreeSet, HashMap};
use std::sync::Arc;
use rayon::prelude::*;
use texturecraft_compose::PixelStore;
use texturecraft_core::{Channel, ChannelKind, LayerId};
use texturecraft_texel::{TILE, TILE_AREA, TileData, TileImage, from_u16, from_u16_signed, to_u16, to_u16_signed};
pub(crate) fn dec(kind: ChannelKind, v: u16) -> f32 {
if kind == ChannelKind::Signed { from_u16_signed(v) } else { from_u16(v) }
}
pub(crate) fn enc(kind: ChannelKind, v: f32) -> u16 {
if kind == ChannelKind::Signed { to_u16_signed(v) } else { to_u16(v) }
}
/// What one image receives: its channel kind, the painted value (unused when erasing or for
/// coverage images), whether a stencil's color replaces it (base color) and the values a clone
/// or smudge stroke carries for it.
struct Blend<'a> {
kind: ChannelKind,
value: &'a [f32],
stencil_color: bool,
carried: Option<&'a TileImage>,
}
/// Blend `alpha × opacity` into one image of `n` value components plus coverage. With a
/// per-texel source, its alpha factor scales the stroke and, when `stencil_color`, its color
/// replaces `value`; `carried` (clone, smudge) replaces `value` per texel. `staged` holds the
/// destination tiles prepared while the stroke was drawn.
fn over(img: &mut TileImage, b: &Blend, src: &CommitSource, mut staged: Option<StagedImage>) {
let comps = img.comps();
let empty = empty_texel(b.kind, comps);
let key = BlendKey::new(b, src);
// Tiles blend independently: build each new tile in parallel, then swap them in. The old
// tile data stays shared with undo snapshots.
let image = &*img;
let tiles: Vec<_> = src.tiles.iter().map(|&t| (t, staged.as_mut().and_then(|s| s.take(image, src.alpha, &key, &empty, t)))).collect();
let updated: Vec<((u32, u32), Vec<u16>)> = tiles
.into_par_iter()
.filter_map(|((tx, ty), staged)| {
let a = src.alpha.tile(tx, ty)?;
if let Some((data, true)) = staged {
return Some(((tx, ty), data));
}
if src.erase && !image.is_allocated(tx, ty) {
return None;
}
let carried = match b.carried.map(|c| c.tile(tx, ty)) {
Some(None) => return None,
Some(Some(t)) => Some(t),
None => None,
};
let mut dst = match (staged, image.tile(tx, ty)) {
(Some((d, _)), _) => d,
(None, Some(t)) => t.to_vec(),
(None, None) => empty.repeat(TILE_AREA),
};
blend_tile(&mut dst, comps, a, (tx, ty), b, src, carried);
Some(((tx, ty), dst))
})
.collect();
for ((tx, ty), data) in updated {
img.set_tile(tx, ty, Some(Arc::new(data)));
}
}
/// Blend the stroke's alpha tile `a` into tile `(tx, ty)` of an image (`dst`, `comps` per texel).
fn blend_tile(dst: &mut [u16], comps: usize, a: &[u16], (tx, ty): (u32, u32), b: &Blend, src: &CommitSource, carried: Option<&[u16]>) {
let n = comps.saturating_sub(1);
let opacity = src.opacity.clamp(0.0, 1.0);
for i in 0..TILE_AREA {
let mut m = from_u16(a.get(i).copied().unwrap_or(0)) * opacity;
if m <= 0.0 {
continue;
}
let mut color = None;
if let Some(f) = src.per_texel {
let (x, y) = (tx * TILE + i as u32 % TILE, ty * TILE + i as u32 / TILE);
match f(x, y) {
Some((c, af)) => {
m *= af;
color = Some(c);
}
None => continue,
}
if m <= 0.0 {
continue;
}
}
let Some(px) = dst.get_mut(i * comps..(i + 1) * comps) else { continue };
let cov = from_u16(px[n]);
for k in 0..n {
let p = dec(b.kind, px[k]);
let target = match (carried, color) {
(Some(t), _) => dec(b.kind, t.get(i * n + k).copied().unwrap_or(0)),
(None, Some(c)) if b.stencil_color => c.get(k).copied().unwrap_or(0.0),
_ => b.value.get(k).copied().unwrap_or(0.0),
};
let v = if src.erase { p * (1.0 - m) } else { target * m + p * (1.0 - m) };
px[k] = enc(b.kind, v);
}
px[n] = to_u16(if src.erase { cov * (1.0 - m) } else { m + cov * (1.0 - m) });
}
}
/// One empty texel of an image with `comps` components: zero coverage and a zero value (32768
/// in signed encoding). New tiles start as this.
fn empty_texel(kind: ChannelKind, comps: usize) -> Vec<u16> {
let mut t = vec![enc(kind, 0.0); comps.saturating_sub(1)];
t.push(0);
t
}
/// `dst` as a copy of tile `from` (None: an empty tile of `empty` texels), reusing its memory.
fn fill_from(dst: &mut Vec<u16>, from: Option<&[u16]>, empty: &[u16]) {
dst.clear();
match from {
Some(t) => dst.extend_from_slice(t),
None => {
for _ in 0..TILE_AREA {
dst.extend_from_slice(empty);
}
}
}
}
/// What a pre-blended tile was blended with, besides the stroke alpha.
#[derive(Clone, Debug, PartialEq)]
struct BlendKey {
value: Vec<f32>,
opacity: f32,
erase: bool,
}
impl BlendKey {
fn new(b: &Blend, src: &CommitSource) -> BlendKey {
BlendKey { value: b.value.to_vec(), opacity: src.opacity, erase: src.erase }
}
}
/// One destination tile prepared while the stroke is drawn.
#[derive(Debug)]
struct StagedTile {
/// The layer tile it was copied from (None: the layer had no tile there).
from: Option<TileData>,
/// The stroke alpha tile it is blended with (None: a plain copy of `from`).
alpha: Option<TileData>,
data: Vec<u16>,
}
/// The staged tiles of one image and what pre-blended ones were blended with.
#[derive(Debug, Default)]
struct StagedImage {
key: Option<BlendKey>,
tiles: HashMap<(u32, u32), StagedTile>,
}
impl StagedImage {
/// The staged tile `t` for a commit with `key` and the stroke `alpha`, when it still
/// matches `image` (the document can change while a stroke is drawn, e.g. through an
/// agent's command): `(data, true)` when it is final, `(copy of the image tile, false)`
/// when it still needs blending.
fn take(&mut self, image: &TileImage, alpha: &TileImage, key: &BlendKey, empty: &[u16], t: (u32, u32)) -> Option<(Vec<u16>, bool)> {
let mut e = self.tiles.remove(&t)?;
let current = image.tile_handle(t.0, t.1);
let same = |a: Option<&TileData>, b: Option<&TileData>| match (a, b) {
(None, None) => true,
(Some(a), Some(b)) => Arc::ptr_eq(a, b),
_ => false,
};
if !same(e.from.as_ref(), current) || e.data.len() != TILE_AREA * image.comps() {
return None;
}
if e.alpha.is_some() && self.key.as_ref() == Some(key) && same(e.alpha.as_ref(), alpha.tile_handle(t.0, t.1)) {
return Some((e.data, true));
}
if e.alpha.is_some() {
// Blended with an older stroke alpha: back to the layer tile.
fill_from(&mut e.data, e.from.as_deref().map(Vec::as_slice), empty);
}
Some((e.data, false))
}
/// Prepare the tiles `src.tiles` of `img` (re-blending those staged before): a copy of the
/// image tile, blended with the stroke when it has no per-texel source or carried values
/// (those blend at the commit).
fn stage(&mut self, img: Option<&TileImage>, comps: usize, b: &Blend, src: &CommitSource) {
let key = BlendKey::new(b, src);
if self.key.as_ref() != Some(&key) {
// The stroke's settings changed: earlier blends are void.
self.tiles.clear();
self.key = Some(key);
}
let blend = src.per_texel.is_none() && b.carried.is_none();
let empty = empty_texel(b.kind, comps);
let todo: Vec<((u32, u32), Option<StagedTile>)> = src.tiles.iter().map(|t| (*t, self.tiles.remove(t))).collect();
let staged: Vec<((u32, u32), StagedTile)> = todo
.into_par_iter()
.filter_map(|((tx, ty), old)| {
let from = img.and_then(|i| i.tile_handle(tx, ty));
// Erasing never allocates a tile.
if from.is_none() && src.erase {
return None;
}
let mut data = old.map(|o| o.data).unwrap_or_default();
fill_from(&mut data, from.map(|f| f.as_slice()), &empty);
let alpha = src.alpha.tile_handle(tx, ty).filter(|_| blend).cloned();
if let Some(a) = &alpha {
blend_tile(&mut data, comps, a, (tx, ty), b, src, None);
}
Some(((tx, ty), StagedTile { from: from.cloned(), alpha, data }))
})
.collect();
self.tiles.extend(staged);
}
}
/// Destination tiles prepared while a stroke is drawn, so the commit only swaps them in. At 8K
/// a commit of 1300 tiles of five channels spends ~45 ms on fresh memory alone; staged as the
/// stroke reaches the tiles (and re-blended when it passes again) it costs a few milliseconds.
#[derive(Debug, Default)]
pub struct Staging {
/// By layer channel (None: a mask paint effect).
images: BTreeMap<Option<Channel>, StagedImage>,
}
impl Staging {
/// Prepare tiles `src.tiles` of every image a [`commit_layer`] of `layer` with the same
/// arguments will write (call after the stroke alpha of those tiles changed).
pub fn stage_layer(&mut self, pixels: &PixelStore, layer: LayerId, values: &BTreeMap<Channel, [f32; 3]>, src: &CommitSource) {
for c in commit_channels(pixels, layer, values, src.erase) {
let b = layer_blend(c, values, src);
self.images.entry(Some(c)).or_default().stage(pixels.layer(layer, c), c.components() + 1, &b, src);
}
}
/// Prepare tiles `src.tiles` of the mask paint effect a [`commit_mask`] of `effect` with
/// the same arguments will write.
pub fn stage_mask(&mut self, pixels: &PixelStore, effect: LayerId, value: f32, src: &CommitSource) {
let value = [value.clamp(0.0, 1.0)];
let b = Blend { kind: ChannelKind::Scalar, value: &value, stencil_color: false, carried: src.carried_mask };
self.images.entry(None).or_default().stage(pixels.masks.get(&effect), 2, &b, src);
}
fn take(&mut self, key: Option<Channel>) -> Option<StagedImage> {
self.images.remove(&key)
}
}
/// The channels a layer commit writes: the painted ones, or every painted channel of the layer
/// when erasing (only those in `values` when it is not empty).
fn commit_channels(pixels: &PixelStore, layer: LayerId, values: &BTreeMap<Channel, [f32; 3]>, erase: bool) -> Vec<Channel> {
if erase {
let painted: BTreeSet<Channel> = pixels.layers.keys().filter(|(id, _)| *id == layer).map(|(_, c)| *c).collect();
painted.into_iter().filter(|c| values.is_empty() || values.contains_key(c)).collect()
} else {
values.keys().copied().collect()
}
}
/// How channel `c` of a layer commit blends.
fn layer_blend<'a>(c: Channel, values: &'a BTreeMap<Channel, [f32; 3]>, src: &CommitSource<'a>) -> Blend<'a> {
static ZERO: [f32; 3] = [0.0; 3];
let value = values.get(&c).map_or(&ZERO[..], |v| &v[..]);
Blend {
kind: c.kind(),
value: value.get(..c.components()).unwrap_or(value),
stencil_color: c == Channel::BaseColor,
carried: src.carried.and_then(|m| m.get(&c)),
}
}
/// Per-texel override of a stroke: `(x, y)` → (base color, alpha factor), None = no paint.
pub type TexelFn<'a> = &'a (dyn Fn(u32, u32) -> Option<([f32; 3], f32)> + Sync);
/// The stroke being committed: its alpha, touched tiles, opacity cap and mode.
#[derive(Clone, Copy)]
pub struct CommitSource<'a> {
pub alpha: &'a TileImage,
pub tiles: &'a BTreeSet<(u32, u32)>,
pub opacity: f32,
pub erase: bool,
/// Projection tool: base color and alpha per texel from a stencil.
pub per_texel: Option<TexelFn<'a>>,
/// Clone and smudge: straight values per channel carried by the stroke (replace `values`).
pub carried: Option<&'a BTreeMap<Channel, TileImage>>,
/// Scalar values sampled from a mask by clone or smudge.
pub carried_mask: Option<&'a TileImage>,
}
/// Commit a stroke into paint layer `layer` (channels in `values`; erase clears every painted
/// channel of the layer, or only those in `values` when it is not empty). `staging` holds the
/// tiles prepared while the stroke was drawn (empty for one-shot fills).
pub fn commit_layer(pixels: &mut PixelStore, layer: LayerId, size: (u32, u32), values: &BTreeMap<Channel, [f32; 3]>, src: CommitSource, staging: &mut Staging) {
let channels = commit_channels(pixels, layer, values, src.erase);
for &c in &channels {
pixels.layer_mut(layer, c, size);
}
// The channels blend in parallel too: an 8K stroke touches hundreds of tiles per channel
let images: Vec<(Channel, &mut TileImage, Option<StagedImage>)> =
pixels.layers.iter_mut().filter(|((id, c), _)| *id == layer && channels.contains(c)).map(|((_, c), img)| (*c, img, staging.take(Some(*c)))).collect();
images.into_par_iter().for_each(|(c, img, staged)| over(img, &layer_blend(c, values, &src), &src, staged));
}
/// Commit a stroke into the paint effect `effect` of a mask, painting gray `value`.
pub fn commit_mask(pixels: &mut PixelStore, effect: LayerId, size: (u32, u32), value: f32, src: CommitSource, staging: &mut Staging) {
let img = pixels.mask_mut(effect, size);
let value = [value.clamp(0.0, 1.0)];
over(img, &Blend { kind: ChannelKind::Scalar, value: &value, stencil_color: false, carried: src.carried_mask }, &src, staging.take(None));
}
/// Commit a stroke into a coverage-only image (1 component), e.g. the quick mask.
pub fn commit_coverage(img: &mut TileImage, src: CommitSource) {
over(img, &Blend { kind: ChannelKind::Scalar, value: &[], stencil_color: false, carried: None }, &src, None);
}
#[cfg(test)]
mod tests {
use super::*;
fn src<'a>(alpha: &'a TileImage, tiles: &'a BTreeSet<(u32, u32)>, opacity: f32, erase: bool) -> CommitSource<'a> {
CommitSource { alpha, tiles, opacity, erase, per_texel: None, carried: None, carried_mask: None }
}
fn alpha(v: f32) -> (TileImage, BTreeSet<(u32, u32)>) {
let mut a = TileImage::new(64, 64, 1);
a.set(5, 5, &[to_u16(v)]);
(a, [(0, 0)].into_iter().collect())
}
#[test]
fn paint_then_paint_then_erase_is_premultiplied_over() {
let mut px = PixelStore::default();
let id = LayerId(1);
let vals: BTreeMap<Channel, [f32; 3]> = [(Channel::Roughness, [0.8; 3])].into_iter().collect();
let (a, tiles) = alpha(0.5);
commit_layer(&mut px, id, (64, 64), &vals, src(&a, &tiles, 1.0, false), &mut Staging::default());
let t = px.layer(id, Channel::Roughness).unwrap().get(5, 5);
assert!((from_u16(t[0]) - 0.4).abs() < 1e-3, "premul v·a");
assert!((from_u16(t[1]) - 0.5).abs() < 1e-3, "coverage a");
commit_layer(&mut px, id, (64, 64), &vals, src(&a, &tiles, 1.0, false), &mut Staging::default());
let t = px.layer(id, Channel::Roughness).unwrap().get(5, 5);
assert!((from_u16(t[1]) - 0.75).abs() < 1e-3);
assert!((from_u16(t[0]) - 0.6).abs() < 1e-3);
commit_layer(&mut px, id, (64, 64), &BTreeMap::new(), src(&a, &tiles, 1.0, true), &mut Staging::default());
let t = px.layer(id, Channel::Roughness).unwrap().get(5, 5);
assert!((from_u16(t[1]) - 0.375).abs() < 1e-3);
assert!((from_u16(t[0]) - 0.3).abs() < 1e-3);
}
#[test]
fn signed_height_and_stroke_opacity() {
let mut px = PixelStore::default();
let id = LayerId(2);
let vals: BTreeMap<Channel, [f32; 3]> = [(Channel::Height, [-0.5; 3])].into_iter().collect();
let (a, tiles) = alpha(1.0);
commit_layer(&mut px, id, (64, 64), &vals, src(&a, &tiles, 0.5, false), &mut Staging::default());
let t = px.layer(id, Channel::Height).unwrap().get(5, 5);
assert!((from_u16_signed(t[0]) + 0.25).abs() < 1e-3);
assert!((from_u16(t[1]) - 0.5).abs() < 1e-3);
}
#[test]
fn mask_commit_and_untouched_tiles_stay_shared() {
let mut px = PixelStore::default();
let (a, tiles) = alpha(1.0);
commit_mask(&mut px, LayerId(9), (64, 64), 1.0, src(&a, &tiles, 1.0, false), &mut Staging::default());
let before = px.clone();
commit_mask(&mut px, LayerId(9), (64, 64), 0.0, src(&a, &tiles, 1.0, true), &mut Staging::default());
assert_eq!(from_u16(before.masks[&LayerId(9)].get(5, 5)[1]), 1.0);
assert_eq!(px.masks[&LayerId(9)].get(5, 5)[1], 0);
}
#[test]
fn carried_values_replace_the_tool_value_and_coverage_images_work() {
let mut px = PixelStore::default();
let (a, tiles) = alpha(1.0);
let mut carried = TileImage::new(64, 64, 1);
carried.set(5, 5, &[to_u16(0.25)]);
let carried: BTreeMap<Channel, TileImage> = [(Channel::Roughness, carried)].into_iter().collect();
let vals: BTreeMap<Channel, [f32; 3]> = [(Channel::Roughness, [0.8; 3])].into_iter().collect();
commit_layer(&mut px, LayerId(3), (64, 64), &vals, CommitSource { carried: Some(&carried), ..src(&a, &tiles, 1.0, false) }, &mut Staging::default());
assert!((from_u16(px.layer(LayerId(3), Channel::Roughness).unwrap().get(5, 5)[0]) - 0.25).abs() < 1e-3);
let mut cov = TileImage::new(64, 64, 1);
commit_coverage(&mut cov, src(&a, &tiles, 0.5, false));
assert!((from_u16(cov.get(5, 5)[0]) - 0.5).abs() < 1e-3);
}
fn source<'a>(a: &'a TileImage, tiles: &'a BTreeSet<(u32, u32)>, carried: Option<&'a BTreeMap<Channel, TileImage>>, erase: bool) -> CommitSource<'a> {
CommitSource { carried, ..src(a, tiles, 0.8, erase) }
}
#[test]
fn layer_roughness_does_not_override_mask_coverage() {
let (alpha, tiles) = alpha(1.0);
let mut roughness = TileImage::new(64, 64, 1);
roughness.set(5, 5, &[to_u16(0.25)]);
let carried = [(Channel::Roughness, roughness)].into();
let source = CommitSource { carried: Some(&carried), ..src(&alpha, &tiles, 1.0, false) };
let mut pixels = PixelStore::default();
commit_mask(&mut pixels, LayerId(1), (64, 64), 1.0, source, &mut Staging::default());
assert_eq!(pixels.masks[&LayerId(1)].get(5, 5)[0], u16::MAX);
}
#[test]
fn staged_commits_match_and_stale_copies_are_ignored() {
let vals: BTreeMap<Channel, [f32; 3]> = [(Channel::BaseColor, [0.2, 0.4, 0.6]), (Channel::Height, [-0.5; 3])].into_iter().collect();
let (a, tiles) = alpha(0.7);
let mut base = PixelStore::default();
commit_layer(&mut base, LayerId(1), (64, 64), &vals, src(&a, &tiles, 1.0, false), &mut Staging::default());
commit_mask(&mut base, LayerId(2), (64, 64), 0.5, src(&a, &tiles, 1.0, false), &mut Staging::default());
let carried: BTreeMap<Channel, TileImage> = vals.keys().map(|c| (*c, a.clone())).collect();
// Staged when the stroke started, then again after the alpha changed (pre-blended
// tiles re-blend), and staged once more with its last alpha change left out (that
// tile blends at the commit): the commit matches an unstaged one.
for (erase, carry, stage_last) in [(false, false, true), (true, false, true), (false, false, false), (false, true, true)] {
let mut a = a.clone();
let mut staged = base.clone();
let mut staging = Staging::default();
let c = carry.then_some(&carried);
staging.stage_layer(&staged, LayerId(1), &vals, &source(&a, &tiles, c, erase));
staging.stage_mask(&staged, LayerId(2), 1.0, &source(&a, &tiles, c, erase));
a.set(7, 9, &[to_u16(0.3)]);
staging.stage_layer(&staged, LayerId(1), &vals, &source(&a, &tiles, c, erase));
staging.stage_mask(&staged, LayerId(2), 1.0, &source(&a, &tiles, c, erase));
a.set(8, 9, &[to_u16(0.9)]);
if stage_last {
staging.stage_layer(&staged, LayerId(1), &vals, &source(&a, &tiles, c, erase));
staging.stage_mask(&staged, LayerId(2), 1.0, &source(&a, &tiles, c, erase));
}
let mut plain = base.clone();
commit_layer(&mut plain, LayerId(1), (64, 64), &vals, source(&a, &tiles, c, erase), &mut Staging::default());
commit_mask(&mut plain, LayerId(2), (64, 64), 1.0, source(&a, &tiles, c, erase), &mut Staging::default());
commit_layer(&mut staged, LayerId(1), (64, 64), &vals, source(&a, &tiles, c, erase), &mut staging);
commit_mask(&mut staged, LayerId(2), (64, 64), 1.0, source(&a, &tiles, c, erase), &mut staging);
assert_eq!((&staged.layers, &staged.masks), (&plain.layers, &plain.masks), "erase {erase}, carried {carry}, staged last {stage_last}");
}
// Tiles staged before the layer changed or with another value are stale: the commit
// reads the current tile.
let mut px = base.clone();
let mut staging = Staging::default();
staging.stage_layer(&px, LayerId(1), &vals, &src(&a, &tiles, 1.0, false));
staging.stage_mask(&px, LayerId(2), 0.25, &src(&a, &tiles, 1.0, false));
commit_layer(&mut px, LayerId(1), (64, 64), &vals, src(&a, &tiles, 1.0, false), &mut Staging::default());
let mut expected = px.clone();
commit_layer(&mut expected, LayerId(1), (64, 64), &vals, src(&a, &tiles, 1.0, false), &mut Staging::default());
commit_mask(&mut expected, LayerId(2), (64, 64), 1.0, src(&a, &tiles, 1.0, false), &mut Staging::default());
commit_layer(&mut px, LayerId(1), (64, 64), &vals, src(&a, &tiles, 1.0, false), &mut staging);
commit_mask(&mut px, LayerId(2), (64, 64), 1.0, src(&a, &tiles, 1.0, false), &mut staging);
assert_eq!((&px.layers, &px.masks), (&expected.layers, &expected.masks));
}
}
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.