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
//
// Focus Detail (prototype, off by default; docs/design/focus-detail.md): a micro level (core/Micro.h) far larger
// than what is worth decompressing, streamed by where the brush and the camera are.
//
// - On disk (a .sfdetail file, memory-mapped): the base mesh, then every base triangle's micro grid ("tile") as
// quantized 16-bit heights, row-delta coded and compressed (zstd when the build has it, else the tile codec of
// core/MicroStore.h). A directory gives each tile's place, its exact range and how far its coarse grid is from
// it. Coarse grids (level kCoarseLevel, a subsample of the full grid) sit in compressed chunks of kChunk tiles.
// - In memory: MicroMesh::disp keeps its full-size layout, so brushes and the renderer work unchanged. A tile
// outside the focus holds its coarse grid upsampled (exact at the coarse points, linear in between, so shared
// edges stay watertight); a tile in the focus holds its full grid.
// - The focus: the tiles under and ahead of the brush (its position plus velocity, a short time ahead) and the
// visible tiles whose coarse grid would be more than FocusView::errorPx off on screen. Promotions run each
// frame within a time budget, highest priority first; demotions free the least recently wanted tiles once the
// full tiles exceed budgetBytes (a tile wanted in the last 8 frames stays). Brushes and undo never write a coarse tile: MicroStroke::touch and
// MicroUndo::swapWith promote the tiles they are about to change first (ensureFull).
// - Edited tiles are dirty until saved; a dirty tile that gets demoted is compressed into memory ("parked").
// save() appends only the dirty and parked tiles, the coarse chunks holding them and a new directory, then
// rewrites the header (the old directory stays valid until then: a crash keeps the last save).
// - When a brush widens the displacement range (MicroMesh::widen), rescale() divides the coarse grids and parked
// tiles at once and the tiles still in the file as they are read (a per-tile shift in the directory).
// Undo needs nothing new: a stroke's MicroUndo already keeps copy-on-write deltas of the tiles it touched.
#pragma once
#include "core/Mesh.h"
#include <glm/glm.hpp>
#include <atomic>
#include <cstddef>
#include <cstdint>
#include <functional>
#include <memory>
#include <mutex>
#include <span>
#include <string>
#include <vector>
namespace sf {
struct MicroMesh;
struct MicroTriangle;
struct FocusView {
bool valid = false;
glm::mat4 viewProj{1.0f};
glm::vec3 eye{0.0f};
float focalPx = 1000.0f; // pixels per world unit at distance 1 (viewport height / (2 tan(fov / 2)))
float errorPx = 0.5f; // a visible tile is promoted when its coarse grid is further off than this on screen
};
struct FocusBrush {
bool present = false; // the cursor is over the model (hovering or stroking)
glm::vec3 position{0.0f};
glm::vec3 velocity{0.0f}; // world units per second
float radius = 0.0f; // world units
bool mirrorX = false; // X symmetry: the mirrored brush too
};
struct FocusStats {
size_t tiles = 0, fullTiles = 0, dirtyTiles = 0, parkedTiles = 0;
size_t parkedBytes = 0, fullBytes = 0, fileBytes = 0;
uint64_t promoted = 0, demoted = 0, syncPromoted = 0; // since open
double promoteMs = 0; // total time promoting (decompress + upsample/copy + markDirty)
double lastUpdateMs = 0; // the last update() (scoring + promotions + demotions)
size_t lastWanted = 0; // tiles the last update() wanted full
size_t lastPending = 0; // of those, still coarse after it (the time budget ran out)
};
class FocusDetail {
public:
static constexpr int kCoarseLevel = 3; // 8 x 8 segments, 45 points per tile
static constexpr uint32_t kChunk = 1024; // coarse grids per compressed chunk
// Writes a detail file for `base` (its triangles are the tiles) at micro level `level` (> kCoarseLevel) with
// `step` world units per integer unit; `tile(T, t, out)` fills tile t's samples (T is set for t). Tiles are
// generated, compressed and written in parallel batches: the full level is never in memory.
using TileFn = std::function<void(const MicroTriangle& T, uint32_t t, int16_t* out)>;
static bool write(const std::string& path, const Mesh& base, int level, float step, const TileFn& tile,
std::string& error);
// Opens a detail file: `out` becomes its base mesh with a micro level whose tiles all hold their coarse grids,
// and the returned manager is attached to it (MicroMesh::focus).
static std::shared_ptr<FocusDetail> open(const std::string& path, Mesh& out, std::string& error);
~FocusDetail();
// Once a frame (main thread): scores every tile, promotes the wanted ones (most wanted first) for at most
// `budgetMs`, demotes the least recently wanted while over budgetBytes.
void update(Mesh& m, const FocusView& view, const FocusBrush& brush, double budgetMs = 4.0);
// Makes tiles `tris` full now (brushes, undo); `edit` marks them dirty. Thread-safe.
void ensureFull(MicroMesh& mm, std::span<const uint32_t> tris, bool edit);
// MicroMesh::widen divided every value by 2^doublings and multiplied the step: the same for what isn't in disp.
void rescale(MicroMesh& mm, int doublings);
// Writes the changed tiles to the file (appended), a new directory and header. Returns false with `error`.
bool save(Mesh& m, std::string& error);
// 0 = coarse (upsampled), 1 = full.
int tileLevel(uint32_t tri) const { return tri < state_.size() && state_[tri] != kCoarse ? 1 : 0; }
FocusStats stats() const;
const std::string& path() const { return path_; }
bool unsaved() const; // edits since the last save
size_t budgetBytes = size_t(512) << 20; // full tiles kept (2 bytes a point) before the LRU demotes
float lookaheadSeconds = 0.25f; // how far ahead of the brush promotion looks
float brushReach = 2.0f; // promoted around the brush: this many radii
private:
FocusDetail() = default;
enum : uint8_t { kCoarse = 0, kFull = 1, kDirty = 2 };
struct Entry {
uint64_t offset = 0;
uint32_t bytes = 0;
uint16_t range = 0; // the largest |value| of the full tile
uint16_t shift = 0; // the stored tile is in step / 2^shift units (the range widened since it was written)
float coarseErr = 0; // world units: the most the upsampled coarse grid is off
uint32_t pad2 = 0;
};
struct ChunkEntry {
uint64_t offset = 0;
uint32_t bytes = 0, pad = 0;
};
bool mapFile(std::string& error);
void unmap();
bool readTile(uint32_t t, int16_t* out) const; // the full grid (parked first, else the file)
void fillCoarse(MicroMesh& mm, uint32_t t) const; // upsamples the coarse grid into disp
void promoteLocked(MicroMesh& mm, std::span<const uint32_t> tris, bool edit, bool sync);
void demoteLocked(MicroMesh& mm, uint32_t t);
std::string path_;
int level_ = 0;
uint32_t n_ = 0, samples_ = 0, coarseN_ = 0, coarseSamples_ = 0, codec_ = 0;
float step_ = 0;
uint64_t generation_ = 0, garbage_ = 0;
bool rescaled_ = false; // the coarse chunks in the file are in an older step
std::vector<Entry> dir_;
std::vector<ChunkEntry> chunks_;
std::vector<int16_t> coarse_; // tiles * coarseSamples, always resident
std::vector<uint8_t> state_;
std::vector<uint32_t> lastWanted_; // per tile: the update it was last wanted in
uint32_t frame_ = 0;
std::vector<std::vector<uint8_t>> parked_; // per tile: a demoted dirty tile, compressed (or empty)
std::vector<glm::uvec3> tris_; // the base triangles (edges between tiles)
uint64_t baseHash_ = 0; // of the saved base positions and normals
size_t fullTiles_ = 0;
mutable std::mutex mutex_;
FocusStats stats_;
std::vector<uint32_t> scratch_;
std::vector<float> score_;
// The mapped file
int fd_ = -1;
const uint8_t* map_ = nullptr;
size_t mapBytes_ = 0;
};
// A synthetic asset for benchmarks and tests: the standard scenes' procedural head with about `baseTriangles`
// base triangles at micro level `level`, plus skin-like detail (wrinkles and pores) generated per tile. Written
// to `path` (nothing in memory at full resolution).
bool focusWriteSyntheticHead(const std::string& path, size_t baseTriangles, int level, std::string& error);
// The standard-1b asset (base ~61K triangles at level 7: just over a billion micro triangles) in the cache folder,
// written the first time (a minute or so). Returns its path, or empty with `error`.
std::string focusStandard1bPath(std::string& error, const std::function<void(const std::string&)>& log = {});
struct BenchOptions;
// The Focus Detail benchmark (sculptforge-cli --bench-focus; docs/design/focus-detail.md): open, memory, promotion
// latency, an orbit close to the surface, Clay and Move strokes with and without prediction, undo, incremental
// save, and every tile decompressed for comparison. Markdown.
std::string runFocusBenchmark(const BenchOptions& options);
} // namespace sf