// SPDX-FileCopyrightText: 2025 Erin Catto // SPDX-License-Identifier: MIT #pragma once #include "host/camera.h" #include "box3d/types.h" // Polled key state for samples that need continuous input (character movers). // Fed from the host event loop; read with the KEY_* aliases in gfx/keycodes.h. bool IsKeyDown( int key ); void SetKeyDown( int key, bool down ); void ClearKeysDown(); // Key action passed to Keyboard, matching the old GLFW press/release values so // sample code reads naturally without leaking sokol_app event types. enum { ACTION_RELEASE = 0, ACTION_PRESS = 1, }; // Character input relative to the camera. Throttle x is forward and y is right. struct MoverInput { b3Vec3 forward; b3Vec3 right; b3Vec2 throttle; bool jump; bool sprint; bool walk; }; struct SampleContext { void Save(); void Load(); Camera camera; bool minimized = false; class Sample* sample = nullptr; b3Capacity capacity; // Latest cursor position in framebuffer pixels, fed from the host event // loop. Drives picking on the step that follows a mouse move. float mouseX = 0.0f; float mouseY = 0.0f; // Relative cursor motion for the latest move, fed from the host. Used for // third-person look while the cursor is locked. float mouseDX = 0.0f; float mouseDY = 0.0f; int windowWidth = 1920; int windowHeight = 1080; // Used to shift the origin and test round-off problems b3Vec3 origin = b3Vec3_zero; // Recording output path and the path the Replay viewer opens. Edited in the UI and persisted. char recordingFile[256] = "recording.b3rec"; char replayFile[256] = ""; // Last recording saved this session, empty until a save succeeds. The default record path // may name a stale file from an earlier run, so Play only trusts this one. char savedRecordingFile[256] = ""; // Keyframe ring policy the Replay viewer applies on open, persisted across sessions. int replayKeyframeBudgetMB = 512; int replayKeyframeMinInterval = 16; float hertz = 60.0f; float recycleDistance = 0.05f; float drawDistance = 100.0f; // meters, view/cull box half extent, persisted // Camera the sample set up on creation. Home returns to it. Fitting the world bounds instead // can put a scene with a large ground plate beyond the draw distance. b3Pos homePivot = {}; float homeYaw = 0.0f; float homePitch = 0.0f; float homeRadius = 0.0f; int subStepCount = 4; int restitutionIterations = 2; int workerCount = 1; bool transparentDynamic = false; bool transparentKinematic = false; bool enableWarmStarting = true; bool enableContinuous = true; bool enableRestitutionPropagation = false; bool enableSSE2Fallback = false; bool enableSleep = true; bool pause = false; int singleStep = 0; bool restart = false; // UI visibility (Tab / View > Hide UI). When hidden only the minimal HUD shows. bool showUI = true; // Bottom metrics drawer (M), set by Ctrl+O for the fuzzy picker. bool showMetrics = false; bool openSamplePicker = false; // Left profile panel (I) bool showProfile = false; // Controls help window (Help > Controls, toggled with ?). Promoted to the // context so the key handler can reach it. Seeded from newUser after Load. bool showControls = false; // Deferred request from the Replay > Open menu. The native file dialog // blocks on a nested run loop, so it must run outside the frame (top of // OnFrame) rather than mid-frame inside the ImGui callback, which would // re-enter the render loop. See OpenReplayFileDialog. bool openReplayPicker = false; // Render toggles fed into FrameInput each frame. They live here, not in // main.cpp, so the Render menu and the frame loop share one source. bool enableShadows = true; bool enableGtao = true; // View-only: treat simulation +Z as up when drawing. Does not touch the // simulation. The frame loop hands this to the camera's render transform. bool viewZUp = false; float sunStrength = 1.0f; int debugView = 0; int sampleIndex = 0; // No settings file found yet. The first run opens the replay viewer with the // controls window up, so there is something to watch and a key to every action. bool newUser = true; }; class Sample { public: explicit Sample( SampleContext* context ); virtual ~Sample(); void CreateWorld( b3Capacity* capacity ); // Position the first HUD text line below the menu bar, or near the top when // the UI is hidden. Mirrors Box2D ResetText. void ResetText(); // Update and render are split to support pausing the simulation virtual void Step(); virtual void Render() { } // Draw sample controls into the shared info panel. Return true if any widget // was drawn so the panel can add a separator. virtual bool DrawControls() { return false; } // Let a debug sample hide the Solver section. virtual bool HasSolverControls() const { return true; } // Allow a sample without a world step to hide the profile panel. virtual bool HasProfile() const { return true; } // Width of the right info panel in em. The bottom drawer clears to the same width. A sample that // hosts heavier content there, such as the replay viewer's detail pane, can widen it. virtual float InfoPanelWidthEm() const; // Bounds the Frame shortcut should fit when the selection is not a body, e.g. a recorded query. // Takes priority over FocusBody so an explicit selection wins over a hovered body. Returns false // by default, leaving the body and whole-scene paths in charge. virtual bool FocusBounds( b3AABB* bounds ); // Body the Frame shortcut should fit. Defaults to whatever the cursor is over. // The replay viewer overrides this to fit its persistent selection instead, so // framing works regardless of where the cursor sits. virtual b3BodyId FocusBody() const; // Home, and the frame shortcut with nothing selected. Defaults to the camera the sample set up on // creation. The replay viewer overrides this to fit the recording, whose world is player-owned and // separate from the empty base world. virtual void FocusHome(); // Arm recording on the live world, snapshotting it as the seed so capture can begin at any // step boundary. Stop writes the file named by the context and frees the buffer. void StartRecording(); void FinishRecording(); // Left profile panel, a table of the step sections readable at a glance. bool IsProfileVisible() const; float GetProfilePanelWidth() const; void DrawProfile(); // Bottom metrics drawer (Frame Time / Counters / Renderer). void DrawMetrics(); // Append extra tabs to the metrics drawer's tab bar (the Replay viewer adds Timeline). virtual void DrawMetricsTab() { } // Draw extra top-level windows when the UI is shown (the Replay viewer adds the Outline panel). virtual void DrawSampleWindows() { } virtual void Keyboard( int key, int action, int modifiers ) { } virtual void MouseDown( b3Vec2 p, int button, int modifiers ); virtual void MouseUp( b3Vec2 p, int button ); virtual void MouseMove( b3Vec2 p ); void ToggleThirdPerson(); // WASD, space, shift and ctrl, active only in third person so the free camera keeps its keys. MoverInput GetMoverInput() const; B3_PRINTF_FORMAT( 2, 3 ) void DrawTextLine( const char* text, ... ); void ResetProfile(); // Static ground box at the origin, drawn with the procedural grid material b3BodyId AddGroundBox( float extent ); #if defined( NDEBUG ) static constexpr bool m_isDebug = false; #else static constexpr bool m_isDebug = true; #endif static constexpr int m_maxTasks = 64; static constexpr int m_maxThreads = 64; static constexpr int m_profileCapacity = 512; SampleContext* m_context; Camera* m_camera; b3WorldId m_worldId; b3Pos m_mousePoint; b3BodyId m_mouseBodyId; b3JointId m_mouseJointId; float m_mouseFraction; float m_mouseForceScale; float m_launchSpeedScale; int m_stepCount; int m_textX; int m_textLine; int m_textIncrement; int m_triangleIndex; uint64_t m_userMaterialId; // Active recording, or null when not recording. The step recording began on drives the status. struct b3Recording* m_recording; int m_recordStartStep; b3Profile m_profiles[m_profileCapacity]; int m_currentProfileIndex; int m_profileReadIndex; int m_profileWriteIndex; // View-space distance range the shadow cascades split over, set during // construction. Left at zero the range is guessed from the world bounds, // which only works when the camera sits close to the content. A scene // viewed from far off wants an explicit range: the guess spends every // cascade on the empty space in front of the camera and the shadows stop // partway into the scene. // // Authored against the sample's opening camera, so flying well away from // it can still outrun the far end. float m_shadowSplitNear; float m_shadowSplitFar; b3Vec2 m_mouseLast; b3Vec2 m_mouseDelta; bool m_didStep; bool m_stepWhilePaused; bool m_haveMouseLast; }; #define MAX_SAMPLES 256 typedef Sample* SampleCreateFcn( SampleContext* context ); struct SampleEntry { const char* Category; const char* Name; SampleCreateFcn* CreateFcn; }; extern SampleEntry g_sampleEntries[MAX_SAMPLES]; extern int g_sampleCount; // Index of the registered Replay viewer, or -1 if none. Gates the Replay menu. extern int g_replayIndex; int RegisterSample( const char* category, const char* name, SampleCreateFcn* fcn ); // Register the Replay viewer and record its index in g_replayIndex. int RegisterReplay( const char* category, const char* name, SampleCreateFcn* fcn ); // Destroy the active sample and build the selected one. restart keeps the camera // by leaving the restart flag set while the new sample constructs. void SelectSample( SampleContext* context, int selection, bool restart ); // Frame the selection, or go home when nothing is selected void FrameSelection( SampleContext* context ); // Run the native "open replay" file picker and, on success, hand the chosen // file to the Replay viewer. Must be called outside the frame (the dialog spins // a blocking nested run loop), driven by SampleContext::openReplayPicker. void OpenReplayFileDialog( SampleContext* context ); // The single host UI callback: menu bar, sample picker, info panel, profile panel, // and the bottom metrics drawer. void DrawUI( SampleContext* context ); struct CastClosestContext { b3ShapeId shapeId; b3Pos point; b3Vec3 normal; float fraction; uint64_t materialId; int childIndex; int triangleIndex; bool hit; }; float CastClosestCallback( b3ShapeId shapeId, b3Pos point, b3Vec3 normal, float fraction, uint64_t materialId, int triangleIndex, int childIndex, void* context ); struct MechanicalEnergy { float Total() const { return linear + angular + potential; } float linear; float angular; float potential; }; // Kinetic and gravitational potential energy summed over the bodies. Restitution samples // use the total as the invariant that may only decrease. MechanicalEnergy MeasureEnergy( b3WorldId worldId, const b3BodyId* bodyIds, int count );