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.

Coarse levels: one level for every visible cluster (the finest that fits), not per cluster

islandmed3feba900e0da
diff --git a/docs/design/micro-coarse-lod.md b/docs/design/micro-coarse-lod.md
index adc7bbfd..62891440 100644
--- a/docs/design/micro-coarse-lod.md
+++ b/docs/design/micro-coarse-lod.md
@@ -60,11 +60,13 @@ drawn vs the floor's 2M budget; png_diff against the flag off where the base edg
## What shipped first (plain meshes, 2026-11-05)
-- Grids as in item 1, the first cell 4x the mean edge (a 2x level drew too much to pay for its memory), up to five
- levels; each cell's point and normal kept, so an edit can recompute them. Clusters are main's UploadOrder ones
+- Grids as in item 1, the first cell 4x the mean edge (a 2x level drew too much to pay for its memory), five levels
+ for every cluster; each cell's point and normal kept, so an edit can recompute them. Clusters are main's UploadOrder ones
(not yet n2stroke's micro layout: join there when it lands, MicroRenderer's clusters would take the same lists).
-- Selection as item 3 (0.75 px at rest, twice that while the view moves), raised x1.5 until the tier's budget holds;
- everything fitting in full detail draws in full. No balance pass yet: clusters at different levels may leave a gap
- of a coarse cell along their seam, under a pixel or two at the thresholds used.
+- Selection: not per cluster (item 3) but one level for every visible cluster, the finest whose triangles fit the
+ tier's budget; everything fitting in full detail draws in full. Per-cluster levels left visible gaps along seams
+ wherever two levels met, and a scan's clusters (64-triangle chunks in the file's triangle order) are ragged strips,
+ so the seams are everywhere: one level keeps the surface closed with no balance pass or border rule. Distance-adaptive
+ levels come back with compact clusters (n2stroke's layout) and item 4's border fallback.
- Edits: clusters a stroke moved draw in full until the first frame without new edits, which recomputes their levels
and every cell point within a cell of the edit (cells for vertices pushed where none were are added).
diff --git a/src/render/Clusters.cpp b/src/render/Clusters.cpp
index 1b2a9e51..cf155897 100644
--- a/src/render/Clusters.cpp
+++ b/src/render/Clusters.cpp
@@ -450,7 +450,7 @@ CoarseLevels buildCoarseLevels(const Mesh& mesh, const UploadOrder& order) {
size_t previous = order.clusterTriangles(uint32_t(c));
for (int level = 0; level < int(L.levels.size()); ++level) {
float error = 0.0f;
- if (!clusterOnCells(L, mesh, order, uint32_t(c), level, tris, error) || tris.empty() || tris.size() * 10 > previous * 8) break;
+ if (!clusterOnCells(L, mesh, order, uint32_t(c), level, tris, error)) break; // (every level: one is drawn for all)
lod.first[lod.levels] = uint32_t(lists[c].size());
lod.count[lod.levels] = uint32_t(tris.size() * 3);
lod.capacity[lod.levels] = roomFor(tris.size() * 3);
@@ -459,7 +459,6 @@ CoarseLevels buildCoarseLevels(const Mesh& mesh, const UploadOrder& order) {
for (const auto& m : tris) lists[c].insert(lists[c].end(), m.begin(), m.end());
lists[c].resize(lod.first[lod.levels - 1] + lod.capacity[lod.levels - 1], 0);
previous = tris.size();
- if (tris.size() < 8) break;
}
lists[c].shrink_to_fit();
}
diff --git a/src/render/Clusters.h b/src/render/Clusters.h
index 39d6e2c4..7c787c8a 100644
--- a/src/render/Clusters.h
+++ b/src/render/Clusters.h
@@ -79,8 +79,8 @@ bool clusterProxy(const Mesh& mesh, const UploadOrder& order, uint32_t c, size_t
// over the whole mesh, the first cell four times the mean edge, each next level twice as coarse; a cell's point is the
// mean of the vertices in it (its normal their normals' sum). Every cluster gets per level its triangles mapped to
// cells (degenerate and repeated ones dropped) and its error, the farthest any of its vertices is from its cell's
-// point. Two clusters at one level share their cells' points: no cracks between them. A cluster's chain stops when a
-// level would keep more than 80% of the one before.
+// point. Two clusters at one level share their cells' points: no cracks between them, so the renderer draws every
+// cluster at one level (levels side by side would leave gaps along the seams: a scan's clusters are ragged strips).
struct CoarseLevels {
static constexpr int kMaxLevels = 5;
struct Lod {
diff --git a/src/render/Renderer.cpp b/src/render/Renderer.cpp
index 95bfbb19..f37e9325 100644
--- a/src/render/Renderer.cpp
+++ b/src/render/Renderer.cpp
@@ -3152,59 +3152,38 @@ void Renderer::cull(const MeshSlot& s, const CullView& frame, bool proxy) {
}
}
-// Clark 1976 / QSplat: per cluster the coarsest level whose error, projected at the cluster's nearest point, stays
-// under `px` pixels; `px` is raised (x1.5) until the triangles drawn fit `budget`. Everything fitting in full detail
-// draws in full. (No normal cones for the coarse levels: their back faces go to the GPU's culling.)
-void Renderer::cullCoarse(const MeshSlot& s, const CullView& frame, float px, size_t budget) {
+// Clark 1976: the detail from what the screen can hold. Everything in full detail if it fits the budget; else every
+// visible cluster at one level, the finest that fits (the coarsest if none does): one level for all keeps the surface
+// closed (render/Clusters.h). Clusters an edit moved draw in full until updated (their seams may gap until then).
+void Renderer::cullCoarse(const MeshSlot& s, const CullView& frame, size_t budget) {
cull(s, frame, false); // (the visible clusters, in full)
coarseClusters_.clear();
coarseLevel_.clear();
- lodScratch_.clear();
- const bool ortho = frameProj_[3][3] == 1.0f;
- const float unit = 0.5f * frameViewport_.w * frameProj_[1][1]; // pixels per world unit at distance 1
- // (back-facing clusters cull() dropped may still be wanted coarse: the same frustum test, no cone)
size_t full = 0;
- const size_t nc = std::min(s.bounds.size(), s.drawCount.size());
- std::vector<uint8_t>& shown = coarseShown_;
- shown.assign(nc, 0);
- for (uint32_t c : drawClusters_) shown[c] = 1;
- for (uint32_t c = 0; c < nc; ++c) {
- if (s.drawCount[c] == 0 || !insideFrustum(frame, s.bounds[c])) continue;
- const ClusterBounds& b = s.bounds[c];
- const float d = std::max(glm::dot(b.center - frame.eye, frame.forward) - b.radius, std::max(frame.nearDistance, 1e-6f));
- lodScratch_.push_back({c, ortho ? unit : unit / d, shown[c] != 0});
- if (shown[c]) full += size_t(s.drawCount[c]) / 3;
- }
- drawClusters_.clear();
- auto level = [&](const LodPick& k, float t) {
- const CoarseLevels::Lod& lod = s.coarse->clusters[k.c];
- if (s.coarseDirty[k.c]) return -1; // (edited: in full until updated)
- int pick = -1;
- while (pick + 1 < lod.levels && lod.error[pick + 1] * k.scale <= t) ++pick;
- return pick;
- };
- float t = px;
- if (full > budget) {
- for (int round = 0; round < 30; ++round, t *= 1.5f) {
- size_t total = 0;
- for (const LodPick& k : lodScratch_) {
- const int l = level(k, t);
- total += l < 0 ? (k.fullShows ? size_t(s.drawCount[k.c]) / 3 : 0) : s.coarse->clusters[k.c].count[l] / 3;
- }
- if (total <= budget) break;
+ for (uint32_t c : drawClusters_) full += size_t(s.drawCount[c]) / 3;
+ if (full <= budget) return;
+ // (clusters facing away stay out: the coarse ones go to the GPU's culling as the full ones)
+ const CoarseLevels& L = *s.coarse;
+ int pick = int(L.levels.size()) - 1;
+ for (int level = 0; level < int(L.levels.size()); ++level) {
+ size_t total = 0;
+ for (uint32_t c : drawClusters_)
+ total += s.coarseDirty[c] || L.clusters[c].levels <= level ? size_t(s.drawCount[c]) / 3 : L.clusters[c].count[level] / 3;
+ if (total <= budget) {
+ pick = level;
+ break;
}
- } else {
- t = 0.0f;
}
- for (const LodPick& k : lodScratch_) {
- const int l = t > 0.0f ? level(k, t) : -1;
- if (l < 0) {
- if (k.fullShows) drawClusters_.push_back(k.c);
+ size_t kept = 0;
+ for (uint32_t c : drawClusters_) {
+ if (s.coarseDirty[c] || L.clusters[c].levels <= pick) {
+ drawClusters_[kept++] = c;
} else {
- coarseClusters_.push_back(k.c);
- coarseLevel_.push_back(uint8_t(l));
+ coarseClusters_.push_back(c);
+ coarseLevel_.push_back(uint8_t(pick));
}
}
+ drawClusters_.resize(kept);
}
// Draws `clusters` of `s` (the VAO for `part` bound): their triangles, the wireframe's edges, or their motion
@@ -3478,7 +3457,7 @@ void Renderer::drawSlot(const MeshSlot& s, bool active, bool flat, const RenderS
if (static const bool log = std::getenv("SF_COARSE_LOG") != nullptr; log && s.coarse && !coarse)
std::fprintf(stderr, "coarse lod: not drawn (per-triangle %d, wireframe %d, drawn %zu, budget %zu)\n", int(perTriangle),
int(active && settings.wireframe), s.drawnTriangles, budget);
- if (coarse) cullCoarse(s, frameCull_, kCoarseLodPx * (settings.motionProxy ? 2.0f : 1.0f), budget);
+ if (coarse) cullCoarse(s, frameCull_, budget);
else cull(s, frameCull_, settings.motionProxy && coarseAllowed);
// The back faces left in clusters along the silhouette: the GPU skips them too when they can't show.
if (cullBackfaces_ || xrayCull_) gl::Enable(GL_CULL_FACE);
diff --git a/src/render/Renderer.h b/src/render/Renderer.h
index 15dfa560..489097e0 100644
--- a/src/render/Renderer.h
+++ b/src/render/Renderer.h
@@ -418,12 +418,11 @@ private:
bool proxyPrebuild_ = false; // (setProxyPrebuild)
double proxyMsPerCluster_ = 0.0; // measured, so a frame's batches fit its budget on slow cores too
// Coarse levels (docs/design/micro-coarse-lod.md; SF_COARSE_LOD=0 turns them off): plain meshes over the triangle
- // budget draw per cluster a coarse level (render/Clusters.h: CoarseLevels), at rest too: the coarsest whose error
- // stays under kCoarseLodPx on screen, raised until the budget holds; full detail when it all fits.
+ // budget draw every visible cluster at one coarse level (render/Clusters.h: CoarseLevels), the finest that fits the
+ // budget; full detail when it all fits.
const bool coarseLod_ = !(std::getenv("SF_COARSE_LOD") && std::string(std::getenv("SF_COARSE_LOD")) == "0");
void markCoarseDirty(MeshSlot& s, uint32_t c);
void updateCoarse(MeshSlot& s, const Mesh& mesh);
- static constexpr float kCoarseLodPx = 0.75f;
size_t lodBudget_ = 0; // the last still draw's triangle budget: sync builds the coarse levels of meshes over it
void buildCoarse(MeshSlot& s, const Mesh& mesh);
void uploadCoarsePoints(MeshSlot& s);
@@ -475,18 +474,11 @@ private:
// The clusters of `s` to draw this frame: in full (drawClusters_), and with `proxy` as their motion proxy
// where it is built (proxyClusters_).
void cull(const MeshSlot& s, const CullView& view, bool proxy = false);
- // The coarse-level cull (spike): every visible cluster in full (drawClusters_) or at a level (coarseClusters_,
- // coarseLevel_): per cluster the coarsest whose error stays under `px` pixels, `px` raised until `budget` holds.
- void cullCoarse(const MeshSlot& s, const CullView& view, float px, size_t budget);
+ // The coarse-level cull: every visible cluster in full (drawClusters_) if that fits `budget`, else at one level
+ // (coarseClusters_, coarseLevel_), the finest that fits.
+ void cullCoarse(const MeshSlot& s, const CullView& view, size_t budget);
std::vector<uint32_t> coarseClusters_;
std::vector<uint8_t> coarseLevel_;
- struct LodPick {
- uint32_t c;
- float scale; // pixels per world unit at the cluster's nearest point
- bool fullShows;
- };
- std::vector<LodPick> lodScratch_;
- std::vector<uint8_t> coarseShown_;
void drawSlot(const MeshSlot& s, bool active, bool flat, const RenderSettings& settings);
enum class DrawPart { Triangles, Lines, Proxy };
void drawPatches(const MeshSlot& s, GLenum mode, DrawPart part, GLint primBaseLocation);
diff --git a/tests/test_render_clusters.cpp b/tests/test_render_clusters.cpp
index 3d8f023e..2ad57b1f 100644
--- a/tests/test_render_clusters.cpp
+++ b/tests/test_render_clusters.cpp
@@ -396,7 +396,7 @@ TEST(coarse_levels_closed_at_each_level_and_light) {
if (l.levels == 0) continue;
first += l.count[0] / 3;
coarsest += l.count[l.levels - 1] / 3;
- for (int k = 1; k < l.levels; ++k) shrinking = shrinking && l.count[k] < l.count[k - 1] && l.error[k] >= l.error[k - 1];
+ for (int k = 1; k < l.levels; ++k) shrinking = shrinking && l.count[k] <= l.count[k - 1] && l.error[k] >= l.error[k - 1];
}
std::printf(" coarse levels: %zu cells; level 0 %zu, coarsest %zu of %zu triangles; every cluster has %zu levels or more\n",
L.positions.size(), first, coarsest, m.triangleCount(), minLevels);