mirror of
https://github.com/storytold/photocraft.git
synced 2026-11-21 01:18:43 +00:00
* Add headless GPU backend foundation for composition and flat export (issue #8062 PR 1) * Fix headless GPU readback bounds, API compliance, and error preservation (#8062) * Fix GPU readback bounds, context thread spawn error, and test parity (#8062) * Fix BandRenderer Send bound, PNG reborrows, and clippy lints (#8062) * Fix effect shadow test construction and remove dead code wrappers (#8062) * Use short reborrows for Headless renderer without lifetime escaping (#8062) * Fix clippy collapsible_if and ensure multi-band geometry in flat export tests (#8062) * Fix automation Rect import, add renderer diagnostics, and harden flat export retries (#8062) * Fix GPU feature test APIs and native target gates * Verify unsupported GPU effects before testing band seams * Use compositor buffer ownership API after upstream memory accounting change * Update export renderer test helper for owned compositor buffers * Fix headless GPU backend review findings (#10842) - release a closed document's GPU caches through a BandRenderer hook - bound the monitored readback wait and report a stalled GPU as device loss - reject 32-bit float documents before band readback so exports fall back to CPU - keep previews at 8-bit RGBA and report the palette/Duotone renderer bypass - retain renderer diagnostics when encoding fails - strengthen renderer, save-path and GPU diagnostics tests * Add GPU close-hook and 8-bit preview regression tests (#10842) * fix(io): correct renderer binding mutability * Fix remaining headless GPU review findings (#10842) - release a document's GPU caches when file.close, file.closeAll or file.closeOthers removes it through a command - honor cancellation while band readback waits, polling in 100 ms slices - fault the device after a readback timeout so later exports skip it - report single-layer, CMYK ink-mixing, ORA and PDF CPU paths to a requested renderer - keep fallback warnings in their export instead of leaking them into the next one - requeue renderer diagnostics when a renderer-aware save's final write fails - write MCP/serve diagnostics without panicking on a broken stderr - document the actual colour-space contract and drop F32 from the GPU depth list * Use question mark for cancellable readback errors * Keep GPU export diagnostics with their attempt and stop bands on cancel Encode native .pcraft bytes before draining renderer diagnostics, and requeue export warnings when a workspace write fails, so callers still report the adapter or fallback reason with the error. Move a failed GPU attempt's queued diagnostics into its CPU retry result instead of leaving them for a later successful export to report. Stop GPU band readback at the next band after cancellation, and check the interrupt before each CpuRenderer sink delivery. Band readback uploads half-precision textures, so reject U16 alongside F32: their samples cannot survive the upload. Tighten the 8-bit CPU/GPU parity checks to 1/255. * Keep headless export warnings when a workspace write fails (#10842) A capability-scoped save encodes the export, then writes it; when the write fails, the export warnings (folded together with renderer diagnostics) were pushed back through `BandRenderer::push_diagnostic`, whose default is a no-op. A custom renderer that overrides only `drain_diagnostics` therefore lost the adapter or fallback reason that belonged with the error. Keep them in `Headless` instead and return them from the next `drain_diagnostics`, alongside the renderer's own queue. The regression uses a renderer without a `push_diagnostic` override and checks the warnings survive the failed write and drain exactly once. Also name the actual source of the depth limit in the headless GPU matrix: layer content is uploaded as half-precision textures, not band readback. * Stop CPU bands and CPU retries on cancellation (#10912) The CPU retry after a retryable GPU error composes through `FlatSource::bands`, whose shared `emit` sink did not poll the export interrupt: a cancel was only observed after the whole composite finished. Check it once per band, as `CpuRenderer` does, for both RGB and CMYK ink bands. The flat and streamed-PNG retry branches also check before starting the full CPU composite again, so a cancelled export returns `IoError::Cancelled` instead of re-rendering the document. Tests: band-sink cancellation for RGB and CMYK inks, a renderer call counter proving a second export reaches the renderer, and a pending `wait_slices` poll observing cancellation set mid-wait. * Merge origin/main into GPU foundation (#10842) * Keep GPU-path diagnostics on every failure path, honour cancel in native copy - save: export warnings of a failed local write stay in Headless pending diagnostics - render: preview fallback warnings are returned, drained, and added to the doc.render reply - io: renderer-neutral fallback wording; native single-layer copy checks cancellation per band - gpu: gate wait_slices tests off wasm32 (#10842) --------- Co-authored-by: FredApps <153173854+FredApps@users.noreply.github.com>
125 lines
5.0 KiB
Rust
125 lines
5.0 KiB
Rust
//! Renderer contract and band provider interface for headless composition and export.
|
|
|
|
use photocraft_doc::{DocId, Document};
|
|
use photocraft_geom::Rect;
|
|
use photocraft_raster::Interrupt;
|
|
|
|
use crate::IoError;
|
|
|
|
/// A horizontal band of rendered straight-alpha RGBA float samples (`[R, G, B, A]`).
|
|
///
|
|
/// Semantics:
|
|
/// - Color space: the document's embedded colour profile for RGB documents (sRGB when the
|
|
/// document is untagged), sRGB working composite for Lab and Grayscale, or profile-converted
|
|
/// composite for CMYK.
|
|
/// - Alpha representation: straight (unpremultiplied) alpha in `pixels[..][3]`, where `1.0` is
|
|
/// fully opaque and `0.0` is fully transparent. Color channels `pixels[..][0..3]` carry
|
|
/// unpremultiplied sample values.
|
|
/// - Memory layout: contiguous row-major vector of length `rect.width() * rect.height()`.
|
|
/// Sample at `(x, y)` is located at `(y - rect.y0) * rect.width() + (x - rect.x0)`.
|
|
/// - Geometry: `rect` spans document coordinates, matching full document width across horizontal
|
|
/// slices from top (`y = 0`) to bottom (`y = height`).
|
|
#[derive(Clone, Debug)]
|
|
pub struct RenderBand {
|
|
/// Document-coordinate bounding rectangle of this band.
|
|
pub rect: Rect,
|
|
/// Interleaved straight-alpha samples `[r, g, b, a]`, row-major.
|
|
pub pixels: Vec<[f32; 4]>,
|
|
}
|
|
|
|
/// Errors raised by a [`BandRenderer`].
|
|
#[derive(Debug, thiserror::Error)]
|
|
pub enum RenderError {
|
|
/// The document or requested feature is not supported by this renderer.
|
|
#[error("unsupported document or feature: {0}")]
|
|
Unsupported(String),
|
|
/// The rendering backend, hardware adapter, or pipeline is unavailable.
|
|
#[error("rendering backend unavailable: {0}")]
|
|
Unavailable(String),
|
|
/// A GPU device error, device loss, or driver crash occurred.
|
|
#[error("rendering device failure: {0}")]
|
|
Device(String),
|
|
/// The rendering operation was cancelled by caller request.
|
|
#[error("rendering was cancelled")]
|
|
Cancelled,
|
|
/// Rendering execution failed within the rendering provider.
|
|
#[error("rendering failed: {0}")]
|
|
Execution(String),
|
|
/// Downstream sink callback returned an I/O, encoder, or cancellation error.
|
|
#[error("sink error: {0}")]
|
|
Sink(#[source] Box<IoError>),
|
|
}
|
|
|
|
impl RenderError {
|
|
/// Create a new sink error wrapping [`IoError`].
|
|
pub fn sink(err: IoError) -> Self {
|
|
match err {
|
|
IoError::Cancelled => RenderError::Cancelled,
|
|
other => RenderError::Sink(Box::new(other)),
|
|
}
|
|
}
|
|
|
|
/// Whether this error represents an availability or capability limitation of the renderer,
|
|
/// where a complete export attempt should restart on the reference CPU compositor.
|
|
///
|
|
/// Sink errors (codec failures, disk full, cancellation) are fatal to the export and
|
|
/// MUST NEVER be retried on the CPU compositor. Execution errors represent contract or
|
|
/// internal provider failures that are rejected.
|
|
pub fn is_retryable(&self) -> bool {
|
|
match self {
|
|
RenderError::Unsupported(_) | RenderError::Unavailable(_) | RenderError::Device(_) => true,
|
|
RenderError::Execution(_) | RenderError::Cancelled | RenderError::Sink(_) => false,
|
|
}
|
|
}
|
|
}
|
|
|
|
/// A provider of rendered composite bands for flat export.
|
|
pub trait BandRenderer: Send {
|
|
/// Renders `doc` over `rect` in horizontal bands, passing each band to `sink`.
|
|
/// `band_rows`: preferred rows per band (0 to let provider choose). `ctl` reports
|
|
/// cancellation; a renderer that waits for the device polls it between bounded waits.
|
|
fn render_bands(
|
|
&mut self,
|
|
doc: &Document,
|
|
rect: Rect,
|
|
band_rows: i32,
|
|
ctl: &Interrupt<'_>,
|
|
sink: &mut dyn FnMut(RenderBand) -> Result<(), IoError>,
|
|
) -> Result<(), RenderError>;
|
|
|
|
/// Drain renderer diagnostic messages (e.g. backend/adapter status once, fallback reasons).
|
|
fn drain_diagnostics(&mut self) -> Vec<String> {
|
|
Vec::new()
|
|
}
|
|
|
|
/// Record a diagnostic message on this renderer.
|
|
fn push_diagnostic(&mut self, _diagnostic: String) {}
|
|
|
|
/// Drop cached state for a document that was closed or replaced. The default does nothing:
|
|
/// renderers without per-document caches stay ready for the next document.
|
|
fn forget_document(&mut self, _doc: DocId) {}
|
|
}
|
|
|
|
/// Default reference band renderer using `photocraft-compose`.
|
|
#[derive(Clone, Copy, Debug, Default)]
|
|
pub struct CpuRenderer;
|
|
|
|
impl BandRenderer for CpuRenderer {
|
|
fn render_bands(
|
|
&mut self,
|
|
doc: &Document,
|
|
rect: Rect,
|
|
band_rows: i32,
|
|
ctl: &Interrupt<'_>,
|
|
sink: &mut dyn FnMut(RenderBand) -> Result<(), IoError>,
|
|
) -> Result<(), RenderError> {
|
|
ctl.check().map_err(|_| RenderError::Cancelled)?;
|
|
photocraft_compose::render_bands(doc, rect, band_rows, |buf| {
|
|
// Stop at the next band when the sink cancels, instead of composing the whole canvas.
|
|
ctl.check().map_err(|_| IoError::Cancelled)?;
|
|
sink(RenderBand { rect: buf.rect, pixels: buf.into_px() })
|
|
})
|
|
.map_err(RenderError::sink)
|
|
}
|
|
}
|