856f865cf98d
setup.rs
use super::batch::tile_grid;
use super::consts::{ACC_FORMAT, CHUNK, CHUNK_UNIFORM, FX_BUDGET, MAX_PATTERN_TEXTURE_BYTES, OP_UNIFORM, PAGE, PATTERN_BUDGET, RESIDENT_BUDGET};
use super::kit::{Kit, tex_entry, uniform_entry};
use super::paging::{cell_rect, field_reaches, first_error, grid_rects};
use super::pipelines::{NO_EFFECT_MAPS, Pipelines};
use super::textures::{FxEntry, Resident, Tex, TexKind};
use super::{Compositor, DeviceHealth, DocId, Document, Fault, HashMap, LayerContent, Plan, Rect, Role, TILE_SIZE, Unsupported, fx, plan, prefix, timing};
/// Classification of a synchronous compositor pipeline build failure.
///
/// Only a recognized shader compiler diagnostic is considered deterministic. Every other
/// error, including generic validation, internal, and out-of-memory errors, is conservative
/// and must be treated as transient or unknown by callers.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum BuildFailureKind {
/// A known compiler diagnostic means the same shader is expected to fail on relaunch.
DeterministicShaderCompilation,
/// The failure may depend on device state, resource pressure, or driver behavior.
TransientOrUnknown,
}
/// A pipeline build error with a conservative retry classification.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct BuildFailure {
pub kind: BuildFailureKind,
pub message: String,
}
impl std::fmt::Display for BuildFailure {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(&self.message)
}
}
impl std::error::Error for BuildFailure {}
fn classify_build_diagnostic(diagnostic: &str) -> BuildFailureKind {
// FXC's X3507 diagnostic is a concrete shader compilation failure observed when
// compiling generated compositor shaders. Do not classify generic validation text.
if diagnostic.contains("X3507") { BuildFailureKind::DeterministicShaderCompilation } else { BuildFailureKind::TransientOrUnknown }
}
impl Compositor {
/// Create a compositor with the default accumulation format ([`ACC_FORMAT`]).
pub fn new(device: &wgpu::Device) -> Self {
Self::new_with_format(device, ACC_FORMAT)
}
/// The accumulation format to use on `adapter`: `Rgba32Float` when it can be a render target,
/// else `Rgba16Float`. Some drivers (e.g. Intel Vulkan) don't support rendering to `Rgba32Float`
/// and would otherwise panic at render-pipeline creation.
pub fn preferred_acc_format(adapter: &wgpu::Adapter) -> wgpu::TextureFormat {
let feats = adapter.get_texture_format_features(wgpu::TextureFormat::Rgba32Float);
if feats.allowed_usages.contains(wgpu::TextureUsages::RENDER_ATTACHMENT) { wgpu::TextureFormat::Rgba32Float } else { wgpu::TextureFormat::Rgba16Float }
}
/// [`Compositor::new_with_format`], but a shader the driver can't take is an `Err` instead of
/// a panic. Pipelines are built by the first draw that needs each one; one the driver can't
/// build (e.g. a D3D12 shader-compiler failure) makes that render [`Unsupported`], so the
/// caller falls back to the CPU compositor. Where errors only arrive asynchronously (WebGPU),
/// creation is assumed to have worked.
pub fn try_new_with_format(device: &wgpu::Device, acc_format: wgpu::TextureFormat) -> Result<Self, Unsupported> {
match first_error(device, || Self::build(device, acc_format)) {
(comp, None) => Ok(comp),
(_, Some(e)) => Err(Unsupported(format!("couldn't create the compositor: {e}"))),
}
}
/// [`Compositor::try_new_with_format`] that also builds every pipeline now, on a dedicated
/// Rayon pool of `threads` instead of the process-wide pool, so a failing one is an `Err`
/// here rather than on a later draw.
///
/// The dedicated pool keeps shader compilation from occupying workers needed by CPU
/// compositing. If the pool cannot be created, the pipelines are built one after another on
/// the calling thread.
#[cfg(not(target_arch = "wasm32"))]
pub fn try_new_with_format_threads(device: &wgpu::Device, acc_format: wgpu::TextureFormat, threads: usize) -> Result<Self, Unsupported> {
Self::try_new_with_format_threads_classified(device, acc_format, threads).map_err(|e| Unsupported(e.message))
}
/// [`Compositor::try_new_with_format_threads`] with an explicit failure classification for
/// callers that cache deterministic failures across launches. Only recognized shader compiler
/// diagnostics are marked deterministic; all other wgpu errors are transient or unknown.
#[cfg(not(target_arch = "wasm32"))]
pub fn try_new_with_format_threads_classified(device: &wgpu::Device, acc_format: wgpu::TextureFormat, threads: usize) -> Result<Self, BuildFailure> {
let comp = Self::try_new_with_format(device, acc_format).map_err(|e| BuildFailure { kind: BuildFailureKind::TransientOrUnknown, message: e.0 })?;
let pipelines = &comp.kit.pipelines;
let pool = rayon::ThreadPoolBuilder::new().num_threads(threads.max(1)).thread_name(|index| format!("photocraft-gpu-build-{index}")).build();
let error = match pool {
Ok(pool) => pool.install(|| pipelines.build_all(device, false)),
Err(e) => {
log::warn!("GPU compositor: couldn't create dedicated build pool; building sequentially: {e}");
pipelines.build_all(device, true)
}
};
match error {
None => Ok(comp),
Some(e) => Err(BuildFailure { kind: classify_build_diagnostic(&e), message: format!("couldn't build the compositor's pipelines: {e}") }),
}
}
/// Create a compositor whose accumulation/render-target format is `acc_format`. Pass
/// `Rgba16Float` on adapters that can't render to `Rgba32Float` (e.g. some Intel Vulkan drivers),
/// which otherwise fails at render-pipeline creation. See `Compositor::preferred_acc_format`.
/// Pipelines are built on first use (see [`Compositor::try_new_with_format`]).
pub fn new_with_format(device: &wgpu::Device, acc_format: wgpu::TextureFormat) -> Self {
Self::build(device, acc_format)
}
/// The compositor's shaders, layouts and pipeline table ([`Pipelines`]); no pipeline yet.
fn build(device: &wgpu::Device, acc_format: wgpu::TextureFormat) -> Self {
let bgl0 = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
label: Some("pc_compose_uniforms"),
entries: &[uniform_entry(0, CHUNK_UNIFORM), uniform_entry(1, OP_UNIFORM)],
});
let bgl1 = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
label: Some("pc_compose_textures"),
entries: &(0..8).map(tex_entry).collect::<Vec<_>>(),
});
let pipelines = std::sync::Arc::new(Pipelines::new(device, acc_format, &bgl0, &bgl1));
let dummy = Tex::new(device, "pc_compose_dummy", 1, 1, wgpu::TextureFormat::Rgba8Unorm, wgpu::TextureUsages::TEXTURE_BINDING).view;
let kit = Kit { pipelines, bgl0, bgl1, dummy };
Self::from_kit(kit, device.limits().max_texture_dimension_2d, acc_format)
}
/// Test hook: how many of the compositor's pipelines have been built so far (shared with its
/// siblings), and how many it has.
#[doc(hidden)]
pub fn pipeline_counts(&self) -> (usize, usize) {
self.kit.pipelines.counts()
}
/// Create an independent compositor on the same device, reusing compiled pipelines.
/// Texture caches, budgets, focus and timing start at their defaults; no document state is
/// shared. Render with the same device and queue as this compositor.
pub fn sibling(&self) -> Self {
let mut sibling = Self::from_kit(self.kit.clone(), self.device_max, self.acc_format);
sibling.health = self.health.clone();
sibling
}
fn from_kit(kit: Kit, device_max: u32, acc_format: wgpu::TextureFormat) -> Self {
Self {
kit,
pool: Vec::new(),
residents: HashMap::new(),
fx: HashMap::new(),
prefix: prefix::Prefix::default(),
temps: Vec::new(),
patterns: HashMap::new(),
pattern_mode: photocraft_color::ColorMode::Rgb,
pattern_doc: DocId(0),
pattern_budget: PATTERN_BUDGET,
max_dim: 0,
device_max,
page: PAGE,
chunk: CHUNK,
resident_budget: RESIDENT_BUDGET,
fx_budget: (FX_BUDGET as u64).saturating_sub(prefix::MAX_BYTES),
layer_need: 0,
lent: 0,
exact_resident: false,
focus: None,
frame: 0,
stamp: 0,
staged: 0,
recorded: 0,
layer_alloc: None,
admit_freed: 0,
fail_allocs: 0,
acc_format,
cmyk: 0,
health: None,
timer: None,
}
.with_texture_limit(device_max)
}
fn with_texture_limit(mut self, max: u32) -> Self {
self.set_texture_limit(max);
self
}
/// Plan paging for a texture side limit of `max` (clamped to the device's own limit and at
/// least one tile). Tests use a small limit to exercise documents larger than it on any
/// adapter. Drops every cached texture.
pub fn set_texture_limit(&mut self, max: u32) {
let tile = TILE_SIZE as u32;
self.max_dim = max.min(self.device_max).max(tile);
let mut page = tile;
while page * 2 <= self.max_dim.min(PAGE) {
page *= 2;
}
self.page = page;
self.chunk = CHUNK.min(page);
self.prefix.set_step(self.chunk);
self.pool.clear();
self.residents.clear();
self.fx.clear();
self.temps.clear();
self.prefix.clear();
}
/// The page side layer surfaces are stored in.
pub fn page_size(&self) -> u32 {
self.page
}
/// The chunk side cells are tiled in.
pub fn chunk_size(&self) -> u32 {
self.chunk
}
/// Test hook: the next `n` layer page textures fail as if the device were out of memory
/// (a real one can't be forced), so the fallback paths of #6563 can be tested.
#[doc(hidden)]
pub fn fail_layer_allocs(&mut self, n: u32) {
self.fail_allocs = n;
}
/// Set the GPU memory resident layer pages may hold (default [`RESIDENT_BUDGET`]), exactly:
/// nothing is lent to it ([`Self::fit_layers`]) until the next [`Self::set_memory_budget`].
pub fn set_resident_budget(&mut self, bytes: u64) {
// The loan goes back to the effect maps, so the total budget stays what it was.
self.fx_budget = self.fx_budget.saturating_add(self.lent);
self.lent = 0;
self.resident_budget = bytes;
self.exact_resident = true;
}
/// Set the GPU memory the compositor may hold for layer pages and caches together
/// (a quarter of it, at most [`FX_BUDGET`], for effect maps and lower-stack chunks). Uploads and evicted pages in
/// flight during a refresh stay within about a quarter more.
pub fn set_memory_budget(&mut self, bytes: u64) {
let caches = (FX_BUDGET as u64).min(bytes / 4);
self.prefix.set_budget((caches / 2).min(prefix::MAX_BYTES));
self.fx_budget = caches.saturating_sub(self.prefix.budget());
self.resident_budget = bytes.saturating_sub(caches);
self.lent = 0;
self.exact_resident = false;
self.lend();
}
/// Record that a render needs `needed` bytes of layer pages and return the resident budget
/// they now have. A render of the `whole` document sets the need; a part of it only raises
/// it, so a large partial refresh never shrinks what the next full one keeps resident.
///
/// Pages that miss their share by less than the effect-map share borrow from it: an evicted
/// effect map is rebuilt by the next refresh that draws it, but one page too many sends the
/// whole refresh to the CPU compositor, 10× slower (#5973, P60: 150 layers of 6 MP on an
/// integrated GPU missed by 5 % and took 680 ms instead of 62).
/// The lower-stack share is never lent: it is what keeps a mid-stack edit at half the work.
/// The loan holds across [`Self::set_memory_budget`] until a later call needs less or more.
pub fn fit_layers(&mut self, needed: u64, whole: bool) -> u64 {
self.layer_need = if whole { needed } else { self.layer_need.max(needed) };
self.lend();
self.resident_budget
}
/// Return the loan to the effect maps, then lend what [`Self::layer_need`] still lacks, if
/// the effect-map share covers it (lending part of it would fit nothing and only evict maps).
fn lend(&mut self) {
self.fx_budget = self.fx_budget.saturating_add(self.lent);
self.resident_budget = self.resident_budget.saturating_sub(self.lent);
let short = self.layer_need.saturating_sub(self.resident_budget);
self.lent = if short <= self.fx_budget && !self.exact_resident { short } else { 0 };
self.fx_budget = self.fx_budget.saturating_sub(self.lent);
self.resident_budget = self.resident_budget.saturating_add(self.lent);
}
/// The budget of layer pages, effect maps and lower-stack chunks (bytes).
pub fn memory_budget(&self) -> u64 {
self.resident_budget.saturating_add(self.fx_budget).saturating_add(self.prefix.budget())
}
/// Bytes held by reusable lower-stack chunks, within the overall cache allowance.
pub fn composite_cache_bytes(&self) -> u64 {
self.prefix.bytes()
}
/// Cap lower-stack reuse (default at most 512 MiB); zero disables it. The released allowance
/// goes back to effect maps, preserving the total budget and layer-page allowance.
pub fn set_composite_cache_budget(&mut self, bytes: u64) {
let caches = self.fx_budget.saturating_add(self.prefix.budget());
self.prefix.set_budget(bytes.min(caches));
self.fx_budget = caches.saturating_sub(self.prefix.budget());
}
/// Bytes of the layer pages a render of `region` needs resident (each layer and mask
/// surface's tiles within the region's page cells, in their texture format).
pub fn working_set(&self, doc: &Document, region: Rect) -> u64 {
let Ok(plan) = plan(doc) else { return 0 };
let grid = tile_grid(doc.bounds());
let cells = grid_rects(region.intersect(&doc.bounds()), self.page)
.into_iter()
.map(|r| cell_rect((r.x0.div_euclid(self.page as i32), r.y0.div_euclid(self.page as i32)), self.page))
.fold(Rect::EMPTY, |a, c| if a.is_empty() { c } else { a.union(&c) });
let mut seen = std::collections::HashSet::new();
let mut total = 0u64;
for p in &plan.passes {
let sources = [p.tex.as_ref().map(|t| (t.layer, t.role, t.surface.get())), p.mask.as_ref().map(|m| (m.layer, Role::Mask, m.surface.get()))];
for (layer, role, s) in sources.into_iter().flatten() {
if seen.insert((layer, role)) {
let a = s.tile_bounds().intersect(&grid).intersect(&cells);
total += a.width() as u64 * a.height() as u64 * TexKind::for_surface(role, s.format()).bytes_per_pixel() as u64;
}
}
}
total
}
/// The GPU memory resident layer pages may hold (bytes; see [`Compositor::set_memory_budget`]).
pub fn resident_budget(&self) -> u64 {
self.resident_budget
}
/// Whether a render of `region` keeps every layer page it needs within the budget; when it
/// doesn't, each render re-uploads what was evicted.
pub fn fits_budget(&self, doc: &Document, region: Rect) -> bool {
self.working_set(doc, region) <= self.resident_budget
}
/// The document area the view shows (`None`: unknown). Full refreshes draw its cells last.
pub fn set_focus(&mut self, focus: Option<Rect>) {
self.focus = focus;
}
/// GPU memory held by resident layer pages (bytes).
pub fn resident_bytes(&self) -> u64 {
self.residents.values().map(Resident::bytes).sum()
}
/// GPU memory held by cached pattern textures (bytes).
pub fn pattern_cache_bytes(&self) -> u64 {
self.patterns.values().map(|p| p.bytes).sum()
}
/// Set the GPU memory pattern textures may hold (default [`PATTERN_BUDGET`]). It takes effect
/// at the end of the next refresh.
pub fn set_pattern_budget(&mut self, bytes: u64) {
self.pattern_budget = bytes;
}
/// Whether `doc` can be composited on the GPU. Documents and layers larger than the texture
/// limit are fine: surfaces are stored in page-sized textures and effect maps of regions
/// larger than the limit are built per page cell.
pub fn supports(&self, doc: &Document) -> Result<(), Unsupported> {
let p = plan(doc)?;
self.check_fx(doc, &p)
}
/// Whether the maps of an effect region are built per page cell (it exceeds the limit).
pub(crate) fn fx_paged(&self, region: Rect) -> bool {
region.width() > self.max_dim || region.height() > self.max_dim
}
/// How far beyond a page cell the effect maps of `f` must be computed to be exact in it.
pub(crate) fn fx_apron(doc: &Document, f: &plan::FxLayer<'_>) -> i32 {
let vector_shape = matches!(f.layer.content, LayerContent::Shape(_)) && photocraft_compose::effect_outline(f.layer).is_none();
let progs: Vec<fx::MapProgram> = f
.layer
.effects
.items
.iter()
.filter(|e| e.enabled())
.map(|e| fx::program_with(e, &doc.global_light, vector_shape, &doc.patterns, (0.0, 0.0)))
.collect();
let want = field_reaches(&progs);
// Distance fields are exact one pixel inside the window they are computed from.
progs.iter().map(|p| p.reach(&|k| want.get(&k).copied().unwrap_or(0))).max().unwrap_or(0).saturating_add(2)
}
/// Effect maps must fit in textures (per page cell when the region exceeds the limit), and
/// patterns in one texture.
pub(crate) fn check_fx(&self, doc: &Document, p: &Plan<'_>) -> Result<(), Unsupported> {
if !p.fx.is_empty() && !self.kit.pipelines.effect_maps() {
return Err(Unsupported(NO_EFFECT_MAPS.into()));
}
for f in &p.fx {
if self.fx_paged(f.region) {
let side = i64::from(self.page) + 2 * i64::from(Self::fx_apron(doc, f));
if side > i64::from(self.device_max) {
return Err(Unsupported(format!("effects of `{}` reach too far to build per page", f.layer.name)));
}
}
for e in f.layer.effects.items.iter().filter(|e| e.enabled()) {
// Effect noise is speckled in the CPU maps; keep CPU and GPU identical by
// rendering noise-carrying effects on the CPU path.
let noisy = match e {
photocraft_doc::Effect::DropShadow(s) | photocraft_doc::Effect::InnerShadow(s) => s.noise > 0.0,
photocraft_doc::Effect::OuterGlow(g) | photocraft_doc::Effect::InnerGlow(g) => g.noise > 0.0,
_ => false,
};
if noisy {
return Err(Unsupported(format!("effect noise on `{}` uses the CPU path", f.layer.name)));
}
for s in fx::program_with(e, &doc.global_light, false, &doc.patterns, (0.0, 0.0)).stages {
if s.lut.as_ref().is_some_and(|l| l.len() > 4096) {
return Err(Unsupported(format!("effect blur on `{}` too wide for the GPU path", f.layer.name)));
}
if let Some(pat) = &s.pattern {
self.check_pattern(pat)?;
}
}
}
}
for pass in &p.passes {
if let Some(pat) = pass.pattern {
self.check_pattern(pat)?;
}
}
Ok(())
}
/// A pattern's texture must fit the device and the per-pattern cap; a larger one renders on
/// the CPU compositor.
fn check_pattern(&self, pat: &photocraft_doc::Pattern) -> Result<(), Unsupported> {
if pat.width > self.device_max || pat.height > self.device_max {
return Err(Unsupported(format!("pattern `{}` larger than the GPU texture limit", pat.name)));
}
if u64::from(pat.width) * u64::from(pat.height) * 16 > MAX_PATTERN_TEXTURE_BYTES {
return Err(Unsupported(format!("pattern `{}` too large for a GPU texture; the CPU path paints it", pat.name)));
}
Ok(())
}
/// Drop GPU textures of a closed document.
pub fn forget_doc(&mut self, doc: DocId) {
self.residents.retain(|_, r| r.doc != doc);
self.fx.retain(|_, e| e.doc != doc);
self.patterns.retain(|_, p| p.doc != doc);
self.prefix.forget(doc);
}
/// [`Self::forget_doc`] for every document `keep` rejects: what the compositor holds for
/// documents that were closed, however their canvas entry went (#4529).
pub fn retain_docs(&mut self, keep: impl Fn(DocId) -> bool) {
let mut gone: Vec<DocId> = self
.residents
.values()
.map(|r| r.doc)
.chain(self.fx.values().map(|e| e.doc))
.chain(self.patterns.values().map(|p| p.doc))
.chain(self.prefix.doc())
.filter(|d| !keep(*d))
.collect();
gone.sort_by_key(|d| d.0);
gone.dedup();
for d in gone {
self.forget_doc(d);
}
}
/// Documents the compositor holds pages, effect maps, pattern textures or a lower-stack
/// composite for.
pub fn held_docs(&self) -> Vec<DocId> {
let mut docs: Vec<DocId> = self
.residents
.values()
.map(|r| r.doc)
.chain(self.fx.values().map(|e| e.doc))
.chain(self.patterns.values().map(|p| p.doc))
.chain(self.prefix.doc())
.collect();
docs.sort_by_key(|d| d.0);
docs.dedup();
docs
}
/// GPU memory held by cached effect maps (bytes).
pub fn fx_cache_bytes(&self) -> usize {
self.fx.values().map(FxEntry::bytes).sum()
}
/// Watch `health` (see [`DeviceHealth::watch`]): once the device is lost or reported an
/// error, every render returns [`Unsupported`] without touching the GPU, so callers use the
/// CPU compositor instead.
pub fn set_health(&mut self, health: DeviceHealth) {
self.health = Some(health);
}
/// Why the device can't be used (`None` while healthy or unwatched).
pub fn fault(&self) -> Option<Fault> {
self.health.as_ref().and_then(DeviceHealth::fault)
}
/// The accumulation texture format used by this compositor.
pub fn acc_format(&self) -> wgpu::TextureFormat {
self.acc_format
}
/// The device health monitor if one was attached with [`Compositor::set_health`].
pub fn health(&self) -> Option<&DeviceHealth> {
self.health.as_ref()
}
/// Clear all resident layer pages, effect maps, pattern textures and lower-stack composites.
pub fn reset_cache(&mut self) {
self.residents.clear();
self.fx.clear();
self.patterns.clear();
self.prefix.clear();
}
/// Measure how long the GPU spends executing each [`Compositor::render`], with timestamp
/// queries read back asynchronously (nothing waits for the GPU). Returns whether the device
/// supports it: without [`timing::FEATURES`] there is no measurement at all, and callers
/// report no GPU time rather than the encode-and-submit cost `composite_ms` already is.
///
/// A measurement arrives a frame or two after the refresh it belongs to, so it carries that
/// refresh's own pixel count; take it with [`Compositor::take_gpu_timing`].
pub fn measure_gpu_time(&mut self, device: &wgpu::Device, queue: &wgpu::Queue) -> bool {
// `PHOTOCRAFT_NO_GPU_TIMING` turns it off: a kill switch for a driver whose timestamp
// queries misbehave, and the control arm for measuring what the queries themselves
// cost — the device is identical either way, so only the instrumentation varies.
if std::env::var_os("PHOTOCRAFT_NO_GPU_TIMING").is_some() {
return false;
}
if self.timer.is_none() {
self.timer = timing::GpuTimer::new(device, queue);
}
self.timer.is_some()
}
/// Whether [`Compositor::measure_gpu_time`] is on for this compositor.
pub fn measures_gpu_time(&self) -> bool {
self.timer.is_some()
}
/// The most recent finished GPU measurement, leaving none behind (a stale number is never
/// reported twice as new). `None` while unmeasured, unsupported, or still in flight.
///
/// [`Compositor::render`] already drains this into [`Stats::gpu_time`], so the app never
/// calls it; it is how a bench or a test collects a measurement without issuing another
/// render to carry it.
pub fn take_gpu_timing(&mut self) -> Option<timing::GpuTiming> {
self.timer.as_mut().and_then(timing::GpuTimer::take)
}
}
#[cfg(test)]
mod build_failure_tests {
use super::{BuildFailureKind, classify_build_diagnostic};
#[test]
fn only_concrete_shader_compiler_diagnostic_is_deterministic() {
assert_eq!(classify_build_diagnostic("error X3507: loop control variable must be integer"), BuildFailureKind::DeterministicShaderCompilation);
assert_eq!(classify_build_diagnostic("Validation Error: invalid bind group"), BuildFailureKind::TransientOrUnknown);
assert_eq!(classify_build_diagnostic("out of memory"), BuildFailureKind::TransientOrUnknown);
assert_eq!(classify_build_diagnostic("shader compilation failed"), BuildFailureKind::TransientOrUnknown);
}
}
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.