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.
C++ 3d3d-sculptingcppdear-imguidigital-sculptingfbxgame-developmentgaussian-splattinggltfimage-to-3dmcpopenglopenusdsculptingtext-to-3dunreal-engine
Focal Shift shapes alpha brushes, ClayBuildup and custom brushes (#60)
islandmedbaecf0413a50
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 48a643f3..bbd6fe02 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,13 @@ All notable changes to SculptForge are listed here. The format follows## [Unreleased]+### Fixed+- Focal Shift now shapes brushes that use an alpha, as in ZBrush (#60): the alpha is multiplied by the round+ falloff Focal Shift controls, so at -100 the whole alpha shows hard to its edges, at 0 a Square alpha's corners+ round off into a soft mound, and at +100 only a soft point in the middle is left. Before, alpha brushes always+ behaved as at -100. Focal Shift also reaches the built-in ClayBuildup's square tip and custom (Brush Lab)+ brushes now, which ignored it; at 0 they keep their own tip exactly as before.+## [0.10.4] - 2026-11-01### Addeddiff --git a/docs/guide/sculpting.md b/docs/guide/sculpting.mdindex fc085f74..efabf5a7 100644--- a/docs/guide/sculpting.md+++ b/docs/guide/sculpting.md@@ -141,8 +141,12 @@ Because **Draw Size** is measured on screen, the brush covers less of the modelyou want for detail work.The brush cursor shows two rings, as in ZBrush: the outer one is the Draw Size, the inner one is Focal Shift-(where the brush works at half strength). Masking, painting, Move and SnakeHook follow Focal Shift too; custom-brushes made in Brush Lab keep their own tip shape.+(where the brush works at half strength). Masking, painting, Move and SnakeHook follow Focal Shift too. Custom+brushes made in Brush Lab and ClayBuildup's square tip keep their own tip shape at 0 and shift it like the others.++With an [alpha](#alphas), Focal Shift works as in ZBrush: the alpha is multiplied by the round falloff. At -100+the whole alpha shows, hard to its edges (a Square alpha stamps the full square); at 0 the falloff softens it and+rounds a square's corners; at +100 only a soft point in the middle is left.Over the model, the rings lie on the surface, as in SculptGL: they turn with the surface under the pointer, bendover its bumps and curves, and show the brush's real size there, with a short line pointing out of the surface.@@ -249,6 +253,9 @@ Notes:An alpha is a grayscale stamp that shapes the brush tip: white is full effect, black is none. It affects everybrush, built-in or custom. Choose one from the **Alpha** tile on the left shelf (the alpha picker) or the**Alpha** palette, which also shows a large preview of the current alpha.+[Focal Shift](#draw-size-z-intensity-rgb-intensity-and-focal-shift) fades it as in ZBrush: set it to -100 to+stamp the whole alpha (a crisp square, or a pattern out to its edges), 0 for a soft round fade, +100 for a soft+point.diff --git a/src/core/BrushAlpha.cpp b/src/core/BrushAlpha.cppindex 203a8cf3..da7cb151 100644--- a/src/core/BrushAlpha.cpp+++ b/src/core/BrushAlpha.cpp@@ -295,6 +295,13 @@ float BrushAlpha::sample(float u, float v) const {return a + (b - a) * ty;}+float BrushAlpha::stamp(float u, float v, float focal) const {+ const float d = std::sqrt(u * u + v * v);+ if (empty()) return d < 1.0f ? brushFalloff(d, 1.0f, focal) : 0.0f;+ const float a = sample(u, v);+ return a > 0.0f ? a * alphaFalloff(d, 1.0f, focal) : 0.0f;+}+BrushAlpha BrushAlpha::round() { return BrushAlpha{}; }BrushAlpha BrushAlpha::square() {diff --git a/src/core/BrushAlpha.h b/src/core/BrushAlpha.hindex 9c303880..d39497d0 100644--- a/src/core/BrushAlpha.h+++ b/src/core/BrushAlpha.h@@ -26,6 +26,8 @@ struct BrushAlpha {bool empty() const { return values.empty(); }// u, v in brush-local -1..1 (v points up); 0 outside the stamp.float sample(float u, float v) const;+ // What a dab uses: sample() x alphaFalloff (Focal Shift, -1..1; #60). Empty = brushFalloff with `focal`.+ float stamp(float u, float v, float focal) const;static BrushAlpha round();static BrushAlpha square();diff --git a/src/core/Sculpt.cpp b/src/core/Sculpt.cppindex 13bf2f0a..322b3c2b 100644--- a/src/core/Sculpt.cpp+++ b/src/core/Sculpt.cpp@@ -50,6 +50,11 @@ float focalRingFraction(float focal) {return 1.0f - std::pow(0.5f, 1.0f / k);}+float alphaFalloff(float dist, float radius, float focal) {+ const float f = brushFalloff(dist, radius * kAlphaReach, focal);+ return focal < 0.0f ? f + (1.0f - f) * std::min(-focal, 1.0f) : f; // (-1: flat to the corners)+}+void brushVertices(const Mesh& mesh, const BVH& bvh, const glm::vec3& center, float radius, std::vector<uint32_t>& out) {bvh.queryVertices(mesh, center, radius, out);if (mesh.hasHidden()) std::erase_if(out, [&](uint32_t v) { return mesh.vertexHidden(v); });@@ -505,7 +510,7 @@ void Sculptor::dab(Mesh& mesh, BVH& bvh, BrushType type, const DabParams& p, Sym}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;+ const float reach = useAlpha ? kAlphaReach : type == BrushType::ClayBuildup ? 1.3f : 1.0f;remeshDab(mesh, bvh, p, sym, type == BrushType::Smooth ? 2.0f : 1.0f, reach);}dabVerts_.clear();@@ -528,7 +533,7 @@ void Sculptor::dabSingle(Mesh& mesh, BVH& bvh, BrushType type, const DabParams&auto clock = std::chrono::steady_clock::now();// Alphas and the square ClayBuildup tip reach into the corners of their square.const bool useAlpha = p.alpha && !p.alpha->empty();- const float reach = useAlpha ? 1.4143f : type == BrushType::ClayBuildup ? 1.3f : 1.0f;+ const float reach = useAlpha ? kAlphaReach : type == BrushType::ClayBuildup ? 1.3f : 1.0f;brushVertices(mesh, bvh, p.center, p.radius * reach, verts_);if (verts_.empty()) return;@@ -582,7 +587,7 @@ void Sculptor::dabSingle(Mesh& mesh, BVH& bvh, BrushType type, const DabParams&const uint32_t v = verts_[i];const glm::vec3& x = pos[v];const glm::vec3 o = x - p.center;- const float f = useAlpha ? p.alpha->sample(glm::dot(o, right) / r, glm::dot(o, up) / r)+ const float f = useAlpha ? p.alpha->stamp(glm::dot(o, right) / r, glm::dot(o, up) / r, p.focal): brushFalloff(glm::length(o), r, p.focal);glm::vec3 d(0.0f);@@ -655,6 +660,13 @@ void Sculptor::dabSingle(Mesh& mesh, BVH& bvh, BrushType type, const DabParams&const float corner = std::clamp((1.3f - glm::length(o) / r) / 0.3f, 0.0f, 1.0f);const float edge = std::clamp((1.0f - cheb) / 0.35f, 0.0f, 1.0f);w = edge * edge * (3.0f - 2.0f * edge) * corner;+ // Focal Shift (#60) keeps this tip at 0: below, harder edges and a broader slab; above, it fades+ // toward a soft round point, as an alpha does.+ if (p.focal < 0.0f) w = std::pow(w, std::exp2(2.0f * std::max(p.focal, -1.0f)));+ else if (p.focal > 0.0f) {+ const float k = std::min(p.focal, 1.0f);+ w *= 1.0f - k + k * brushFalloff(glm::length(o), r * 1.3f, k);+ }}glm::vec3 planePoint = areaCenter + areaNormal * (sign * r * 0.08f * s);float h = glm::dot(x - planePoint, areaNormal);@@ -825,7 +837,8 @@ void Sculptor::dabRecipeSingle(Mesh& mesh, BVH& bvh, const BrushRecipe& r, constif (verts_.empty()) return;const auto& pos = mesh.positions;const auto& nrm = mesh.normals;- // An alpha (if any) modulates the recipe's tip, oriented on the view-facing plane.+ // An alpha (if any) modulates the recipe's tip, oriented on the view-facing plane. Focal Shift shifts the tip+ // (0 keeps the recipe's own Hardness / Tip Sharpness), and so the alpha with it.const bool useAlpha = p.alpha && !p.alpha->empty();glm::vec3 aUp = projectOnPlane(p.alphaUp, p.viewDir);aUp = glm::length(aUp) > 1e-6f ? glm::normalize(aUp) : glm::vec3(0, 1, 0);@@ -851,6 +864,7 @@ void Sculptor::dabRecipeSingle(Mesh& mesh, BVH& bvh, const BrushRecipe& r, constconst AreaSums sums = areaSums(verts_.size(), [&](size_t i, AreaSums& acc) {const uint32_t v = verts_[i];float t = std::clamp((1.0f - glm::distance(pos[v], p.center) / rad) / edge, 0.0f, 1.0f);+ if (p.focal != 0.0f) t = std::pow(t, std::exp2(2.0f * std::clamp(p.focal, -1.0f, 1.0f))); // (brushFalloff's)float w = std::pow(t * t * (3.0f - 2.0f * t), exponent);acc.normal += nrm[v] * w;acc.center += pos[v] * w;diff --git a/src/core/Sculpt.h b/src/core/Sculpt.hindex 65f43beb..482963eb 100644--- a/src/core/Sculpt.h+++ b/src/core/Sculpt.h@@ -57,7 +57,7 @@ struct DabParams {glm::vec3 strokeDelta{0.0f}; // world-space movement since the previous dab (recipe, SnakeHook, Nudge, DamStandard)const BrushAlpha* alpha = nullptr; // stamp shaping the falloff (null/empty = round)glm::vec3 alphaUp{0.0f, 1.0f, 0.0f}; // world direction of the alpha's top edge (screen up, or rotated)- float focal = 0.0f; // ZBrush Focal Shift, -1..1 (see brushFalloff); recipes keep their own tip+ float focal = 0.0f; // ZBrush Focal Shift, -1..1 (brushFalloff; alphaFalloff with an alpha)const VectorDisplacement* vdm = nullptr; // the Vdm brush's map (null = the built-in Horn); top edge = alphaUp// Smooth: keep the volume (#40). A Taubin step, one shrink then one inflate, removes bumps as the plain// (Laplacian) smooth does without shrinking the form. Not on micro levels (they smooth plainly).@@ -86,6 +86,12 @@ void brushVertices(const Mesh& mesh, const BVH& bvh, const glm::vec3& center, flfloat brushFalloff(float dist, float radius, float focal = 0.0f);// Where brushFalloff drops to one half, as a fraction of the radius (the brush cursor's inner ring).float focalRingFraction(float focal);+// An alpha's stamp covers the square around the brush circle: its corners are radius x sqrt 2 out.+constexpr float kAlphaReach = 1.4143f;+// Focal Shift on an alpha brush (#60), as in ZBrush: the alpha is multiplied by this round falloff, which reaches+// the stamp's corners (radius x kAlphaReach). -1 is 1 everywhere (the alpha shows hard to its edges), 0 the+// smoothstep (soft, rounding a square alpha's corners), +1 a narrow soft point (the alpha mostly gone).+float alphaFalloff(float dist, float radius, float focal);// Where brush time goes (core/Benchmark.h, Help > Performance): milliseconds summed over dabs since the// counters were last zeroed. kernel = finding the vertices and moving / masking / painting them.diff --git a/src/core/Texture.cpp b/src/core/Texture.cppindex 6c3d6610..1f1ce28c 100644--- a/src/core/Texture.cpp+++ b/src/core/Texture.cpp@@ -1292,8 +1292,9 @@ size_t TexturePainter::dabTiles(const DabContext& c, const Paint& paint, bool coif (d2 >= c.r2) continue;const glm::vec3 N = c.normals ? N0 * b.x + N1 * b.y + N2 * b.z : faceN;if (glm::dot(N, mi.viewDir) > 0.0f) continue;- const float f = c.useAlpha ? c.p.alpha->sample(glm::dot(o, mi.aRight) / c.r, glm::dot(o, mi.aUp) / c.r)- : brushFalloff(std::sqrt(d2), c.r, c.p.focal);+ const float f = c.useAlpha+ ? c.p.alpha->stamp(glm::dot(o, mi.aRight) / c.r, glm::dot(o, mi.aUp) / c.r, c.p.focal)+ : brushFalloff(std::sqrt(d2), c.r, c.p.focal);const float wgt = f * c.s * (1.0f - std::clamp(m0 * b.x + m1 * b.y + m2 * b.z, 0.0f, 1.0f));if (wgt <= 0.0f) continue;if (!rec) rec = &tile(ti, c.target, w, h, c.tex);@@ -1501,7 +1502,7 @@ size_t TexturePainter::dab(Mesh& mesh, const BVH& bvh, const DabParams& p, const// Front faces only: never paint through to the far side.const glm::vec3 N = normals ? N0 * b.x + N1 * b.y + N2 * b.z : faceN;if (glm::dot(N, mi.viewDir) > 0.0f) return;- const float f = useAlpha ? p.alpha->sample(glm::dot(o, mi.aRight) / r, glm::dot(o, mi.aUp) / r)+ const float f = useAlpha ? p.alpha->stamp(glm::dot(o, mi.aRight) / r, glm::dot(o, mi.aUp) / r, p.focal): brushFalloff(std::sqrt(d2), r, p.focal);const float wgt = f * s * (1.0f - std::clamp(m0 * b.x + m1 * b.y + m2 * b.z, 0.0f, 1.0f));if (wgt <= 0.0f) return;diff --git a/tests/test_brushes.cpp b/tests/test_brushes.cppindex 268e0a88..bd2dce41 100644--- a/tests/test_brushes.cpp+++ b/tests/test_brushes.cpp@@ -329,7 +329,9 @@ TEST(alpha_shapes_and_orients_dabs) {BrushAlpha square = BrushAlpha::square();DabParams p = dabAt(glm::vec3(0));p.alpha = □+ p.focal = -1.0f; // (Focal Shift -100: the alpha shows hard to its edges; at 0 it rounds the corners, #60)stroke(sq, BrushType::Standard, p);+ p.focal = 0.0f;const uint32_t c = nearest(sq.mesh, glm::vec3(0)), diag = nearest(sq.mesh, glm::vec3(0.25f, 0, 0.25f));CHECK(sq.mesh.positions[diag].y > 0.9f * sq.mesh.positions[c].y);CHECK(round.mesh.positions[diag].y == 0.0f);@@ -368,6 +370,79 @@ TEST(alpha_shapes_and_orients_dabs) {CHECK(r.mesh.positions[nearest(r.mesh, glm::vec3(0.12f, 0, 0))].y == 0.0f);}+// #60: Focal Shift shapes alpha brushes as in ZBrush. The alpha is multiplied by a round falloff reaching the+// stamp's corners: -100 shows the whole square, 0 rounds its corners into a soft mound, +100 leaves a small point.+TEST(focal_shift_shapes_alpha_dabs) {+ CHECK(alphaFalloff(0.0f, 1.0f, 0.0f) == 1.0f);+ for (float d : {0.0f, 0.5f, 1.0f, 1.3f, 1.414f}) CHECK(alphaFalloff(d, 1.0f, -1.0f) == 1.0f);+ CHECK(alphaFalloff(1.2f, 1.0f, 0.0f) < 0.1f && alphaFalloff(1.5f, 1.0f, 0.0f) == 0.0f);+ CHECK(alphaFalloff(0.5f, 1.0f, 1.0f) < 0.5f * alphaFalloff(0.5f, 1.0f, 0.0f));++ const BrushAlpha square = BrushAlpha::square();+ CHECK(square.stamp(0.7f, 0.7f, -1.0f) == square.sample(0.7f, 0.7f));+ CHECK(square.stamp(0.7f, 0.7f, 0.0f) < 0.5f * square.stamp(0.7f, 0.0f, 0.0f)); // rounded corners+ CHECK(square.stamp(1.2f, 0.0f, -1.0f) == 0.0f);+ const BrushAlpha round = BrushAlpha::round(); // (empty: the plain brush falloff, Focal Shift included)+ CHECK(round.stamp(0.4f, 0.0f, 0.5f) == brushFalloff(0.4f, 1.0f, 0.5f) && round.stamp(1.1f, 0.0f, -1.0f) == 0.0f);++ // A square-alpha dab: how much moves (footprint) and how much of the corner survives.+ struct Footprint { int moved = 0; float corner = 0.0f, centre = 0.0f; };+ auto dabWith = [&](BrushType type, float focal) {+ Document d = planeDoc();+ DabParams p = dabAt(glm::vec3(0));+ p.alpha = □+ p.alphaUp = glm::vec3(0, 0, -1);+ p.focal = focal;+ stroke(d, type, p);+ Footprint f;+ for (const glm::vec3& v : d.mesh.positions) f.moved += std::abs(v.y) > 1e-4f;+ f.corner = d.mesh.positions[nearest(d.mesh, glm::vec3(0.22f, 0, 0.22f))].y;+ f.centre = d.mesh.positions[nearest(d.mesh, glm::vec3(0))].y;+ return f;+ };+ for (BrushType type : {BrushType::Standard, BrushType::ClayBuildup}) {+ const Footprint hard = dabWith(type, -1.0f), soft = dabWith(type, 0.0f), point = dabWith(type, 1.0f);+ CHECK(hard.centre > 0.0f && soft.centre > 0.0f && point.centre > 0.0f);+ CHECK(hard.moved > soft.moved && soft.moved > point.moved);+ CHECK(hard.corner > 0.8f * hard.centre); // the full square+ CHECK(soft.corner < 0.5f * soft.centre); // corners rounded+ CHECK(point.corner < 0.05f * point.centre); // almost gone+ CHECK(point.moved < hard.moved / 2);+ }+}++// #60: Focal Shift reaches the built-in square ClayBuildup tip and custom (recipe) brushes; 0 keeps their own tip.+TEST(focal_shift_reaches_clay_buildup_and_recipes) {+ auto height = [&](float focal, bool recipe, const glm::vec3& at) {+ Document d = planeDoc();+ DabParams p = dabAt(glm::vec3(0));+ p.focal = focal;+ if (recipe) {+ BrushRecipe r;+ r.name = "test";+ d.sculptor.beginStroke(d.mesh, "test");+ d.sculptor.dabRecipe(d.mesh, d.bvh, r, p, kNoSymmetry);+ d.undo.push(d.sculptor.endStroke());+ } else {+ stroke(d, BrushType::ClayBuildup, p);+ }+ const uint32_t v = nearest(d.mesh, at);+ return d.mesh.positions[v].y / std::max(d.mesh.positions[nearest(d.mesh, glm::vec3(0))].y, 1e-9f);+ };+ for (bool recipe : {false, true}) {+ const glm::vec3 at = recipe ? glm::vec3(0.15f, 0, 0) : glm::vec3(0.27f, 0, 0); // (on the tip's soft edge)+ const float hard = height(-0.8f, recipe, at), plain = height(0.0f, recipe, at), soft = height(0.8f, recipe, at);+ CHECK(hard > plain + 0.02f && plain > soft + 0.02f);+ }+ // 0 is bit-identical to no Focal Shift at all (the brush's own tip).+ Document a = planeDoc(), b = planeDoc();+ DabParams p = dabAt(glm::vec3(0));+ stroke(a, BrushType::ClayBuildup, p);+ p.focal = 0.0f;+ stroke(b, BrushType::ClayBuildup, p);+ CHECK(a.mesh.positions == b.mesh.positions);+}+TEST(brush_set_alpha_command) {CommandRegistry reg;Document d = planeDoc();diff --git a/tests/test_texture.cpp b/tests/test_texture.cppindex b0c6a8f7..8b7b72be 100644--- a/tests/test_texture.cpp+++ b/tests/test_texture.cpp@@ -631,6 +631,7 @@ TEST(texture_dab_sharpness_does_not_depend_on_mesh_density) {DabParams p = dab(glm::vec3(0.013f, 0, -0.021f), 0.1f);p.alpha = □p.alphaUp = glm::vec3(0, 0, 1);+ p.focal = -1.0f; // (Focal Shift -100 keeps the alpha hard to its edge; 0 would soften it, #60)CHECK(painter.dab(m, bvh, p, glm::vec3(0.0f), Symmetry{false, false, false}) > 0);UndoRecord rec;painter.end(rec);diff --git a/tests/ui/focal_alpha.sfui b/tests/ui/focal_alpha.sfuinew file mode 100644index 00000000..10aa359f--- /dev/null+++ b/tests/ui/focal_alpha.sfui@@ -0,0 +1,40 @@+# #60: Focal Shift shapes brushes with an alpha, as in ZBrush. The same Square-alpha dab moves the whole square at+# -100, a rounded mound at 0 and only a small point at +100 (moved_sum: the summed movement).+run new_sphere subdivisions=5+run brush_set_alpha name=square+click "Standard##brush.standard"++key o+key minus+key 1+key 0+key 0+key enter+expect_value focal_shift == -100+snapshot+stroke 0.5 0.5 0.5 0.5+remember moved_sum hard+expect_value moved > 50+key ctrl+z++key o+key 0+key enter+expect_value focal_shift == 0+snapshot+stroke 0.5 0.5 0.5 0.5+remember moved_sum soft+expect_value moved_sum < $hard*0.8+shot focal-alpha-soft+key ctrl+z++key o+key 1+key 0+key 0+key enter+expect_value focal_shift == 100+snapshot+stroke 0.5 0.5 0.5 0.5+expect_value moved_sum < $soft*0.6+expect_value moved_sum < $hard*0.3