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
//
// Built-in Lit Sphere ("material capture") materials. Each is a lit-sphere image
// generated procedurally here (no third-party images): the viewport looks up
// the colour by the view-space normal, so a whole material costs one texture
// fetch. Vertex paint multiplies the lit sphere; cavity shading is applied on top.
#pragma once
#include <cstdint>
#include <string>
#include <vector>
namespace sf {
int litsphereCount();
const char* litsphereName(int index);
// Case-insensitive; also accepts names without spaces ("redwax"). -1 if unknown.
int findLitSphere(const std::string& name);
// The material new documents (and thumbnails) start with: Soft Clay, a matte warm clay.
int defaultLitSphere();
// The order the pickers list the Lit Spheres in: k = 0 is the default, then the others in index order.
int litsphereInListOrder(int k);
// How strongly the viewport darkens creases and lifts ridges on top of this lit sphere (the
// curvature term in the mesh shader); the Sculpt material leans on it more than the others.
struct LitSphereCavity {
float crease = 0.55f, ridge = 0.2f;
};
LitSphereCavity litsphereCavity(int index);
// `size` x `size` RGBA8 pixels, sRGB-encoded, rows bottom-up (OpenGL order):
// pixel (i, j) shows the sphere normal x = (i + 0.5) / size * 2 - 1,
// y = (j + 0.5) / size * 2 - 1. Pixels outside the disk repeat the rim.
// For a custom Lit Sphere: its own pixels, resampled to `size`.
std::vector<uint8_t> generateLitSphere(int index, int size = 256);
// --- Custom Lit Spheres (#15) ---
// Sphere images the artist loads (Material > Load Lit Sphere...) or drops into the library's Lit Spheres folder. They come
// after the built-ins in index order (lit sphereCount() includes them), for the session; the registry is process-wide
// and only touched from one thread (the app's main thread, or a CLI / test).
struct CustomLitSphere {
std::string name; // the file name without its extension
std::string path; // the image it was read from (empty: embedded in a project)
int size = 0; // size x size pixels
std::vector<uint8_t> rgba; // sRGB RGBA8, rows bottom-up, as generateLit Sphere
uint64_t hash = 0; // of the pixels (thumbnail keys, finding a project's Lit Sphere again)
std::string group; // the sub-folder of the library's Lit Spheres folder it is in ("" = none): a list heading
bool removed = false; // removeCustomLit Sphere: kept so indices stay put, but listed and found no more
};
constexpr int kMaxLitSphereSide = 1024; // bigger images are scaled down
int builtinLitSphereCount();
bool isCustomLitSphere(int index); // also true for a removed one (its index stays taken)
// Shown in the material lists: a built-in, or a custom Lit Sphere that wasn't removed.
bool isLitSphereListed(int index);
const CustomLitSphere* customLitSphere(int index); // null for built-ins and bad indices
void clearCustomLitSpheres(); // none loaded, as at start (the warm UI test server, between scripts)
// Changes whenever a custom Lit Sphere is added or its pixels replaced (renderers upload again).
uint64_t litsphereRevision();
// Name plus, for custom Lit Spheres, the pixel hash: a cache key that changes with the image.
std::string litsphereKey(int index);
// .png .jpg .jpeg .exr (also .bmp .tga .hdr, which stb_image reads).
bool isLitSphereFile(const std::string& path);
// Reads a sphere image: 8-bit formats through stb_image, OpenEXR as linear light (clamped, then sRGB). A non-square
// image is cropped to its centred square; the name is the file name without its extension.
bool readLitSphereImage(const std::string& path, CustomLitSphere& out, std::string& error);
bool decodeLitSphereImage(const unsigned char* bytes, size_t size, CustomLitSphere& out, std::string& error);
// PNG of the Lit Sphere's pixels (top row first), e.g. to embed it in a project; false for built-ins.
bool encodeLitSpherePng(int index, std::vector<uint8_t>& png);
// Adds `m`, or replaces the pixels of the custom Lit Sphere of the same name (case-insensitive; a removed one comes
// back at its old index); a built-in's name gets " 2" (" 3" ...). Returns its index.
int addCustomLitSphere(CustomLitSphere m);
// Takes a custom Lit Sphere out of the lists and name lookups for the rest of the session (its file is the caller's
// business). False for built-ins and bad indices.
bool removeCustomLitSphere(int index);
// Renames a listed custom Lit Sphere (#124; its file is the caller's business). False, with `error`, for built-ins, a
// name that isn't a valid file name (checkLitSphereFileName) or one another listed Lit Sphere has (case-insensitive).
bool renameCustomLitSphere(int index, const std::string& name, std::string& error);
// Where a custom Lit Sphere's image is now (after a rename or a move to another folder); bumps no revision (the pixels
// are the same). False for built-ins.
bool relocateCustomLitSphere(int index, const std::string& path, const std::string& group);
// A Lit Sphere or folder name that is also a portable file name: not empty, no / \ : * ? " < > |, no control
// characters, not "." or ".." or starting with a dot, no trailing dot or space, at most 100 bytes.
bool checkLitSphereFileName(const std::string& name, std::string& error);
// The groups the listed custom Lit Spheres are in, sorted case-insensitively ("" not included).
std::vector<std::string> litsphereGroups();
// The listed custom Lit Sphere read from `path` (exact path), or -1.
int findLitSphereByPath(const std::string& path);
// The index of a custom Lit Sphere with exactly these pixels, or -1.
int findLitSphereByHash(uint64_t hash);
// Every Lit Sphere image directly in each folder (sorted by name; later folders replace earlier ones by name).
// Returns a message per file that couldn't be read.
std::vector<std::string> loadLitSphereFolders(const std::vector<std::string>& dirs);
// Studio Lit Sphere folders from SCULPTFORGE_LITSPHERE_PATH (':' separated, ';' on Windows), read-only.
std::vector<std::string> studioLitSphereDirs();
} // namespace sf