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.

Focal Shift shapes alpha brushes, ClayBuildup and custom brushes (#60)

islandmedbaecf0413a50
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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
### Added
diff --git a/docs/guide/sculpting.md b/docs/guide/sculpting.md
index 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 model
you 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, bend
over 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 every
brush, 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.
![The alpha picker](images/alpha-picker.jpg)
diff --git a/src/core/BrushAlpha.cpp b/src/core/BrushAlpha.cpp
index 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.h
index 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.cpp
index 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, const
if (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, const
const 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.h
index 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, fl
float 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.cpp
index 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 co
if (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.cpp
index 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 = &square;
+ 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 = &square;
+ 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.cpp
index 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 = &square;
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.sfui
new file mode 100644
index 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