Files
photocraft/crates/io/src/renderer.rs
T
Khawar Zamman WaniandFredApps 1089932ae9 Add a headless GPU backend for composition and flat export (#10842)
* 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>
2026-11-05 04:53:25 +01:00

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)
}
}