Skip to content

Latest commit

 

History

History
247 lines (195 loc) · 14.1 KB

AGENTS.md

File metadata and controls

247 lines (195 loc) · 14.1 KB

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Build System

Spectrum uses Sharpmake (a C#-based build system) to generate Visual Studio 2026 project files, and vcpkg for dependency management.

First-time setup

setup.bat          # Init Sharpmake submodule + build it, then generates VS projects

Regenerate VS projects (after changing main.sharpmake.cs or adding/removing files)

generate_project.bat

Regenerate code from .prism files

Tools → Regenerate Prism code in VS (Prism extension), or run bin/profile/prismc.exe from sources/Prism/.

Changing the Prism grammar

The grammar is a cpp-peglib (PEG) string in sources/Prism/PrismGrammar.h; there is no generated parser, so a grammar edit is just a rebuild of the Prism project. peglib.h (vcpkg port cpp-peglib) is included only by the plain, non-module sources/Prism/PrismBridge.cpp (a header unit of it leaves its static string constants null), which hands Parsing.cpp a small AST (PrismAst.h). Keywords are contextual (!IDCHAR-guarded tokens), so where a keyword-led alternative follows an ID-led one, order them keyword first (see rt_stat, value_id). All PSO kinds share one pso_block; which statements each kind takes is checked in Parsing.cpp (PsoKind), and PSO/node parameters are typed by name in the grammar. prismc --check a.prism parses files without validating or generating anything, for trying grammar changes.

Build

Open projects/Spectrum.sln in Visual Studio 2026. Three configurations: Debug, Profile, Retail.

Executables output to bin/Debug, bin/Profile, bin/Retail. The working directory for running is workdir/.

Architecture

Layer Stack (bottom to top)

Modules       — C++ module wrappers for third-party libraries (assimp, cereal, etc.)
Core          — Engine foundation: math, serialization, threads, events, filesystem, profiling
HAL           — Hardware Abstraction Layer over D3D12: device, queues, resources, descriptors, shaders
RenderSystem  — High-level rendering: FrameGraph, materials, lighting, GUI, scene, assets
Spectrum      — Application entry point, ties everything together

Each layer has a Defines.h that chains upward (e.g. RenderSystem/Defines.h includes HAL/Defines.h). Every .cpp/.ixx in a project gets this forced-included automatically via Sharpmake.

C++ Modules (.ixx)

The codebase uses C++23 modules (.ixx files) extensively. Each subsystem exposes a module interface — for example HAL.Device.ixx exports module HAL:Device. Headers (.h) are used for things that can't be modules (forced includes, third-party interop).

Prism

Prism is the engine's declaration language: .prism files in sources/Prism/defs/ declare shared GPU/CPU structs and their resource bindings, PSOs, raytracing PSOs, FrameGraph passes, pipelines, enums, constants and HLSL helper functions. prismc (a cpp-peglib-based compiler, sources/Prism/) generates HLSL and C++ from them into sources/HAL/autogen/, sources/RenderSystem/FrameGraph/autogen/ and workdir/shaders/autogen/. The language was called SIG (shader input groups) before it grew beyond bindings; the engine-side binding code keeps that name (HAL/SIG/, SlotID, Table::).

FrameGraph

The RenderSystem/FrameGraph subsystem manages render pass scheduling, automatic resource transitions, and async compute. Render passes declare their resource reads/writes; the FrameGraph resolves barriers and execution order.

Modules Layer

sources/Modules/ wraps third-party vcpkg libraries as C++ modules (.ixx). Each subfolder (assimp/, cereal/, etc.) contains an .ixx that re-exports the library through the module system.

Key Files

  • main.sharpmake.cs — all project/solution configuration; edit this to add files, dependencies, or defines
  • vcpkg.json — vcpkg dependency manifest
  • vcpkg-configuration.json — vcpkg registry config (uses git registry + custom overlay in custom-overlay/)
  • workdir/ — runtime working directory (shaders, assets); not fully committed (see .gitignore)

CI/CD

GitHub Actions workflow at .github/workflows/build.yml builds the Retail configuration on windows-2025-vs2026 runners. vcpkg dependencies are cached in vcpkg_installed/. Build artifacts (workdir output) are uploaded after a successful build.

Runtime-tunable settings (Variable<T>)

Any bool/float/enum knob that should be inspectable or editable at runtime — an A/B toggle, a debug visualization switch, a tunable threshold — goes through Variable<T> (sources/Core/Tree/Tree.ixx), not a hand-wired check_box_text/float_slider/edit_text row built directly in main.cpp or wherever the class lives. The hand-wired version was the actual shape VSM and triangle_drawer::auto_rotate_sun used to take — nine near-identical 7-line blocks in main.cpp for VSM alone — before being migrated to this system; don't reintroduce that pattern for a new toggle.

class stencil_renderer : public GUI::base, public VariableContext
{
public:
    Variable<bool>  draw_aabb        = { false, "Draw AABB", this };
    Variable<float> falloff          = { 1.0f, "Falloff", this, 0.0f, 5.0f };   // constrained -> slider
    Variable<float> arbitrary_offset = { 0.0f, "Offset", this };                // unconstrained -> free-form text box
    Variable<Mode>  mode             = { Mode::Fast, "Mode", this };            // enum -> combo box (magic_enum-driven)
};

Declaring a Variable<T> member is the entire integration: it self-registers with its owning VariableContext and shows up automatically in the app's Properties debug panel (ParameterWindow.ixx picks the widget type — slider, checkbox, text box, or combo box — from T and whether a range was given), already wired with a "Reset" button and live sync if the value changes from somewhere other than that widget (see get_default()/is_default()/ reset_to_default(), and the on_change/on_changed events on Variable<T>/VariableBase). None of that needs to be built by hand again.

The owning class must derive VariableContext (as above) to get an implicit this for the Variable's third constructor argument. If it can't (e.g. it already derives GUI::base, whose own add_child would become ambiguous with VariableContext's), use VariableContext::create(L"name") to obtain an owned std::unique_ptr<VariableContext> member instead, and pass *that.

Every VariableContext of a given class registers under the same fixed name (e.g. every mesh_renderer is named "mesh_renderer"), so if a class is instantiated more than once, otherwise-identical entries pile up as flat, indistinguishable siblings in the Properties tree. Disambiguate by wrapping construction in VariableContext::Scope scope(some_persistent_context); — subsequently-constructed named contexts nest under some_persistent_context instead of the global root. The context passed to Scope must outlive the Scope itself (a base-class this, or a create()-obtained member) — see the comments on VariableContext::Scope in Tree.ixx for why a Scope owning a temporary context is wrong.

Profiling

PROFILE(L"name") (CPU) and PROFILE_GPU(L"name") (GPU) are scoped timers defined in sources/Core/Profiling/macros.h, forced-included everywhere via Core/Defines.h. They compile to ((void)0) unless PROFILING is defined for the build config, so they're free to add liberally — no need to gate them behind anything yourself.

When writing or editing any function that does non-trivial per-frame CPU work (loops over resources/passes, resource-view creation, upload/copy calls) or issues GPU commands (draws, dispatches, barrier-heavy resource binding), add scoped PROFILE blocks around its logically distinct sub-sections, not just one at the top of the function:

{
    PROFILE(L"vsm_hiz_copy");
    // ... the copy dispatch ...
}
{
    PROFILE(L"vsm_hiz_downsample");
    // ... the downsample loop ...
}
  • Scope with an explicit { } block — the macro declares a local variable whose destructor stops the timer at end of scope, so an unbracketed PROFILE(...) at the top of a big function silently times everything after it, not just the intended section.
  • Name markers by what they measure, not where they live (vsm_hiz_copy, not loop1) — this is what shows up in the profiler UI and needs to be legible next to unrelated markers from other systems.
  • Prefer several small, named scopes over one broad one when a function has multiple distinct phases (setup vs. dispatch vs. teardown) — this is what makes a profiler capture actionable instead of just "this function is slow somewhere."
  • This is the same convention already used throughout HAL.CommandList.cpp (commit_tables, transitions, rt_transitions) and MipMapGeneration.cpp — match that granularity when adding new instrumented code, don't invent a different style.

Temporary debug logging

Debug logging added to chase a specific problem is scaffolding, not code. It exists for one investigation and becomes noise the moment that investigation ends — so it needs to be obvious on sight and trivial to remove.

Write temporary log output to files with a .temp extension, never into log.txt or the engine's normal logging path. *.temp is gitignored, so scratch output can never be committed by accident, and the extension makes every temporary artifact greppable as a set rather than something you have to remember file by file.

When a debugging session ends, ask before cleaning up. Once the bug is found and fixed, list the temporary logging that was added — the call sites and the .temp files — and ask whether to remove it. Don't strip it automatically: a fix often needs one more round of verification, and silently deleting the instrumentation that proved it means rebuilding it from scratch. Equally, don't leave it behind unmentioned — untracked PROFILE-adjacent spam and stray writes accumulate and are hard to attribute later.

This is specifically about temporary instrumentation. Permanent diagnostics that earn their place — the VSM active-window diag, the D3D12 message callback — are normal code and stay.

Visual confirmation

A clean build and 0 D3D12 validation errors prove the pipeline runs without crashing — they say nothing about whether a denoiser actually denoises, a shadow looks right, or a debug view shows what it's supposed to. Anything whose correctness is a visual judgment call, not a log-checkable fact, is not something to verify by guessing, screenshotting blind, or declaring success off the log alone.

When a change needs that kind of check, stop and ask the user to look at it themselves — say exactly which toggle(s)/GUI setting(s) to flip and to what value (e.g. "Shadow Src → RTX Ref"), and what to look for. Don't flip runtime defaults, rebuild, and run the app repeatedly to eyeball it in their place.

Editing files

Use the editor's native file-edit tool for changes, not a script (Python, sed, etc.) that reads a file and writes back a modified copy. The one exception is a genuine multiple-occurrence replacement (renaming a symbol throughout a file, etc.) — the native tool's own "replace all" mode is still preferred there; reach for a script only when that isn't enough.

Comments

Comment sparingly. Prefer code that doesn't need explaining, and don't restate in prose what the line below already says: // increment the counter above ++counter is pure cost, and comments that merely narrate drift out of sync with the code and start actively lying.

Write a comment when the reader would otherwise be right to think the code is wrong:

  • A workaround for a driver, API, or compiler bug — say which, and what breaks without it.
  • A non-obvious ordering or lifetime requirement — why this call must precede that one.
  • A deliberate deviation from the obvious implementation, with the reason.
  • A constant whose value came from measurement or a spec, not from choice.

The test is whether someone competent would be tempted to "simplify" the code and break it. If yes, explain why it is the way it is. If no, leave it alone.

FrameGraph: A/B resource selection

When a pass reads one of several alternative resources chosen at runtime — a debug view source, a ping-pong history buffer, a denoised vs. raw input — make the selection in the setup function too, not only where the resource is bound for rendering.

Setup is what links a resource to the pass. Calling builder.need() on both sides of a choice declares a dependency on the alternative that will never be read, and the graph then has to honour it: the unused resource is kept alive across this pass, and the transitions compiled for it are barriers paid for nothing. Worse, the edge is invisible at the call site that actually matters — the render function looks correct because it binds only one of them.

Resolve the choice once into a single handle, then use that same handle in both places:

// selection resolved once, stored on the context
ui_ctx.result_texture_handler = Handlers::Texture(debug_source(dbg.mode));

// setup: link only what was selected
if (builder.exists(ui_ctx.result_texture_handler))
    builder.need(ui_ctx.result_texture_handler, ResourceFlags::PixelRead);

// render: bind the same handle
if (ui_ctx.result_texture_handler)
    c.result_texture_srv = *ui_ctx.result_texture_handler;
  • Guard with builder.exists() before need() — the selected resource may not be produced at all in the current graph configuration, and a hard need() on a resource no pass writes is a graph-build failure rather than a missing input.
  • Resolve the selection before setup runs (in graph construction) rather than recomputing the branch in both functions. Two copies of the same condition drift, and when they disagree the pass links one resource and binds another — which surfaces as a binding that reads whatever the unused resource happened to contain, not as an error.
  • UI_Render in sources/RenderSystem/GUI/Base.cpp is the reference: the DebugMode switch picks the source once in create_graph, and both the setup and render sides use only result_texture_handler.