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
//
// Scripted demos for recording product videos: a timeline of real input
// (mouse moves, clicks, brush strokes, typing) played into the running app,
// with captions and a visible cursor drawn on top. UI elements are found by
// their labels through Dear ImGui's test-engine hooks, so the demo clicks the
// real buttons rather than calling functions behind the UI's back.
//
// sculptforge --demo sculpt --record sculpt.mp4 --size 1920x1080
//
// The same machinery runs UI tests: a .sfui script of clicks, typing, strokes
// and expectations against the real interface, with screenshots (UiTest.cpp).
//
// sculptforge --ui-test tests/ui/brush_lab.sfui --ui-out shots/
#pragma once
#include <glm/glm.hpp>
#include <imgui.h>
#include <SDL3/SDL.h>
#include <array>
#include <chrono>
#include <functional>
#include <map>
#include <string>
#include <utility>
#include <vector>
namespace sf {
class App;
class Demo {
public:
explicit Demo(App& app) : app_(app) {}
static std::vector<std::string> names();
bool load(const std::string& name, std::string& error);
void update(float dt); // before the UI is built: plays the timeline
void drawOverlay(); // inside the ImGui frame: captions and cursor
bool finished() const { return step_ >= steps_.size(); }
float clock() const { return clock_; } // seconds of the script so far (its own time, not the wall clock)
int frameStride() const { return stride_; } // >1 while fast-forwarding through waits
// The recording's virtual camera: the part of the window the video shows (its centre and zoom, 1 = all of it),
// eased between the targets set by zoomTo/zoomToItem. Captions and the fade stay the same size on screen.
void view(ImVec2& center, float& zoom) const;
// Screen rect of the most recent UI item with this label (text before "##" also matches;
// "Window/label" picks the item in one window).
bool findItem(const std::string& label, ImVec2& center, bool* visible = nullptr, ImVec4* clip = nullptr) const;
static void beginFrame(); // clears the item table (called before ImGui::NewFrame)
// Items drawn between these are also found as "NAME/label" (palettes in the shell's trays and drop-downs,
// whose ImGui window is the tray, keep their panel names: "Parts/Append").
static void pushScope(const char* name);
static void popScope();
static std::vector<std::string> similarItems(const std::string& label); // for test failure messages
static std::vector<std::string> offscreenItems(); // items drawn past the window's edge last frame ("window/label")
// Items in WINDOW (its name before "##") that ran past its inner right edge last frame, scrollable or not.
static std::vector<std::string> pastRightEdge(const std::string& window);
// A control whose label is wider than the control (cut off): widgets report it while drawing, under the scopes
// open then ("Extract/Corners"). clippedLabels(scope) lists last frame's, all of them for an empty scope.
static void noteClippedLabel(const std::string& label);
static std::vector<std::string> clippedLabels(const std::string& scope);
// UI tests (UiTest.cpp). Steps that fail stop the run; failures() lists why.
bool loadScript(const std::string& path, std::string& error);
// A benchmark take (sculptforge --benchmark-script, BenchTake.cpp): the script played in real time in the
// interactive loop. Only the steps a person could do in real time load: shots and expectations are skipped with a
// warning, steps that run commands or read other files (run, env, drop, choose_file, restart...) are refused.
// `stroke` sends its pointer samples at 240 a second (each frame: those since the last), as a tablet does.
bool loadTake(const std::string& path, std::string& error);
// Called with every pointer position the script sends (after the app has handled it): the take's stroke lag.
std::function<void(float x, float y)> pointerHook;
bool testing() const { return testing_; }
const std::vector<std::string>& failures() const { return failures_; }
int stepsRun() const { return int(step_); }
// Every piece of text drawn in the last frame (ImGui log capture), for expect_text.
void setFrameText(std::string text) { frameText_ = std::move(text); }
std::string shortcutsMarkdown() const; // dump_shortcuts: the default shortcuts as Markdown tables
// A screenshot requested by a `shot` step: the frame loop saves the next frame there.
std::string takeShotRequest() { return std::exchange(shotRequest_, std::string()); }
// The last screenshot's pixels (RGBA, top row first), for the luma@X,Y values.
void setLastShot(std::vector<uint8_t> rgba, int w, int h) {
lastShot_ = std::move(rgba);
lastShotW_ = w;
lastShotH_ = h;
}
void printProfile() const; // the slowest script lines (SF_UI_PROFILE=1), after the script ran
private:
using Step = std::function<bool(float t)>; // returns true when done; t = seconds since the step began
// Timeline building blocks.
void wait(float seconds);
void caption(const std::string& title, const std::string& subtitle, float seconds, bool top = false);
void moveTo(float x, float y, float seconds);
void moveToItem(const std::string& label, float seconds = 0.6f);
void click(const std::string& label); // move to the item and click it
void stroke(std::function<ImVec2(float u)> path, float seconds, bool invert = false, bool hold = false); // hold: the button stays down
void orbit(float dx, float dy, float seconds); // right-drag on the background
void type(char* buffer, size_t size, const std::string& text, float seconds);
void run(std::function<void()> action);
void waitUntil(std::function<bool()> done, float timeout, int stride);
// Camera moves for the video (they start and the timeline carries on; `seconds` is the ease).
void zoomTo(ImVec2 center, float zoom, float seconds);
void zoomToItem(const std::string& label, float zoom, float seconds, ImVec2 offset = ImVec2(0, 0));
void zoomTo(std::function<ImVec2()> where, float zoom, float seconds); // centre found when the move starts
void zoomOut(float seconds) { zoomTo(ImVec2(-1, -1), 1.0f, seconds); }
void fadeTo(float black, float seconds); // 1 = black (fade out), 0 = clear (fade in)
// UI test steps.
void fail(int line, const std::string& message);
bool parseStep(int line, const std::vector<std::string>& words, std::string& error);
void testClick(int line, const std::string& label, int button, bool doubleClick);
// phase: 0 press and release, 1 press only (key_down), 2 release only (key_up).
void testKey(int line, const std::string& combo, int phase = 0);
void testKeyNow(SDL_Keycode key, SDL_Keymod mods);
double query(const std::string& name, bool& known) const;
void buildShowcase();
void buildSculpt();
void buildImageTo3D();
void buildBrushLab();
void buildGameReady();
void buildSplats();
// Input injection.
void mouseMotion(float x, float y, SDL_MouseID which = 0); // which = SDL_PEN_MOUSEID: synthesized from a pen
void mouseButton(bool down, int button, SDL_MouseID which = 0, int clicks = 1);
// Pen events as SDL3 sends them (UiTest.cpp): the pen's own event, then the mouse event SDL synthesizes.
void penProximity(bool in);
void penMove(float x, float y); // PEN_MOTION (+ mouse motion), touching or hovering
void penPressure(float pressure); // PEN_AXIS pressure
void penTouch(bool down, bool eraser); // PEN_DOWN / PEN_UP (+ left button)
void penButtonEvent(int button, bool down); // PEN_BUTTON_DOWN / UP (+ SDL 3.4's mouse button)
void penStroke(std::function<ImVec2(float u)> path, float p0, float p1, bool eraser, bool leave, float seconds,
std::function<void()> afterSample = {}, // afterSample: e.g. a driver's stray mouse event
bool tail = false); // tail: the pressure falls to 0 over the last samples before the lift (#146)
// World -> screen in window coordinates.
ImVec2 project(const glm::vec3& p) const;
// A point on the model, given as a fraction of its on-screen bounds (nudged until it hits the surface).
ImVec2 onModel(float u, float v) const;
App& app_;
std::vector<Step> steps_;
size_t step_ = 0;
float stepTime_ = 0.0f;
// SF_UI_PROFILE=1 (docs/testing-flow.md): the real time each script line took, printed when the script ends.
std::vector<int> stepLines_; // the script line each step came from
std::vector<std::string> scriptLines_; // the script's lines, for the report
std::vector<double> lineSeconds_; // real seconds spent on each line
std::chrono::steady_clock::time_point lastUpdate_{};
// The longest real time between two frames since it was last read (UI tests: longest_frame_ms; reading resets it).
std::chrono::steady_clock::time_point lastFrame_{};
mutable double longestFrameMs_ = 0.0;
int stride_ = 1;
ImVec2 mouse_{960, 540};
bool buttonDown_ = false;
bool buttonHeld_ = false; // orbit: right button pressed
int dragCursor_ = -1; // the system cursor at the end of the last button_drag, before letting go
struct Caption {
std::string title, subtitle;
float start = 0.0f, duration = 0.0f;
bool top = false; // upper third (when the lower one has UI to show)
};
std::vector<Caption> captions_;
float clock_ = 0.0f;
struct View {
ImVec2 center{-1, -1}; // -1: the middle of the window
float zoom = 1.0f;
};
struct Tween {
View from, to;
float start = 0.0f, duration = 0.0f;
} view_;
float fadeFrom_ = 0.0f, fadeTo_ = 0.0f, fadeStart_ = 0.0f, fadeDuration_ = 0.0f;
float fade() const;
ImVec2 viewCenter(const View& v) const;
bool testing_ = false;
bool take_ = false; // loadTake: real-time pointer samples, no shots or expectations
std::vector<std::string> failures_;
std::string frameText_, shotRequest_, shotDir_, scriptName_, lineText_;
std::vector<uint8_t> lastShot_;
int lastShotW_ = 0, lastShotH_ = 0;
std::string scriptDir_; // the .sfui script's folder: relative `drop` paths, $SCRIPT_DIR in env steps
std::string expandLibrary(std::string text) const; // $LIBRARY -> the Library library folder (UiTest.cpp)
SDL_Keymod held_ = SDL_KMOD_NONE; // modifiers held by `hold` (Ctrl to mask, Ctrl+Shift to hide...)
// Simulated pen (pen_* steps).
SDL_PenID testPen_ = 1; // tablet_plug gives the next pen a new id, as SDL does
uint32_t testTabletMouse_ = 0; // the simulated tablet's mouse device (tablet_plug / tablet_unplug)
bool penIn_ = false, penDown_ = false, penEraser_ = false;
ImVec2 penAt_{960, 540}; // the simulated pen (mouse_ is SDL's shared cursor, which stray mouse events move too)
SDL_PenInputFlags penState_ = 0;
// The pen's mouse events as SDL 3.2 makes them (true), or none: SDL after it dropped a touching pen (#95,
// sdl_pen_mouse / pen_lost). A Huion-style driver also sends mouse events of its own (pen_stream huion).
bool sdlPenMouse_ = true;
bool huionStream_ = false;
// pen_rest on: the pen lies still in range and, as a real one does, sends a hair of tilt and sub-pixel motion
// every frame (phoenix 11-05) until pen_rest off.
bool penResting_ = false;
ImVec2 penRestAt_{0, 0};
int penRestFrame_ = 0;
bool penPressed_ = false; // pen_press: down until pen_lift (pen_rest's noise then rests the tip)
void penRestNoise();
// spacemouse_echo on: while the virtual cap is pushed, a SpaceMouse driver that doesn't know the app (3DxWare's
// defaults) moves the system pointer and scrolls the wheel every frame (fenix, Discord 11-06).
// spacemouse_echo scroll: as macOS 3DxWare scrolls for an app it doesn't know: the wheel from the cap's first stir
// (inside the app's dead zone), by the cap's push, and on for a quarter second after it is let
// go; no pointer motion (a slow tilt zoomed the view away, fenix 11-06).
bool spaceMouseEcho_ = false, spaceMouseScrollEcho_ = false;
float scrollMomentum_ = 0.0f, scrollMomentumLeft_ = 0.0f;
std::array<float, 6> virtualAxes_{};
void spaceMouseEchoFrame(float dt);
static constexpr SDL_MouseID kDriverMouse = 7; // the driver's own mouse device
// `snapshot` saves the active mesh; moved* values compare against it. `remember` keeps values for $NAME.
std::vector<glm::vec3> basePositions_, baseNormals_;
std::map<std::string, double> remembered_;
// Simulated SpaceMouse (spacemouse* steps): an SDL virtual joystick with a SpaceMouse Compact's ids.
SDL_JoystickID virtualSpaceMouse_ = 0;
SDL_Joystick* virtualSpaceMouseHandle_ = nullptr;
bool attachVirtualSpaceMouse();
void detachVirtualSpaceMouse();
};
} // namespace sf