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.

core-200m novel track: N1 optimistic screen-space strokes and N2 wavelet displacement prototypes

islandmed2b0cfcb89e76
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 445bd309..b7e13ef8 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -87,6 +87,7 @@ add_library(sculptforge_core STATIC
src/core/UvPack.cpp
src/core/UvUnwrap.cpp
src/core/TileImage.cpp
+ src/core/Wavelet.cpp
src/core/EnvironmentMath.cpp
src/core/MeshMaps.cpp
src/core/LayerStack.cpp
@@ -299,6 +300,7 @@ if(SCULPTFORGE_BUILD_APP)
src/app/main.cpp
src/app/Bench.cpp
src/app/Calibration.cpp
+ src/app/OptimisticBench.cpp
src/app/PanelPerformanceProfile.cpp
src/app/CrashLog.cpp
src/app/App.cpp
diff --git a/docs/design/core-200m.md b/docs/design/core-200m.md
index 9cf935e8..cbe37de6 100644
--- a/docs/design/core-200m.md
+++ b/docs/design/core-200m.md
@@ -152,6 +152,50 @@ Every number twice: this laptop and the floor profile (`SF_HW_SIMULATE=floor`),
Nothing here merges into a release without the floor-tier numbers.
+## 7b. The novel track (Tony, 11-03: beyond the known playbook)
+
+Sections 1-6 are the known playbook done well (multiresolution offsets, cluster LOD to a pixel budget, a cached
+screen, scale-adaptive dabs). The novel track changes *what a stroke is*, not only how fast it runs. Each item is a
+prototype with numbers before anything ships; measured on this laptop, the floor profile and the Windows PC.
+
+**N1. Optimistic screen-space strokes.** The screen is the first thing a dab changes, the mesh the last. Each dab is
+applied at once to the cached screen (depth, normal, colour) by one GPU pass over the dab's screen rectangle: the
+surface point from depth, the brush's displacement along the dab normal, the bent normal from the kernel's gradient,
+the colour re-shaded by the ratio of the Lit Sphere lookups at the bent and the original normal (so cavity, material
+and paint stay). Cost: the brush's pixels, under 1 ms, whatever the mesh size. The true mesh is solved on the solver
+thread a few frames later and replaces the optimistic pixels; the swap is pop-free where the estimate holds (open
+surface, no silhouette change), and the residual is measured (the "pop": the per-pixel difference between the
+optimistic image and the solved mesh at the same dabs). Stroke latency stops depending on mesh size. Differs from the
+geometry preview we have (render/Ghost.h): that moves the mesh's vertices in the vertex shader, so its cost follows the
+clusters under the brush; N1 never touches geometry. Limits: silhouettes (the outline doesn't move until reconcile),
+brushes that read the surface (Smooth, Flatten: approximated from the canvas's depth), occluded surface (not on screen,
+nothing to show, nothing lost: the solver is exact).
+
+**N2. Wavelet (multi-scale) displacement.** Store each patch's heights as interpolating-wavelet coefficients (integer
+lifting on the triangle grid: a point new at level k stores its height minus the floor-average of its two parents on the
+coarser edge), losslessly invertible. A dab whose radius spans 64-256 samples at level l adds its kernel to the level-l
+coefficients only: a 300 px brush writes thousands of values instead of millions, so **cost falls as the brush grows**,
+and the fine coefficients (the detail) ride along unchanged. Reconstruction (the inverse transform) runs lazily for what
+is drawn or picked, and can move to the GPU (each level is one pass over its new points). The result is identical, bit
+for bit, to adding the coarse kernel and linearly interpolating it to the fine points (tested), which is what today's
+stride-sampled micro brushes approximate at full write cost.
+
+**N3. Procedural stroke layers (research).** A stroke stored as an operation (path, brush, parameters, the base it was
+applied to) instead of its result; detail is evaluated at any resolution on demand, so it isn't bounded by memory, and a
+stroke can be edited after the fact (strength, path, falloff). Hard parts: brushes that read the surface (order
+dependence: replay is sequential), determinism across versions, the cost of evaluating many layers (cache per patch per
+level; N2's coefficients are the cache). Prototype after N1 and N2: a layer stack of Standard / Clay strokes evaluated
+into N2 coefficients per patch on demand.
+
+**N4. Pen prediction for the last frames.** The alpha-beta-gamma predictor (core/PenPredictor.h, from the zero-latency
+work) extrapolates the pen ~25 ms; with N1 the predicted dabs are drawn optimistically too (weight < 1, as the preview
+does), hiding the last frame or two of display latency. Literature: no gain predicting past ~33 ms.
+
+**N5. Idle-time pre-refinement around the cursor.** When the pen hovers, spend idle frames preparing what the next dab
+will need under and ahead of the cursor: Focus Detail promotion, N2 reconstruction of the patches under the cursor, BVH
+and undo-tile allocations, shading. The first dab then finds everything warm (the beta measured a 965 ms first-dab stall
+on Windows at 15M; perf/beta-boost removes its cause, N5 keeps such costs off the stroke in general).
+
## 8. Phase 1 results
Run: `sculptforge --benchmark core-200m --benchmark-no-video` (Release). The scene: the bench head at 196,608 base
@@ -260,6 +304,25 @@ driver blocking the draw calls on this shared Asahi desktop. That is this machin
Windows PC (RTX 3060) run below shows the same scene on a desktop GPU and driver.
+### Windows PC (RTX 3060, NVIDIA 616.56, Ryzen 5600X, 32 GB; 1920x1080; CI Windows build of this branch)
+
+Six runs interleaved real GPU / floor 100 % / floor 75 %, governor pinned (`SF_GOVERNOR=0`); every run's log checked
+for the profile it ran with. Orbit, ms:
+
+| | drawn | frame p50 / p99 / max | GPU p50 / p99 | swap wait p99 | open / first frame |
+|---|---|---|---|---|---|
+| real GPU (x2) | 0.62M | 0.8-0.9 / 2.1-2.3 / 3-8 | 0.6 / 1.7-2.1 | 0.4-1.2 | 0.29-0.30 / 1.32-1.34 s |
+| floor 100 % (x2) | 0.62M | 0.8-0.9 / 2.2-2.3 / 3-10 | 0.6 / 1.7-2.0 | 0.3-1.1 | 0.28-0.35 / 1.36-1.41 s |
+| floor 75 % (x2) | 0.36M | 0.9 / 2.2 / 3-11 | 0.5 / 1.5-1.8 | 0.8-0.9 | 0.30-0.38 / 1.33-1.44 s |
+
+- **200M orbits at ~1,100 fps, p99 2.2 ms**, 15x under the 33 ms target, on the floor budgets too. The 29-43 ms tail of
+ the M1 laptop is its presentation stack (above), not the engine.
+- First frame 1.3-1.4 s (the first full shading of 110M grid points on 6 cores) against 0.7 s on the M1's 10; within
+ the < 5 s target, and phase 2 (shading on demand) removes it.
+- The floor profile on a 3060 tests the budgets, not an iGPU's fill rate; real iGPU runs by testers still decide.
+- RAM was not measured on Windows: `residentBytes()` read only Linux's /proc, so every Windows and macOS benchmark
+ reported 0 MB. Fixed on this branch (working set / Mach task info); remeasured below once the CI build is in.
+
What the floor simulation does not show: a real iGPU's fill rate (it doesn't slow the GPU) and 4-core open time
(the open stayed 0.7 s; whether the first shading runs on the capped pool is not verified). Real UHD 620 / Iris Xe
runs by testers are what confirm it.
diff --git a/src/app/OptimisticBench.cpp b/src/app/OptimisticBench.cpp
new file mode 100644
index 00000000..5d93409d
--- /dev/null
+++ b/src/app/OptimisticBench.cpp
@@ -0,0 +1,503 @@
+// SculptForge - open source digital sculpting
+// SPDX-License-Identifier: GPL-3.0-or-later
+#include "app/OptimisticBench.h"
+
+#include "core/BVH.h"
+#include "core/Document.h"
+#include "core/HardwareProfile.h"
+#include "core/Image.h"
+#include "core/Sculpt.h"
+#include "core/Symmetry.h"
+#include "core/ThreadPool.h"
+#include "render/Camera.h"
+#include "render/GL.h"
+#include "render/Renderer.h"
+
+#include <SDL3/SDL.h>
+#include <glm/gtc/matrix_transform.hpp>
+#include <glm/gtc/type_ptr.hpp>
+
+#include <algorithm>
+#include <chrono>
+#include <cmath>
+#include <cstdio>
+#include <filesystem>
+#include <fstream>
+#include <sstream>
+
+namespace sf {
+
+namespace {
+
+using Clock = std::chrono::steady_clock;
+double msSince(Clock::time_point t) { return std::chrono::duration<double, std::milli>(Clock::now() - t).count(); }
+
+constexpr GLenum kDepthComponent = 0x1902;
+constexpr int kW = 1920, kH = 1080;
+constexpr int kMaxDabs = 64; // the pass's uniform arrays
+
+// One pass over a dab's screen rectangle: every dab of the stroke so far displaces the canvas's surface point along
+// its area normal by the Standard kernel (core/Sculpt.cpp, as render/Ghost.cpp's ghostMove), the normal bends by the
+// kernels' gradients, and the colour is re-shaded by the ratio of the Lit Sphere lookups (the mesh shader's, view
+// space) at the bent and the original normal, so cavity, material and paint stay as drawn.
+const char* kVS = R"(#version 330 core
+void main() {
+ vec2 p = vec2((gl_VertexID << 1) & 2, gl_VertexID & 2);
+ gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);
+}
+)";
+const char* kFS = R"(#version 330 core
+uniform sampler2D uColor, uDepth, uMatcapTex;
+uniform mat4 uInvProj, uProj;
+uniform vec2 uProjScale, uSize;
+uniform int uCount;
+uniform vec4 uDabC[64]; // view-space centre, radius
+uniform vec4 uDabN[64]; // view-space area normal, amplitude (strength x radius x 0.06)
+out vec4 fragColor;
+bool surface(ivec2 p) { return texelFetch(uDepth, clamp(p, ivec2(0), ivec2(uSize) - 1), 0).r < 1.0; }
+vec3 viewPos(ivec2 p) {
+ p = clamp(p, ivec2(0), ivec2(uSize) - 1);
+ float d = texelFetch(uDepth, p, 0).r;
+ vec4 q = uInvProj * vec4((vec2(p) + 0.5) / uSize * 2.0 - 1.0, d * 2.0 - 1.0, 1.0);
+ return q.xyz / q.w;
+}
+vec3 lit(vec3 n, vec3 v) {
+ vec3 bx = normalize(vec3(v.z, 0.0, -v.x));
+ vec3 by = cross(v, bx);
+ vec2 uv = vec2(dot(bx, n), dot(by, n)) * 0.495 + 0.5;
+ return pow(texture(uMatcapTex, uv).rgb, vec3(2.2));
+}
+// The displacement of the surface point P by every dab (the Standard kernel along each area normal), and the
+// tangential gradient that bends a normal n.
+vec3 displace(vec3 P, vec3 n, out vec3 g) {
+ vec3 m = vec3(0.0);
+ g = vec3(0.0);
+ for (int i = 0; i < uCount; ++i) {
+ vec3 o = P - uDabC[i].xyz;
+ float dist = length(o), rad = uDabC[i].w;
+ if (dist >= rad || dist < 1e-9) continue;
+ float t = 1.0 - dist / rad;
+ m += uDabN[i].xyz * (uDabN[i].w * t * t * (3.0 - 2.0 * t));
+ vec3 grad = uDabN[i].w * (-(6.0 * t - 6.0 * t * t) / rad) * o / dist;
+ g += (grad - n * dot(grad, n)) * dot(uDabN[i].xyz, n);
+ }
+ return m;
+}
+// The surface normal from depth, smoothed: central differences over baselines of 1-3 pixels summed (the canvas holds
+// the mesh's facets, the mesh shader interpolates vertex normals), each pair skipped across a depth jump.
+vec3 normalAt(ivec2 p) {
+ vec3 P = viewPos(p), sum = vec3(0.0);
+ for (int k = 1; k <= 3; ++k) {
+ vec3 l = viewPos(p - ivec2(k, 0)), r = viewPos(p + ivec2(k, 0)), d = viewPos(p - ivec2(0, k)), u = viewPos(p + ivec2(0, k));
+ float jump = 0.05 * abs(P.z);
+ if (abs(r.z - l.z) > jump || abs(u.z - d.z) > jump) continue;
+ sum += cross(r - l, u - d);
+ }
+ if (dot(sum, sum) < 1e-30) { // (at an edge: the one-pixel step on the smaller side)
+ vec3 l = viewPos(p - ivec2(1, 0)), r = viewPos(p + ivec2(1, 0)), d = viewPos(p - ivec2(0, 1)), u = viewPos(p + ivec2(0, 1));
+ sum = cross(abs(r.z - P.z) < abs(P.z - l.z) ? r - P : P - l, abs(u.z - P.z) < abs(P.z - d.z) ? u - P : P - d);
+ }
+ vec3 n = normalize(sum);
+ return dot(n, P) > 0.0 ? -n : n;
+}
+vec2 toPixel(vec3 P) {
+ vec4 c = uProj * vec4(P, 1.0);
+ return (c.xy / c.w * 0.5 + 0.5) * uSize - 0.5;
+}
+void main() {
+ vec2 p = gl_FragCoord.xy - 0.5;
+ // Inverse warp: the canvas pixel q whose displaced surface point lands on p (fixed point q = p - offset(q)),
+ // from p and, for pixels the surface may grow over, from points towards the nearest dab.
+ vec2 best = vec2(-1.0);
+ vec2 toward = vec2(0.0);
+ float near = 1e30;
+ for (int i = 0; i < uCount; ++i) {
+ vec2 c = toPixel(uDabC[i].xyz);
+ if (distance(c, p) < near) near = distance(c, p), toward = c - p;
+ }
+ float bestErr = 4.0; // (accept a landing within 2 px; the closest one found)
+ for (int s = 0; s < 4 && bestErr > 0.04; ++s) {
+ vec2 q = p + toward * (0.12 * float(s));
+ for (int k = 0; k < 16; ++k) {
+ ivec2 iq = ivec2(floor(q + 0.5));
+ if (!surface(iq)) break;
+ vec3 g;
+ vec3 P = viewPos(iq);
+ vec2 err = toPixel(P + displace(P, vec3(0.0), g)) - p; // (the bend isn't needed here)
+ float e = dot(err, err);
+ if (e < bestErr) bestErr = e, best = q - err;
+ if (e < 0.04) break;
+ q -= err * (k < 8 ? 1.0 : 0.5); // (damped later: where the warp folds, a full step can oscillate)
+ }
+ }
+ ivec2 ip = ivec2(p);
+ if (best.x < 0.0) {
+ if (!surface(ip)) { fragColor = texelFetch(uColor, ip, 0); return; } // background stays
+ best = p; // (no landing point found: shade in place)
+ }
+ ivec2 iq = ivec2(floor(best + 0.5));
+ vec3 n0 = normalAt(iq);
+ vec3 g;
+ displace(viewPos(iq), n0, g);
+ vec3 n1 = normalize(n0 - g);
+ vec2 ndc = (gl_FragCoord.xy / uSize) * 2.0 - 1.0;
+ vec3 v = normalize(vec3(-ndc / uProjScale, 1.0)); // the mesh shader's viewRay
+ vec3 ratio = lit(n1, v) / max(lit(n0, v), vec3(1e-3));
+ vec4 c = texture(uColor, (best + 0.5) / uSize); // (bilinear at the landing point: no stair-steps where it stretches)
+ fragColor = vec4(pow(pow(c.rgb, vec3(2.2)) * ratio, vec3(1.0 / 2.2)), c.a);
+}
+)";
+
+GLuint compile(GLenum type, const char* src, std::string& error) {
+ GLuint s = gl::CreateShader(type);
+ gl::ShaderSource(s, 1, &src, nullptr);
+ gl::CompileShader(s);
+ GLint ok = 0;
+ gl::GetShaderiv(s, GL_COMPILE_STATUS, &ok);
+ if (!ok) {
+ char log[2048] = {};
+ gl::GetShaderInfoLog(s, sizeof log, nullptr, log);
+ error = log;
+ }
+ return s;
+}
+
+struct Target {
+ GLuint fbo = 0, color = 0, depth = 0;
+ void make(bool withDepth) {
+ gl::GenTextures(1, &color);
+ gl::BindTexture(GL_TEXTURE_2D, color);
+ gl::TexImage2D(GL_TEXTURE_2D, 0, GLint(GL_RGBA8), kW, kH, 0, GL_RGBA, GL_UNSIGNED_BYTE, nullptr);
+ gl::TexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GLint(GL_NEAREST));
+ gl::TexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GLint(GL_NEAREST));
+ gl::GenFramebuffers(1, &fbo);
+ gl::BindFramebuffer(GL_FRAMEBUFFER, fbo);
+ gl::FramebufferTexture2D(GL_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, GL_TEXTURE_2D, color, 0);
+ if (withDepth) {
+ gl::GenTextures(1, &depth);
+ gl::BindTexture(GL_TEXTURE_2D, depth);
+ gl::TexImage2D(GL_TEXTURE_2D, 0, GLint(GL_DEPTH_COMPONENT24), kW, kH, 0, kDepthComponent, GL_FLOAT, nullptr);
+ gl::TexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GLint(GL_NEAREST));
+ gl::TexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GLint(GL_NEAREST));
+ gl::FramebufferTexture2D(GL_FRAMEBUFFER, GL_DEPTH_ATTACHMENT, GL_TEXTURE_2D, depth, 0);
+ }
+ gl::BindFramebuffer(GL_FRAMEBUFFER, 0);
+ }
+ void release() {
+ gl::DeleteFramebuffers(1, &fbo);
+ gl::DeleteTextures(1, &color);
+ if (depth) gl::DeleteTextures(1, &depth);
+ *this = {};
+ }
+};
+
+std::vector<uint8_t> readColor(const Target& t) {
+ std::vector<uint8_t> px(size_t(kW) * kH * 4);
+ gl::BindFramebuffer(GL_FRAMEBUFFER, t.fbo);
+ gl::PixelStorei(GL_PACK_ALIGNMENT, 1);
+ gl::ReadPixels(0, 0, kW, kH, GL_RGBA, GL_UNSIGNED_BYTE, px.data());
+ gl::BindFramebuffer(GL_FRAMEBUFFER, 0);
+ return px;
+}
+
+void savePng(const std::vector<uint8_t>& px, const std::string& path) {
+ Image img;
+ img.width = kW, img.height = kH;
+ img.rgba.resize(px.size());
+ for (int y = 0; y < kH; ++y) // (GL rows are bottom-up)
+ std::copy_n(px.data() + size_t(kH - 1 - y) * kW * 4, size_t(kW) * 4, img.rgba.data() + size_t(y) * kW * 4);
+ std::string err;
+ if (!img.savePng(path, err)) std::fprintf(stderr, "%s\n", err.c_str());
+}
+
+struct Diff {
+ double mean = 0, p99 = 0, over8 = 0; // over the region either image changed (0-255 levels, fraction)
+ size_t pixels = 0;
+};
+// Per-pixel max channel difference of a and b over the pixels where `before` differs from either; `mask` (one per
+// pixel, optional) keeps only the pixels it marks.
+Diff diff(const std::vector<uint8_t>& a, const std::vector<uint8_t>& b, const std::vector<uint8_t>& before,
+ const std::vector<uint8_t>* mask = nullptr) {
+ std::vector<int> d;
+ for (size_t i = 0; i < a.size(); i += 4) {
+ if (mask && !(*mask)[i / 4]) continue;
+ int ca = 0, cb = 0, ab = 0;
+ for (int k = 0; k < 3; ++k) {
+ ca = std::max(ca, std::abs(int(a[i + k]) - int(before[i + k])));
+ cb = std::max(cb, std::abs(int(b[i + k]) - int(before[i + k])));
+ ab = std::max(ab, std::abs(int(a[i + k]) - int(b[i + k])));
+ }
+ if (ca > 1 || cb > 1) d.push_back(ab);
+ }
+ Diff r;
+ r.pixels = d.size();
+ if (d.empty()) return r;
+ double sum = 0;
+ size_t over = 0;
+ for (int v : d) sum += v, over += v > 8;
+ std::sort(d.begin(), d.end());
+ r.mean = sum / double(d.size());
+ r.p99 = d[std::min(d.size() - 1, size_t(double(d.size()) * 0.99))];
+ r.over8 = double(over) / double(d.size());
+ return r;
+}
+
+double median(std::vector<double> v) {
+ if (v.empty()) return 0;
+ std::sort(v.begin(), v.end());
+ return v[v.size() / 2];
+}
+
+} // namespace
+
+bool parseOptimisticBenchArg(int argc, char** argv, int& i, bool& run, OptimisticBenchOptions& o) {
+ const std::string a = argv[i];
+ auto next = [&]() -> std::string { return i + 1 < argc ? argv[++i] : std::string(); };
+ if (a == "--bench-optimistic") run = true;
+ else if (a == "--bench-optimistic-sizes") {
+ o.sizesMillions.clear();
+ std::stringstream ss(next());
+ for (std::string s; std::getline(ss, s, ',');)
+ if (!s.empty()) o.sizesMillions.push_back(std::atof(s.c_str()));
+ } else if (a == "--bench-optimistic-out") o.outPath = next();
+ else if (a == "--bench-optimistic-shots") o.shotsDir = next();
+ else return false;
+ return true;
+}
+
+int runOptimisticBench(const OptimisticBenchOptions& o) {
+ if (simulatedFloorTier()) ThreadPool::setSharedThreadCount(4); // SF_HW_SIMULATE=floor: the solver on 4 cores
+ if (!SDL_Init(SDL_INIT_VIDEO)) {
+ std::fprintf(stderr, "SDL_Init failed: %s\n", SDL_GetError());
+ return 1;
+ }
+ SDL_GL_SetAttribute(SDL_GL_CONTEXT_MAJOR_VERSION, 3);
+ SDL_GL_SetAttribute(SDL_GL_CONTEXT_MINOR_VERSION, 3);
+ SDL_GL_SetAttribute(SDL_GL_CONTEXT_PROFILE_MASK, SDL_GL_CONTEXT_PROFILE_CORE);
+ SDL_GL_SetAttribute(SDL_GL_CONTEXT_FLAGS, SDL_GL_CONTEXT_FORWARD_COMPATIBLE_FLAG);
+ SDL_Window* window = SDL_CreateWindow("SculptForge optimistic strokes", 320, 200, SDL_WINDOW_OPENGL | SDL_WINDOW_HIDDEN);
+ SDL_GLContext context = window ? SDL_GL_CreateContext(window) : nullptr;
+ if (!context) {
+ std::fprintf(stderr, "OpenGL 3.3 context creation failed: %s\n", SDL_GetError());
+ if (window) SDL_DestroyWindow(window);
+ SDL_Quit();
+ return 1;
+ }
+ SDL_GL_MakeCurrent(window, context);
+ int code = 0;
+ std::string error;
+ Renderer renderer;
+ if (const char* missing = gl::load([](const char* n) { return reinterpret_cast<gl::GenericProc>(SDL_GL_GetProcAddress(n)); })) {
+ std::fprintf(stderr, "Missing OpenGL function: %s\n", missing);
+ code = 1;
+ } else if (!renderer.init(error)) {
+ std::fprintf(stderr, "%s\n", error.c_str());
+ code = 1;
+ }
+ GLuint prog = 0, vao = 0;
+ if (code == 0) {
+ GLuint vs = compile(GL_VERTEX_SHADER, kVS, error), fs = compile(GL_FRAGMENT_SHADER, kFS, error);
+ prog = gl::CreateProgram();
+ gl::AttachShader(prog, vs);
+ gl::AttachShader(prog, fs);
+ gl::LinkProgram(prog);
+ GLint ok = 0;
+ gl::GetProgramiv(prog, GL_LINK_STATUS, &ok);
+ gl::DeleteShader(vs);
+ gl::DeleteShader(fs);
+ if (!ok) {
+ std::fprintf(stderr, "optimistic pass: %s\n", error.c_str());
+ code = 1;
+ }
+ gl::GenVertexArrays(1, &vao);
+ }
+ std::ostringstream md;
+ md << "## Optimistic screen-space strokes (N1), " << reinterpret_cast<const char*>(gl::GetString(GL_RENDERER)) << "\n\n"
+ << "Canvas " << kW << "x" << kH << ", Standard, " << o.dabs << " dabs of " << o.radiusPx << " px, strength 0.5.\n\n"
+ << "| Mesh | pass per dab (GPU, median / max) | whole stroke on the canvas | mesh: Standard dabs (CPU) + upload | "
+ "interior pop: optimistic vs truth (mean / p99 levels, > 8) | interior, doing nothing vs truth | pixels | "
+ "outline (coverage changed): pixels, pop vs doing nothing (mean) |\n"
+ << "|---|---:|---:|---:|---:|---:|---:|---:|\n";
+ for (double sizeM : o.sizesMillions) {
+ if (code) break;
+ Document doc;
+ std::fprintf(stderr, "core-200m N1: %gM head...\n", sizeM);
+ doc.mesh = makeBenchHead(size_t(sizeM * 1e6));
+ doc.bvh.build(doc.mesh);
+ Mesh& m = doc.mesh;
+ Camera cam;
+ cam.aspect = float(kW) / float(kH);
+ cam.frame(m.bounds());
+ RenderSettings rs;
+ std::vector<SceneMesh> scene{SceneMesh{1, &m, true, true}};
+ renderer.syncScene(scene);
+ Target canvas, out;
+ canvas.make(true);
+ out.make(false);
+ gl::BindFramebuffer(GL_FRAMEBUFFER, canvas.fbo);
+ gl::Viewport(0, 0, kW, kH);
+ renderer.draw(cam, kW, kH, rs);
+ gl::Finish();
+ const std::vector<uint8_t> before = readColor(canvas);
+ std::vector<float> depth(size_t(kW) * kH);
+ gl::BindFramebuffer(GL_FRAMEBUFFER, canvas.fbo);
+ gl::ReadPixels(0, 0, kW, kH, kDepthComponent, GL_FLOAT, depth.data());
+ gl::BindFramebuffer(GL_FRAMEBUFFER, 0);
+ const glm::mat4 view = cam.view(), proj = cam.projection(), invProj = glm::inverse(proj), invView = glm::inverse(view);
+ auto viewAt = [&](float x, float y) {
+ const int ix = std::clamp(int(x), 0, kW - 1), iy = std::clamp(int(y), 0, kH - 1);
+ const float d = depth[size_t(iy) * kW + ix];
+ glm::vec4 q = invProj * glm::vec4((x + 0.5f) / kW * 2 - 1, (y + 0.5f) / kH * 2 - 1, d * 2 - 1, 1);
+ return std::pair<glm::vec3, bool>(glm::vec3(q) / q.w, d < 1.0f);
+ };
+ // The stroke, from the canvas alone: a line across the face; each dab's centre from the depth under the
+ // pointer, its radius from the pixel size there, its area normal from the depth on a ring around it.
+ struct Dab {
+ glm::vec3 cView, nView;
+ float radius;
+ };
+ std::vector<Dab> dabs;
+ for (int i = 0; i < std::min(o.dabs, kMaxDabs); ++i) {
+ const float u = float(i) / float(std::max(1, o.dabs - 1));
+ const float x = kW * (0.38f + 0.24f * u), y = kH * (0.55f + 0.04f * std::sin(u * 6.2831853f));
+ auto [c, hit] = viewAt(x, y);
+ if (!hit) continue;
+ const float pxWorld = -c.z * 2.0f * std::tan(cam.fovY * 0.5f) / float(kH);
+ const float radius = o.radiusPx * pxWorld;
+ glm::vec3 nsum(0.0f);
+ for (int k = 0; k < 8; ++k) { // ring at half the radius: the area normal as the solver's averages it
+ const float a0 = 6.2831853f * k / 8, a1 = 6.2831853f * (k + 1) / 8, rr = 0.5f * o.radiusPx;
+ auto [p0, h0] = viewAt(x + rr * std::cos(a0), y + rr * std::sin(a0));
+ auto [p1, h1] = viewAt(x + rr * std::cos(a1), y + rr * std::sin(a1));
+ if (h0 && h1) nsum += glm::cross(p0 - c, p1 - c);
+ }
+ glm::vec3 n = glm::length(nsum) > 0 ? glm::normalize(nsum) : glm::vec3(0, 0, 1);
+ if (glm::dot(n, c) > 0) n = -n;
+ dabs.push_back({c, n, radius});
+ }
+ // Optimistic: each dab one pass over its rectangle (all dabs so far evaluated), timed GPU-side by Finish.
+ gl::BindFramebuffer(GL_READ_FRAMEBUFFER, canvas.fbo);
+ gl::BindFramebuffer(GL_DRAW_FRAMEBUFFER, out.fbo);
+ gl::BlitFramebuffer(0, 0, kW, kH, 0, 0, kW, kH, GL_COLOR_BUFFER_BIT, GL_NEAREST);
+ gl::UseProgram(prog);
+ gl::BindVertexArray(vao);
+ gl::Uniform1i(gl::GetUniformLocation(prog, "uColor"), 0);
+ gl::Uniform1i(gl::GetUniformLocation(prog, "uDepth"), 1);
+ gl::Uniform1i(gl::GetUniformLocation(prog, "uMatcapTex"), 2);
+ gl::UniformMatrix4fv(gl::GetUniformLocation(prog, "uInvProj"), 1, GL_FALSE, glm::value_ptr(invProj));
+ gl::UniformMatrix4fv(gl::GetUniformLocation(prog, "uProj"), 1, GL_FALSE, glm::value_ptr(proj));
+ gl::Uniform2f(gl::GetUniformLocation(prog, "uProjScale"), proj[0][0], proj[1][1]);
+ gl::Uniform2f(gl::GetUniformLocation(prog, "uSize"), float(kW), float(kH));
+ gl::ActiveTexture(GL_TEXTURE0 + 1);
+ gl::BindTexture(GL_TEXTURE_2D, canvas.depth);
+ gl::ActiveTexture(GL_TEXTURE0 + 2);
+ gl::BindTexture(GL_TEXTURE_2D, renderer.matcapTexture(rs.matcap));
+ gl::ActiveTexture(GL_TEXTURE0);
+ gl::BindTexture(GL_TEXTURE_2D, canvas.color); // (each pass re-shades its rectangle from the drawn canvas, all dabs so far)
+ gl::TexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GLint(GL_LINEAR));
+ gl::TexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GLint(GL_LINEAR));
+ std::vector<glm::vec4> uc, un;
+ std::vector<double> passMs;
+ const auto all0 = Clock::now();
+ gl::Enable(GL_SCISSOR_TEST);
+ for (size_t i = 0; i < dabs.size(); ++i) {
+ uc.push_back(glm::vec4(dabs[i].cView, dabs[i].radius));
+ un.push_back(glm::vec4(dabs[i].nView, 0.5f * dabs[i].radius * 0.06f));
+ gl::Finish();
+ const auto t = Clock::now();
+ gl::Uniform1i(gl::GetUniformLocation(prog, "uCount"), GLint(uc.size()));
+ gl::Uniform4fv(gl::GetUniformLocation(prog, "uDabC"), GLsizei(uc.size()), glm::value_ptr(uc[0]));
+ gl::Uniform4fv(gl::GetUniformLocation(prog, "uDabN"), GLsizei(un.size()), glm::value_ptr(un[0]));
+ // The dab's screen rectangle (its radius projected at its depth, plus a margin).
+ const glm::vec4 cc = proj * glm::vec4(dabs[i].cView, 1.0f);
+ const float sx = (cc.x / cc.w * 0.5f + 0.5f) * kW, sy = (cc.y / cc.w * 0.5f + 0.5f) * kH;
+ const int rp = int(std::ceil(o.radiusPx * 1.5f)) + 2; // (the surface may grow past the radius)
+ gl::BindFramebuffer(GL_FRAMEBUFFER, out.fbo);
+ gl::Viewport(0, 0, kW, kH);
+ gl::Scissor(int(sx) - rp, int(sy) - rp, 2 * rp, 2 * rp);
+ gl::DrawArrays(GL_TRIANGLES, 0, 3);
+ gl::Finish();
+ passMs.push_back(msSince(t));
+ }
+ gl::Disable(GL_SCISSOR_TEST);
+ const double allMs = msSince(all0);
+ gl::UseProgram(0);
+ const std::vector<uint8_t> optimistic = readColor(out);
+ // Truth: the same dabs by the Standard brush on the mesh (world space), then drawn.
+ Sculptor& sc = doc.sculptor;
+ Symmetry sym;
+ sym.x = false;
+ const auto s0 = Clock::now();
+ sc.beginStroke(m, "Standard");
+ for (const Dab& d : dabs) {
+ DabParams p;
+ p.center = glm::vec3(invView * glm::vec4(d.cView, 1.0f));
+ p.viewDir = glm::normalize(glm::vec3(invView * glm::vec4(d.cView, 0.0f)));
+ p.radius = d.radius;
+ p.strength = 0.5f;
+ sc.dab(m, doc.bvh, BrushType::Standard, p, sym);
+ }
+ sc.endStroke();
+ renderer.syncScene(scene);
+ gl::Finish();
+ const double solveMs = msSince(s0);
+ gl::BindFramebuffer(GL_FRAMEBUFFER, canvas.fbo);
+ gl::Viewport(0, 0, kW, kH);
+ renderer.draw(cam, kW, kH, rs);
+ gl::Finish();
+ const std::vector<uint8_t> truth = readColor(canvas);
+ std::vector<float> depthAfter(depth.size());
+ gl::BindFramebuffer(GL_FRAMEBUFFER, canvas.fbo);
+ gl::ReadPixels(0, 0, kW, kH, kDepthComponent, GL_FLOAT, depthAfter.data());
+ gl::BindFramebuffer(GL_FRAMEBUFFER, 0);
+ // Interior: surface before and after; outline: the stroke changed what covers the pixel (a re-shade can't).
+ std::vector<uint8_t> interior(depth.size()), outline(depth.size());
+ for (size_t i = 0; i < depth.size(); ++i) {
+ const bool a = depth[i] < 1.0f, b = depthAfter[i] < 1.0f;
+ interior[i] = a && b;
+ outline[i] = a != b;
+ }
+ const Diff pop = diff(optimistic, truth, before, &interior), none = diff(before, truth, before, &interior);
+ const Diff popEdge = diff(optimistic, truth, before, &outline), noneEdge = diff(before, truth, before, &outline);
+ char row[512];
+ std::snprintf(row, sizeof row, "| %.1fM | %.2f / %.2f ms | %.1f ms | %.0f ms | %.1f / %.0f, %.1f%% | %.1f / %.0f, %.1f%% | %zu | %zu: %.1f vs %.1f |\n",
+ double(m.triangleCount()) / 1e6, median(passMs), *std::max_element(passMs.begin(), passMs.end()), allMs,
+ solveMs, pop.mean, pop.p99, pop.over8 * 100, none.mean, none.p99, none.over8 * 100, none.pixels, popEdge.pixels, popEdge.mean, noneEdge.mean);
+ md << row;
+ std::fprintf(stderr, "%s", row);
+ if (!o.shotsDir.empty()) {
+ std::error_code ec;
+ std::filesystem::create_directories(o.shotsDir, ec);
+ char tag[32];
+ std::snprintf(tag, sizeof tag, "%gm", sizeM);
+ savePng(before, o.shotsDir + "/n1-" + tag + "-before.png");
+ savePng(optimistic, o.shotsDir + "/n1-" + tag + "-optimistic.png");
+ savePng(truth, o.shotsDir + "/n1-" + tag + "-truth.png");
+ std::vector<uint8_t> heat(truth.size(), 255); // |optimistic - truth| x 4, red on white
+ for (size_t i = 0; i < truth.size(); i += 4) {
+ int dmax = 0;
+ for (int k = 0; k < 3; ++k) dmax = std::max(dmax, std::abs(int(optimistic[i + k]) - int(truth[i + k])));
+ const uint8_t v = uint8_t(255 - std::min(255, dmax * 4));
+ heat[i + 1] = heat[i + 2] = v;
+ }
+ savePng(heat, o.shotsDir + "/n1-" + tag + "-pop.png");
+ }
+ canvas.release();
+ out.release();
+ renderer.syncScene({});
+ }
+ md << "\nPass: one GPU pass over the dab's rectangle evaluating every dab so far (its cost is the brush's pixels, not "
+ "the mesh). Mesh: the Standard brush on the CPU plus the upload, i.e. what the optimistic canvas hides. Pop: "
+ "per-pixel max channel difference over the pixels the stroke changed in either image.\n";
+ if (prog) gl::DeleteProgram(prog);
+ if (vao) gl::DeleteVertexArrays(1, &vao);
+ renderer.shutdown();
+ SDL_GL_DestroyContext(context);
+ SDL_DestroyWindow(window);
+ SDL_Quit();
+ if (o.outPath.empty()) std::printf("%s", md.str().c_str());
+ else std::ofstream(o.outPath) << md.str();
+ return code;
+}
+
+} // namespace sf
diff --git a/src/app/OptimisticBench.h b/src/app/OptimisticBench.h
new file mode 100644
index 00000000..2011a2ed
--- /dev/null
+++ b/src/app/OptimisticBench.h
@@ -0,0 +1,33 @@
+// SculptForge - open source digital sculpting
+// SPDX-License-Identifier: GPL-3.0-or-later
+//
+// Research (docs/design/core-200m.md §7b, N1): optimistic screen-space strokes, measured offline.
+//
+// sculptforge --bench-optimistic [--bench-sizes 5,15,33] [--bench-out FILE] [--bench-shots DIR]
+// For each size: the bench head drawn into a colour + depth canvas (1920x1080); a 240 px Standard stroke placed from
+// the canvas alone (dab centres and area normals from its depth); each dab applied to the canvas by one GPU pass over
+// its screen rectangle (re-shaded by the Lit Sphere ratio at the bent normal), timed; then the same dabs sculpted on
+// the real mesh by the Standard brush (timed: the latency the canvas hides) and drawn ("truth"). Reports the pass cost
+// against mesh size and the "pop" (optimistic image vs truth) against doing nothing (canvas before vs truth).
+#pragma once
+
+#include "core/Benchmark.h"
+
+#include <string>
+#include <vector>
+
+namespace sf {
+
+struct OptimisticBenchOptions {
+ std::vector<double> sizesMillions{5, 15, 33};
+ float radiusPx = 240.0f;
+ int dabs = 30;
+ std::string outPath; // Markdown report (default: stdout)
+ std::string shotsDir; // PNGs before / optimistic / truth per size (default: none)
+};
+
+// True when argv[i] was one of the options above (advancing i past its value); `run` set by --bench-optimistic.
+bool parseOptimisticBenchArg(int argc, char** argv, int& i, bool& run, OptimisticBenchOptions& o);
+int runOptimisticBench(const OptimisticBenchOptions& o);
+
+} // namespace sf
diff --git a/src/app/main.cpp b/src/app/main.cpp
index b853e166..abf842c5 100644
--- a/src/app/main.cpp
+++ b/src/app/main.cpp
@@ -4,8 +4,10 @@
#include "app/Bench.h"
#include "app/Calibration.h"
#include "app/CrashLog.h"
+#include "app/OptimisticBench.h"
#include "ai/AiPolicy.h"
#include "core/Benchmark.h"
+#include "core/Wavelet.h"
#include "core/FocusDetail.h"
#include "core/Pack.h"
@@ -154,11 +156,18 @@ int main(int argc, char** argv) {
std::string logDir, crashTest;
bool sizeGiven = false;
sf::BenchCommandLine bench;
+ bool optimistic = false; // --bench-optimistic (research, docs/design/core-200m.md N1)
+ sf::OptimisticBenchOptions optimisticOptions;
bool calibrate = false, calibrateQuick = false, calibrateSave = true;
for (int i = 1; i < argc; ++i) {
std::string a = argv[i];
auto next = [&]() -> std::string { return i + 1 < argc ? argv[++i] : std::string(); };
if (sf::parseBenchArg(argc, argv, i, bench)) continue;
+ if (sf::parseOptimisticBenchArg(argc, argv, i, optimistic, optimisticOptions)) continue;
+ if (std::string(argv[i]) == "--bench-wavelet") { // research (docs/design/core-200m.md N2), CPU only
+ const std::string out = i + 1 < argc && argv[i + 1][0] != '-' ? argv[++i] : std::string();
+ return sf::runWaveletBench(out);
+ }
if (a == "--calibrate") calibrate = true;
else if (a == "--calibrate-quick") calibrate = calibrateQuick = true;
else if (a == "--calibrate-no-save") calibrateSave = false;
@@ -226,6 +235,7 @@ int main(int argc, char** argv) {
}
if (automatedRun()) isolateSettings();
if (bench.run) return finishIsolated(sf::runAppBenchmark(bench));
+ if (optimistic) return finishIsolated(sf::runOptimisticBench(optimisticOptions));
if (calibrate) return finishIsolated(sf::runCalibrateCommandLine(calibrateQuick, calibrateSave));
if (!options.uiTest.empty()) {
if (!sizeGiven) options.width = 1600, options.height = 960;
diff --git a/src/core/Wavelet.cpp b/src/core/Wavelet.cpp
new file mode 100644
index 00000000..e4d6ff3c
--- /dev/null
+++ b/src/core/Wavelet.cpp
@@ -0,0 +1,193 @@
+// SculptForge - open source digital sculpting
+// SPDX-License-Identifier: GPL-3.0-or-later
+#include "core/Wavelet.h"
+
+#include "core/BVH.h"
+#include "core/Benchmark.h"
+#include "core/HardwareProfile.h"
+#include "core/Micro.h"
+#include "core/Sculpt.h"
+#include "core/ThreadPool.h"
+
+#include <algorithm>
+#include <atomic>
+#include <chrono>
+#include <cmath>
+#include <cstdio>
+#include <fstream>
+#include <sstream>
+#include <vector>
+
+namespace sf {
+
+namespace {
+
+// One lifting stage: every point new at spacing s gets (forward) its height less the floor-average of its two
+// parents on the spacing-2s lattice, or (inverse) that back. Modulo 2^16 both ways, so always exactly invertible.
+void stage(int16_t* g, uint32_t n, uint32_t s, bool forward) {
+ for (uint32_t j = 0; j <= n; j += s)
+ for (uint32_t i = 0; i + j <= n; i += s) {
+ const bool io = (i / s) & 1, jo = (j / s) & 1;
+ if (!io && !jo) continue; // (on the coarser lattice)
+ uint32_t ai, aj, bi, bj;
+ if (io && !jo) ai = i - s, aj = j, bi = i + s, bj = j; // along a row
+ else if (!io && jo) ai = i, aj = j - s, bi = i, bj = j + s; // along a column
+ else ai = i - s, aj = j + s, bi = i + s, bj = j - s; // along the diagonal
+ const int a = g[MicroMesh::index(ai, aj, n)], b = g[MicroMesh::index(bi, bj, n)];
+ const int p = (a + b) >> 1; // floor
+ int16_t& v = g[MicroMesh::index(i, j, n)];
+ v = int16_t(uint16_t(uint16_t(v) + uint16_t(forward ? -p : p)));
+ }
+}
+
+} // namespace
+
+void waveletForward(int16_t* grid, uint32_t n) {
+ for (uint32_t s = 1; s < n; s <<= 1) stage(grid, n, s, true);
+}
+
+void waveletInverse(int16_t* grid, uint32_t n) {
+ for (uint32_t s = n >> 1; s >= 1; s >>= 1) stage(grid, n, s, false);
+}
+
+void waveletAddCoarse(int16_t* coeffs, uint32_t n, uint32_t s, const std::function<int(uint32_t, uint32_t, int)>& delta) {
+ s = std::clamp<uint32_t>(s, 1, n);
+ for (uint32_t t = n >> 1; t >= s && t >= 1; t >>= 1) stage(coeffs, n, t, false); // the lattice's heights
+ for (uint32_t j = 0; j <= n; j += s)
+ for (uint32_t i = 0; i + j <= n; i += s) {
+ int16_t& v = coeffs[MicroMesh::index(i, j, n)];
+ v = int16_t(std::clamp(int(v) + delta(i, j, int(v)), -32767, 32767));
+ }
+ for (uint32_t t = s; t < n; t <<= 1) stage(coeffs, n, t, true); // back to coefficients; finer ones untouched
+}
+
+int runWaveletBench(const std::string& outPath) {
+ using Clock = std::chrono::steady_clock;
+ auto ms = [](Clock::time_point t) { return std::chrono::duration<double, std::milli>(Clock::now() - t).count(); };
+ if (simulatedFloorTier()) ThreadPool::setSharedThreadCount(4); // SF_HW_SIMULATE=floor: 4 cores
+ std::fprintf(stderr, "core-200m N2: building a Micro 7 head...\n");
+ Mesh m = makeCore200mMesh(20000, 7);
+ if (!m.micro) {
+ std::fprintf(stderr, "core-200m N2: no micro level\n");
+ return 1;
+ }
+ BVH bvh;
+ bvh.build(m);
+ MicroMesh& mm = mutableMicro(m);
+ mm.ensureTopology(m);
+ const AABB box = m.bounds();
+ const float height = box.max.y - box.min.y;
+ // Room for the largest dab, so neither path rescales the heights (the comparison stays in one unit).
+ mm.widen(float(mm.rangeMax) * mm.step + 0.5f * 0.2f * height * 0.06f * 1.5f);
+ const uint32_t n = mm.n, S = mm.samples;
+ const glm::vec3 c = (box.min + box.max) * 0.5f;
+ RayHit hit;
+ if (!surfaceRaycast(m, bvh, glm::vec3(c.x + 0.1f * height, c.y + 0.05f * height, box.max.z + height), glm::vec3(0, 0, -1), hit)) {
+ std::fprintf(stderr, "core-200m N2: no surface in front\n");
+ return 1;
+ }
+ std::ostringstream md;
+ md << "## Wavelet (multi-scale) displacement (N2): " << double(mm.microTriangles()) / 1e6 << "M micro triangles, Micro "
+ << mm.level << ", " << mm.baseTriangles << " patches, " << ThreadPool::shared().threads() << " threads\n\n"
+ << "Standard, strength 0.5, one dab. Today = the adaptive micro brush (MicroStroke: kernel on a stride, written "
+ "to every fine point, stitched). Wavelet = the kernel added to the coefficients of the lattice where the radius "
+ "spans >= 64 samples (finer coefficients untouched); reconstruct = the inverse transform of the touched patches "
+ "(the lazy push-up, needed only for what is drawn or picked). Error: |x - exact| over the touched points, exact "
+ "= the brush evaluated at every fine point, as a share of its largest change.\n\n"
+ << "| Radius (~px at a framing view) | patches | today: dab | wavelet: lattice | values written today / wavelet | "
+ "wavelet: dab | reconstruct | wavelet error (mean / max) | today's error (mean / max) |\n|---|---:|---:|---:|---:|---:|---:|---:|---:|\n";
+ std::vector<int16_t> original(mm.disp.begin(), mm.disp.end());
+ for (float frac : {0.025f, 0.05f, 0.1f, 0.2f}) {
+ const float r = frac * height;
+ // Today's brush.
+ std::copy(original.begin(), original.end(), mm.disp.begin());
+ MicroStroke stroke;
+ stroke.begin(m);
+ const auto t0 = Clock::now();
+ stroke.dab(m, bvh, BrushType::Standard, hit.position, glm::vec3(0, 0, -1), r, 0.5f, false, 0.0f, glm::vec3(0, 1, 0), false, 0.0f);
+ const double todayMs = ms(t0);
+ const uint64_t todayPoints = stroke.points;
+ stroke.end(m);
+ std::vector<int16_t> today(mm.disp.begin(), mm.disp.end());
+ // The exact brush (every fine point evaluated): the reference both are measured against.
+ std::copy(original.begin(), original.end(), mm.disp.begin());
+ MicroStroke exactStroke;
+ exactStroke.adaptive = false;
+ exactStroke.begin(m);
+ exactStroke.dab(m, bvh, BrushType::Standard, hit.position, glm::vec3(0, 0, -1), r, 0.5f, false, 0.0f, glm::vec3(0, 1, 0), false, 0.0f);
+ exactStroke.end(m);
+ std::vector<int16_t> exact(mm.disp.begin(), mm.disp.end());
+ std::copy(original.begin(), original.end(), mm.disp.begin());
+ // The patches the dab can reach (as the brush finds them: base triangles near the centre).
+ std::vector<uint32_t> tris;
+ bvh.queryTriangles(m, hit.position, r + mm.bulgeMax + float(mm.rangeMax) * mm.step, tris);
+ // Stored as coefficients (the one-time transform, not part of a dab).
+ for (uint32_t t : tris) waveletForward(mm.disp.data() + size_t(t) * S, n);
+ uint32_t s = 1; // the coarsest lattice where the radius still spans >= 64 samples
+ while (s < n / 2 && r / (mm.baseEdge * float(2 * s) / float(n)) >= 64.0f) s <<= 1;
+ const float invStep = 1.0f / mm.step, amp = 0.5f * r * 0.06f;
+ // The brush's area normal: the interpolated base normals under it, weighted by the falloff (as the brush's).
+ glm::vec3 nsum(0.0f);
+ for (uint32_t t : tris) {
+ MicroTriangle T;
+ T.set(m, t, n);
+ for (uint32_t j = 0; j <= n; j += s)
+ for (uint32_t i = 0; i + j <= n; i += s) {
+ glm::vec3 sp, nn;
+ T.eval(i, j, sp, nn);
+ const float dist = glm::length(sp - hit.position);
+ if (dist < r) nsum += nn * (1.0f - dist / r);
+ }
+ }
+ const glm::vec3 an = glm::length(nsum) > 0 ? glm::normalize(nsum) : glm::normalize(hit.normal);
+ std::atomic<uint64_t> written{0};
+ const auto t1 = Clock::now();
+ poolFor(tris.size(), [&](size_t b, size_t e) {
+ uint64_t w = 0;
+ for (size_t k = b; k < e; ++k) {
+ MicroTriangle T;
+ T.set(m, tris[k], n);
+ waveletAddCoarse(mm.disp.data() + size_t(tris[k]) * S, n, s, [&](uint32_t i, uint32_t j, int h) {
+ glm::vec3 sp, nn;
+ T.eval(i, j, sp, nn);
+ const float dist = glm::length(sp + nn * (float(h) * mm.step) - hit.position);
+ if (dist >= r) return 0;
+ const float tt = 1.0f - dist / r;
+ ++w;
+ return int(std::lround(amp * tt * tt * (3.0f - 2.0f * tt) * glm::dot(an, nn) * invStep));
+ });
+ }
+ written += w;
+ }, 4);
+ const double waveletMs = ms(t1);
+ const auto t2 = Clock::now();
+ poolFor(tris.size(), [&](size_t b, size_t e) {
+ for (size_t k = b; k < e; ++k) waveletInverse(mm.disp.data() + size_t(tris[k]) * S, n);
+ }, 4);
+ const double reconstructMs = ms(t2);
+ double sumW = 0, maxW = 0, sumT = 0, maxT = 0, maxChange = 0;
+ size_t count = 0;
+ for (uint32_t t : tris)
+ for (uint32_t k = 0; k < S; ++k) {
+ const size_t i = size_t(t) * S + k;
+ maxChange = std::max(maxChange, double(std::abs(int(exact[i]) - int(original[i]))));
+ const double dw = std::abs(int(mm.disp[i]) - int(exact[i])), dt = std::abs(int(today[i]) - int(exact[i]));
+ sumW += dw, maxW = std::max(maxW, dw), sumT += dt, maxT = std::max(maxT, dt), ++count;
+ }
+ const double scale = 100.0 / std::max(maxChange, 1.0), per = 1.0 / double(std::max<size_t>(count, 1));
+ char row[512];
+ std::snprintf(row, sizeof row, "| %.3f (~%.0f px) | %zu | %.2f ms | spacing %u (%u per edge) | %.2fM / %.1fk | %.2f ms | %.1f ms | %.2f%% / %.1f%% | %.2f%% / %.1f%% |\n",
+ double(r), double(frac * 1080.0f), tris.size(), todayMs, s, n / s, double(todayPoints) / 1e6,
+ double(written.load()) / 1e3, waveletMs, reconstructMs, sumW * per * scale, maxW * scale, sumT * per * scale, maxT * scale);
+ md << row;
+ std::fprintf(stderr, "%s", row);
+ }
+ std::copy(original.begin(), original.end(), mm.disp.begin());
+ md << "\nValues written today: grid points the brush visited (MicroStroke::points). The wavelet dab's cost follows "
+ "the lattice points, so it falls (relative to today) as the brush grows.\n";
+ if (outPath.empty()) std::printf("%s", md.str().c_str());
+ else std::ofstream(outPath) << md.str();
+ return 0;
+}
+
+} // namespace sf
diff --git a/src/core/Wavelet.h b/src/core/Wavelet.h
new file mode 100644
index 00000000..8d740556
--- /dev/null
+++ b/src/core/Wavelet.h
@@ -0,0 +1,32 @@
+// SculptForge - open source digital sculpting
+// SPDX-License-Identifier: GPL-3.0-or-later
+//
+// Research (docs/design/core-200m.md §7b, N2): multi-scale displacement on micro patches.
+//
+// A patch's grid of 16-bit heights (core/Micro.h layout, n = 2^L segments) as interpolating-wavelet coefficients by
+// integer lifting: a point that is new at spacing s (its coordinates multiples of s, not all of 2s) stores its height
+// minus the floor-average of its two parents on the coarser edge through it (the points s away along that edge); the
+// three corners store their heights. Arithmetic is modulo 2^16, so the transform is exactly invertible whatever the
+// values. A coarse edit (waveletAddCoarse) changes only the points of the spacing-s lattice: the finer coefficients,
+// the detail, ride along and the edit reaches the fine points as its linear interpolation when reconstructed.
+#pragma once
+
+#include <cstdint>
+#include <functional>
+#include <string>
+
+namespace sf {
+
+// In place, heights -> coefficients (finest spacing first) and back (coarsest first). n = 2^L, (n+1)(n+2)/2 values.
+void waveletForward(int16_t* grid, uint32_t n);
+void waveletInverse(int16_t* grid, uint32_t n);
+// Coefficients of one patch: adds delta(i, j, height) (in units of the height step; i, j on the spacing-`s` lattice,
+// `height` the point's current height) to the lattice points, touching only that lattice's coefficients
+// ((n/s+1)(n/s+2)/2 points).
+void waveletAddCoarse(int16_t* coeffs, uint32_t n, uint32_t s, const std::function<int(uint32_t i, uint32_t j, int height)>& delta);
+
+// sculptforge --bench-wavelet / sculptforge-cli --bench-wavelet: a micro head (Micro 7), a Standard dab of growing
+// radius on today's adaptive micro brush against the coarse wavelet edit; Markdown to `outPath` (or stdout).
+int runWaveletBench(const std::string& outPath);
+
+} // namespace sf
diff --git a/tests/test_micro.cpp b/tests/test_micro.cpp
index f26da718..92aed49f 100644
--- a/tests/test_micro.cpp
+++ b/tests/test_micro.cpp
@@ -12,6 +12,7 @@
#include "core/Primitives.h"
#include "core/Project.h"
#include "core/TierConfig.h"
+#include "core/Wavelet.h"
#include "io/Zip.h"
#include <chrono>
@@ -600,3 +601,28 @@ TEST(micro_core200m_scene_small) {
for (size_t i = 0; i < mm.disp.size() && same; ++i) same = back.mesh.micro->disp[i] == mm.disp[i];
CHECK(same);
}
+
+TEST(wavelet_round_trip_and_coarse_edit) {
+ // N2 (docs/design/core-200m.md): the integer lifting transform is exactly invertible, whatever the values, and a
+ // coarse edit leaves the fine detail alone: the result is the old surface plus the coarse change interpolated.
+ const uint32_t n = 32, S = (n + 1) * (n + 2) / 2;
+ std::vector<int16_t> g(S), orig;
+ uint32_t seed = 12345;
+ for (int16_t& v : g) seed = seed * 1664525u + 1013904223u, v = int16_t(seed >> 16);
+ orig = g;
+ waveletForward(g.data(), n);
+ CHECK(g != orig);
+ waveletInverse(g.data(), n);
+ CHECK(g == orig);
+ // A smooth surface with fine detail, then a constant raise on the spacing-8 lattice.
+ for (uint32_t j = 0; j <= n; ++j)
+ for (uint32_t i = 0; i + j <= n; ++i)
+ g[MicroMesh::index(i, j, n)] = int16_t(100 * i + 37 * j + ((i * 7 + j * 13) % 5) * 20);
+ orig = g;
+ waveletForward(g.data(), n);
+ waveletAddCoarse(g.data(), n, 8, [](uint32_t, uint32_t, int) { return 500; });
+ waveletInverse(g.data(), n);
+ int worst = 0;
+ for (uint32_t k = 0; k < S; ++k) worst = std::max(worst, std::abs(int(g[k]) - int(orig[k]) - 500));
+ CHECK(worst <= 3); // (floor averages round at most once per finer level: 3 levels below spacing 8)
+}