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
// SculptForge - open source digital sculpting
// SPDX-License-Identifier: GPL-3.0-or-later
#pragma once
#include "core/IndexBits.h"
#include "core/PaintLayer.h"
#include <glm/glm.hpp>
#include <cstdint>
#include <limits>
#include <memory>
#include <functional>
#include <span>
#include <string>
#include <utility>
#include <vector>
namespace sf {
struct PaintTexture;
struct MultiresStack;
struct SubdivTopology;
struct ImplicitAdjacency;
struct MicroMesh;
struct SelectionSetList;
// The vertices or triangles around a vertex (Mesh::neighbors, Mesh::vertexTriangles), in ascending order: a view
// of the mesh's adjacency lists or, where the mesh's adjacency is implicit, the list itself. Use it like a span
// (but don't keep a pointer into it past its lifetime).
class IndexRing {
public:
static constexpr uint32_t kCapacity = 64;
IndexRing() = default;
IndexRing(const uint32_t* b, const uint32_t* e) : ptr_(b), size_(uint32_t(e - b)) {}
const uint32_t* data() const { return ptr_ ? ptr_ : buf_; }
const uint32_t* begin() const { return data(); }
const uint32_t* end() const { return data() + size_; }
size_t size() const { return size_; }
bool empty() const { return size_ == 0; }
uint32_t operator[](size_t i) const { return data()[i]; }
uint32_t front() const { return data()[0]; }
uint32_t back() const { return data()[size_ - 1]; }
private:
friend class Mesh;
const uint32_t* ptr_ = nullptr; // null: the indices are in buf_
uint32_t size_ = 0;
uint32_t buf_[kCapacity]; // (not initialised: only the first size_ are used)
};
struct AABB {
glm::vec3 min{std::numeric_limits<float>::max()};
glm::vec3 max{std::numeric_limits<float>::lowest()};
void expand(const glm::vec3& p) {
min = glm::min(min, p);
max = glm::max(max, p);
}
void expand(const AABB& b) {
min = glm::min(min, b.min);
max = glm::max(max, b.max);
}
bool valid() const { return min.x <= max.x; }
glm::vec3 center() const { return (min + max) * 0.5f; }
glm::vec3 extent() const { return max - min; }
};
// A sculpt layer: per-vertex offsets blended in with a weight. Layers are
// exported as glTF morph targets (blend shapes) for facial/corrective animation.
struct SculptLayer {
std::string name;
std::vector<glm::vec3> delta;
float weight = 1.0f;
};
// Triangle mesh with vertex adjacency, suitable for sculpting.
//
// Optional attributes (see docs/architecture-attributes.md) are empty until
// a feature needs them, so plain meshes pay nothing. When present their size
// always matches the vertex / triangle / corner count; rebuildTopology()
// drops any that don't.
// One sphere of a Forge Sphere armature (core/Forge Spheres.h): the root is index 0 with parent -1; every other sphere
// grows from `parent`.
struct ForgeSphere {
glm::vec3 center{0.0f};
float radius = 1.0f;
int parent = -1;
};
// A Tube's curve (core/Tube.h): control points the tube passes through, each with its own radius. Not empty =
// a Tube Part, whose triangles are swept along the curve until Bake.
struct TubePoint {
glm::vec3 position{0.0f};
float radius = 0.1f;
};
struct TubeShape {
std::vector<TubePoint> points;
bool flatCaps = false; // flat ends instead of round
bool mirrorX = false; // a mirror copy across x = 0 (symmetry X)
float edge = 0.0f; // target edge length; 0 = from the radius (16 sides around the average)
bool empty() const { return points.empty(); }
};
class Mesh {
public:
std::vector<glm::vec3> positions;
std::vector<glm::vec3> normals;
std::vector<glm::uvec3> triangles;
// Per vertex: mask (0 = free, 1 = fully masked) and vertex paint (linear RGB, 0..1).
std::vector<float> mask;
std::vector<glm::vec3> colors;
// Per triangle: face group id (empty = everything in group 0) and hidden flag (empty = all visible).
std::vector<uint32_t> facegroups;
std::vector<uint8_t> hidden;
// Per triangle corner (3 per triangle, in triangle order): texture coordinates.
std::vector<glm::vec2> uvs;
// Per triangle corner (empty = none): UV editing flags (core/Uv.h), kUvSeam on the edge from this corner to
// the next (a marked seam, kept on both sides of the edge) and kUvPin (the corner's UV stays put on Unwrap).
std::vector<uint8_t> uvFlags;
// Per triangle: the triangle it forms a quad with (kNoQuad = a plain triangle; empty = no quads). Imported
// quads are split into two triangles that keep each other here, so the wireframe and the exporters can
// show and write them as quads again. Pairs are symmetric and share one edge, wound oppositely;
// sanitizeAttributes() unpairs anything else, so topology changes can never leave a stale pair.
std::vector<uint32_t> quadPartners;
static constexpr uint32_t kNoQuad = ~0u;
bool hasMask() const { return !mask.empty(); }
bool hasColors() const { return !colors.empty(); }
bool hasFaceGroups() const { return !facegroups.empty(); }
bool hasHidden() const { return !hidden.empty(); }
bool hasUvs() const { return !uvs.empty(); }
bool hasUvFlags() const { return !uvFlags.empty(); }
bool hasQuads() const { return !quadPartners.empty(); }
float maskAt(uint32_t v) const { return mask.empty() ? 0.0f : mask[v]; }
glm::vec3 colorAt(uint32_t v, const glm::vec3& fallback = glm::vec3(1.0f)) const {
return colors.empty() ? fallback : colors[v];
}
uint32_t facegroupAt(uint32_t t) const { return facegroups.empty() ? 0u : facegroups[t]; }
bool triangleHidden(uint32_t t) const { return !hidden.empty() && hidden[t] != 0; }
// The triangle `t` is shown and exported as one quad with, or kNoQuad: a stored pair whose halves share a
// face group (a pair split between groups shows and exports as two triangles).
uint32_t quadPartnerAt(uint32_t t) const {
if (quadPartners.empty()) return kNoQuad;
const uint32_t u = quadPartners[t];
return u < quadPartners.size() && facegroupAt(t) == facegroupAt(u) ? u : kNoQuad;
}
// Which edge of `t` (t[e] -> t[(e + 1) % 3]) is the diagonal it shares with triangle `u` (wound the other
// way in `u`, whose third corner is not on `t`), or -1 when they don't form a quad.
int quadDiagonal(uint32_t t, uint32_t u) const;
// Face for exporting `t`: returns 4 with the quad's corners in winding order (t[e+1], t[e+2], t[e], then the
// partner's far corner, so an (a,b,c) + (a,c,d) split gives (a,b,c,d) back), 3 with the triangle, or 0 when
// `t` is the second half of a quad written with its partner.
int exportFace(uint32_t t, glm::uvec4& face) const;
// Number of quads (pairs counted once by quadPartnerAt).
size_t quadCount() const;
// True when every triangle around `v` is hidden (such vertices must not be edited).
bool vertexHidden(uint32_t v) const;
// Allocate an attribute (no-op if present); returns it for convenience.
std::vector<float>& ensureMask(float fill = 0.0f);
std::vector<glm::vec3>& ensureColors(const glm::vec3& fill = glm::vec3(1.0f));
std::vector<uint32_t>& ensureFaceGroups(uint32_t fill = 0);
std::vector<uint8_t>& ensureHidden();
std::vector<uint32_t>& ensureQuadPartners();
// Records triangles `t` and `u` as one quad (growing quadPartners to the triangle count, so it can be called
// while triangles are being added).
void pairQuad(uint32_t t, uint32_t u);
// Free an attribute again once it holds only its default (e.g. after "clear mask" / "show all").
void clearMask() { std::vector<float>().swap(mask); }
void clearColors() { std::vector<glm::vec3>().swap(colors); }
void clearFaceGroups() { std::vector<uint32_t>().swap(facegroups); }
void clearHidden() { std::vector<uint8_t>().swap(hidden); }
void clearQuads() { std::vector<uint32_t>().swap(quadPartners); }
// Drops attributes whose size no longer matches the mesh and unpairs invalid quad pairs (called by
// rebuildTopology).
void sanitizeAttributes();
// Sculpt layers. While any exist, `base` holds the positions with every
// layer at zero and positions == base + sum(layer.weight * layer.delta).
std::vector<glm::vec3> base;
std::vector<SculptLayer> layers;
int addLayer(std::string name);
void removeLayer(int index);
// Re-evaluates every vertex and recomputes normals (BVH must be rebuilt by the caller).
void setLayerWeight(int index, float weight);
// The array a stroke on `layer` writes to (-1 = base), and the weight its offsets are scaled by.
std::vector<glm::vec3>& layerTarget(int layer);
float layerTargetWeight(int layer) const;
// Recomputes positions of `verts` from base + layers.
void evaluate(std::span<const uint32_t> verts);
void evaluateAll();
const std::vector<glm::vec3>& basePositions() const { return layers.empty() ? positions : base; }
// Paint layers (core/PaintLayer.h). While any exist, `paintBase` holds the
// Base layer and `colors` the composited stack; `activePaintLayer` is the
// layer painting writes into (-1 = Base). Empty = plain vertex paint in `colors`.
std::vector<glm::vec3> paintBase;
std::vector<PaintLayer> paintLayers;
int activePaintLayer = -1;
// Texture painting (core/Texture.h): an RGBA texture on the UVs, shared by copies of the mesh until
// one of them changes it (mutableTexture copies first). `paintToTexture`: the Paint brush, fills and
// the paint layers work on the texture instead of the vertices.
std::shared_ptr<PaintTexture> texture;
bool paintToTexture = false;
// Subdivision levels (core/Multires.h): the stack this mesh is one level of, shared copy-on-write by
// copies of the mesh. Null = a plain mesh. sanitizeAttributes() drops it if the topology no longer fits.
std::shared_ptr<MultiresStack> multires;
// Micro-displacement level (core/Micro.h): above this mesh (the base, its highest subdivision level), a grid of
// scalar displacements per triangle that the brushes and the renderer use instead of the mesh. Shared
// copy-on-write by copies of the mesh (mutableMicro). Null = none. sanitizeAttributes() drops it if the
// triangle or vertex count changes.
std::shared_ptr<MicroMesh> micro;
// Forge Spheres (core/Forge Spheres.h): not empty = a Forge Sphere Part, whose triangles are made from this armature (the
// spheres and their links, or the skin while `Forge SpherePreview`). Copies, undo steps and projects carry it.
std::vector<ForgeSphere> forgespheres;
bool forgespherePreview = false;
// Tube (core/Tube.h): not empty = a Tube Part, whose triangles are swept from this curve; Bake clears it.
TubeShape tube;
// Selection Sets (core/SelectionSets.h): named snapshots of the mask, face groups, vertex paint, hidden faces, UVs
// and shape, immutable and shared by copies of the mesh (undo steps swap the whole list). They belong to the
// Part, not to one subdivision level: stepping levels keeps them. Null = none.
std::shared_ptr<const SelectionSetList> selectionSets;
size_t vertexCount() const { return positions.size(); }
size_t triangleCount() const { return triangles.size(); }
// Must be called after the triangle list or vertex count changes. A mesh that is the current level of its
// subdivision stack, made by Divide, gets implicit adjacency (implicitAdjacency).
void rebuildTopology();
void recomputeAllNormals();
// Recompute normals of the faces around `verts` and of every vertex they touch. With `curvature` (indexed
// by vertex), also each of those vertices' curvatureAt, from the same triangles (a brush stroke hands it to
// the renderer, which then needn't walk the rings again).
void updateNormals(std::span<const uint32_t> verts, float* curvature = nullptr);
// The same, given the vertices whose normals may have changed (any superset: the others come out the
// same): fill(begin, end, set) adds those of jobs [begin, end) of `count` with set.insertLocal(). A brush
// gives the corners of the BVH leaves its query listed, which is cheaper than every moved vertex's ring.
void updateNormalsAround(size_t count, size_t grain, const std::function<void(size_t, size_t, IndexBits&)>& fill,
float* curvature = nullptr);
// Marks the vertices fill() lists dirty for the GPU without recomputing their normals (a draft stroke, whose
// normals wait for its end: Sculptor::draftStrokes).
void markDirtyAround(size_t count, size_t grain, const std::function<void(size_t, size_t, IndexBits&)>& fill);
// The renderer's cavity term at `v` (render/Clusters.h): how far the average of the other corners of its
// triangles sits above the vertex along its normal (> 0 in a crease), over their mean distance. Each
// neighbour of an inner vertex of a manifold is the corner of two of its triangles, so this is the average
// over its ring.
float curvatureAt(uint32_t v) const;
// The vertices sharing an edge with `v`, and the triangles around it, in ascending order.
IndexRing neighbors(uint32_t v) const {
if (implicit_) return implicitNeighbors(v);
return {adjList_.data() + adjOffsets_[v], adjList_.data() + (adjEnds_.empty() ? adjOffsets_[v + 1] : adjEnds_[v])};
}
IndexRing vertexTriangles(uint32_t v) const {
if (implicit_) return implicitTriangles(v);
return {vtList_.data() + vtOffsets_[v], vtList_.data() + (vtEnds_.empty() ? vtOffsets_[v + 1] : vtEnds_[v])};
}
// The vertices sharing a polygon edge with `v`: neighbors() less the far ends of the quad diagonals at `v`
// (each quad is stored as two triangles; its diagonal is no edge of the polygon). Smoothing averages this ring:
// with the diagonals, a vertex on one end of a quad's diagonal and not the other is pulled along it, which
// shears a quad mesh into zigzags (#69). Without quads, neighbors() itself.
IndexRing polygonNeighbors(uint32_t v) const {
if (quadPartners.empty()) return neighbors(v);
return quadNeighbors(v);
}
// True when the adjacency follows from the subdivision level this mesh is (see rebuildTopology).
bool implicitAdjacency() const { return bool(implicit_); }
// Dynamic topology (core/Dyntopo.h): adjacency lists that can be rewritten one vertex at a time, so local
// remeshing under the brush doesn't rebuild the whole mesh's. Between begin and end each vertex's lists
// have their own capacity (a list that outgrows it moves to the end of the arrays); end packs them back
// into the usual form. rebuildTopology() also ends it. Not for meshes with implicit adjacency.
bool beginDynamicAdjacency();
void endDynamicAdjacency();
bool dynamicAdjacency() const { return !adjEnds_.empty(); }
// Replace vertex v's triangles / ring (ascending). v may be vertexCount() - 1 after addVertexSlot().
void setVertexTriangles(uint32_t v, std::span<const uint32_t> tris);
void setNeighbors(uint32_t v, std::span<const uint32_t> ring);
// Appends empty lists for a new last vertex, or drops the last vertex's (the caller sizes the vertex arrays).
void addVertexSlot();
void removeLastVertexSlot();
AABB bounds() const;
// Bytes this mesh holds (every array, topology included; not the shared texture or subdivision stack).
size_t memoryBytes() const;
// GPU synchronisation state: [dirtyBegin, dirtyEnd) bounds what needs re-uploading,
// topologyDirty means everything (including indices) does.
// Vertex attributes (mask, colours) share the vertex range; facesDirty
// means per-triangle state (hidden, face groups) needs re-uploading.
// Within the range each changed vertex has a bit in dirtyBits, and each block of kDirtyBlock vertices with
// any a mark in dirtyBlocks, so uploads find a dab's vertices without scanning the mesh (core/UploadOrder.h).
uint32_t dirtyBegin = std::numeric_limits<uint32_t>::max();
uint32_t dirtyEnd = 0;
bool topologyDirty = true;
bool facesDirty = true;
static constexpr uint32_t kDirtyBlockShift = 11, kDirtyBlock = 1u << kDirtyBlockShift; // 2048 vertices
std::vector<uint8_t> dirtyBlocks;
std::vector<uint64_t> dirtyBits;
// Dynamic topology (core/Dyntopo.h): triangle slots whose corners changed (in place, added, removed or
// renumbered, so possibly >= triangleCount()) since the last upload. A renderer can patch those instead of
// a full upload; topologyDirty still means everything. Cleared by clearDirty().
std::vector<uint32_t> changedTriangles;
void markDirty(uint32_t v) {
dirtyBegin = std::min(dirtyBegin, v);
dirtyEnd = std::max(dirtyEnd, v + 1);
const size_t b = v >> kDirtyBlockShift;
if (b >= dirtyBlocks.size()) growDirtyBlocks(b + 1);
dirtyBlocks[b] = 1;
dirtyBits[v >> 6] |= uint64_t(1) << (v & 63);
}
void growDirtyBlocks(size_t blocks); // (out of line: rarely needed)
// Marks the vertices [begin, end).
void markDirtyRange(uint32_t begin, uint32_t end);
void clearDirty();
void markAllDirty() {
if (positions.empty()) return;
markDirtyRange(0, static_cast<uint32_t>(positions.size()));
}
bool vertexDirty(uint32_t v) const { return (v >> 6) < dirtyBits.size() && (dirtyBits[v >> 6] >> (v & 63)) & 1; }
private:
void finishTopology();
bool beginNormalSet(); // updateNormals: room for the set (false: no topology)
void finishNormals(float* curvature, bool computeNormals = true); // ... then each member's normal (and curvatureAt)
IndexRing implicitTriangles(uint32_t v) const;
IndexRing implicitNeighbors(uint32_t v) const;
IndexRing quadNeighbors(uint32_t v) const;
// Vertex adjacency (CSR), or, on a mesh that is a level made by Divide (whose triangles are the ones its
// subdivision topology generates), that topology and two small indexes into it: the triangles and rings
// around a vertex are worked out from the coarse polygons around it instead of stored, which saves about 24
// bytes per triangle.
std::vector<uint32_t> adjOffsets_, adjList_;
std::vector<uint32_t> vtOffsets_, vtList_;
std::shared_ptr<const ImplicitAdjacency> implicit_; // (core/Mesh.cpp)
// Dynamic adjacency (beginDynamicAdjacency): each list starts at its offset and ends at its end, with
// room up to offset + cap. Empty otherwise.
std::vector<uint32_t> adjEnds_, adjCaps_, vtEnds_, vtCaps_;
static void setList(std::vector<uint32_t>& offsets, std::vector<uint32_t>& ends, std::vector<uint32_t>& caps,
std::vector<uint32_t>& list, uint32_t v, std::span<const uint32_t> values);
// updateNormals: the vertices to update, as a set and as a list.
IndexBits normalBits_;
std::vector<uint32_t> scratchVerts_;
};
// Shape-preserving Taubin (lambda/mu) smoothing of positions; needs topology.
// Ignores sculpt layers, so use it on freshly built meshes.
void taubinSmooth(Mesh& m, int iterations);
// Merges coincident vertices (UV/normal seams from importers), drops
// degenerate triangles and builds topology and normals. `layers` (optional)
// hold per-vertex deltas indexed like m.positions and become sculpt layers.
// Optional attributes of `m` are carried over (vertex ones from the first
// vertex of each welded group, triangle/corner ones per kept triangle).
Mesh weldImported(const Mesh& m, const std::vector<SculptLayer>& layers = {});
// Carries the quad pairs of `src` over to `dst`, built from some of its triangles: `newIndex[t]` is the index of
// src triangle t in dst (Mesh::kNoQuad = dropped). Pairs that lost a half are dropped; call before
// dst.rebuildTopology(), which checks the rest.
void remapQuads(const Mesh& src, const std::vector<uint32_t>& newIndex, Mesh& dst);
// Appends the quad pairs of `src` (whose triangles were appended to `dst` after `firstTriangle` others).
void appendQuads(Mesh& dst, size_t firstTriangle, const Mesh& src);
// Mesh::colors are linear RGB; files that store display colours (OBJ, PLY) convert.
glm::vec3 srgbToLinear(const glm::vec3& c);
glm::vec3 linearToSrgb(const glm::vec3& c);
// Gives every vertex of `dst` the mask and colour of the nearest vertex of
// `src` (only the attributes `src` has). For rebuilt surfaces such as voxel
// remesh or re-imported scans; needs no topology.
void transferVertexAttributes(const Mesh& src, Mesh& dst);
} // namespace sf