Skip to content

Free, open-source 3D sculpting for Linux, macOS and Windows: dense meshes, remeshing, painting, built-in AI (image/text to 3D), Send to Unreal, game-ready LODs, Gaussian splats and OpenUSD.

Merge origin/integration/next (zero-latency, hw-profile, micromesh, pbr) into feat/kelvinlet-alpha

islandmed27cd8cea8dcc
diff --cc CHANGELOG.md
index 3e67057d,6e12166a..4d96ad41
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -7,41 -7,137 +7,172 @@@ All notable changes to SculptForge are
## [Unreleased]
### Added
+ - **Micro levels: hundreds of millions of sculptable polygons** (**Tool > Geometry > Micro**, `micro_*`
+ commands). Above the highest subdivision level a SubTool can carry a micro level: per triangle a regular grid of
+ 16-bit heights along the interpolated normal of the smooth (Phong-tessellated) base, instead of a mesh.
+ 300 million micro triangles take 374 MB (1.25 bytes each; the whole app about 0.8 GB), where a mesh of that size
+ would need about 27 GB. Unlike ZBrush's HD Geometry the whole model is sculptable at once.
+ - Brushes: Standard, Clay, Clay Buildup, Smooth, Inflate, Flatten, Trim, Layer, Pinch / Crease / Dam Standard
+ (as height sharpening), Mask; symmetry, Focal Shift, pressure and the mask apply. Big brushes are evaluated on
+ a coarser grid and interpolated (scale-adaptive). Move reshapes the base below the micro level and the detail
+ rides along (dual scale); "Move along normals" moves the micro surface itself.
+ - Viewport: the micro surface is evaluated on the GPU per frame, with a level of detail per cluster and a
+ triangle budget (2M on a laptop profile, 8M on a workstation, `RenderSettings::renderTriangleBudget`), crack
+ free; the shading keeps every micro detail. 300M micro triangles orbit at 70+ fps with 4x antialiasing (M1 Pro).
+ - Bake Micro (to a mesh), Export Displacement (32-bit EXR or 16-bit PNG, scalar or vector, over the base UVs).
+ - Undo: a packed journal per stroke (tiles in Morton order, each tile's change predicted and packed).
+ - Very large levels stay out of core in a sparse memory-mapped file (only what you touch is in memory).
+ - Projects: format 7 when a SubTool has a micro level (others stay format 6 for older versions).
+ - `sculptforge --bench-micro --bench-sizes 33,100,300` measures it. Guide chapter "Micro levels".
+ - Automatic hardware detection and calibration. On first launch, and again when the graphics card, its driver or
+ the version changes, SculptForge spends about a second or two (under a small overlay; Esc skips) measuring
+ triangle throughput, upload bandwidth, brush speed and memory bandwidth, and probes the GPU (OpenGL strings,
+ video memory through GL_NVX_gpu_memory_info, GL_ATI_meminfo, GLX_MESA_query_renderer, amdgpu sysfs, DXGI or
+ CGL), RAM, threads, SIMD and OS. The result picks a profile: **Laptop / Budget**, **Workstation** (64 GB+ RAM
+ with a 16 GB+ discrete GPU, or Apple Silicon Max / Ultra and big APUs, that measure fast) or a **Software** safe
+ mode for llvmpipe, with a render triangle budget, motion proxy
+ threshold, GPU memory and upload budgets, texture, subdivision and micro-triangle limits and the thread count.
+ Cached in the settings folder; no network use. A one-line status bar message says what was found.
+ - Preferences > Performance shows what was detected and measured ("Detected <GPU>, <memory> -> Workstation"),
+ the settings in effect, **Re-calibrate** and manual overrides (kept across re-calibrations).
+ - An adaptive frame governor holds the view at 60 fps (120 / 144 on a fast display) while it moves, by switching
+ big scenes to their motion proxy sooner or later, with hysteresis; it changes only what is drawn, never the
+ model. Fast Navigation's 10 million triangle threshold now comes from the profile.
+ - On battery (laptops), brushes switch to draft mode, uploads per frame halve and the target is 60 Hz.
+ - `sculptforge --calibrate` prints the profile as JSON (schema sculptforge.calibration/1); commands
+ `performance_profile`, `calibrate` and `set_performance_override` for the console, scripts and MCP.
+ - For developers: `core/TierConfig.h` (resident cache cap, active-triangle budget, upload budget, draft brush
+ mode, zero-copy UMA, target Hz) and `renderTriangleBudget()` for the renderer and micro-displacement
+ (docs/performance.md, "Hardware profile").
+ - Material painting (PBR): a painted texture can carry Roughness, Metallic, Normal, Height (16-bit), Ambient
+ Occlusion, Emissive and Opacity besides its colour, all painted in the same strokes. Turn channels on in
+ **Tool > Texture Map > Material Channels** (`texture_channels`); a channel costs no memory until it is painted
+ (64x64 copy-on-write tiles; untouched tiles aren't stored). **Color > Material** sets what the brush lays on
+ each channel (material swatches, per-channel value swatches and sliders; `paint_material`), and **C** picks the
+ whole material under the cursor. Paint layers hold every channel: channel chips on each layer row turn a
+ channel on or off for that layer, and give it its own blend mode and opacity, including **Normal Combine** for
+ normals (`texture_layer_channel`). Height also yields a normal combined onto the Normal channel. One undo step
+ per stroke, kept per layer and channel. Auto UV, Voxel Remesh, QRemesh and merging SubTools carry every channel.
+ See the guide's Material painting page.
+ - Solo channel view: **Tool > Texture Map** shows one channel on the model (roughness and the other scalars in
+ grey, the normal as colours, emission in colour), live while painting (`channel_view`).
+ - Export Maps with presets (`export_maps`): Unreal (`T_*_BC`, `T_*_N` in DirectX, `T_*_ORM`), Unity URP and HDRP
+ (mask map), glTF, Godot, Blender (one file per channel) and USD, plus your own JSON presets (the guide's Export
+ presets page). Height maps are 16-bit PNG.
+ - Model exports wire the channels into their materials: glTF metal-rough slots (packed occlusion / roughness /
+ metallic, normal, emissive, alpha from opacity), UsdPreviewSurface inputs, the MTL PBR keys and FBX material
+ maps. Send to Unreal imports `T_<Name>_BC / _N / _ORM` and builds an `M_<Name>` material from them.
+ - Preferences > Performance and `perf_info` show the memory of textures and their material channels.
+
+ ### Changed
+ - Texture painting on dense meshes costs the texels a dab reaches instead of the triangles under it: the brush
+ finds the texture tiles under it from the BVH and paints each texel from a cached triangle-and-barycentrics
+ map, tiles in parallel. A 0.35-radius dab with X symmetry on a 21M-triangle sphere: 4K 150-360 ms -> 24-39 ms,
+ 8K 240-350 ms -> 39-55 ms (M1 Pro, ranges over a busy and a quiet machine); results match the old dab within
+ 1/255. Lighter meshes keep the per-triangle dab. No first-dab stutter: the UV bins are shared by every texture on
+ the same UVs (undo steps, copies) and built in parallel when painting starts (about 45 ms at 21M), the area under
+ the hovering brush is readied before it lands, and a stroke into a fresh area stays under 20 ms at 4K.
+ Preferences > Performance counts these caches.
+ - Project format 7 stores material channels. It is written only when a texture has them: other projects are
+ still saved as format 6, and every older project opens as before.
+ - **Sculpt Timeline**: every stroke and operation is a tick on a strip along the bottom of the canvas. Drag the
+ scrubber to see the model at any point of the session, click a step to go there. Sculpting from an earlier
+ point no longer throws the later steps away: they stay as a branch (a lane above the track) you can switch
+ back to, with undo / redo working on the active branch as before. Right-click a stroke to re-tune its strength
+ (0 removes it, 2 doubles it) without redoing the strokes after it; where later strokes overlap it they keep
+ their own displacement on top (they aren't sculpted again; see the guide's Sculpt Timeline chapter). Seeking
+ reuses undo's per-stroke deltas, swaps runs of strokes at once with one normal / BVH / GPU update, and jumps
+ from full checkpoints every 16 steps (within 1 GB; fewer on huge meshes) for long seeks. Each SubTool keeps
+ its own timeline. Commands `timeline_info`, `timeline_seek`, `timeline_select`, `timeline_retune`,
+ `timeline_save`, `timeline_load`; UI test timeline.
+ - **Save with project** (in the timeline's header) also writes the history beside the project as
+ `<name>.sfhist` (strokes, masks, polypaint, visibility, polygroups, branches, re-tuned strengths; a topology
+ change cuts it). Opening the project brings it back when the mesh matches. The project format is unchanged.
+ - **Export timelapse**: the history rendered as a turntable video, the model building up stroke by stroke while
+ the camera goes once around it (1080p or 4K MP4, no captions; needs ffmpeg). Also
+ `sculptforge project.sfproj --timelapse out.mp4 [--size 3840x2160] [--timelapse-seconds 20]`.
+ - **Proof mode** (**Help > Benchmark**, `sculptforge --benchmark`): a scripted 240 Hz pen stroke through the
+ same input handlers a real pen uses, with a 60 px and a 240 px brush and a turn of the view, on 5, 20 and 33
+ million triangle meshes (100 million when free memory allows). A live HUD shows fps, frame time p50 / p95 /
+ p99, how far the stroke trails the pointer (ms and px) and memory; the run is recorded to an MP4 with the HUD in
+ it and written as a JSON result with the processor, graphics card, memory, OS, version and commit.
+ `docs/benchmark.md` describes the format, `tools/benchmark/submit.py` checks results and adds them to
+ `website/benchmarks/results.json`, which the new benchmarks page lists.
+ - The brush cursor follows the surface (#25), as in SculptGL: over the model the Draw Size and Focal Shift rings
+ lie on the surface under the pointer, turned to its (smoothed) direction and pressed onto its shape, at the
+ brush's real size there, with a short normal line; with symmetry on, a fainter mirrored ring shows too. Every
+ brush (sculpt, paint, mask, dynamic topology). A few dozen BVH ray casts per drawn frame, no pass over the mesh
+ (0.09 ms on 5M triangles), and the idle view still draws nothing. **Preferences > Input > Cursor follows
+ surface** (on by default) brings back the flat screen rings.
+
+ - **Predictive Strokes** (Preferences > Performance, on by default): a sculpt stroke's brush is worked out on its
+ own thread while the view keeps drawing at the display's rate. The dabs not finished yet are drawn as a GPU
+ preview on the surface (each brush's kernel in the vertex shader, with its shading and cavities), and the brush
+ cursor and the stroke's head are drawn where the pen will be a frame later. When a dab's result reaches the GPU
+ it replaces its preview in the same frame. Lifting the pen never waits. The finished sculpt is the same, bit for
+ bit, as with it off (`--measure-stroke` with `SF_MEASURE_VERIFY=1` replays the stroke and checks undo).
+ Painting, masking, dynamic topology, Move, Snake Hook and the drag strokes work as before.
+ - **Draft Strokes** (Preferences > Performance, off by default; meant for laptops and battery): with Predictive
+ Strokes, the brush only moves the surface during the stroke; normals, cavities and culling bounds are worked out
+ once when the pen lifts.
+ - `tools/bench_strokes.sh`: the big-brush stroke benchmark on 5M, 21M and 33M triangles, one build or two
+ interleaved (docs/performance.md). `new_sphere triangles=N` makes a sphere of about N triangles.
+ `--measure-stroke` reports frame p95 / p99, the preview's lag, and when the first and last dab reach the screen.
+
+ ### Changed (predictive strokes)
+ - Big brushes on dense meshes no longer slow the view. `tools/bench_strokes.sh`, 200 px brush, M1 Pro shared
+ with other builds (load 9-45, so both columns are slower than on an idle machine; A/B interleaved):
+
+ | | 0.9.7 frame mean / p99 | Now | Brush on screen behind the pointer, 0.9.7 / now | Press | Release |
+ |---|---|---|---|---|---|
+ | 5.2M | 47 / 134 ms | 8.4 / 14 ms | 95 / 1 px | 98 -> 24 ms | 31 -> 0 ms |
+ | 21M | 71 / 651 ms | 8.8 / 18 ms | 37 / 1.5 px | 623 -> 14 ms | 1 -> 0 ms |
+ | 33.6M | 169 / 323 ms | 12.2 / 27 ms | 245 / 4 px | 315 -> 13 ms | 374 -> 0 ms |
+
+ With 60 and 240 px brushes at 21M and 33.6M the p99 frame is 11-31 ms (0.9.7: 26-636 ms). The solved surface
+ itself still trails as before; the preview covers it (docs/performance.md, "Predictive strokes").
+ - Packing a stroke's vertices for the GPU no longer walks every vertex's neighbours again: the cavity term comes
+ from the normals pass. Clusters a stroke moved get quick culling bounds, made exact when it ends.
+ - `Mesh::recomputeAllNormals` (new meshes, undo of big changes, timeline seeks) runs in parallel.
+
+ ### Fixed (predictive strokes)
+ - A big brush that raised the surface past the GPU's position grid stalled the view for seconds on dense meshes
+ (the whole mesh was re-packed inside a frame); it is re-packed on the brush thread now.
+- **Kelvinlet brushes**: physically based elastic brushes from the regularized Kelvinlets of de Goes & James
+ (SIGGRAPH 2017): the exact displacement of an elastic solid under a softened point load, so the surface moves
+ like clay pushed with a thumb, with no falloff edge. **KelvinGrab** (an elastic Move: tri-scale kernel, 1/r^5
+ falloff), **KelvinTwist** (press and drag right to turn clockwise around that point; every ring turns rigidly,
+ so volume is kept), **KelvinScale** (drag left to pinch, right to swell; integrated as a radial flow, so it never
+ folds through the centre) and **KelvinSnake** (a multi-scale SnakeHook whose pull narrows as it travels, so
+ horns taper by themselves). **Brush > Kelvinlet & Capture**: **Squash** is Poisson's ratio, from rubbery (0) to
+ incompressible clay that bulges around the thumb (100); **Sharpness** a tighter, cusped peak with the same
+ reach. Symmetry (the twist mirrors as a pseudovector), masks, hidden parts, sculpt layers, pressure and undo work
+ as with every brush. Each move touches only the points inside an adaptive cutoff (where the move is still more
+ than 4% of its largest, the last part faded smoothly to 0), evaluates the kernel from a radial table, works out a
+ fast drag in pieces in one pass, and passes on only what moved to undo, normals and the BVH. KelvinGrab and
+ DetailClone are on the bottom shelf; all five are in the brush picker, the LightBox and the `stroke` command.
+ On dense meshes a long move is applied at most about a brush radius per frame (the rest in the next frames),
+ the far field is evaluated on a coarse lattice and, over 400k vertices, deferred to a world lattice that a
+ sixth of the vertices take each frame (all of it when the stroke ends), and the cutoff tightens up to 10% of
+ the peak over a vertex budget. Twist and Scale at 33M / 50 px: 57 ms frames (was 110-280); KelvinGrab still
+ about 190 ms there (renderer sync), see docs/performance.md.
+- **Capture from view** (<kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>C</kbd>, askNK's request): drag a square (Shift: a
+ circle) over any sculpted detail and get, side by side, a **grayscale height alpha** (height toward the viewer
+ over a fitted plane, normalized, optionally detail-only) and a **vector displacement map**: each point's true 3D
+ offset from a smooth base (the broad form as a fitted quadric, the rest by implicit fairing with the rim held),
+ in the base's own tangent frame, so overhangs and sideways leans come along. Options: Base Smoothing, Edge Fade,
+ Resolution, Fit plane, Invert. **Use as Alpha**, **Use as VDM**, **Detail Clone** or **Save to Library** (the
+ alpha as a PNG in the LightBox Alphas folder, the VDM in the brush library; VDMs now show in the LightBox Brush
+ tab with their thumbnails). Commands `capture_alpha` and `capture_vdm`.
+- **DetailClone** brush: stamps the VDM brush's map along the stroke, one copy every stamp width (Clone Spacing),
+ each turned to follow the stroke (Clone follows stroke) and shaped to the surface under it; a click stamps one.
+- `new_bench_sphere millions=N` makes the benchmark's sphere of N million triangles (with subdivision levels),
+ and `SF_MEASURE_BRUSH=<brush>` makes `--measure-stroke` measure another built-in brush (`SF_KELVIN_LOG=1` logs
+ each Kelvinlet move: pieces, vertices, kernel / normals / BVH milliseconds).
+- Tests: tests/test_kelvinlet.cpp (kernel normalization and far-field cancellation, divergence against Squash,
+ bulge, exact twist, pinch without folding, symmetry, mask, undo, sculpt layers, threads, Detail Clone, the
+ captures with a VDM round trip within 9% RMS and a curved-surface capture; a dense-mesh timing check with
+ SF_BENCH_LIMITS=1) and the UI test kelvinlet_capture.
## [0.9.7] - 2026-10-31
diff --cc docs/performance.md
index 1c622dc9,3d2d1a93..2175ae29
--- a/docs/performance.md
+++ b/docs/performance.md
@@@ -12,90 -12,348 +12,432 @@@ sculptforge-cli --bench ..
Machine for all figures: Apple M1 Pro (8 performance + 2 efficiency cores, 32 GB unified memory, 30 GB usable
under Asahi Linux), integrated GPU, Mesa 26.1 (OpenGL 4.6). How the benchmark works is described under v0.5 below.
+ ## Next version: predictive strokes (feat/zero-latency)
+
+ A stroke on a heavy mesh used to run in the frame loop: each frame placed a dab (45-50 ms at 21M with a 200 px
+ brush), re-packed what it moved for the GPU (about 28 ms) and only then drew. Now the brush runs on its own
+ thread and the frame loop only commits what it finished, so the view draws at the display's rate whatever a dab
+ costs; what the brush hasn't finished is drawn ahead of it by the GPU.
+
+ ```
+ tools/bench_strokes.sh [-s 5,21,33] [-n RUNS] [-r RADIUS_PX] BINARY [BINARY_B] # A/B runs interleaved
+ ```
+
+ It runs `sculptforge --run SCENE --measure-stroke 3,R` (a fast two-turn circle, X symmetry) on 5.2M
+ (`new_sphere subdivisions=8; subdiv_divide`), 21.0M (two Divides) and 33.6M triangles
+ (`new_sphere triangles=2100000; subdiv_divide; subdiv_divide`) and averages SculptForge's own figures.
+
+ **How to read the figures below.** They were taken on the M1 Pro while other agents were building and testing on
+ the same machine (load average 9 to 45 on 10 cores during the runs), so absolute times are two to four times
+ those of an idle machine and vary from run to run (0.9.7 measured 65 ms frames at 21M on an idle machine; here
+ 71-180 ms). A and B were interleaved run by run, two runs each, so they saw the same load. "A" is main (0.9.7)
+ with only the measurement additions, "B" this branch with Predictive Strokes on (the default).
+
+ - Frame: the interval between frames on screen, mean / p95 / p99 (120 Hz display, vsync).
+ - Surface lag: how far round the circle the last dab whose result is on the GPU is behind the pointer.
+ - Preview lag: the same for the preview's head (B; for A it is the surface).
+ - Press: from the press to the first frame on screen that shows it (B: the preview of the first dab); first
+ surface: until the first dab's own result is on screen.
+ - Release: how long letting go holds up the UI; until done: until the last dab's result is on screen.
+
+ 200 px brush:
+
+ | Mesh | | Frame mean / p95 / p99 | Surface lag | Preview lag | Press | First surface | Release | Until done |
+ |---|---|---:|---:|---:|---:|---:|---:|---:|
+ | 5.2M | A | 47.0 / 98.5 / 134 ms | 95 px | 95 px | 98 ms | 98 ms | 31 ms | 44 ms |
+ | | B | **8.4 / 11.3 / 14.3 ms** | 72 px | **1.0 px** | **24 ms** | 68 ms | **0 ms** | 64 ms |
+ | 21.0M | A | 71.0 / 245 / 651 ms | 37 px | 37 px | 623 ms | 623 ms | 1.4 ms | 8 ms |
+ | | B | **8.8 / 14.1 / 17.6 ms** | 198 px | **1.5 px** | **14 ms** | 144 ms | **0 ms** | 224 ms |
+ | 33.6M | A | 169 / 311 / 323 ms | 245 px | 245 px | 315 ms | 315 ms | 374 ms | 493 ms |
+ | | B | **12.2 / 22.8 / 27.0 ms** | 307 px | **4.1 px** | **13 ms** | 264 ms | **0 ms** | 500 ms |
+
+ 60 and 240 px brushes (the sizes proof mode reported stalls with):
+
+ | Mesh, brush | | Frame mean / p95 / p99 | Surface lag | Preview lag | Press | Release | Until done |
+ |---|---|---:|---:|---:|---:|---:|---:|
+ | 21.0M, 60 px | A | 14.8 / 22.1 / 26.2 ms | 16 px | 16 px | 26 ms | 5 ms | 10 ms |
+ | | B | **8.4 / 9.9 / 11.4 ms** | 31 px | **0.7 px** | **8 ms** | 0 ms | 33 ms |
+ | 33.6M, 60 px | A | 24.9 / 31.6 / 34.8 ms | 48 px | 48 px | 34 ms | 31 ms | 42 ms |
+ | | B | **8.9 / 14.3 / 17.2 ms** | 63 px | **1.9 px** | **13 ms** | 0 ms | 82 ms |
+ | 21.0M, 240 px | A | 215 / 433 / 433 ms | 283 px | 283 px | 582 ms | 544 ms | 675 ms |
+ | | B | **10.2 / 18.5 / 23.8 ms** | 465 px | **3.1 px** | **21 ms** | 0 ms | 1132 ms |
+ | 33.6M, 240 px | A | 292 / 636 / 636 ms | 226 px | 226 px | 779 ms | 826 ms | 1362 ms |
+ | | B | **12.8 / 27.2 / 31.1 ms** | 337 px | 117 px* | **11 ms** | 0 ms | 1689 ms |
+
+ \* One of the two runs had a preview lag of 230 px, the other 4 px; repeated runs with the head logged gave
+ 4 px and couldn't reproduce it (a tiling window manager resizing the window mid-stroke, which other agents'
+ windows did during these runs, also moves the canvas under the scripted circle).
+
+ What the figures say:
+
+ - **Frames no longer depend on the brush.** B's frames are 8-13 ms on average at every size, p99 11-31 ms,
+ where A's worst frames were 0.3 to 1.2 s (the solver and the upload ran inside the frame). The long stalls proof
+ mode saw are gone: the biggest was a vertex leaving the GPU's position grid (a big brush raising the surface),
+ which re-packed the whole mesh inside a frame (seconds at 33M); it is re-packed on the brush thread now, and
+ the stroke's end work (exact culling bounds of everything it moved) runs there too, so release is 0 ms.
+ - **The brush trails the pointer by a few pixels on screen**, where it trailed by 40-280 px: the preview shows
+ every dab not yet solved, and the pen's next position. The surface itself (the solver's result) still trails
+ by as much as before, or more on a loaded machine (B batches dabs so that packing stays under half the work,
+ so the real surface updates less often); when it lands it replaces the preview without a visible jump: with
+ `SF_MEASURE_POP=1` the view changes by 0.055 (mean, 0-255) when a batch replaces its preview, against 0.36 if
+ there were no preview (5M, 200 px).
+ - **Press** is the first frame (8-24 ms, the preview of the first dab); the first dab's own result follows when
+ the solver has it.
+ - **Until done** is longer for B with big brushes: B places every queued dab after the pen lifts (the preview
+ already shows them) and A's frame loop thinned more. It doesn't hold anything up: the UI keeps going, and a new
+ stroke or command first finishes the old one.
+ - The targets set for this work were 33M with a 200 px brush at 60 fps (frames under 16.7 ms), the brush under
+ 20 px behind the pointer, press and release under 50 ms. Met on this loaded machine: press (13 ms), release
+ (0 ms), the brush on screen behind the pointer (4 px), the mean frame at 21M (8.8 ms). Not met: 33M frames are
+ 12.2 ms mean but 22.8 / 27.0 ms at p95 / p99. Those frames wait on the GPU (`SF_FRAME_LOG=16`: the time is
+ in the swap, drawing 33M triangles; the preview costs about 1-2 ms of it), not on the CPU.
+
+ ### Where a batch's time goes (21M, 200 px, `SF_STROKE_LOG=1`, loaded)
+
+ The solver thread: the dab 160-300 ms (kernel 50-115, normals 65-150, BVH 25-50), then packing the upload
+ 110-180 ms before this work, 25-45 ms after it (vertices 25-40, bounds under 1.5). On an idle machine divide by
+ about four. The main thread's commit (glBufferSubData of 30-55 MB): 2-3 ms, occasionally 10.
+
+ What changed, in order:
+
+ 1. **Predictive strokes** (app/AsyncStroke.cpp). The queued dabs go to a solver thread in batches; each frame
+ the finished batch is committed and the next one starts. The mesh, its BVH and the sculptor belong to the
+ solver while it runs (syncScene and the pollers wait; every path that edits the document ends the stroke
+ first). The dabs, their order and parameters are the frame loop's (each batch sees the view as it was when it
+ began), so the result is the same bit for bit: `SF_MEASURE_VERIFY=1` replays the measured stroke without the
+ thread and checks undo.
+ 2. **The preview** (render/Ghost.h, the GHOST shader variant). The dabs not yet on the GPU (in flight, queued, and
+ the stroke's head where the pen will be a frame later, core/PenPredictor.h) move the uploaded vertices as each
+ brush kernel would; the kernels are differentiated forward (height gradient and Laplacian over the tangent
+ plane) for the bent normal and the cavity term, with no extra varyings (a tiled GPU writes every vertex's
+ outputs to memory). Each dab's surface point comes from a sphere fitted to the last two placed dabs (their
+ normals turn by an angle over the distance between them): centre within 0.003-0.07 r, normal within 1-5
+ degrees (measured with a debug log since removed). Only the clusters a ghost dab reaches use it. The brush cursor is drawn at the
+ predicted pen position too.
+ 3. **Two-part upload** (Renderer::prepareStrokeUpload / commitStrokeUpload). The solver thread packs the dirty
+ vertices and the culling bounds; the GL thread only calls glBufferSubData. The cavity term comes from the
+ normals pass (Mesh::curvatureAt from each vertex's triangles, the ring average on a manifold) instead of a
+ second walk of every vertex's ring (packing 110 -> 30 ms a batch at 21M, loaded). Clusters a stroke moved get
+ bounds round their vertices' boxes (found while packing) without a normal cone; exact ones at the end.
+ 4. **No stalls**: the position grid re-pack and the end-of-stroke bounds on the solver thread (above); batches
+ sized so packing stays under half the work, and after release every dab left in one batch with the end
+ work (21M, 240 px: until done 2.9 -> 0.6 s).
+ 5. **Mesh::recomputeAllNormals** sums each vertex's own triangles in parallel when the topology is known (same
+ order, same bits, no face array): it summed on one thread, which dominated full-history timeline seeks.
+
+ Not done: persistent-mapped upload buffers (the commit is 2-3 ms, not worth the complexity on GL 3.3 / macOS
+ 4.1); per-vertex dirty bitsets per cluster beyond what UploadOrder already does; normals in the shader (they
+ are already 2 x 11-bit octahedral in 12-byte vertices since v0.6). The CPU dab itself (kernel, normals, BVH) is
+ unchanged: it bounds how soon the real surface catches up, not the frame rate.
+
+ ### Draft strokes (33.6M, measured both ways)
+
+ `SF_DRAFT_STROKE=1` (Preferences > Performance > Draft Strokes): dabs only move vertices and refit the BVH;
+ the moved clusters draw with per-pixel face normals; normals, cavities and exact bounds are worked out once at
+ pen lift, on the solver thread. Interleaved, two runs each, A = draft off, B = draft on:
+
+ | Brush | | Frame mean / p95 / p99 | Surface lag | Press | First surface | Until done |
+ |---|---|---:|---:|---:|---:|---:|
+ | 200 px | off | 12.4 / 24.6 / 28.6 ms | 438 px | 14 ms | 476 ms | 1182 ms |
+ | | draft | 13.6 / 27.0 / 30.6 ms | 445 px | 38 ms | 523 ms | 2985 ms |
+ | 240 px | off | 12.8 / 26.6 / 30.9 ms | 281 px | 18 ms | 757 ms | 1988 ms |
+ | | draft | 13.8 / 29.0 / 32.1 ms | 427 px | 22 ms | 719 ms | 3070 ms |
+
+ On this machine draft strokes don't pay: the frames were never CPU-bound (the solver is on its own thread), the
+ dab saves its normals pass but the stroke's end then recomputes the normals of everything the stroke touched,
+ so the last result arrives later. (The draft runs coincided with the heaviest load of the session, 18-45.)
+ It should help where the solver's cores are the bottleneck and energy matters (a laptop on battery, fewer
+ cores): off by default, for the hardware tiers to turn on.
+
+ ## Micro-displacement levels: 300M-1B sculptable triangles (feat/micromesh)
+
+ ```
+ sculptforge --bench-micro --bench-sizes 33,100,300 [--bench-micro-level 5] [--bench-brushes TEXT]
+ sculptforge-cli --bench-micro ... # without the GPU: memory, brush and shading times
+ ```
+
+ A micro level (core/Micro.h) stores the surface above the highest subdivision level as one 16-bit height per
+ point of a regular grid on each base triangle, along the interpolated normal of the Phong-tessellated base.
+ Micro triangles are never stored: brushes evaluate them on the CPU, the renderer in its vertex shader
+ (render/MicroRenderer.h). The benchmark divides a bench sphere to the size, sculpts strokes of 30 dabs with X
+ symmetry (two dabs a step) and orbits. M1 Pro, Release; the machine was shared with other jobs during these runs
+ (load average 10-20), so treat single rows as +/-30%.
+
+ Memory and frames:
+
+ | | 33M (Micro 4) | 104M (Micro 4) | 299M (Micro 4) | 299M (Micro 5) | **1.02B (Micro 5)** |
+ |---|---:|---:|---:|---:|---:|
+ | Base triangles | 130k | 406k | 1.2M | 292k | 995k |
+ | Micro level in memory | 42 MB | 130 MB | 374 MB | 332 MB | 1131 MB |
+ | per micro triangle / micro vertex | 1.25 / 2.50 B | 1.25 / 2.50 B | 1.25 / 2.50 B | 1.11 / 2.22 B | 1.11 / 2.22 B |
+ | Process RSS, everything | 263 MB | 432 MB | 801 MB | 710 MB | **1713 MB** |
+ | GPU buffers | 125 MB | 392 MB | 1128 MB | 997 MB | 3398 MB |
+ | Divide to micro | 5 ms | 32 ms | 60 ms | 29 ms | 93 ms |
+ | First shading + upload | 0.1 s | 0.7 s | 1.2 s | 1.7 s | 5.1 s |
+ | Orbit, 4x AA | 8.3 ms | 9.7 ms | 14.0 ms | 8.9 ms | 13.4 ms |
+ | Orbit, no AA / moving | 5.0 / 2.9 ms | 6.6 / 4.7 ms | 10.4 / 4.5 ms | 6.2 / 4.1 ms | 11.3 / 5.0 ms |
+ | Triangles drawn (still / moving) | 4.3M / 1.1M | 3.9M / 1.0M | 3.4M / 0.9M | 3.4M / 0.9M | 3.0M / 0.8M |
+ | Save / open project | 31 / 61 ms | 71 / 100 ms | 217 / 285 ms | 187 / 264 ms | 649 / 489 ms |
+
+ The same 300M as a plain mesh would need about 27 GB (90 B per triangle, see 33M below). The frame time follows
+ the triangle budget and the number of base triangles on screen, not the micro triangle count: 33M at Micro 4
+ and 299M at Micro 5 (130k and 292k base triangles) both draw in 8-9 ms. Patches of one or four triangles are
+ drawn unrolled (gl_VertexID), not instanced: instancing them cost 21 ms a moving frame at 299M, unrolled 4.4 ms.
+
+ Brushes, per dab step (both mirrors), GPU upload included:
+
+ | | 33M | 104M | 299M (Micro 4) | 299M (Micro 5) | 1.02B (Micro 5) |
+ |---|---:|---:|---:|---:|---:|
+ | Standard (r 0.12, ~64 px) | 2.4 ms | 11 ms | 13 ms | 17 ms | 39 ms |
+ | Standard, 300 px (r 0.56) | 13.5 ms | 56 ms | 115 ms | 48 ms | 283 ms |
+ | Smooth (large, r 0.4) | 9.4 ms | 21 ms | 50 ms | 44 ms | 54 ms |
+ | Move, 300 px (base cage) | 13 ms | 19 ms | 58 ms (45 after the pick fix) | 22 ms | 55 ms |
+ | Undo step, Standard stroke (30 dabs) | 0.6 MB | 1.7 MB | 4.7 MB | 3.4 MB | 11.2 MB |
+
+ Scale-adaptive brushes: a dab is evaluated on grid points `stride` apart (about 48 across its radius) and
+ interpolated in between, so the evaluation (the "kernel" column of the report) stays bounded; writing the
+ interpolated values, stitching and the GPU upload still grow with the points under the brush. The 300 px grab
+ (Move) deforms the base cage and doesn't touch the micro level at all: 20 ms at 31M against 45 ms at 299M (Micro 4,
+ ten times the base triangles) in one run; at Micro 5 (2.4x the base) 22 ms. Picking at 299M went from 37 to 11 ms
+ once the candidates were filtered by their own displacement range along the ray.
+
+ Undo journal: tiles in Morton order, each the stroke's change predicted from its neighbour and packed (minimum +
+ bit width): about a third of whole tiles. A short stroke stays under the 500 KB target (10 dabs of r 0.15 at
+ 5M: 31 KB); the benchmark's 30-dab strokes over 300M are 2-5 MB, limited by the rounding noise each dab leaves
+ (2-4 bits per point). A whole-surface edit (micro_noise) keeps whole tiles.
+
+ What a frame still costs: the CPU shading (normals, curvature) of what a dab changed, about 20 ns per grid point,
+ within a budget per frame (TierConfig::shadeBudgetPoints, 3M: the rest of a big dab's normals follow over the next
+ frames); the first full shading of a level (1-5 s). Candidates: shading on the GPU from the displacement texture
+ (needs the edge neighbours in the fragment shader), and storing the coarse part of big strokes on a coarse grid
+ (multires-style) so a 300 px dab writes thousands of points instead of millions.
+ ## Hardware profile, calibration and the frame governor (feat/hw-profile)
+
+ SculptForge measures the computer it runs on and sets its budgets from what it measured. Code:
+ `src/core/HardwareProfile.*` (probe types, mapping, cache, JSON, commands), `src/core/TierConfig.*` (the knobs other
+ modules read), `src/core/FrameGovernor.*` (run-time adaptation), `src/app/Calibration.*` (OpenGL probe and GPU
+ benchmarks, `--calibrate`), `src/app/PanelPerformanceProfile.cpp` (first-launch flow, Preferences > Performance).
+ Nothing in it uses the network.
+
+ ### When it runs
+
+ On first launch, and again when `GL_VENDOR`, `GL_RENDERER` or `GL_VERSION` (which carries the driver version)
+ or the app version changes, or when the cache holds only a CPU calibration from `sculptforge-cli`. The result
+ is cached in `<settings folder>/hardware_profile.json` (Linux `~/.local/share/SculptForge/SculptForge/`, macOS
+ `~/Library/Application Support/SculptForge/SculptForge/`, Windows `%APPDATA%\SculptForge\SculptForge\`). In the
+ app it runs over the first frames, one step per frame under a small overlay (Esc or Skip skips it; the profile
+ then comes from the probe alone). UI tests, renders, recordings, demos and the `--measure-*` runs never
+ calibrate and keep the fixed defaults (Fast Navigation at 10 million triangles), so their results don't depend
+ on the machine. `SF_NO_CALIBRATION=1` skips it too.
+
+ ```
+ sculptforge --calibrate [--calibrate-quick] [--calibrate-no-save] # prints JSON (schema sculptforge.calibration/1)
+ sculptforge-cli -c 'calibrate' # CPU half only (no OpenGL); GPU numbers from the cache
+ sculptforge-cli -c 'performance_profile' # the cached profile as JSON
+ sculptforge-cli -c 'set_performance_override name=render_triangle_budget value=12000000' # value=auto clears
+ ```
+
+ The same three commands are in the command registry, so the console, scripts and MCP clients have them; in the
+ app `calibrate` measures the GPU too.
+
+ ### What it probes
+
+ | | How |
+ |---|---|
+ | GPU | `GL_VENDOR`, `GL_RENDERER`, `GL_VERSION`, `GL_MAX_TEXTURE_SIZE`, timer queries (`GL_TIME_ELAPSED`) |
+ | Memory type | Software (llvmpipe, softpipe, SwiftShader, GDI Generic, Microsoft Basic Render), unified (Apple GPUs on macOS and Asahi), integrated or discrete, from the renderer string, refined by `GLX_RENDERER_UNIFIED_MEMORY_ARCHITECTURE_MESA` / `..._ACCELERATED_MESA` where available. Only the memory type comes from names; tiers come from measurements and memory sizes |
+ | Video memory | the first that answers: `GL_NVX_gpu_memory_info` (NVIDIA; Mesa's radeonsi and asahi too), `GL_ATI_meminfo` (free memory only), `GLX_MESA_query_renderer` (Mesa on X11), amdgpu's `mem_info_vram_total` in sysfs (Linux, also on Wayland), DXGI (Windows), CGL (macOS). Unified memory counts at most two thirds of the RAM (Metal's working set), whatever the driver reports |
+ | Machine | RAM, hardware threads, SIMD (SSE4.2 / AVX2 / AVX-512 on x86, NEON / SVE on ARM) and what the build uses, OS, CPU brand (x86 cpuid, macOS sysctl, the device tree on ARM Linux) |
+
+ ### What it measures (about 0.5-1.5 s of work; medians of 5 runs, 3 quick)
+
+ | Measurement | Work |
+ |---|---|
+ | Triangle throughput | a 512 x 256 quad grid (262k triangles, about 4 pixels each, like a whole sculpt on screen) drawn instanced into a 1024 x 1024 offscreen target, every instance in front of the last; the instance count is chosen for about 25 ms a run; GL timer queries, else glFinish around the CPU clock |
+ | Upload bandwidth | `glBufferSubData` of a 32 MB buffer, waited for (glFinish) |
+ | Brush dab | 20 Standard dabs (X symmetry, radius 0.12) on a generated 1M-triangle sphere, undone between runs |
+ | Memory bandwidth | `memcpy` of 64 MB |
+
+ ### Profiles
+
+ Two main tiers and a safe mode:
+
+ - **Workstation**: 64 GB or more of RAM (60 GB reported) and either a discrete GPU with 16 GB or more (15 GB
+ reported) or a GPU sharing the system memory (Apple Silicon Max / Ultra, big APUs), whose pool counts as two
+ thirds of the RAM; and in both cases at least 1000M triangles/s, dabs under 3 ms, memory over 4 GB/s.
+ - **Laptop / Budget**: everything else (8-32 GB RAM, 2-8 GB GPUs, Apple Silicon with less than 64 GB, thermal and
+ battery limits).
+ - **Software** (safe mode): a software renderer, or under 60M triangles/s.
+
+ A re-calibration of the same GPU keeps the previous tier while the new triangle throughput is within 15% of the
+ boundary, so a busy machine doesn't flip between tiers. Settings, before overrides:
+
+ | Setting | How |
+ |---|---|
+ | `render_triangle_budget` | half a 60 Hz frame of the measured throughput, clamped per tier (Software 0.25-4M, Laptop 2-40M, Workstation 8-600M) |
+ | `motion_proxy_threshold` | the budget (at least 262k): scenes over it draw the motion proxy while the view moves |
+ | `vram_budget_mb` | 80% of dedicated memory; unified: two thirds of RAM; integrated: half of RAM; software: a quarter |
+ | `upload_budget_mb_per_frame` | a quarter of a 60 Hz frame at the measured upload bandwidth (4-1024 MB) |
+ | `max_texture_size` | the GL limit, at most 4096 / 8192 / 16384 by tier, 8192 under 2 GB of GPU memory |
+ | `max_subdivision_triangles` | the smaller of half the RAM at 100 bytes per triangle and the GPU budget at 16 bytes per triangle, capped by tier |
+ | `micro_triangle_limit` | a quarter of the GPU budget at 8 bytes per micro-triangle, capped by tier |
+ | `threads` | hardware threads (at most 16, the pool's limit); half in safe mode, where llvmpipe draws on the same cores. Applies at the next start |
+ | `target_fps` | 60, 120 or 144 from the display (`TierConfig::targetHz`) |
+
+ Every setting can be overridden by hand (Preferences > Performance > Manual overrides, or `set_performance_override`),
+ and overrides survive re-calibration.
+
+ ### TierConfig (core/TierConfig.h)
+
+ What feat/micromesh and feat/zero-latency read, through `currentTierConfig()` (thread-safe; `tierConfigRevision()`
+ changes when it does):
+
+ | Field | Software | Laptop / Budget | Workstation |
+ |---|---|---|---|
+ | `residentCacheCapMB` | RAM / 8, at most 1 GB | RAM / 4, at most 4 GB | RAM x 2/5, at most 64 GB |
+ | `activeTriangleBudget` | 0.5M | 2M | 8M+ (half the render budget, at most 64M) |
+ | `uploadBudgetMBPerFrame` | the profile's | the profile's | the profile's |
+ | `draftBrushMode` (normals and cavity at pen release) | on | on | off (continuous) |
+ | `zeroCopyUMA` | the GPU shares system memory: unified or integrated, in any tier (a 64 GB+ Apple Silicon Workstation too) | | |
+ | `targetHz` | 60 | 60 / 120 / 144 from the display | 60 / 120 / 144 from the display |
+
+ The app reads the power source with `SDL_GetPowerInfo` at start and every 5 seconds. On battery, whatever the tier
+ (an Apple Silicon Workstation is a laptop too): draft brushes,
+ half the upload budget and 60 Hz (unless set by hand), and the status bar says so. The `draft_brush` override
+ (on / off) wins over both. `draftBrushMode` is a flag for the brush engine; the brushes don't read it yet.
+
+ ### Render triangle budget and the frame governor
+
+ `renderTriangleBudget()` (core/HardwareProfile.h) is the number of triangles the 3D view may draw per frame to
+ hold the target frame rate; `motionProxyThreshold()` is where Fast Navigation switches big scenes to their
+ motion proxy. The frame governor (core/FrameGovernor.h) adjusts both from real frames:
+
+ - Inputs per drawn frame: CPU time from input to swap (without the vsync wait), GPU time from a `GL_TIME_ELAPSED`
+ query read up to 4 frames later (never waiting), triangles drawn, the scene's full triangle count, whether
+ the view is moving and whether the proxy was used. Only moving frames count: still frames draw everything in
+ full and the governor can't change them. Frames over 250 ms (dialogs, loading) are ignored.
+ - Every 20 counted frames it takes the medians. Above the target frame time it lowers the budget (aiming at 80%
+ of the frame, at most halving it); under 60% it raises it (at most 1.25x) when the budget is what limits the
+ view. In between it holds (the dead band). After a change, 5 frames are ignored.
+ - Raising the budget past the scene's size would switch the proxy off; it only does when the predicted full
+ frame stays under 90% of the target, so the view never flips between proxy and full detail.
+ - Bounds: an eighth to four times the profile's budget. It changes only how much is drawn, never the mesh.
+
+ Today's renderer uses the governed threshold for the motion proxy (Preferences > Performance > Fast Navigation;
+ `SF_FAST_NAVIGATION_TRIANGLES` still overrides it for tests).
+
+ **How micromesh consumes it:** read `renderTriangleBudget()` once per frame (an atomic load) and amplify
+ micro-displacement only until the frame's drawn triangles reach it, finest where the screen-space error is
+ largest; keep the generated micro-triangles under `currentPerformanceSettings().microTriangleLimit` and their
+ pages under `currentTierConfig().residentCacheCapMB`. Report the triangles actually drawn through
+ `Renderer::lastDrawnTriangles()` so the governor sees them; it then raises or lowers the budget continuously
+ (continuous level of detail converges without the proxy's step, see the `governor_converges_*` tests).
+
+ ### This machine
+
+ Apple M1 Pro under Asahi Linux, on battery, with about 35 other processes compiling (load average 35 on 10
+ cores), so the CPU numbers here are low (memory bandwidth measured 23 GB/s on a quieter run, dabs 0.07 ms on a
+ 0.2M sphere):
+
+ ```
+ "gl_renderer": "Apple M1 Pro (G13S C0)", "gl_version": "4.6 (Core Profile) Mesa 26.1.8", "gpu_kind": "unified",
+ "vram_mb": 31667 (GL_NVX_gpu_memory_info: all of the RAM), "timer_query": true, "cpu_threads": 10, "simd": ["neon"]
+ measurements: 1358M triangles/s (GPU timer), upload 12.8 GB/s, dab 0.37 ms (2.5k vertices), memory 5.9 GB/s, 607 ms
+ profile: Laptop (32 GB of RAM is under the 64 GB Workstation needs; this run predates the unified-memory rule, so its
+ reason read "no discrete GPU"; it now reads "30.9 GB RAM")
+ settings: render budget 11.3M, motion proxy from 11.3M, GPU memory 20.6 GB, uploads 50 MB/frame, textures 8192,
+ subdivision 120M, micro-triangles 256M, 10 threads, 60 fps
+ tier_config: cache 4 GB, active 2M, uploads 25 MB/frame (battery), draft brushes, zero-copy UMA, 60 Hz, on battery
+ ```
+
+ Across runs on the busy machine the triangle throughput ranged 913-1410M/s and upload 4.3-21 GB/s.
+
+ ## 0.9.7: big brushes on dense meshes (feat/perf-pass)
+
+## Kelvinlet brushes and Capture from view (feat/kelvinlet-alpha)
+
+Measured with the stroke the app draws itself, on the benchmark sphere at 5M, 21M and 33M triangles (with
+subdivision levels, X symmetry on), Move as the reference in the same session:
+
+```
+SF_MEASURE_BRUSH=KelvinGrab sculptforge --run "new_bench_sphere millions=21" --measure-stroke 3,50
+SF_KELVIN_LOG=1 ... # per move: pieces, vertices, kernel / normals / BVH ms, renderer sync so far
+```
+
+**Caveat: the machine was shared** with several other builds and test runs (load average 14-57 on 10 cores, noted
+per row), and the tiling window manager sometimes gave the window half the size (those runs were thrown away:
+every figure here is with the full window, circle radius 176 px). Each figure is the better of two runs. Treat them
+as an upper bound and as a comparison with Move in the same conditions, not as clean numbers.
+
+Frame time while drawing the fast two-turn circle (mean / worst, ms), 50 px and 300 px brush (300 px is as big as
+the sphere on screen: a whole-model grab). "Before" is the first version of the branch, "now" after the
+dense-mesh pass described below; Move was measured in each session:
+
+| Mesh | Brush | Move | KelvinGrab before -> now | KelvinTwist before -> now | KelvinScale before -> now | load |
+|---|---|---:|---:|---:|---:|---:|
+| 5M | 50 px | 8.3 / 11 | 14.2 -> **9.6** / 22 | 14.6 -> **8.9** / 18 | 35.8 -> **9.3** / 15 | 12-16 |
+| 5M | 300 px | 42 / 57 | 197 -> 145 / 210 | 124 -> 163 / 232 | 120 -> 384 / 491 | 13-24 |
+| 21M | 50 px | 20.6 / 38 | 43.8 -> 138 / 195 | 35.2 -> **55** / 152 | 77.6 -> **52** / 122 | 17-22 |
+| 21M | 300 px | 203 / 223 | 1297 -> **557** / 668 | 968 -> **499** / 688 | 935 -> **415** / 558 | 17-23 |
+| 33M | 50 px | 19.2 / 37 | 179 -> 187 / 805 | 110 -> **58** / 99 | 279 -> **57** / 104 | 23-58 |
+| 33M | 300 px | 381 / 405 | no frame in 3 s -> **920** / 1022 | no frame -> **505** / 746 | 1546 -> **1170** / 2234 | 16-38 |
+
+(Both columns are under heavy, varying load; KelvinGrab's "before" at 21M / 50 px came from a quieter moment.)
+
+**Targets not met.** The goal was KelvinGrab at 33M under 20 ms (50 px) and 50 ms (300 px). Measured: 187 and 920
+ms. Twist and Scale at 33M / 50 px came down from 110-280 to 57-58 ms. On the same machine Move took 19 and 381
+ms. So a 300 px move under 50 ms at 33M would be well beyond what plain Move does today. A KelvinGrab move at
+33M / 50 px costs about 39 ms on the CPU (`SF_KELVIN_LOG`: about 900 000 vertices, kernel 15, normals 14, BVH
+10 ms). What is left is the renderer: about 60 ms a frame of sync, because the deferred far field touches
+vertices spread over a large box every frame. The next step is GPU-side: show the far field as a vertex-shader
+displacement from the lattice (a 3D texture) and write it to the mesh when the stroke ends. That needs the
+render pipeline (feat/zero-latency).
+
+What the dense-mesh pass does (`src/core/Kelvinlet.cpp`, `src/app/PanelKelvinlet.cpp`):
+
+1. **Bounded work per frame.** The app applies at most about one brush radius of a long move per frame (half that
+ when the last move found more vertices than `KelvinletSettings::vertexBudget`, 600 000, a constant until the
+ hardware profile sets it). For Twist and Scale the cap is a 0.3 rad turn or a 0.2 log-scale step. It moves
+ once per frame and catches up in later frames, also when the pointer rests, and completely when the stroke
+ ends.
+2. **A coarse proxy for the far field.** Regions above 150 000 vertices evaluate the field on a lattice (spacing
+ 0.06 radius) beyond half a radius from the load's path and interpolate it trilinearly; the near field stays
+ exact. Regions above 400 000 vertices (predicted from the last move) go further: only the near field (within
+ 1.2 radii, smoothly weighted) moves at once. The far field is gathered on a world lattice (spacing 0.1 radius),
+ and a sixth of the vertices (runs of 4096 indices) take what they gathered each frame.
+3. **An adaptive cutoff.** It is 4% of the peak, rising to 10% when the predicted region is over the budget.
+4. **A threaded VDM capture.** The flood fill runs one ring at a time in parallel, and the adjacency and the
+ triangles are built in parallel.
+
+Error metric (tests/test_kelvinlet.cpp):
+- **Lattice proxy:** the largest deviation from the exact field is 0.53% of the step's size. That includes the
+ 0.5% floor below which a vertex's move is skipped, which the exact path has too.
+- **Deferred far field, at the stroke's end:** within 1.1% of the brush radius of the immediate evaluation
+ (under a pixel for brushes up to about 70 px; about 3 px for a 300 px brush). The deviation is smooth, with no
+ seams.
+- **During a drag:** the far part of the surface (beyond about one radius) trails the near part by up to six
+ frames, then settles.
+- **Undo** is exact.
+
+The core per-move cost on its own (`sculptforge_tests kelvinlet_grab_dense_mesh_timing`, 1.3M triangles, r 0.3,
+no renderer): about 1.6-3.4 ms a move for 13 000-27 000 vertices, depending on the load.
+
+Capture from view (`sculptforge-cli`, a VDM horn and a DamStandard cut sculpted on the sphere, square half size
+0.15 unless noted):
+
+| Mesh | Height alpha 256 / 1024 px | VDM 256 px (points) | VDM, half size 0.4 (points) |
+|---|---:|---:|---:|
+| 21M (load ~20) | 18 / 106 ms | 117 ms (50 k) | 1329 ms (456 k) |
+| 33M (load ~21) | 55 / 240 ms | 439 ms (76 k) | 3852 ms (696 k) |
+| 33M, threaded region (load ~11) | | 128 ms (76 k) | 1212 ms (696 k) |
+
+The alpha is a z-buffer of the triangles under the square plus a box-blur high pass (three box blurs: the
+1024 px alpha went from 652 to 106 ms at 21M). The VDM is region finding (flood fill over the vertices near the
+square), a quadric fit to its outer band, and implicit fairing by conjugate gradients (90-270 iterations); on a
+large patch the flood fill and adjacency build dominated; they are threaded now (the last row).
+
+## Next version: big brushes on dense meshes (feat/perf-pass)
+
What a user feels on a heavy model is a large brush: how far it trails the pointer, how long a frame takes, and
what happens on press and release. Measured with the stroke the app draws itself (pointer read once per pass of
the loop, as a busy program gets it):
diff --cc src/app/App.cpp
index 9dcb6c81,ec4c0e48..176ed671
--- a/src/app/App.cpp
+++ b/src/app/App.cpp
@@@ -713,12 -774,11 +774,14 @@@ int App::run()
sm.cy = c.y + c.h * 0.5f;
sm.r = 0.25f * std::min(c.w, c.h);
sm.started = true;
- sm.start = sm.lastFrame = seconds();
+ sm.start = sm.lastFrame = sm.pressAt = seconds();
strokeProbe_ = &sm.dabs;
+ strokeRadiusProbe_ = &sm.radii;
if (options_.measureStrokeRadius > 0.0f) radiusPx_ = std::clamp(options_.measureStrokeRadius, 2.0f, 800.0f);
+ if (const char* b = std::getenv("SF_MEASURE_BRUSH")) // e.g. KelvinGrab: measure another built-in brush
+ for (int i = 0; i < int(BrushType::Count); ++i)
+ if (SDL_strcasecmp(brushName(BrushType(i)), b) == 0) brush_ = BrushType(i), doc_.activeBrush = -1;
+ if (verify) sm.before = meshStateHash(doc_.mesh);
onMouseDown(sm.cx + sm.r, sm.cy, SDL_BUTTON_LEFT);
if (drag_ != Drag::Stroke) {
std::printf("Stroke: no stroke began (nothing to sculpt under the circle's start)\n");
@@@ -754,8 -851,11 +854,12 @@@
return double(sm.dabs.size()) >= 0.9 * expected && !off.empty() && off.back() < spacing ? 0 : 1;
}
}
- drainStrokeDabs(kStrokeBudgetSeconds); // the stroke's queued dabs, for a limited time: then look at the pointer again
+ // The stroke's queued dabs: handed to the solver thread (predictive strokes, AsyncStroke.cpp), or placed here
+ // for a limited time, then look at the pointer again.
+ if (asyncStroke_) pumpStroke();
+ else drainStrokeDabs(kStrokeBudgetSeconds);
+ mark();
+ kelvinCatchUp(); // a long Kelvinlet move, a bounded part per frame (PanelKelvinlet.cpp)
Uint64 now = SDL_GetTicksNS();
float dt = float(double(now - lastTicks) * 1e-9);
lastTicks = now;
@@@ -1386,30 -1561,10 +1581,12 @@@ void App::dabAt(float x, float y, floa
}
void App::endStroke() {
+ if (asyncStroke_) solverWait(); // (the dabs in flight; then the solver thread is idle)
drainStrokeDabs(0.0); // the dabs still waiting belong to this stroke
+ doc_.sculptor.flushDetailClone(doc_.mesh, doc_.bvh, symmetry_); // a Detail Clone click
+ kelvinFinish(); // the rest of a Kelvinlet move (PanelKelvinlet.cpp)
- strokeMask_ = false;
- maskClickPending_ = false; // (a command can end a Ctrl+click before its release)
- firstDabPending_ = false;
- // Preferences > Performance shows what the stroke cost.
- if (doc_.sculptor.timings.dabs > 0) {
- perf_.lastStroke = doc_.sculptor.timings;
- perf_.lastStrokeSyncMs = perf_.strokeSyncMs;
- perf_.lastStrokeFrames = perf_.strokeFrames;
- }
- doc_.sculptor.timings = {};
- perf_.strokeSyncMs = 0.0;
- perf_.strokeFrames = 0;
- UndoRecord r = doc_.sculptor.endStroke();
- finishPaintStroke(r);
- if (r.topology && !r.topology->uvs.empty())
- status_ = "Dynamic topology removed the UVs of the remeshed SubTool (Undo brings them back)";
- if (!r.empty()) {
- doc_.undo.push(std::move(r));
- doc_.modified = true;
- updateTitle();
- }
+ // (a command can end a Ctrl+click before its release: finishStrokeNow clears the mask click too)
+ finishStrokeNow(); // AsyncStroke.cpp
}
// ---------------------------------------------------------------------------
diff --cc src/core/Benchmark.cpp
index db2217b9,4924dc1c..c493971e
--- a/src/core/Benchmark.cpp
+++ b/src/core/Benchmark.cpp
@@@ -96,19 -109,10 +109,20 @@@ void registerPerformanceCommands(Comman
(ThreadPool::shared().serial() ? " (multithreading off)" : "") + "; " +
millions(double(u.triangles)) + " triangles; memory " + mb(u.total()) + " (meshes " +
mb(u.mesh) + ", BVH " + mb(u.bvh) + ", subdivision levels " + mb(u.levels) +
- ", undo " + mb(u.undo) + "), GPU buffers about " + mb(u.gpu);
+ ", undo " + mb(u.undo) + ", textures " + mb(u.textures) + " of which material channels " + mb(u.channels) + ", texture painting caches " + mb(u.paintCaches) +
+ "), GPU buffers about " + mb(u.gpu);
return {true, msg};
}});
+ registry.add({"new_bench_sphere",
+ "Replace the scene with the benchmark's sphere of about `millions` million triangles (a cube made "
+ "round, then divided: subdivision levels like a real sculpt), for measuring brushes on heavy meshes.",
+ {{"millions", ParamSpec::Type::Number, "Triangles in millions (0.01-200, default 5).", false}},
+ [](Document& doc, const Args& a) -> CommandResult {
+ const double m = std::clamp(argNumber(a, "millions", 5.0), 0.01, 200.0);
+ doc.setMesh(makeBenchSphere(size_t(m * 1e6)), "Sphere");
+ doc.path.clear();
+ return {true, "Created benchmark sphere with " + std::to_string(doc.mesh.triangleCount()) + " triangles"};
+ }});
registry.add({"set_multithreading",
"Run brushes, normal and BVH updates, project saving and other per-dab work on every core (on, the "
"default) or on one thread (off: slower, for comparing or troubleshooting). Results are the same.",
diff --cc src/core/Sculpt.cpp
index 0237d348,c3d0526b..b0a445a1
--- a/src/core/Sculpt.cpp
+++ b/src/core/Sculpt.cpp
@@@ -458,10 -479,18 +484,22 @@@ UndoRecord Sculptor::endStroke()
void Sculptor::dab(Mesh& mesh, BVH& bvh, BrushType type, const DabParams& p, Symmetry sym) {
if (!active_) return;
+ if (isKelvinletBrush(type)) { // Kelvinlet.cpp (no remeshing: they move the surface, as Move does)
+ dabKelvinlet(mesh, bvh, type, p, sym);
+ return;
+ }
+ if (microReady(mesh)) { // a micro level: the grid takes the dab (core/MicroSculpt.cpp)
+ const double k0 = micro_.findMs + micro_.kernelMs, s0 = micro_.stitchMs;
+ const uint64_t pts = micro_.points;
+ for (const glm::vec3& m : mirrors(sym))
+ micro_.dab(mesh, bvh, type, p.center * m, p.viewDir * m, p.radius, p.strength * std::clamp(p.pressure, 0.0f, 1.0f),
+ p.invert, p.focal, p.alphaUp * m, false, 0.0f);
+ timings.kernelMs += micro_.findMs + micro_.kernelMs - k0;
+ timings.normalsMs += micro_.stitchMs - s0;
+ timings.vertices += micro_.points - pts;
+ ++timings.dabs;
+ return;
+ }
if (type != BrushType::Move) {
const bool useAlpha = p.alpha && !p.alpha->empty(); // (the reach dabSingle gives the brush)
const float reach = useAlpha ? 1.4143f : type == BrushType::ClayBuildup ? 1.3f : 1.0f;
diff --cc src/core/Sculpt.h
index a1c9f7ff,fbfef624..258ec4b8
--- a/src/core/Sculpt.h
+++ b/src/core/Sculpt.h
@@@ -133,21 -125,27 +140,42 @@@ public
// DragDot; restoreStroke) put positions back, not topology. restoreStroke holds it too.
void holdTopology() { topologyHeld_ = true; }
+ // Kelvinlet brushes (core/Kelvinlet.h, defined in Kelvinlet.cpp): one step of KelvinGrab / KelvinSnake
+ // (step.delta), KelvinTwist (step.angle) or KelvinScale (step.logScale), mirrored by `sym`. dab() turns a plain
+ // dab into steps. The settings are Brush > Kelvinlet's.
+ KelvinletSettings kelvinlet;
+ void kelvinletStep(Mesh& mesh, BVH& bvh, BrushType type, const KelvinletStep& step, Symmetry sym);
+ // Detail Clone: a stroke that never moved has its one stamp waiting (for a direction): this presses it.
+ // Call before endStroke() (harmless for every other brush).
+ void flushDetailClone(Mesh& mesh, BVH& bvh, Symmetry sym);
+ // A dense Kelvinlet stroke defers part of its far field (Kelvinlet.cpp, KelvinFarField): whether some is still
+ // waiting, and applying it (one group of vertices, or all; flushDetailClone applies all at a stroke's end).
+ bool kelvinletFarPending() const;
+ void flushKelvinletFar(Mesh& mesh, BVH& bvh, bool all);
+ // The last kelvinletStep found more vertices than kelvinlet.vertexBudget (the app then moves less per frame).
+ bool kelvinletOverBudget() const { return kelvinOverBudget_; }
+
+ // The cavity term (Mesh::curvatureAt) of every vertex whose normal this stroke's dabs updated, by vertex,
+ // worked out with the normals (the renderer packs it instead of walking the rings again); null outside a
+ // stroke. Entries of other vertices are stale.
+ const float* strokeCurvature() const { return active_ && !curvature_.empty() ? curvature_.data() : nullptr; }
+
+ // Draft strokes (Preferences > Performance > Draft Strokes): when set before beginStroke (it asks once), dabs move the vertices
+ // and refit the BVH but leave the normals and the cavity term as they were (the brushes that read normals see
+ // the stroke-start ones, so the result differs slightly from a full stroke); the vertices are only marked
+ // for the GPU. flushDraft works out every normal and cavity term the stroke touched, once (the app calls
+ // it before endStroke). Not with dynamic topology.
+ bool draftStrokes = false;
+ bool draftActive() const { return draft_; }
+ bool draftPending() const { return draft_ && !draftLeaves_.empty(); }
+ void flushDraft(Mesh& mesh, const BVH& bvh);
+
+ // Micro level timings (findMs, kernelMs, stitchMs, points) of the current stroke (core/Micro.h).
+ const MicroStroke& microStroke() const { return micro_; }
+ // Move on a micro level: false (default) deforms the base cage and the detail rides along; true moves the
+ // micro displacement along its normals instead.
+ bool microMoveAlongNormals = false;
+ MicroStroke& microStroke() { return micro_; }
// Mirror sign vectors for the enabled symmetry axes (always starts with (1,1,1)).
static std::vector<glm::vec3> mirrors(Symmetry sym);