856f865cf98d
paint_thread.rs
//! Live strokes paint on a thread of their own, so a heavy brush never holds up the frame: the
//! canvas hands the new pen points over, waits a little for them (`LIVE_STROKE_WAIT`), and shows
//! the newest step the stroke has painted. While the thread is behind, points that arrive meanwhile
//! are painted together as one step, and the cursor, panels and pen input keep their frame rate.
//!
//! Each step is the stroke's own copy of the document, as when it painted on the UI thread, so the
//! canvas shows and refreshes it the same way (`LiveStroke::since`).
use std::sync::{Arc, Condvar, Mutex, MutexGuard, PoisonError};
use std::thread::JoinHandle;
use std::time::Duration;
use web_time::Instant;
use photocraft_engine::paint::StrokePoint;
use photocraft_geom::Rect;
use super::strokes::EngineStroke;
/// What painting one batch of points gave: the rectangle it changed, or why it failed.
pub(super) type Step = photocraft_engine::Result<Rect>;
/// The stroke as last painted, for the canvas to show.
#[derive(Clone)]
pub(super) struct Shown {
pub(super) doc: Arc<photocraft_doc::Document>,
/// See `EngineStroke::wants_time`.
pub(super) wants_time: bool,
/// The Brush's smoothing string (`photocraft_engine::brush_cmds::LiveStroke::smoothing_string`).
pub(super) smoothing_string: Option<([f64; 2], [f64; 2])>,
}
impl Shown {
fn of(stroke: &EngineStroke) -> Self {
let smoothing_string = match stroke {
EngineStroke::Brush(l) => l.smoothing_string(),
_ => None,
};
Self { doc: stroke.doc().clone(), wants_time: stroke.wants_time(), smoothing_string }
}
}
struct State {
/// Points handed over that the stroke hasn't painted yet.
pending: Vec<StrokePoint>,
/// The stroke, while nothing is painting with it.
stroke: Option<EngineStroke>,
/// Steps painted since the canvas last took them, and what the last one shows.
steps: Vec<Step>,
shown: Shown,
/// A step failed: later points are dropped and `shown` stays the last good step, as when the
/// canvas stopped feeding the stroke after its error.
failed: bool,
/// The canvas let go of the stroke: the thread ends.
closed: bool,
/// Tests: the thread holds a step it took until this is cleared (see `PaintThread::hold`).
#[cfg(test)]
held: bool,
/// Tests: the next step panics (see `PaintThread::panic_next_step`).
#[cfg(test)]
panic_next: bool,
}
impl State {
fn idle(&self) -> bool {
self.stroke.is_some() && self.pending.is_empty()
}
}
struct Shared {
state: Mutex<State>,
changed: Condvar,
}
impl Shared {
fn lock(&self) -> MutexGuard<'_, State> {
self.state.lock().unwrap_or_else(PoisonError::into_inner)
}
/// Paint the pending points, if the stroke is free.
fn paint_pending(&self) {
let (pts, stroke) = {
let mut st = self.lock();
if st.pending.is_empty() {
return;
}
let Some(stroke) = st.stroke.take() else { return };
(std::mem::take(&mut st.pending), stroke)
};
#[cfg(test)]
self.test_hooks();
let mut stroke = stroke;
let step = stroke.push(&pts);
let mut st = self.lock();
if step.is_ok() {
st.shown = Shown::of(&stroke);
} else {
st.failed = true;
st.pending.clear();
}
st.steps.push(step);
st.stroke = Some(stroke);
drop(st);
self.changed.notify_all();
}
/// Tests: wait while the step is held (the stroke is busy with it), then panic if asked to.
#[cfg(test)]
fn test_hooks(&self) {
let mut st = self.lock();
while st.held && !st.closed {
st = self.changed.wait(st).unwrap_or_else(PoisonError::into_inner);
}
let panic = std::mem::take(&mut st.panic_next);
drop(st);
assert!(!panic, "a step panicked on the live stroke's thread (test)");
}
fn run(&self) {
loop {
{
let mut st = self.lock();
while st.pending.is_empty() && !st.closed {
st = self.changed.wait(st).unwrap_or_else(PoisonError::into_inner);
}
if st.closed {
return;
}
}
self.paint_pending();
}
}
}
/// A live stroke painting on its own thread (or inline, where there are no threads: the web).
pub(super) struct PaintThread {
shared: Arc<Shared>,
/// `None`: painting inline, in `push`.
thread: Option<JoinHandle<()>>,
shown: Shown,
}
impl PaintThread {
pub(super) fn start(stroke: EngineStroke) -> Self {
let shown = Shown::of(&stroke);
let state = State {
pending: Vec::new(),
stroke: Some(stroke),
steps: Vec::new(),
shown: shown.clone(),
failed: false,
closed: false,
#[cfg(test)]
held: false,
#[cfg(test)]
panic_next: false,
};
let shared = Arc::new(Shared { state: Mutex::new(state), changed: Condvar::new() });
let thread = if cfg!(target_arch = "wasm32") {
None
} else {
let worker = shared.clone();
// Without a thread (the system refused one) the stroke paints inline, as it used to.
std::thread::Builder::new().name("live stroke".into()).spawn(move || worker.run()).ok()
};
Self { shared, thread, shown }
}
/// Hand points over to be painted (none after a failed step).
pub(super) fn push(&mut self, pts: Vec<StrokePoint>) {
if pts.is_empty() {
return;
}
{
let mut st = self.shared.lock();
if st.failed {
return;
}
st.pending.extend(pts);
}
if self.thread.is_some() {
self.shared.changed.notify_all();
} else {
self.shared.paint_pending();
}
}
/// Wait up to `wait` for everything handed over to be painted; returns the steps painted since
/// the last call, oldest first, and updates what `shown` shows.
pub(super) fn catch_up(&mut self, wait: Duration) -> Vec<Step> {
let (shown, steps) = {
let mut st = self.wait_idle(wait);
(st.shown.clone(), std::mem::take(&mut st.steps))
};
self.shown = shown;
steps
}
/// Is the stroke still painting points it was given, or holding steps `catch_up` hasn't taken?
/// (A step can finish just after a frame's wait ran out; the next frame must collect it.)
pub(super) fn busy(&self) -> bool {
let st = self.shared.lock();
!st.steps.is_empty() || (!st.idle() && self.thread.as_ref().is_some_and(|t| !t.is_finished()))
}
pub(super) fn shown(&self) -> &Shown {
&self.shown
}
/// Wait for everything handed over to be painted; the steps since the last `catch_up` and the
/// stroke itself (`None` if its thread stopped mid-step).
pub(super) fn finish(mut self) -> (Vec<Step>, Option<EngineStroke>) {
let steps = self.catch_up(Duration::MAX);
let stroke = self.shared.lock().stroke.take();
(steps, stroke)
}
/// Tests: from now on the thread holds the next step it takes, as a slow brush would, until
/// the returned function lets it go (from any thread).
#[cfg(test)]
pub(super) fn hold(&self) -> impl FnOnce() + Send + 'static {
self.shared.lock().held = true;
let shared = self.shared.clone();
move || {
shared.lock().held = false;
shared.changed.notify_all();
}
}
/// Tests: the next step panics on the thread, which then stops with the stroke.
#[cfg(test)]
pub(super) fn panic_next_step(&self) {
self.shared.lock().panic_next = true;
}
/// Tests: is the thread still running? (It keeps the shared state alive until it ends.)
#[cfg(test)]
pub(super) fn thread_alive(&self) -> impl Fn() -> bool + use<> {
let weak = Arc::downgrade(&self.shared);
move || weak.strong_count() > 0
}
/// Look at the stroke once it has painted everything handed over.
#[cfg(test)]
pub(super) fn peek<R>(&self, f: impl FnOnce(&EngineStroke) -> R) -> Option<R> {
self.wait_idle(Duration::MAX).stroke.as_ref().map(f)
}
fn wait_idle(&self, wait: Duration) -> MutexGuard<'_, State> {
let deadline = Instant::now().checked_add(wait);
let mut st = self.shared.lock();
// A stopped thread (inline painting never waits) has nothing more to give.
while !st.idle() && self.thread.as_ref().is_some_and(|t| !t.is_finished()) {
let left = deadline.map_or(Duration::MAX, |d| d.saturating_duration_since(Instant::now()));
if left.is_zero() {
break;
}
// Wake now and then to notice a thread that stopped without a word.
let (guard, _) = self.shared.changed.wait_timeout(st, left.min(Duration::from_millis(50))).unwrap_or_else(PoisonError::into_inner);
st = guard;
}
st
}
}
impl Drop for PaintThread {
fn drop(&mut self) {
// The thread finishes the step it is on, if any, and ends; nothing waits for it.
self.shared.lock().closed = true;
self.shared.changed.notify_all();
}
}
#[cfg(test)]
mod tests {
use super::*;
use photocraft_engine::Session;
use photocraft_engine::brush_cmds::LiveStroke;
use serde_json::json;
#[test]
fn a_stroke_painted_on_the_thread_in_any_batches_equals_one_painted_inline() {
let mut s = Session::new();
s.execute("file.new", json!({"width": 400, "height": 120, "background": "white"})).unwrap();
s.execute("layer.new.layer", json!({"name": "paint"})).unwrap();
let begin = || {
let p = json!({"points": [[20, 60, 1.0]], "brush": {"size": 40, "hardness": 0.3, "smoothing": {"amount": 0.4}}, "seed": 3});
EngineStroke::Brush(Box::new(LiveStroke::begin(&s, &p).unwrap()))
};
let pts: Vec<StrokePoint> = (1..=60).map(|i| StrokePoint::new(20.0 + 6.0 * f64::from(i), 60.0 + 20.0 * (f64::from(i) / 9.0).sin(), 1.0)).collect();
// Never waiting, so the thread merges points that arrive while it paints into one step.
let mut thread = PaintThread::start(begin());
assert!(thread.thread.is_some(), "a thread of its own");
let mut steps = Vec::new();
for chunk in pts.chunks(3) {
thread.push(chunk.to_vec());
steps.extend(thread.catch_up(Duration::ZERO));
}
let (rest, painted) = thread.finish();
steps.extend(rest);
assert!(!steps.is_empty() && steps.iter().all(Result::is_ok), "every step painted");
let painted = painted.expect("the stroke comes back");
let mut inline = begin();
inline.push(&pts).unwrap();
let layer = s.active().unwrap().active_layer.unwrap();
let surface = |e: &EngineStroke| e.doc().layer(layer).unwrap().surface().unwrap().clone();
let (a, b) = (surface(&painted), surface(&inline));
let differ = (0..120).flat_map(|y| (0..400).map(move |x| (x, y))).filter(|&(x, y)| a.rgba(x, y) != b.rgba(x, y)).count();
assert_eq!(differ, 0, "pixels differ from the inline stroke");
assert!(b.rgba(200, 60 + (20.0 * (30.0f64 / 9.0).sin()) as i32)[3] > 0.5, "the stroke is there");
}
#[test]
fn a_painted_step_keeps_the_stroke_busy_until_the_canvas_takes_it() {
// The step finishes after the frame stopped waiting: the canvas must ask for another frame.
let mut s = Session::new();
s.execute("file.new", json!({"width": 200, "height": 100, "background": "white"})).unwrap();
let p = json!({"points": [[20, 50, 1.0]], "brush": {"size": 20}});
let mut thread = PaintThread::start(EngineStroke::Brush(Box::new(LiveStroke::begin(&s, &p).unwrap())));
thread.push(vec![StrokePoint::new(120.0, 50.0, 1.0)]);
thread.peek(|_| ());
assert!(thread.busy(), "a painted step nobody took yet");
assert_eq!(thread.catch_up(Duration::ZERO).len(), 1);
assert!(!thread.busy());
}
#[test]
fn after_a_failed_step_the_stroke_paints_nothing_more_and_shows_its_last_good_step() {
// The Mixer Brush keeps its last good preview after an error (`take_steps`); points queued
// behind the failed batch must not paint over it.
let mut s = Session::new();
s.execute("file.new", json!({"width": 200, "height": 100, "background": "white"})).unwrap();
s.execute("layer.new.layer", json!({"name": "paint"})).unwrap();
let p = json!({"points": [[30, 50]], "size": 16});
let mixer = photocraft_engine::brush_cmds::mixer_live::LiveMixer::begin(&s, &p).unwrap();
let mut thread = PaintThread::start(EngineStroke::Mixer(Box::new(mixer)));
let good = thread.shown().doc.clone();
// More samples than a live Mixer stroke takes, then one it would take.
thread.push(vec![StrokePoint::new(40.0, 50.0, 1.0); 70_000]);
thread.peek(|_| ());
thread.push(vec![StrokePoint::new(150.0, 50.0, 1.0)]);
let steps = thread.catch_up(Duration::MAX);
assert!(matches!(steps.as_slice(), [Err(_)]), "only the failed step");
assert!(Arc::ptr_eq(&thread.shown().doc, &good), "the last good step stays shown");
assert!(!thread.busy());
}
}
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.