Skip to content

armgit / klad

Public Imported from GitHub
0

A drawing app built for agent/human collaboration

Rust

DESIGN: drag previews and how vector patches are drawn

Indicode BV444f73d3edd0
diff --git a/docs/DESIGN.md b/docs/DESIGN.md
index 08fad53..f7c6b06 100644
--- a/docs/DESIGN.md
+++ b/docs/DESIGN.md
@@ -1,4 +1,4 @@
-_Last updated: 2026-11-07 15:00_
+_Last updated: 2026-11-07 16:20_
# klad: design
@@ -444,7 +444,7 @@ Scripts are any language that prints edit ops as JSON lines into `klad apply`. G
- Stroke select (S, M2): a click picks the mark you see under the pointer. With "all layers" (the S and V options and Edit > Pick from all layers, `pickAllLayers` in the settings, on by default) that is on the topmost visible, unlocked paint layer that shows paint there, which becomes active: a layer shows paint where its raster's alpha, times its own and its groups' opacity, outside its mask and inside its clip base, passes 5%, and a layer whose pixels are not loaded counts by its marks' shapes (`Scene::seen_at`, `Scene::marks_at`); with "this layer" it is the active layer. In that layer the mark is the topmost one covering the point (inside a stroke's painted width or a fill's coverage, never an eraser stroke), and only when none covers it does one within 5 pt of the point count, so a thin line is still easy to take (`markedit::pick`); when no layer shows paint there, the topmost mark within those 5 pt on any of the layers is taken. A shift click adds or removes on the active layer, a dragged loop picks every stroke whose samples are all inside it and every fill whose pixels are, shift adds or toggles. With "a lasso cuts strokes at its edge" (on by default) the loop also takes the parts of strokes and fills crossing it: the selection shows the dashed lasso and the parts that will move, and the first edit (move, recolour, delete, ...) writes one `lasso` op that splits them, after which the selection is the moved marks. The selection shows as thin lines and a box with corner handles (uniform scale), edge handles (stretch one axis; dragging past the other edge flips) and a rotate knob; dragging moves it on the GPU (the selected marks drawn alone, over the cel replayed without them) and release writes one `transform` or `lasso` op. Layer settings recolour (the current colour), makes thinner or thicker, sets opacity, flips left-right or up-down and deletes, each as one history step. The selection is shared with the agent as addresses.
- Layers (M2 batch 4): layer settings sets clip to the layer below and lock alpha, adds a mask (empty, or hiding all), turns it on and off, removes it, and "paint on the mask" makes the mask the active layer (it also has its own row under its layer). Painting on a mask hides the layer under the strokes; the eraser shows it again. While a mask is active, what it hides is tinted red ("show the mask in red", on by default), and the brush panel says whether the brush or the eraser is on. The brush and fill tools record lock alpha from the active layer.
- Live previews and clipping: the editor composes the active layer between cached images of everything below and above it only when that is exact (the active layer and the groups around it are not clipped, masked or a clip base); otherwise each dirty tile composes the whole stack. A drag (a shape with V, strokes with S or V, any grab: move, scale, turn, stretch, an alt-drag copy) previews the edit it will commit: at its first move the editor takes a snapshot of the document and the pixels (tiles are shared, so this is cheap), and while the pointer moves a background job applies the drag's ops in memory, redraws only the tiles they change (vector nodes through the tile patching below, strokes through the cel's replay) and composes those tiles through the whole stack, so clips, masks, blends, group effects and everything above the dragged thing stay exactly right. One job runs at a time and the newest pointer position wins; only tiles on screen are composed while dragging. The composed tiles go straight to the canvas plane, which is shown while a preview is up. On release the edit is written at once (it costs only its tiles), a last job composes the final position, and its tiles are taken as they are when the edit only moved vector nodes; tiles the preview touched that the edit did not are composed again. In a lean scene, while a mask is tinted, or before the canvas has caught up, a drag shows only its outline and lands on release.
-- Vector edits redraw only their tiles: a changed vector cel whose node order is kept is patched where its changed nodes were and are (their bounds grown for strokes, miter joins, blur and generator instances; added, removed and hidden nodes count), drawn on one surface that holds every node touching those tiles so no node is cut at a tile edge and the tiles are bit-identical to a full rasterization; a new order, or a node without bounds, redraws the cel. A swapped vector raster (an edit, undo or redo from the remembered rasters) dirties only the tiles whose pixels differ.
+- Vector edits redraw only their tiles: a changed vector cel whose node order is kept is patched where its changed nodes were and are (their bounds grown for strokes, miter joins, blur and generator instances; added, removed and hidden nodes count), drawn on one surface that holds every node touching those tiles and starts on a tile boundary, so no node is cut at a tile edge, big blurs downsample on the same grid, and the tiles are bit-identical to a full rasterization; hidden nodes and nodes without bounds draw nothing and are left out; a new order, or a node without bounds, redraws the cel. A swapped vector raster (an edit, undo or redo from the remembered rasters) dirties only the tiles whose pixels differ.
- Switching the active layer rebuilds only the caches below and above it: when the canvas was complete for that frame and revision, onion skins are off and no mask is tinted, the canvas plane is kept instead of composed again.
- Composed tiles and frame pictures reach the GPU through an outbox the paint callback empties, holding the newest version of each tile: a UI pass that egui discards (a grid or popup laid out for the first time) drops its paint callback, and the tiles it carried would otherwise never be uploaded.
- Direct select (A, M2): click a path, rect or ellipse (inside groups too) to show its points; clicking the selected shape again steps down to the next shape under the pointer, and layer settings list them all; click or shift click points, drag on empty canvas for a box; drag points or handles; alt click the outline adds a point, alt click a point toggles corner and smooth, alt drag a handle breaks it; delete removes points; layer settings have corner, smooth, delete points, simplify and "make it a path". While dragging, the edited outline is drawn live; on release the edit is one `path` op whose layer is rendered in the background, then swapped in.
@@ -454,7 +454,7 @@ Scripts are any language that prints edit ops as JSON lines into `klad apply`. G
- Fill tool (G, M2): click fills inside the lines of this layer, all visible layers or a chosen layer, with gap, tolerance, expand and opacity settings; drag a loop to lasso fill.
- Gradients in layer settings (M2): a shape's fill switches between none, solid, linear and radial; gradients edit their geometry and stops (position, colour, add, remove).
- Canvas mipmaps (M2): every uploaded tile brings its own mip chain (box filtered on the CPU, down to one pixel per tile), so zoomed-out views sample trilinearly instead of shimmering.
-- Frames (M3): the canvas, painting, fills (their reference at that frame), selection, lifts, notes and the shared selection all work at the current frame. Painting paints into the drawing exposed there (on a link into its source, which the timeline says), and painting on a blank frame starts a drawing there. `,` and `.` step a frame, alt `,` and alt `.` jump to the previous and next drawing on the active layer, Home and End go to the first and last frame. The scene keeps drawings loaded across frames, so going back to a frame only recomposes it; a frame with drawings not loaded yet loads in a background frame job while the last frame stays on screen (drawings a job loaded before the document changed are not kept, and load again when needed; see the frame cache below). Drawings away from the current frame drop their replay checkpoints, and beyond 1 GB the least recently shown are evicted; a drawing changed from outside while it is not shown is evicted and reloads when its frame comes back.
+- Frames (M3): the canvas, painting, fills (their reference at that frame), selection, drag previews, notes and the shared selection all work at the current frame. Painting paints into the drawing exposed there (on a link into its source, which the timeline says), and painting on a blank frame starts a drawing there. `,` and `.` step a frame, alt `,` and alt `.` jump to the previous and next drawing on the active layer, Home and End go to the first and last frame. The scene keeps drawings loaded across frames, so going back to a frame only recomposes it; a frame with drawings not loaded yet loads in a background frame job while the last frame stays on screen (drawings a job loaded before the document changed are not kept, and load again when needed; see the frame cache below). Drawings away from the current frame drop their replay checkpoints, and beyond 1 GB the least recently shown are evicted; a drawing changed from outside while it is not shown is evicted and reloads when its frame comes back.
- Timeline panel (M3), along the bottom: a frame ruler with the playhead, one row per layer top first (groups fold, a mask row opens under its layer with `[m+]`), each cel a block across its exposure (drawings blue or green for vector, links purple marked `->c1`), blanks empty. Click a cell to go to that frame and layer; drag on the ruler or on empty cells to scrub; drag the right end of a block to change its exposure (later cels of the layer move); drag a block by its first frame to move it. Buttons, the context menu and keys: new drawing (K), duplicate to the next frame (the copy is placed after the exposure, later cels move back), show a drawing here (a link, picked from the layer's drawings), unlink, delete, hold longer and shorter (`=` and `-`), insert a frame (I, shift for every layer) and remove one, fps and length fields, "+ paint" and "+ vector" layers. Every action is one op and one history step. A row of playback controls sits above the buttons: play, the loop range (drawn orange on the ruler), onion skin and its settings, the shift K exposure, and the dropped frames of the last play; each layer name has an onion dot at its right end.
- Onion skin (M3): O turns it on and off; "onion settings" in the timeline sets before and after, drawings or frames, opacity, falloff and tint; the dot at the right of a layer's name in the timeline shows that layer's onion too (the active layer always shows its own while onion is on). The scene composes the onion rasters (the same `klad-render` code as `--overlay onion`) when the frame, the active layer, a marked layer, the settings or a drawing they show change, and loads the drawings they need with the frame. The active layer's onion is part of the cached image of everything below it, so painting with onion on composes exactly what it composes without; marked layers' onions are drawn inside the below and above caches. The eyedropper and fills never see the onion.
- Frame cache and stepping (M3): the frame shown is the scene's frame (painting, the timeline and the agent channel all use it), and moving to a frame only sets it. What the canvas plane (the live, tiled GPU texture) shows catches up separately: at once when the frame's drawings are loaded and no cached picture of it exists, else 150 ms after the last step, or immediately when the pen touches the canvas. Meanwhile the frame cache shows the frame: one GPU texture per distinct picture (8-bit, premultiplied, with a CPU-made mip chain), at display resolution (the power-of-two level that the zoom needs, full size at 100% and closer), keyed by a hash of everything the picture depends on (the layer tree at that frame, the version of every drawing it shows: stroke file hashes and node hashes, the onion's ghosts when onion is on, the brushes and the level). Holds and links share a key, so they share a texture. A picture is composed by a background job that loads the drawings it is missing (kept in the scene afterwards, under the 1 GB drawing budget) and composes all tiles; at most two jobs run, plus one for the frame you just moved to. After a step the next 4 frames in that direction are composed ahead. The cache is capped at 640 MB, least recently shown first out; after every change the pictures no frame's key names any more are dropped, so an edit costs only the frames it changes. While the frame you stepped to is not on screen yet, held-key repeats are ignored (a fresh press still counts), so a held `.` shows every frame. While a mask is active with its red tint, frames are not cached.