Technical documentation · Architecture
The renderer has to keep a large, layered document responsive within a limited graphics-memory budget. Hundreds of layers may contain only small parts of an illustration. Storing 200 full-size 4096 × 4096 RGBA8 images would require 12.5 GiB before masks, brush state or intermediate results. Rebuilding those images for every pen sample would also repeat almost entirely unchanged work.
Capy Canvas allocates painted regions in tiles, retains their GPU textures, and tracks which composition results an edit invalidates. Shaders draw the marks, apply effects and combine layers into the visible image.
The shared memory budget admits new document bytes and assigns renderer grants from process and device facts.
WgpuRasterizer stores painted layer
content in sparse 256 × 256 texture pages. Pages are allocated as regions are
touched, rather than reserving a full-size paint texture for every empty layer.
Brushes that need coverage or wetness can allocate additional state alongside
those pages. Composite images and filter intermediates have their own storage,
so sparse paint pages do not make total memory independent of document size.
These pages are software-managed regions of the document, separate from the
small on-chip tiles used internally by some GPU architectures.
Native raster restoration stages color, mask and watercolor wetness pages in separate typed vectors. The restore path publishes them only after every tile upload and the final cached batch succeed. Workers prepare its tiles in order, at most eighteen ahead of the next upload. Color tiles decode through the bounded source cache. Mask and wetness samples wait in that window until their turn, then upload straight into their private Float32 scalar pages, so coverage never occupies decoded source slots. A failed decode or upload leaves every live page intact. Cache trimming preserves the prepared frame’s required source and destination pages until that frame consumes them. The native paint cache shares the Raster grant with readback and restore buffers. Pinned and reusable buffers count before completed paint pages. It allocates pages on demand. Private preparation and snapshot workers retain no canonical paint cache.
Paint and coverage pages live in explicit source-local domains,
PaintSource.domain and CoverageSource.domain in the
authored model. A photo base keeps its own
image extent at its base offset inside the paint domain. SceneView::local_extent and target_extent expose
these domains in authored/scene.rs.
The composition frame is a window over those pixels; changing the canvas does not
discard pixels outside it. Retained pixels count toward tile and byte limits.
Reduced composition reads transparent pixels beyond each color or preview
texture's physical bounds, including partial edge cells of shifted sources.
Coverage sources retain their authored outside value through source placement.
Rect::from_extent gives the local pixel bounds used by geometry, merges and sampling.
Canvas geometry commands build one batch in
canvas_geometry.rs:
- A crop only moves root offsets and stores the old extent. It never copies pixels, so growing the canvas again shows the hidden pixels.
- Growing the canvas left or up rebases paint layers and masks by whole tiles: tile keys shift, still sharing their backing, a photo's base offset moves with them, and the layer offset and linked mask offset move the other way. Tile coordinates stay unsigned, and the new strip beside a photo is paintable.
- After every geometry edit, each paint layer and each mask covers the canvas window in its local coordinates.
- A fill, gradient or figure with no selection is bounded to the canvas window on a layer with hidden pixels, and never writes past the layer's extent within an edge page, so growing the canvas shows transparency there. Brush dabs past the canvas edge may write hidden pixels, as they already do on photo layers.
- A turned, flipped or resized canvas (Straighten, Rotate and Flip Image, Image
Size) is an F64
linearmap in the plan; image objects and effect references compose it in double precision. Paint layers and masks get a pendingTransformoperation into a new local frame that holds the whole moved extent, and the selection, Selection Layers and guides are transformed as metadata. Flips and quarter turns sample withNearest, so they move pixels exactly. Source and destination share one tile grid while the operation runs, so a quarter turn of a non-square layer draws into a square extent. - A paint layer with a base image is moved by the plan's
remapsinstead. A flip or quarter turn moves it exactly, turning its tile-padded domain as a whole (sample_remap.rs): the base becomes a new immutable image in its own interpretation, and every paint and material tile moves to one tile. Whole-layer Transform flips and quarter turns of such a layer and its linked mask use the same moves (Document::exact_layer_transform_plan). Any other resample of an untouched source-profile photo layer (no paint tiles or pending operations, full color, not CMYK) keeps the photo's interpretation: its remap is aBaseRemap::Resamplethat the snapshot worker renders through the map into float rows in the photo's own primaries and encodes at its own channels, depth and profile (snapshot/resample_image.rs). RGB and gray gain alpha only where the result exposes transparency. Every other photo layer folds its base into the layer's paint: the record loses its base, and itsTransformreads the removed base throughImageTransform::source_base, so base and paint are resampled once together into working pixels. - A
Transformwhose selection takes every pixel its target holds (no selection, or a rectangle around all of its pages) leaves the pages outside its forward bounds empty. The renderer drops them, in every plane, from the GPU and from the data the next publication copies, so a reduction or turn publishes no transparent tiles and they don't count toward the tile limit. A layer that keeps its base keeps its pages, since they cover it. A mask's transform creates the pages it draws, so its source is only the pages the mask held. - Delete Cropped Paint Pixels trims each paint layer and mask to the tiles its
window touches, rebases them to the smallest tile-aligned extent, and erases the
edges of paint layers with up to four bounded
Eraseoperations, so only edge tiles are rewritten. A layer with a base is cut exactly instead: its base becomes a new image of only the kept samples, or none, and its tiles are cleared outside the window by a remap. Image objects are never cut. - Remaps run on the snapshot worker (
SnapshotRequest::Remap, the Web raster worker included); exact moves read at most four source tiles per result tile and resamples render one result tile at a time. The UI applies the plan with their results only if the drawing has not changed meanwhile, in one undo step; undo restores the original images. - Pixel operations run in the same undo step as the metadata edits
(
CanvasEngine::apply_canvas_plan), on locked layers too. A target whose raster the batch replaced is restored from that raster before its operations run.
A canvas size change resets the renderer's paint pages and restores every layer
from its raster revision, including on undo and redo
(tests/canvas_geometry.rs).
Limits are checked before the edit commits, including the device's texture limit
through CanvasRenderer::max_document_dimension.
A merge plans a RasterOperationKind::Bake with an immutable SceneSnapshot
and explicit SceneScope. Its SourceTarget selects the new paint source. The
frame composites the retained scope over transparency, isolated and moved into
the result's pixels, in the document's blend space. It copies each tile into the
result's pages, decoded to linear pixels in a Perceptual document so the result
looks the same (scene/bake.rs).
Image objects are sampled with their saved kernel, never from the display's mip levels, and
watercolor settles into the result, which keeps no wet state. The authored edit
removes the merged occurrences; the accepted bake snapshot retains their sources,
masks and original image tiles until the job finishes. The bake runs on the
render owner; the UI thread only plans it. Large bakes advance through
1024 × 1024 steps. Each submission captures its native tiles before cache
eviction can discard them. Intermediate native backing belongs to the renderer;
history publishes the complete edit after the last region. Hosts poll readiness
without waiting on the GPU and keep the previous artwork visible during the bake.
A merge allocates the finite support of what it bakes, not the frame: painted
pages or paint domains, image objects with their smooth sampling footprint,
filter radii and the authored frame of generators (output_support in
merge.rs), extended over the canvas when
that fits. Off-frame content therefore survives Merge Visible, Flatten and Stamp
Visible. A filter whose reach can't be represented refuses the bake instead of
being clipped. A
bake that reads image objects, including Rasterize Layer, Rasterize and Apply
Mask, merges of object layers and Copy Selection to Layer from one, runs on the
snapshot worker instead, where canonical image sampling can finish: the worker
evaluates the scope into one immutable working-pixel image, and the shared session
publishes it as the new paint layer's base once the drawing is unchanged
(snapshot/image_capture.rs,
layer_conversions.rs). A changed
drawing cancels the capture and edits nothing. Convert to Object Layer shares an
untouched photo's image, or captures the paint layer's raw appearance, trimmed to
its visible pixels, the same way.
A live bake prepares each step's pages in a private renderer, at most one page
per frame, before the frame that copies them into the result
(scene/bake_preflight.rs).
It evaluates its members' filters once for the whole step and keeps those images
until the step's last page. When the filters would need more image memory than
the image budget, it runs them in the bounded windows the display uses for
filters (windows::Plan), each with its filters' halos; a window's GPU work
completes before the next window allocates its images, so a windowed bake
stores the same pixels as a whole one within the budget. A bake keeps no filter
images once its step is done. Pages keep only the part inside the result's
extent, with coverage kept within 0–1, which a blur of translucent pixels can
round past. A new, empty layer that an operation writes into reserves in history
only the pages it can write (RasterRevision::pending_within).
Frequency Separation bakes Low with an attached Gaussian blur, then computes High
from the original and the captured Low with FrequencyDetail. High stores
0.5 + (original - Low) / 2 in the document's blend space; its Linear Light blend
reconstructs the original. The blur runs once, and High uses Low's native
quantization. Both layers fit one undo step because they reserve only their
pages. The dialog's blur preview is
an immutable typed preview scene supplied by CanvasEngine::set_scene_preview.
ScenePreview retains that scene and the target occurrence; it does not add an
authored occurrence or history entry to the live document.
Visible saved selections are merged into one display-only overlay texture that the presentation pass tints with. The merge works in row bands that each fit one storage binding, rasterizing each selection's coverage for the band, so any admitted canvas size can show them.
The Crop tool's shield is drawn by the presentation pass itself. set_crop_overlay
passes a CropOverlay (the map from document pixels onto the crop's unit square,
and the shield opacity) to the renderer, which folds it into the presentation
uniform. present.wgsl dims the canvas outside the crop and fills the part of the
crop beyond the canvas with the transparency checkerboard; it never samples pixels
hidden beyond the canvas. Inside the crop, the canvas presents exactly as it does
without one, including 8-bit display quantization. Without a crop the shader
skips both on a uniform flag, and a handle drag changes only that uniform and the
guide segments, so it costs a camera-change repaint. The frame, guides and
handles are ordinary CursorSegments.
The viewport is the presentation of that document at the current camera position,
zoom and rotation. The shared
ViewportPresenter samples the
composed image into the platform's target. Panning the view does not, by itself,
require repainting committed raster tiles. Only the artwork's bounding box on
screen runs the artwork shader; the surround around it draws with a shader that
computes the surround color alone (the_surround_skips_the_artwork_shader).
Presentations that initialize a target clear its entire capacity to the shared
surround, including space outside the current viewport. Enlarging the source
rectangle therefore exposes defined background pixels while the next frame is
prepared. Retained targets preserve their previous pixels until drawing replaces
them.
SdrSurfaceColor::clear_color applies the attachment's transfer, primaries and
reference white; a raw linear clear is incorrect for an encoded UNORM target.
Standalone transparent overview targets retain their transparent clear.
Before a drawing's first non-backdrop composition, the presenter shows the
surround or the previous drawing's held artwork. The canvas part contains only
the surface-sized artwork pass; chrome and cursor overlays stay live above it.
UiSession starts a 150 ms fade when the renderer reports Showing. Rapid
switches through Waiting drawings retain the original image. A size, format,
encoding or device mismatch discards it; completion releases its transient GPU
charge. GTK transfers the native child surface with the image so replacing a
worker preserves the displayed pixels.
The same held capture includes the previous meaningful Navigator image, cropped
to its surface bounds. The Navigator draws above panels within its current clip
and starts its own 150 ms fade on a full-scope refresh. Until then it holds the
old image, or shows the panel when no compatible image exists. Both parts share
one transient charge and release independently when their fades finish.
The presenter's bound paper-lighting variant and its slope programs run at Required before a lit canvas can present. The other two lit variants run at Validation after the first lit frame. Unlit canvases and standalone Navigators do not require lit viewport pipelines. Paper bake steps resume when the compiler wakes the host.
Viewport and backdrop uniforms are encoded into the frame that consumes them. An unchanged layer-style table reuses its uploaded bytes; buffer replacement or discarded commands invalidate that reuse. Camera changes preserve changed-cell masks while their cache admission and artwork remain unchanged. The shared command encoder treats passes, copies, clears and mutable raw access as resource work; its separate diagnostics accessor records only bounded timestamp work. Empty or diagnostic submissions can overlap viewport frames without hiding real artwork dependencies from native presentation.
Capture preparation includes constant-generator shader fallbacks. Exact bounds and image captures can extend outside the composition after a crop or offset; boundary tiles cannot always use a constant fill. Display startup retains its in-frame constant folding, while captures prepare the complete effect recipes before encoding on their private renderer. Scene encoding also checks each actual effect job and pending lookup dispatch. A missing recipe queues compilation and defers encoding; capture workers prepare the discovered recipes before retrying. Startup enumeration prefetches recipes and does not establish readiness for a different effect chain or capture output. Private native bake preparation shares the active parent's shader compiler. Retained preparation keeps worker ownership alive without joining shader threads on render or input teardown; cold bake jobs defer until those workers publish.
Persistent source levels record each successfully encoded reduction batch before attempting the next. A deferred decode resumes after that prefix; transient placement and streamed destinations do not acquire persistent source validity. Correction input gathering retains its remaining pages for both raster and object dependencies and keeps the correction invalid until gathering finishes. Discarded submissions invalidate the scene's cached progress. The gathering key includes dependency metadata and native roots, transform identity and damage, revision and evaluation time. Repeated identical damage retains progress. A changed paint-base storage identity retains a presentation backup during source preparation. Backups copy the actual presented views, including ready Half levels, so deferral preserves the displayed rendition.
Dab and style upload growth checks the device's buffer, storage-binding and dynamic-offset limits before replacing either GPU buffer. The preflight includes reordered duplicate dabs and validates batch ranges and source indices before staging changes. CPU staging reserves bounded geometric capacity before GPU replacement; a limit or CPU allocation refusal preserves existing GPU buffers and the style cache. GPU allocation failure follows renderer recovery.
When a view's level would need a native window larger than its Scene grant or a texture, for example a large photo with a blur at about half zoom on a 4K screen, the display presents the next coarser level that fits.
When the view is reduced, each screen pixel spans one to two texels of the
display level and reads only that level, bilinearly. A bilinear sample of the
finer level stays closer to the pixel's area average than a blend with the
coarser level until the pixel spans almost two texels, so only the last fifth
of an octave before the next level blends into the coarser one, which the next
plan then presents alone. At the tiers' Fit zooms the presenter therefore reads one
level. Reduced levels reach the presenter as Rgba16Float copies, halving what
each pixel reads. A new level texture converts in full; later writes accumulate
until the presenter converts them, once per presented frame, so painting updates
add no conversion. The presenter filters the
copies in hardware on every device
(half_float_levels_present_alike_with_or_without_float32_filtering). A copy
keeps every lane that is in range in range and every clipped lane clipped, so
clipping marks agree with the Rgba32Float level. Native views keep reading
Rgba32Float levels.
The copies never take budget from the composition: window caches keep room for
them in the source allowance and admit them from what the composition leaves,
complete pyramids admit them against the pyramid's allowance, and a copy that
does not fit leaves the presenter on the Rgba32Float level.
Object layers sample one immutable source before applying
the layer mask, attached effects, opacity and clipping. Both the native tile
compositor and the display graph evaluate this content directly; an object result
has no writable SourceTarget. SceneScope::RawObjects, ArtworkSource::Objects
and RegionSource::Objects select its internal pixels independently of the
owner's visibility, mask and presentation properties.
Object affines are composed and inverted in binary64 before projecting into a nearby output window. The image reader accepts explicit output origin and pixel density, including densities above native resolution. Source decoding precedes premultiplied working-linear interpolation. Ordered composition converts each sample into the document's blend domain at the composition boundary.
Nearest prepares exact binary64 floor coordinates on a worker in chunks of at most 65,536 output pixels. Geometry is keyed by output mapping and window independently of source identity, retained across source-tile contributions and uploaded for GPU level-zero gathers. Linear evaluates the scale-adapted tent over its complete lattice support, including transparent samples beyond the image rectangle in the normalization. Decoded immutable source tiles share the bounded source cache across objects and paint bases; affine edits keep those source entries. Object metadata includes source identity and interpretation, affine and interpolation; ordinary occurrence metadata owns visibility. Edits damage the old and new bounds with sampling and declared effect support.
Smooth display shows a temporary bilinear result from shared immutable image mip levels until the canonical result is ready, and a moving layer uses it for every pose. One fused pass samples up to 16 objects from up to eight source levels with transparent extension, so admission depends only on mip readiness, not on the window's area or object count. A moving layer never queues canonical work for a superseded pose. The source cache reserves mip storage from its byte budget. Native source preparation runs on up to three workers, each with six tiles queued, and the queue removes duplicates. An idle frame writes up to 32 prepared tiles or reductions into mip pyramids and an input frame two; both frames request enough upcoming tiles to keep the workers busy until the next frame, so a cold document with many distinct images does not wait one frame per handful of tiles. Image identity and source interpretation select the pyramid independently of object placement. Nearest continues reading level zero.
Canonical Object results sample privately across frames. A window larger than 512 output pixels per side is evaluated in equal parts. Each part retains one sampling state and output, with a conversion surface only for perceptual blending; completed parts copy into the window result. No image-child composition or private collection prefix is needed. Only complete results become reusable. A display region combines completed windows of the same layer and density and queues only uncovered regions. Private sampling storage is independent of the window size. Canonical work is budgeted in tent taps. An idle frame records up to 2²³ taps across consecutive tasks; painting and object motion pause canonical work while previews satisfy the frame, and record at most 2²⁰ taps when a frame cannot be composed without it. Each source reads every tile in its support with one dispatch, and only windows whose support crosses the image boundary evaluate the transparent samples of the normalization. Each private cache admits buffers, output textures, prepared geometry and queued metadata within 64 MiB; a window result in progress or used by the current frame is charged to the display that consumes it. Native capture-window admission counts each visible Object layer's page-aligned result footprint, so large batches use the existing bounded window planner. Live display and exact snapshot queries use separate caches, so concurrent evaluators can retain up to two such allowances. The live cache keeps completed results after their copies are encoded and evicts the least recently used ones when admission needs room; snapshot queries release results once their copies are encoded. Resources retired by an edit remain charged through GPU completion. A completed canonical result damages only its own layer's evaluated region and refreshes a complete display. Hidden owners cancel display work; raw object queries retain their independent visibility semantics. Replacing an affine retires its unfinished result. Direct coarse completion damages its evaluated density; native completion also invalidates consumers of native image inputs. Main and overview refinement preserve each other's completed pixels. Canonical captures use the authored kernel, submit bounded worker chunks and check capture cancellation between chunks. Display approximations never become capture inputs. Composed snapshot captures keep committed paint color, mask coverage and watercolor wetness in their lossless backing and decode the pages a region reaches through the bounded source cache, like cold live color. Scalar planes decode with the same reciprocal as restored pages. Native snapshot workers sample each exact image-object page inline, between the jobs of the tile that reads it, into one reusable result and accumulation, and submit after each tile that exceeds the idle tap budget. Their region plans grow with group nesting, not with the number of paint, masked, wet or object layers. A raw capture of one target restores its mask and wetness pages. Untransformed raw paint captures at the source origin select only the pages intersecting their region when watercolor is absent. Composed, transformed, shifted and watercolor captures select neighboring pages for their sampling footprints. Web snapshot workers with a browser image decoder defer pending object work to a separate exact-result cache instead. A region capture first queues the object pages of its whole capture window and defers before encoding anything until they are all complete, so one drain covers every page of a band. Each drain records up to the idle tap budget, submits and awaits GPU completion, then checks cancellation before resuming; while source tiles are still decoding it waits for them instead of submitting empty batches. Successful source commands remain in queue order during retries; histogram consumers and final readback run only after the requested pixels are complete. The live compose context follows filter input captures so those captures retain the display scheduler. Quiet retouch reads use the prepared-source worker and private scheduler with the canonical kernel. A pending read preserves its request and resumes after submitted work; it cannot decode image pixels on the initiating thread. Each attempt uploads every tile the workers have finished and records the idle tap budget unless painting or object motion is active. Object captures encode and release completed results one native page at a time. Native filter input gathers retain completed pages across these retries; a partial input never marks its filter output valid. A page waiting for decodes does not stop the gather: later pages finish if their tiles are resident and request theirs while the decode queue has room. Authored edits, new contacts and changes to input interpretation discard that unfinished gather. Before a cold live object can interrupt composition, the renderer copies the accepted viewport inputs on the GPU and retains their geometry. Physical copies are unique per source texture and mip, while logical sampling views remain available. Display reduction keeps its immutable sampler with the retained uniform-record binding; changing page bindings contain only texture views. Source uploads, paint and private sampling can submit while later filter windows await prepared image tiles. The viewport uses those retained inputs until a complete composition publishes; its evaluated object revision advances with that publication. Completed internal regions remain valid through submitted retries and release copied private results. A retry with unchanged artwork composes only the display regions the deferred frame left unfinished, and the publishing frame repaints every region the deferred frames composed. A region waiting for decodes splits into document pages: resident pages compose, and the rest request their tiles while the decode queue has room. Work that evicts a tile it already read needs more tiles than the decoded cache holds, so it splits for good: display regions into document pages, exact native batches in half. Exact native traversal keeps its direction until a traversal completes. Discarded submissions still invalidate their cache writes. Jobs that defer release their abandoned native scratch slots and material-page bindings before the next attempt. Completed GPU commands retain their resources; the reusable scratch pool does not grow with the number of cold retries. Retained pixels remain charged through GPU completion. Web worker completion wakes the host when a tile is available; native hosts retain paced pending-work polling.
Eight-bit canvas surfaces use deterministic triangular dithering after resampling and display color mapping. The noise uses logical screen coordinates and the encoded attachment domain. Noisy values are rounded to byte code centers before attachment conversion, including the decode for hardware sRGB attachments. It does not change artwork or exports. Floating surfaces, window edges, surrounding UI and diagnostic overlays retain their existing values. Source gradient dithering remains in document coordinates so saved pixels do not depend on the camera.
Browser staging allocates one reusable chunk per upload and closes the preceding chunk before another allocation. New chunks fit the upload rather than reserving the native belt's minimum chunk size. This avoids Safari's rejection of a second copy from a still-mapped buffer (wgpu #10460). Copies stay at their point of use, preserving uniform and texture reuse within a submission. Native builds continue to suballocate mapped chunks. The Safari contact-brush test checks actual rendered pixels.
Viewport presentation and staging uploads return mapping failures to their host. A device removed during buffer allocation must not unwind the render owner; the host can reconstruct its GPU while retaining the shared document session. Disabled coverage and changed-cell buffers use zero initialization without mapping during construction. Nonzero uniforms and native transfer tables return mapping failures from construction. Paint, coverage and wetness pages reset through full-destination GPU copies from immutable zero pages in the working and scalar formats. These copy-only sources avoid clear-only render passes and invalidate reused preview stamps; their storage counts toward the renderer's resident budget. Scene replacement retains its cached resources until the replacement succeeds. Optional save-preview failures leave captured project serialization available. Uploads continue to reuse the staging belt and never wait for GPU completion on the UI thread. Work submitted on its own while a frame is recording, such as native raster restoration, uses a separate belt: finishing the shared belt for it would recall chunks the frame still references and remap them before the frame submits.
Vector layers render on the GPU with the tiled coverage kernel in
vector/. For each path and
display level the CPU derives the 16-pixel tiles it covers and their fill
segments or stroke capsules; the per-layer cache in
scene/vectors.rs keeps
this geometry in a shared GPU pool, a 256-pixel grid of paths and the layer's
last rendered root. Each frame compares the root's chunks with that root and
records which paths were added, removed, changed or reordered. A stale page
then either draws appended front paths over its previous pixels or copies them
and redraws only the tiles the changed paths cover, gathering just the paths
that reach those tiles; a page where most tiles change renders whole.
Display windows derive new geometry for at most 6 ms per frame. A window that
runs out draws the paths it has once and waits; later frames derive its
remaining paths within the same budget without drawing or compositing it, and
the window repaints exactly once when complete. Pending object work keeps frames
coming until every visible path is derived, so opening or zooming a crowded
layer fills in over several frames instead of stalling one; on the Web host this
keeps the browser's single thread responsive. Exact captures, exports
and thumbnails derive everything they draw. With a vector layer visible, a new
display level first shows the level it replaces, resampled, on the pages that
level held, and when zooming out, its overview on the rest; a window that grows
at the same level during a zoom does the same. Each frame then renders at most
four of those pages exactly, nearest the view centre first and only once their
paths are derived within the frame's 6 ms
(crossing_a_level_shows_the_previous_one_resampled_and_refines_a_few_pages_a_frame).
A bake that draws vector layers, such as Merge Down onto paint or Rasterize
Layer, waits in raster_dependencies_ready until every path of those layers has
full-resolution geometry. Worker threads derive it while frames keep presenting;
the Web host derives it within each frame's 6 ms instead. The bake's regions then
draw from it, so the canvas thread derives no path while baking
(baking_crowded_paths_derives_them_off_the_canvas_thread_and_keeps_the_picture).
A blend at full opacity and unclipped over a transparent tile that nothing else
has touched returns its source, and standalone clears of single-level
Rgba32Float storage tiles and pointwise draws, including draws clipped from
their origin, run in the encoder's shared compute pass. A region of 16 vector
pages therefore records about three passes instead of five per page
(baking_a_window_of_paths_records_a_few_passes_not_several_per_page).
submission::CommandEncoder starts another wgpu encoder every 56 passes. wgpu
records each pass and its barriers into about two command buffers, and Android
destroys a command pool that held more than 128 once its work completes
(vendored wgpu), so smaller chunks keep reusing their
pools and the driver memory behind them.
A frame's coverage batches upload into one reusable buffer from the encoder's prologue, as do new geometry, so consecutive vector dispatches share one compute pass instead of alternating with copies. Geometry space that a frame may have read is retired until the next frame begins.
Derived geometry has a 256 MiB budget. Over budget, the cache drops geometry
not drawn in the last two frames, scanning the layer only when a whole level
has gone unused or it has grown by an eighth of the budget since the last scan,
so frames that draw a little keep their cost. The work-count test
frame_work_after_small_edits_and_drags_stays_flat_from_ten_to_fifty_thousand_paths
checks that idle, recolor, undo, redo and drag frames derive and gather the
same paths at 10,000 and 50,000.
The provisional line of a pen stroke arrives through set_vector_preview and
draws above the cached layer, damaging only the part of the line that changed.
A motion arrives through set_vector_motion with the moving item IDs and a
document affine, VectorMotion::transform: a translation for Move, any affine
for Scale and Rotate. The layer's graph node leaves those paths out. Where the
layer's own image is cached, it copies that image and redraws only the 16-pixel
tiles the moving paths cover at the display level; otherwise it renders the
pages without them. The moving paths render once into a texture at the display
level. When the vector layer, its groups and every layer above it blend normally
at full opacity, with no mask, attached filter, adjustment layer or clipping that
reaches down to it, the composition graph splits its root into the layers above
and everything below, the rest of the vector layer included. It caches the
layers above first, and below when the budget holds a second image, only over
the pages the moving paths cover at their start and where the transform takes
them, filling pages as the motion reaches them. Splitting or unsplitting the
graph keeps every other page, whose composite already equals above over below.
Where the moving texture has coverage, the viewport presenter draws the moving
paths between the layers above and the rest, sampling the moving texture through
the inverse affine. The composite already holds above over below, so the presenter
needs only the layers above: above + moving × (1 − above alpha) + (composite − above) × (1 − moving alpha). Elsewhere it shows the composite. A 61 MP
document at the top tier's Fit, whose display budget keeps one image of its
level, still presents a moving selection without composing pages
(width_previews_on_a_display_level_that_keeps_one_layer_image_show_the_paths_and_compose_no_pages).
When only the moving texture
changes, the presenter repaints its previous and new bounds
(replacement_previews_present_only_the_moving_images_bounds). Motion frames
recomposite no pages, and the overview and the Navigator keep the paths where they were until
the motion commits. Otherwise the composition graph resamples the moving texture
through the affine, translations rounded to the level's pixels, above the cached
layer. Moving paths draw above the rest of their layer until the motion commits,
and a scaled preview samples the moving texture, so enlarged paths look soft
until the transform commits and re-derives them
(scaled_and_rotated_paths_preview_from_their_moving_image_near_the_committed_transform).
The engine forwards the working path selection through set_vector_selection.
While paths stay selected and nothing moves, the renderer prepares their moving
texture and, for a split layer, the above and, budget allowing, below images over the square any
turn of the paths about their center reaches, a few pages a frame, nearest the
view first. Pressing selected paths then recomposites only the pages they cover,
from cached images, and draws no paths; turning them composes no pages
(turning_prepared_paths_composes_no_pages). After a display level change the
previous images stay on screen, scaled, while the new level is prepared the same
way (crossing_a_level_with_selected_paths_prepares_a_few_pages_a_frame_and_keeps_the_moving_image).
The prepared images count against the display cache budget and the moving
texture's 4-megapixel limit; images the budget cannot keep are not prepared.
Clearing the selection releases them but keeps the moving texture, and the
images of branches no longer wanted, within the branch budget; the next
selection or press draws into those instead of allocating
(pressing_selected_paths_draws_nothing_their_selection_prepared_and_deselecting_releases_it).
An unapplied style or geometry edit of moving paths arrives through
set_vector_motion_paths: the selection after the edit, in layer order and the
layer's coordinates, while a motion of those paths is set. The moving texture
redraws from those paths at its level, deriving on up to four threads only the
paths whose geometry or outline changed, into the buffers of their previous
derivation, and keeping each other derivation; a color change derives nothing
(replacement_paths_derive_only_changed_outlines_once). The layer keeps its own
paths, so a width scrub or anchor drag recomposites no pages
(replacement_paths_redraw_only_the_moving_image_and_match_the_applied_edit).
Applying the edit clears the paths and the motion along with the document change.
The headless native-document factory is currently a qualification route. GTK's exposed factory remains sRGB8 until the complete color/photo workflows and memory/ latency gates pass. Native integer8/integer16 documents use their selected RGB primaries, Float32 color working attachments and Float32 scalar coverage. Native commit publication quantizes affected pages into the declared backing depth; view transformations do not change those pages.
Native publication batches use the portable downlevel binding budget on every host: up to two RGBA tiles or one gray-alpha tile per dispatch. Tracking, pipeline indexing and upload batching share those capacities. Higher browser device limits do not select a different gray-alpha shader recipe.
Publication rejects NaN RGB and coverage outside [0, 1]. Straight RGB beyond the stored format's range, including infinity, saturates to its largest finite value: ±65,504 for half floats and the Float32 maximum for Float32. The encoder bounds associated RGB before division, handles coverage that rounds to either signed zero, and reconstructs canonical pixels from the emitted half bits and rounded coverage. Preflight applies the same validity policy. Exposure and Levels saturate their power curves to the Float32 range, so an extreme adjustment of bright HDR pixels bakes saturated rather than failing.
Gradient interpolation retains the nearer endpoint's weight from its distance and derives the other weight as its complement. Coverage stays within the two stops' alpha interval. Subtracting a rounded interpolation fraction from one can erase a nonzero weight next to a transparent stop. Zero mixed coverage returns transparent black before unassociation.
working_color.wgsl shares
unassociation, interpolation and perceptual conversion across scene composition,
effects and materials. working_unassociate, working_ratio and
working_has_color treat alpha below the smallest normal Float32
(WORKING_MIN_ALPHA) as empty. Vulkan does not define division by smaller
values, and smudge and blender pickups drive faint halo alpha that low within
one stroke: a GPU that keeps denormals returns NaN there, and the pickup
spreads it. The publication checks and resampling filters use the same
threshold. Material passes clamp the alpha they write, and wet and watercolor
passes the canvas alpha they deposit over, to [0, 1], treating smaller alpha
as transparent. The Perceptual working_encode and
working_decode keep their positive-alpha test: they run for every composited
pixel, and any further test in them measurably slows painting on Mali-G52.
Native scene/image interpolation uses explicit Float32 texel loads.
Before interpolating extreme components, the sampler scales both endpoints by
one binary exponent and bounds the result to their interval before restoring
that scale. Opposite finite HDR endpoints cannot overflow their difference.
Layer pixels are linear document RGB, independently of bit depth. Layers
combine in the document's blend space: linear document RGB, or
the document's encoded values in a Perceptual document. Each blend mode states
its own bounds; see Blend modes. Region tolerance uses encoded document RGB
weighted by coverage, independent of display/checker colors.
Paint color mixing (mix_color in
material_transport.wgsl:
Smudge and blender pickups, the Wet reservoir exchange and Watercolor's
same-layer exchange) follows the brush's Color mixing choice (ColorMixSpace),
never the document's blending. The choice is a style uniform, so no brush
pipeline is specialized for it:
- Oklab converts through linear sRGB/D65 (including document-white adaptation), uses signed cube roots, then returns to document primaries without a blanket negative-RGB clamp.
- Linear light mixes linear document RGB.
- Classic mixes values encoded with the document's own transfer curve
(
sdr_encodeandsdr_decodeinsdr_color.wgsl), as Clip Studio Paint does.
A mix at either endpoint returns that operand exactly in every space.
Watercolor keeps its water activation threshold as a material-model parameter. That threshold no longer rejects faint native pigment. Native transport constrains coverage while retaining extended RGB between commits; it does not clamp RGB to alpha. These helpers are not a claim that all brush dynamics and nonlinear tone controls are fully qualified.
view_color.rs converts the
composition to explicitly declared sRGB, Display P3 or extended-linear sRGB view
coordinates. Surface format controls output transfer encoding. Application colors
in viewport overlays retain their sRGB definitions. Export/Navigator thumbnail
readbacks are explicitly sRGB8; exact color samples retain document RGB. Native
profiled delivery is a separate output conversion and is still being integrated.
LayerBlend has 24 pixel blend modes and Pass Through for groups. Each variant's discriminant is its code: Normal,
Multiply, Screen, Add, Overlay, Soft Light and Color are 0 to 6, and Darken to
Luminosity follow from 7. Documents store the variant name, not the code.
LayerBlend::MENU groups the modes as Photoshop does (Normal, darken, lighten,
contrast, inversion and component modes) for the menus described in
shared UI.
blend_modes.wgsl holds every
formula, on straight colors. blend_composite puts a source over its backdrop,
and blend_clip blends a clipped source inside its base's coverage.
blend_layer selects either behavior with a shared blend evaluation for scene
and display composition. These helpers serve every place a layer's blend applies:
- layers, groups and common-base clipping runs (
scene.wgsl, op 4); - effect interpolation, preserving or filtering alpha as declared
(
fx_adjustmentandfx_filterineffects_color.wgsl); - region and scale composition, including transform previews
(
scene/scale/compose.wgsl); - brushes with a blend mode other than Normal (
material_brush.wgsl), with the brush's mode mapped to the layer mode of the same name. The Normal brush keeps its direct source-over form because the general expression draws dark contact edges on an Adreno Vulkan driver.
blend_code passes a blend to shaders as the mode's code in bits 0-7, the
Perceptual blend space in bit 8 and float documents in bit 9. A layer's Normal is
always 0; a brush sets bit 8 for Normal too, because its dabs lay over paint in
the document's blend space (brushes).
Pass Through has no pixel blend formula. The shared traversal in
scene/stack.rs composes a group's layers
onto a running composite, so a Pass Through group
(documents) continues its parent's
composite with its own layers, and a composition that stops before a layer
(stop_before) stops inside it too. At opacity below 1 or with a mask, the group
retains the backdrop and then fades to its result,
backdrop + opacity × mask × (result − backdrop). Exact tiles and reduced graph
expressions evaluate the same weighted sums and coverage product. Direct clipping
and effect attachment require an explicitly isolated group; admission rejects a
Pass Through group with those relationships.
Ranges. Float documents clamp no result. Modes defined only on [0, 1]
(BlendRange::Unit) clamp their operands to [0, 1] in every document, and float
documents leave them out of their menus; a layer that already uses one keeps it.
| Mode | 8- and 16-bit documents | Float documents |
|---|---|---|
| Normal, Multiply, Darken, Lighten, Difference | Unbounded | Unbounded |
| Add | At most 1 | Unbounded |
| Subtract, Linear Burn | At least 0 | At least 0 |
| Linear Light | Clamped to [0, 1] | At least 0 |
| Pin Light | Clamped to [0, 1] | Unbounded |
| Divide | d / max(s, 2⁻¹⁴), at most 1; a zero source gives 1 over any color and 0 over black |
d / max(s, 2⁻¹⁴) |
| Screen | s + d − s·d |
s + d − min(s, 1)·min(d, 1), which keeps rising above 1 |
| Overlay, Soft Light, Hard Light, Color Burn, Color Dodge, Vivid Light, Hard Mix, Exclusion | Unit | Unit, not offered |
| Hue, Saturation, Color, Luminosity | W3C ClipColor |
ClipColor without its upper bound |
Soft Light is the W3C formula in Linear documents and Photoshop's in Perceptual
ones: with backdrop a and source b, 2ab + a²(1 − 2b) where b ≤ 0.5, else
2a(1 − b) + √a(2b − 1). Hard Mix is 1 where s + d ≥ 1, which matches
Photoshop's threshold of Vivid Light. The component modes use W3C SetLum,
SetSat and ClipColor with the luma weights of the document's primaries (the Y
row of their XYZ matrix). Bit 8 selects Rec. 601 weights, for Photoshop parity
on encoded values in the Perceptual space.
Existing documents. These rules change how some saved documents look:
- Color layers weigh luminance by the document's primaries instead of Rec. 601, in every document, and no longer clip above 1 in float documents.
- In float documents, Add no longer clamps at 1, Screen follows its extension above 1, and Overlay and Soft Light clamp operands outside [0, 1].
- Unit modes clamp operands outside [0, 1] in 8- and 16-bit documents too; there only effect layers produce such values.
The oracle every_blend_mode_matches_the_reference_on_every_path_and_depth
checks every mode against an independent reference through each path above at
8-bit, 16-bit, half-float and float depths, in both blend spaces at 8 and 16
bits, and checks that export renders the same composite.
A document's Blending (Document.blend_space) is Perceptual or Linear
light. Layer pixels are linear premultiplied in both. In a Perceptual document
the composite holds the document's encoded values, premultiplied:
enc(c / a) · a, where enc is the document's transfer curve (sdr_encode with
WORKING_SPACE): sRGB for sRGB and Display P3, 563/256 for Adobe RGB, and 1.8
with a linear toe for ProPhoto. Only 8- and 16-bit documents blend perceptually;
float documents are Linear. FramePacket.scene.composition().blend supplies the
domain to the renderer, and a change recomposes everything.
Normal layers keep hardware premultiplied blending, which is correct on encoded values. Blend modes, clipping, masks, opacity and groups work on the encoded values directly. Scene draws convert behind a uniform; effect shaders are compiled once per blend space, because a branch in every filter pixel costs a Linear document time. Either way a Linear document runs the arithmetic it ran before the setting existed. Resampling stays linear: layer pixels are sampled or reduced first and converted after.
Writers. These put layer pixels into the composite and encode them:
- scene draws of layer pixels:
scene_spaceinscene.wgslandscene_constant.wgsl, selected by the draw'sConvert(ops 1, 7, 12, 13, 14 and 15, and the mask-area tint, op 5). A Flow preview lies on its layer's pixels before they are encoded, as its committed stroke will; - placed layers and watercolor layers, which the renderer draws linear first
and then converts in one draw (
Scene::converted); - effects (
effects.rs): a filter that reads linear values receives decoded input and its result is encoded before it blends onto its input, inline in fused chains and in the last pass of an image filter. A filter that follows the document's Blending (filter spaces) reads and writes the composite's encoded values with no conversion; - constant fill colors and backdrops, encoded on the CPU
(
BlendSpace::composite); - drag frames that draw a moving layer into the display
(
display_resample.wgslanddisplay_maininpixel_transform/display.wgsl), which encode the layer's resampled color whenDisplayLevel::encodeis set.
What holds the composite. Group and clipping scratch tiles, retained display windows and their mips,
image-filter outputs and checkpoints
(scene_images), retained graph branches, the folded constant backdrop, and the backdrop
and result a Pass Through group fades between hold the document's composite
values. Their caches include the blend space
(ImageStages, artwork::Frame and the retouch reference cache's key). An image
filter's input window is captured once per pixel in the filter's declared space:
decoded for a filter that reads linear values, as the composite holds it for one
that follows the document's Blending. Adjacent filters share an image only when
the upper one reads the composite as it is.
Readers. Each decodes where it needs linear values:
| Reader | Where | Reads |
|---|---|---|
| Canvas presentation, Navigator, color picker loupe, screen check, backdrop blur | canvas_linear in present.wgsl and present_screen.wgsl |
decoded before proofing and SDR or HDR mapping |
| Export and snapshot rows, Copy and Copy Merged, histogram, color conversion previews | Scene::capture_region in snapshot.rs |
decoded per tile |
| Eyedropper, Wand and Fill on the composite or the reference layers, tonal selection, whole-image readback | artwork.rs captures |
decoded |
| Clone Stamp, Healing and Spot Healing: the reference layers below the target | reference cache in retouch_sources.rs, captured through artwork.rs |
composed in the document space, cached decoded; retouch_source in retouch_sample.wgsl lays the target over them in the blend space |
| Filter previews | the preview tiles in filter_preview_tiles.rs |
decoded; encoded once more for filters that follow the preview scene's Blending, whose previews decode their result |
| Merges | scene/bake.rs |
composed in the document space, stored decoded |
| Image filter input windows | capture_tile in scene_images.rs |
decoded, or composite values for filters that follow the document's Blending |
| Layered display during drags | scene/scale/compose.wgsl |
composite values; blends with the document's blend code |
| Layer thumbnails, brushes | layer pages | linear layer pixels, not the composite; brushes encode them to lay dabs over them (brushes) |
The export matte, and resizing on export, apply to the decoded rows in linear light.
Layer pixels stay linear, but in a Perceptual document a dab lays over paint on
the document's encoded values, as in Photoshop and Clip Studio Paint: soft edges,
opacity and flow build up in the blend space. source_over in
material_brush.wgsl
serves the dry deposit and coverage passes, the retouching deposit, the Wet
deposit and Watercolor's final deposit; the pass encodes a destination pixel the
first time a dab deposits on it, lays the dabs over it, and decodes it once. Dry
dabs are uploaded with their colors already encoded (prepare_colors in
dry_material.rs), so no
pixel converts a dab's color.
At native resolution, in-place uniform Normal deposition checks retained stroke
coverage before reading color. Fully covered pixels keep their existing color;
the coverage pass still copies their scalar coverage into its next output.
Stroke starts, bristles and other blend modes retain their ordinary evaluation.
Brush blend modes call the layer formulas in the same space, so an Overlay brush
matches an Overlay layer. The brush's blend code carries the space (bit 8), a
uniform, so no pipeline is specialized for it. Edged brushes that Linear light
documents draw with hardware blending (BrushPassPlan::direct) run the material
pass instead, and their kernels compile before pen-down. DabStyle.blend_space
is the document's Blending for artwork and Linear for masks and selections; a
stroke keeps the space it started with for replays.
These stay the same in both spaces: erasing, which scales color and alpha together; paint color mixing, which follows the brush's Color mixing choice; Watercolor's pigment transport; Liquify; and wet or burnt stroke edges.
Watercolor batches updated tiles in three ordered transport steps. Missing pages stay in the batch when neither native color backing nor the original image covers them. Reading an original through the mutable decoded-source cache closes the preceding batch, then consumes its borrowed views before another neighborhood can evict them.
Healing (heal.wgsl) computes
its tone correction in the document's Blending: the membrane matches B − S on
encoded values in a Perceptual document and is added to the copy there.
Spot Healing scores its candidates on linear values in both spaces.
The compositor combines paint and object layers, groups, masks, clipping and blend modes. Its scene code tracks damage: regions whose previously rendered pixels are no longer valid. Stroke-finalization passes, including healing and wet edges, invalidate every page they revisit. Destination storage, redraw regions and reduced source caches use the same stroke coverage pages, including pages far from the final dab.
Eligible paint stacks use region and scale composition. The scene retains source levels across camera changes and moves. Reduced views compose at the requested resolution; native views fill a bounded viewport window and reuse its overlap while panning. A lone affine source over a constant backdrop can be sampled directly by the presenter and Navigator. These display pixels never become document, history or export backing.
A simple paint update rasterizes new dabs into the relevant layer pages and recomposes affected regions. More complex layer structures need intermediate results. The renderer retains those results and tracks their dependencies so, for example, changing a clipping layer does not force unrelated source images to be rebuilt.
Attached adjustments receive their owner's masked content, followed by the preceding attached effects in bottom-to-top order. An owner's completed local result enters ordinary blending or common-base clipping once. An unattached adjustment receives the lower stack through Pass Through groups up to the nearest isolated scope. Only an unattached completed spatial result can checkpoint a stack prefix; a local result belongs to its owner.
Cache dependencies use occurrence handles and local chain inputs. Moving an unrelated row retains valid spatial stages; a downstream parameter edit keeps valid upstream stages. Source changes retain separate rectangles through placement, filter support and page invalidation, so distant contacts do not invalidate the pages between them. Masks branch from the same dependencies at their boundary. Invalidated branches reuse retired textures with the same region and resolution, clearing their valid regions before evaluation. Parameter edits replace cached pixels without allocating another full-size intermediate image.
Image-stage caching handles operations that need reusable image inputs. A blur needs pixels outside its output rectangle, so filter definitions describe their sampling footprint. Global effects, layer reordering and invalidated caches can require much larger updates than a single brush mark. Visible animated effects also need updates without new pen input; hiding an attached effect's owner stops those animation requests.
Pointwise filters declaring display-resolution support use effect nodes in the shared region graph. These nodes reuse the same fused shaders as native tiles; changing a parameter invalidates the effect result while retaining unchanged paint inputs. Masks are sampled in the output grid and shader positions remain document coordinates. Exact queries evaluate document-resolution pixels. The exact presentation executor remains for other effects and persistent watercolor. Active paint transforms use the shared region graph. A transaction captures immutable original tiles and reduces its moving pixels and any unselected remainder once per input level. Whole-layer transactions can reuse a current reduced source. The scene's resampler places these inputs into requested graph regions, with opacity and a constant backdrop folded into the same pass. Groups, masks, clipping and other blends use the ordinary composition rules and branch cache. Mask transactions still evaluate native coverage before that composition.
Large paint previews keep a level-one source pyramid and bind at most 48 original source-page coordinates for each output region. The planner retains its exact sampling geometry and classifies at most 48 regions per frame; unfinished subdivisions resume without changing the accepted display. Partial output stays private until its region is complete. A matching existing fine source keeps its admitted capacity; new allocations still pass budget admission. Fine-source preparation requests every missing coordinate in the admitted region and copies ready pages into the atlas before yielding for pending decodes. Copied pages remain resident without requiring the decoded-source cache to hold the whole region at once. Native spare pages and superseded outputs remain charged until their submitted GPU work completes. Bounded fine inputs wait for retiring spare pages before they are allocated; a preview that leaves native pages for an ordinary display level draws in the same frame. The Scene grant includes live and retiring fine resources, frame workspace and the optional complete display pyramid. Presented views stay pinned; pressure can discard the other pyramid levels.
Display reconstruction selects prefiltered source detail from the local transform footprint. Split selections and footprint boundaries use four samples; partial edge texels retain their actual centers. Mesh triangles draw color directly into the graph target, with later triangles replacing earlier ones where the mesh folds. Reconstruction remains approximate while a transform is active. Native views evaluate native preview pixels; exact queries materialize the source tiles their dependency window reads and retire previous query tiles. Apply evaluates the authoritative transform, and Cancel restores only native pixels that a preview or query changed. Each of these decodes every original page its jobs read before it changes a page. When those originals outnumber the free decoded slots, the transaction copies them into its own pages in batches that fit, keeping completed batches across frames, and later poses draw from those copies without decoding. While a native preview waits for its pages, the canvas keeps the last drawn pose, and the frame that draws the preview recomposes every page it changes. There is no separate placement-drag composite or post-release settling queue.
A transform job binds at most TRANSFORM_SOURCE_PAGES source pages.
ImageTransform::fits_source_pages bounds the pages any destination pixel reads
from its read domain, including Float32 evaluation error. Drags, transform
operations and whole-layer Apply plans refuse a pose beyond it, so Distort keeps
the last pose short of collapsing a corner onto its neighbours' line. Native
previews read moved pixels only within the selection's bounds and plan every job
for a layer and its linked mask before changing a page. A plan that still
exceeds the binding keeps the last drawn pose without a frame error.
Move's Leave Copy retains the original under the moved selection. Selected and
unselected captures reconstruct that original without another image allocation.
While Move is active over a selection, prepare_moving_pixels names the layer
and selection for the next press. Idle frames prepare those inputs within the
composition budget, and the transaction adopts them only while their source
identity and selection match. Painting, restoring or leaving Move releases
prepared inputs. There is no post-release settling work.
A Warp transform is a mesh of Bézier patches with explicit source breakpoints. Exact splits subdivide whole rows or columns with de Casteljau; reopening and mode changes never refit controls. An outer homography follows the mesh. Source lookup uses the same row-major triangle order as rasterization, with the later triangle winning at folds. Regional draws use that window's ordered triangles; draws spanning windows use one copy of each triangle in original order. Its pages are drawn a window of four by four pages at a time: the mesh, tessellated within half a pixel and extended by a skirt past its edges, is first rasterized into a texture of the source position at each destination pixel, and the transform pass samples the original there, averaging a pixel's footprint from its neighbors' positions where the mesh shrinks it. A region job unions the source pages reached by each clipped triangle independently, including neighboring positions and interpolation support. Folds retain separate source neighborhoods; pages in the rectangle between unrelated branches consume no bindings. Traversal stops when the portable view limit requires another destination split. Large flat triangles still split into jobs within that limit. Paint, masks and a selection's moved pixels draw this way in the preview and when applied. A drag rasterizes the mesh at the display level's texels instead, tessellated within half a texel, and resamples the reduced copy at those positions. A pixel selection moved by a warp is resampled on the GPU the same way, a window at a time. What draws meshes compiles in the background when a warp is first shown. Frames wait for it like the transform's other pipelines, so the canvas keeps the frame before it and then draws the current warp, including a drag released before the compile finished.
The transform pass
samples premultiplied linear pixels and their selection together. Nearest
takes the pixel under the sample. Linear is bilinear. Bicubic is
Catmull-Rom over 4 × 4 taps and Lanczos is Lanczos-3 over 6 × 6 taps with
normalized weights; both clamp their overshoot to the range of the four nearest
taps, keep colour at most alpha times the brightest straight colour among them,
and clamp scalar planes to [0, 1], so neither rings past the edges it sharpens.
Where the map minifies, a destination pixel instead averages a grid of bilinear
taps spread over its footprint, as many per axis as source pixels it spans. Each
record carries a cap on that count: drag previews use at most four, and commits,
still previews that Apply may keep, and exact capture use up to sixteen, derived
from the map's Jacobian. A reduction to an eighth therefore averages every
source pixel, as an area reduction would, instead of aliasing. A moving
Bicubic or Lanczos preview draws bilinearly until it stops.
Transform programs compose shared source-access, mapping, filter and output helpers. Each device caches only requested affine, projective or mesh variants and their selected filter; a tap cap of one omits area sampling. Identity copies omit mapping and filtering. Mesh/filter selection follows the effective geometry, including source adapters. Matrix values, dimensions and tap limits stay uniforms. Frame readiness receives the immutable preview and prepares its actual variants before submitting it. The same choice selects capture and command pipelines.
Exact capture (export, snapshots and the artwork readback) evaluates image objects with their saved kernel through the uncapped object sampler. Layer reads for sampling, Wand, Fill and selection coverage use layer offsets and image placements in document coordinates. Raw target bounds retain their local coordinates. Display composition uses the scene's reduced source levels, aligned with the document's texels at every whole-pixel offset. Transform previews reduce their captured layer with the same alignment. Moving sources keep a level finer than the projected pixel footprint. Mesh footprint planning reuses the scene's cached tessellation, and source preparation and regional composition share the resolved footprint. Layer offsets stay integers until each placement record subtracts its page origin, so layer tiles, watercolor neighborhoods and snapshot regions copy whole pixels at every admitted offset. Admission counts the allocated vertex and index buffers; source magnification bounds preserve the signed Bézier derivatives. Affine display sampling counts taps independently along each output axis, preserving edges under uneven scaling, and accounts for partially covered edge texels. The direct Navigator subdivides footprints larger than its retained coarse source can represent with one sample grid. Placed pigment and scalar pages share that sampler through batched compute dispatches, including each region's clear and clip. Mapping, watercolor on a transparent target and reduction share ordered compute batches; scratch pages can be reused after their reduction. Their pipelines are prepared with the document. Projective display resampling uses the same mapped sampler in the existing compute batches. Aligned source reduction evaluates watercolor material only beside wet pages, including the existing neighboring-page halo and current prediction. Other pages reduce their ordinary color inputs directly, so first contact on an empty layer does not clear a material scratch texture for every page of the document. Display resampling and composition share ordered batches too. A placed layer over a constant backdrop resamples directly into its final output.
Material coverage clips mesh triangles to the raw material's source bounds before mapping them into document space. A small wet area therefore requests only the regions it reaches, including the interpolation border.
Placed watercolor maps raw pigment and scalar wetness into document coordinates before evaluating its material appearance. The existing watercolor pass reads the center and four cardinal neighbors of both planes, so edge widths remain document-sized under nonuniform scale. Visible-content bounds include that destination halo. Masks, opacity and blending follow that evaluation. Reduced display levels reuse cached raw pigment and add the material appearance difference within the wet region and its halo. One reduction subtracts the already mapped pigment from the native appearance, converting each first in Perceptual blending, so dry photo pixels keep their cached values. Complete native blocks in Linear blending use the existing Float32 sampler to average four texels per tap. Power-of-two texture dimensions keep these samples exactly centered; partial edges, preview blending, color conversion and float-document material differences retain per-pixel reduction. Subtracting before averaging preserves small HDR corrections. Moving sparse wet paint does not rebuild the full native canvas. An active placement keeps the same raw source representation when it crosses the identity pose. Each cached source level records its color and material representation. Returning to ordinary display can retain a finer raw level within the existing budget; reopening Transform repairs its changed pages instead of decoding the whole photo. Source-pixel damage invalidates retained levels independently of composition interpretation changes. Reduction and direct sampling reuse only matching representations. Neighbor mappings share at most 64 scratch pages within a frame. Neighbor color is mapped only where wetness can contribute, and the material pass borrows that color only for empty centers. Tiles outside mapped wetness bounds take the pigment-only path. Display and snapshot admission include this bounded scratch allowance. On devices without Float32 attachment blending, a source over a newly cleared transparent target renders directly into that target; only an existing backdrop needs the portable blend pass.
Applying a whole-layer transform uses the same raw-plane sampler and native tile encoder. Its private snapshot captures Color, existing WatercolorWetness and linked Mask separately, preserving watercolor metadata without allocating absent wetness. Mask-only jobs omit color. Raw masks read authored scalar coverage directly, using their default coverage for absent pages, without scene composition. Preparation uses those same planes and only their publication variants. Immutable publication recipes share the device; scratch grows only to each capture batch, and results belong to each capture. Private outputs need no promotion back into their disposable source textures. Publication never refuses pixel values: NaN color stores as zero, alpha and coverage clamp to 0–1 (NaN to zero), and infinite color saturates at the edge of the storage range. One bad sample cannot fail a capture or stop painting. Affine captures use source occupancy and the existing conservative filter footprints to skip output pages that equal zero. Imported bases and raster overrides both contribute; nonzero-default masks and other mappings retain full capture. Output domains and origins remain unchanged. Web raster workers receive the page's immutable compiled WebAssembly module in their first request, then instantiate it only when an operation needs Rust. Each worker retains its own memory and GPU device; retiring a worker does not require fetching and compiling the application again.
The shared session publishes one replacement after every output tile succeeds. Cancellation, renderer replacement and failure discard that private result. A scalar-only mask bake uses that worker and preserves its owner, default coverage and inversion. A linked mask is resampled through its owner's map, so applying the transform bakes the owner and mask together. The capture freezes each input's local extent before growing the output canvas, so default mask coverage and hidden source domains do not change during a bake.
Filters are effect occurrences in the document. Attached adjustments process one paint occurrence or isolated group after its content mask, bottom to top, before owner opacity, blending and outer clipping. The base's locally filtered alpha is the common clipping shape for every member of its run. A member's local effects process only that member; effects on a containing isolated group process its completed inner composition. Hidden owners hide their complete chains, and hiding an effect bypasses it without changing ownership. Unattached adjustments process the lower stack and cannot split a clipping run. Generators produce ordinary content rather than attached processing.
At Normal blending an effect mask and opacity interpolate premultiplied input and
result, including alpha for programs declaring EffectAlpha::Filter. Full strength
returns the filtered result once. Spatial effects can expand coverage beyond the
owner's original shape; masks and clipping outside that owner constrain the
completed result at their own boundaries. Declared sampling support governs
capture halos, damage and window budgets along actual dependency paths.
A runtime filter consists of a JSON definition and WGSL shader code. The definition describes its parameters, inputs and execution requirements. Shared code validates it, supplies the control descriptions and prepares the GPU pipeline. The same runtime handles built-in and imported filters.
Curves and Gradient Map retain specialized Rust interpolation and lookup-table preparation. They should not be used as examples of a filter that can be expressed entirely by adding a JSON/WGSL pair.
The runtime filter reference is the contract for implementing a filter. The Tent Blur example provides a small package to study.
A pointwise adjustment computes each output pixel from the input at that position.
Compatible chains of these adjustments are fused into one shader invocation by
the compute or fragment variants in
effects.rs. Each adjustment can
consume the previous one's result without writing it to a texture first. Ordinary
aligned masks can be sampled in the same shader, preserving each effect's mask,
opacity and blend rules. Binding limits and incompatible operations can split a
chain into separate passes.
This reduces intermediate allocations, memory traffic and pass setup. Some composition steps can also be folded into the effect shader, and tile draws that share an attachment can share a render pass. Fusion changes execution, not the order or scope of the layer operations.
Filters that sample neighboring pixels need a different path. The image-stage implementation retains reusable GPU images, tracks input changes and reuses compatible preceding results where possible. Signed document regions retain dependencies before zero and beyond the composition frame. Unsigned texture rectangles describe only bounded allocations. Region capture walks upstream pass dependencies, expands the requested region by each pass footprint, and clamps reads at that pass's true finite support. Directional Gaussian passes retain their mapped axis footprints; large saved kernels can reuse finite edge tails without allocating empty halos. Native captures rebase their signed window into local tile coordinates with an exact 64-bit scene offset; the display graph carries signed regions through source requests, sampling and damage expansion. Retained paint bases remain readable when a capture's source has no live mutable layer pages. Identity paint sources clip the signed request to their finite domain before adding the existing mip halo and page alignment; interpolation padding applies only to transformed sources.
Effect modules share the scene vertex interface without unrelated scene fragment operations. Validation checks the complete authored interface before Naga's reachability analysis removes unused function declarations from the submitted WGSL. Authored modules with attributes retain their complete declarations and dependencies. Pipeline keys include blend mode and identity reference axes; parameter values and translations remain buffer data. Sampling prepares finite support once per pixel and keeps fractional-grid and reduced-edge reconstruction intact.
Compute preparation admits workgroup storage from the validated entry point's statically used variables, including calls. Each variable's WGSL layout size is rounded separately to 16 bytes before comparison with the device limit. Unused entry points and variables consume none of that entry point's allowance; unresolved override-sized arrays cannot pass this check. Shared device limits request 16,384 workgroup bytes when the adapter supports them, retaining the 16,352-byte minimum. Levels Auto fits that minimum on every device: 4,088 workgroup bins and eight counters per lane combine into its 4,096-bin shards.
The composition frame, bake destination and temporary image edge do not limit source reads. Global filters request the finite retained input domain, subject to the same allocation allowance and GPU dimension checks. Output, current-pass input and original input carry their own region and texel footprint through the shared image-grid descriptor. Filter sampling clamps at the declared finite input support; samples beyond an allocated dependency window are transparent. Reduced inputs use the centers of their actual covered cells, including partial boundary cells. Native composition batches up to sixteen source tiles even when a full display pyramid is not admitted. A working image holds at most sixteen page slots, using several rows for narrow documents; each reduction reads its own document-space offset. Admission includes its one to sixteen MiB, according to document dimensions. Full pyramids retain their destination and receive changed rectangles from that image. Root reductions share one compute pass per batch, then update the adjacent display level together. Sparse batches reduce only their covered source rectangles.
Filter-picker previews use the same coordinate contract. Native one-to-one image reads use fragment positions directly, avoiding a window-size-dependent interpolation error from reconstructed UV coordinates.
Filter previews never read the document. Every row shows its filter on one fixed
scene: twelve by two matte ceramic tiles baked into
filter_preview_tiles.rgba, a
768 × 128 preview document whose outer corners are already rounded, so filters
treat the corners as transparent edges instead of hosts clipping their result.
Built-in filters ship that result as 480 × 80 lossy WebP files in
apps/layer-web/filter-previews. Every host
shows them at the row's full width and the strip's 6:1 shape, decoding off the UI
thread, so opening the drawer runs no GPU work. AdjustmentChoice::bundled_preview marks rows whose definition matches the
built-in catalog. Installed and custom filters render live on the same tiles:
the renderer uploads them once in its working space, and the atlas draw
box-filters each result down to the same 480 × 80 row. Filters that analyze
their input build one private guide from the tiles and reuse it until the drawer
hides. Document edits and document changes keep delivered rows; painting only
pauses unfinished work. Accepted requests stay pending while their shaders
prepare, including across render-thread transport. Admission retries after
sixteen milliseconds without repeating the idle delay. Rows without full-source
analysis publish first; analysis-dependent rows run individually afterward.
The tiles come from a generator in
filter_preview_tiles_tests.rs.
After changing it, or a built-in filter's shader or preview parameters, rerun
cargo test -p layer-render-wgpu write_filter_preview_tiles -- --ignored and then
cargo test -p layer-render-wgpu --features bake write_bundled_filter_previews -- --ignored.
filter_preview_tiles_match_their_bake and bundled_filter_previews_match_their_bakes
fail while the files and their generators disagree; the second compares 4 × 4
pixel averages, which tolerate the encoder's half-resolution colour. Global samplers
retain their full declared input. Live display composition uses bounded windows
and reduced sources; native-resolution filter dependencies execute through the
same region executor and publish into that display cache. Native filter images
and display pixels share one composition allowance. Oversized global dependencies
are rejected before a frame changes the document. See
display composition for admission, moving
previews and exact idle refinement.
Analysis reservations and retained guides use the renderer's Other grant. Admission counts retained and incoming resources together; work above the grant is refused before allocation.
Native filter windows admit output sections up to 2048 pixels per side against the complete halo and image-storage bound, falling back to smaller page-aligned sections when needed. Each section retires its temporary images after queue completion. Larger admitted sections reduce overlapping halo work and repeated source composition without raising the memory allowance.
The native snapshot renderer
prepares document metadata independently of the live display cache. A file or
inspection worker owns an immutable ArtworkCapture or scoped SceneSnapshot
and a native Float32
renderer. Content-bounds capture rebases the signed scene offset while retaining
the original composition frame and authored effect mapping; its output allocation
may include retained off-frame images and filter support. Bounds remain signed
integers until the legacy Rect result rounds outward, so distant finite images
retain conservative nonempty hulls without claiming Float32 pixel precision. Region requests restore
only the translated paint, material and mask pages needed by composition and its halos. Compressed backing remains shared;
restoration uses the same integer decoder as live editing. Initial masks use the
existing GPU crossing/coverage and affine-resampling shaders, with bounded
output rectangles and row slices of immutable packed selection coverage.
Waiting for pending raster roots or selected tiles observes worker cancellation;
retiring a reader leaves the producer's publication available to other readers.
Exact artwork samples use the same snapshot worker and region admission. Their typed source selects visible artwork, reference composition, placed layer content, an adjustment's input, or a substituted gesture baseline. Input scope is applied after region preparation, which resets composition state. Raw layer content skips its mask, opacity and effect stack. A request retains immutable backing and a frozen animation time; native snapshot handles also retain effect clocks, while Web serializes the captured phases to its worker. Reference composition uses the shared relationship closure, retaining referenced group contents, clipping bases and attached effect chains. Selection, color sampling and histogram queries resolve the same reference membership.
The GPU reduces a circular footprint in two passes: covered RGB/alpha maxima and normalized sums. Only a 32-byte summary reaches the CPU, which unscales it in f64 and validates the returned straight RGB. Covered transparent pixels affect mean alpha but carry no color weight. Empty and outside results are distinct. Calibration uses these linear samples; the paint picker's Oklab average remains on its existing request path.
Histogram uses GPU reductions on the same immutable queries. Preview samples a
256-by-256 stratified grid in original document coordinates; Exact visits every
pixel. Prepared source windows cover at most 1024-by-1024 pixels and split under
the capture budget. Exact submits at most sixteen native 256-pixel tiles before
waiting, while retaining cancellation checks and budget-driven window splitting.
Source preparation is shared by the tiles in each bounded window.
Four channel histograms and coverage/clipping counts occupy a 4 KiB readback;
no full-resolution image reaches the panel. A pixel with alpha of at least
WORKING_MIN_ALPHA counts once. Smaller alpha, tested by its bits, is
transparent here and in Auto Levels, as in composition and Float32 publication,
so GPUs that flush subnormals give the same counts. Nonfinite color rejects the
result. RGB bin boundaries use exact ratio comparisons, and ambiguous luminance
boundaries use a separate wide integer reduction so ordinary pixels avoid its
register cost.
Waveform optionally extends that same scan with four 256-by-256 count planes. Columns preserve document x; rows use the histogram's existing RGB and luminance bins. Eight GPU counter shards add 8 MiB of scratch, and their final fold adds a 1 MiB summary. Histogram-only requests allocate neither. The immutable result shares its histogram with both panels; only Waveform's changed result, channel, scale or theme regenerates its small display image. No source pixels are read back. Web transfers the count planes as one typed buffer from its snapshot worker. Incremental UI publication retains graph and image objects on status-only changes; shared Rust prepares channel normalization and straight or premultiplied RGBA for the native drawing API. A successful browser analysis worker and its same-color GPU pipelines can serve the next request; at most one remains idle, for five seconds. Cancellation and failures retire their own worker, and a Wasm heap over 256 MiB is released after its result transfers. Concurrent requests retain separate cancellation owners.
Auto Levels has a separate two-pass GPU summary: encoded extrema and 4096 bins per channel over each channel's observed range. Both summaries share bounded source capture and fold cumulative GPU counters once per pass. Each pass submits at most sixteen native tiles before waiting. The extrema readback still precedes the bin pass, which uses those observed ranges. RGB queries apply channel stages before master; individual queries inspect the original adjustment input. Shared Rust selects the .1% and 99.9% nearest ranks from those bins, with value error at most range/4096, validates the candidate and commits once. Explicit calibration and Auto preempt live statistics. Hidden panels release statistics and resume only on demand; old owner, page, source and device results cannot publish.
Local tone and Dehaze guide reductions wait after at most four captured regions, flushing pending work before retrying a budget-limited region. Local tone anchor passes retain GPU ordering and share the final completion wait. Dehaze batches dependent rank passes before its required airlight readback, then batches the refinement passes before publishing its bounded guide.
Snapshot PNG/TIFF output streams sixteen-row strips through the working-color
encoder and profiled row writers using borrowed WorkingRowsOptions. Gain-map
JPEG and AVIF share borrowed GainMapRender settings and generic row callbacks.
A matching, unmodified source with default
conversion and no matte bypasses composition to preserve exact integer samples,
including hidden straight RGB. An explicit matte composites in linear document
RGB before encoding. Region captures return linear-premultiplied document values;
they contain no viewing or mask-area overlay. Cancellation and writer failures
return errors; the caller must publish its temporary file only after success.
Capture dependency plans have an explicit byte ceiling checked before restoring pixels. This planning limit is separate from measured peak process/device memory, codec buffers and retained compressed sources. Global samplers can exceed it and still need their scheduled, qualified route. Snapshot capture/output is currently a headless worker API; GTK export UI, progress/cancellation ownership and recipes still need integration. This does not yet replace live composite residency.
Committed edits queue exact readback of changed 256² tiles for raster history and persistence. Mapping and lossless compression run on a bounded worker; GTK input never waits on the GPU. Move frames and presentation do not perform full canvas readback. The exposed host export still requests a full image; the native snapshot API streams bounded strips. Thumbnails and color sampling use separate bounded requests. Source bytes and immutable compressed tile backing are shared with save snapshots. See the artwork capture and package contract.
MemoryBudget shares RAM and
device allowances across owners. Owners report physical bytes, pins and demand;
class order and max-min distribution assign grants. Unified GPU allocations
count in RAM once. New-byte admission reserves headroom after pins and pending
imports; saving and validating already-owned artwork uses structural limits.
The renderer partitions its display owner among Scene, Objects, Mips, decoded
GPU tiles and Other. Retention demand is capped at 608 MiB for Scene, plus the
complete pyramid when hierarchy-eligible; Objects gets 128 MiB, Mips and decoded
GPU tiles share 1 GiB, and decoded RAM samples get 512 MiB. Image-window work adds
Scene planning demand without raising retention ceilings. Pins and working floors
remain protected under pressure. Requested mips pin their roots and in-flight work.
Idle after-present trims release unused storage against the grants.
memory::memory_tests checks pressure, working floors and retention ceilings.
Stats copies timestamped OS and driver readings from the factory's memory worker, which samples every second even while Stats is closed. Linux and Android report process RSS and its OS peak; Windows reports private commit and its lifetime peak; Apple reports physical footprint and the highest sampled footprint. GPU readings cover the selected Vulkan device-local heap, DXGI process usage in local memory and its budget, or Metal allocations and its working-set recommendation. These are raw readings, separate from cache admission allowances. Limit, tracked, pinned and debt rows come from the shared ledger. Missing queries, including browser process memory, remain unavailable. Process and GPU readings can overlap and are not additive. Canvas storage remains tracked renderer allocation, excluding driver overhead.
Live composite color samples and region classification retain their frame while cold image-object captures prepare on workers. Polling advances prepared GPU sampling without inline source decoding or GPU waits. Region classification retains completed batches across deferred captures; cancellation discards the unfinished request before a replacement can publish.
A paint layer's thumbnail frames and draws one reduced image of the layer: the
smallest power-of-two level at which the pages it holds fit 256 × 256 texels,
each texel keeping the bounds of the painted pixels under it and their average
over those bounds. Framing reads those bounds, so it is exact to the pixel even
when the content covers a few texels of mostly transparent pages, and drawing
shows a texel only inside them, so an edge that crosses a texel stays solid
instead of thinning toward the checkerboard. A preparation reduces up to 48
changed pages into that image, one pass per page, and keeps the image across
revisions: a page is reduced again only when its committed tile or, for a page
without one, the artwork revision changes, so a stroke re-reduces the pages it
touched and a fill of a 24 MP layer is reduced in 8 preparations. Content that
grows past the image reduces the layer again at a new level. Photo layers, masks
and moved layers keep the four-page budget across original photo tiles, painted
overrides, alpha-bounds scans and thumbnail drawing. Incomplete images stay
private. Artwork revisions, selection paint and SDR rendition changes
invalidate prepared work; discarded command buffers invalidate their cache
entries. Each host poll advances one request; up to eight partial
requests can be retained, and layers sharing a photo reuse its integrated
original contributions. Generator thumbnails share the filter-picker
preview execution path, sampling document coordinates on a grid of at most
32 × 32 pixels. They compile asynchronously and retain at most two temporary
images per request. Object-layer rows frame the layer's own objects in linear
light on a grid of at most 256 × 256 pixels: from the canvas's prefiltered image
levels when every object has them, otherwise from one exact collection evaluation.
Thumbnail work that leaves decoding or sampling for the canvas schedules a frame.
The native JSON reply carries canvas_wake; pollers forward it even when the
editor snapshot is unchanged. Its wait_ms hint yields while the canvas is busy
and services bounded preview batches promptly at idle. Windows uses the same
delay for binary thumbnail polling and checks capy_needs_frame after each
binary preview or workspace query, preserving any
existing frame request before the worker waits again. Shared layer revisions
include generator parameters, so all hosts request new pixels after a parameter
edit or undo. Content requests use
occurrence IDs; mask requests use encoded coverage source IDs. GTK, Web and
native bridges share ThumbnailTarget::from_wire_id to decode both targets.
On unified-memory hardware, CPU and GPU share physical RAM. Keeping separate copies solely to move an image between processors can waste both memory and bandwidth; older pipelines built around discrete GPU memory need to account for this. Apple's image-processing guidance describes those costs and the opportunities to remove redundant copies.
Here, "GPU resources" describes how the renderer accesses the pixels, not a requirement for separate VRAM. Textures still have access rules and layouts, and CPU/GPU coordination still matters. Capy Canvas keeps the drawing pipeline in GPU resources through composition and presentation; imports, readbacks and platform APIs may still need staging or copies.
Pages, masks and display images are Rgba32Float or R32Float on every device;
only the presenter's copies of reduced display levels are Rgba16Float, which
every device filters. Two optional features change only how the renderer reads
and blends the others:
- Filtering. Layout entries that receive Float32 textures use
bindings::float_texture, and shaders read them withsample_float(image, sampler, uv, level).PipelineDevice::float_sampling_wgslsuppliestextureSampleLevelwhen the device can filter Float32 textures, and otherwise bilinear and linear-mip interpolation from four texel loads per level with clamp-to-edge addressing. A9–A16 iPads, the iOS simulator and several Android GPU families take the texel path. 8-bit tips, grain, paper and the presenter'sRgba16Floatdisplay levels keep hardware filtering everywhere. Renderer tests run the texel path on any GPU throughWgpuRasterizer::native_headless_without. - Blending. Without Float32 blending,
portable_blendreplaces fixed-function attachment blending with a compute merge.
Hosts request both through layer_render_wgpu::rendering_features, which keeps
only the bits the adapter offers.
The GPU fallback plan lists the remaining feature requirements.
GPU preparation is staged so the platform can display its controls first. Startup prepares the canvas, then the open document, then the selected brush and eraser; unused brushes and filters compile on first use (shader readiness). Required dependencies are ready before drawing uses them, so pipeline creation never lands in a small stroke update. A contact that begins before its brush is ready follows the shared input admission policy. Frame admission includes the display-scale recipes used by the first backdrop. They prepare before its submission, allowing hosts to present that backdrop before starting document and brush preparation. Preparation follows the resolved drawing target, including its paper binding, mask, alpha lock and blend space when a fill remains selected. A paper texture change holds early contacts until the new texture is ready, then replays each contact once. Switching between compute and fragment material routes also invalidates brush readiness. Changing paint color or HDR intensity leaves brush readiness intact when the tip, texture assets and shader pass requirements stay the same.
Headless capture compiles the dependencies its requested regions execute. Creating a read-only snapshot does not compile paint-publication kernels. Interactive brush readiness still prepares those kernels before accepting paint.
On Web, GPU initialization waits for the workspace (at most 1 s), and pipelines
are created through the asynchronous WebGPU APIs, a few at a time: synchronous
creation blocks Chrome's GPU process and display callbacks even when JavaScript
yields between jobs. Each recipe shares one asynchronous preparation result;
encoding requires that result to be ready. Edits wait in the existing ordered
input queue, and snapshot jobs prepare their dependencies before encoding.
The Web --pipeline-readiness journey checks this contract on page and worker
devices; see the Web testing guide.
For brush-specific passes, continue with Brushes. For performance work, use the measurement guide.