This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
Spectrum uses Sharpmake (a C#-based build system) to generate Visual Studio 2026 project files, and vcpkg for dependency management.
setup.bat # Init Sharpmake submodule + build it, then generates VS projectsgenerate_project.batTools → Regenerate Prism code in VS (Prism extension), or run bin/profile/prismc.exe from sources/Prism/.
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.
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/.
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.
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 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::).
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.
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.
main.sharpmake.cs— all project/solution configuration; edit this to add files, dependencies, or definesvcpkg.json— vcpkg dependency manifestvcpkg-configuration.json— vcpkg registry config (uses git registry + custom overlay incustom-overlay/)workdir/— runtime working directory (shaders, assets); not fully committed (see .gitignore)
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.
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.
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 unbracketedPROFILE(...)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, notloop1) — 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) andMipMapGeneration.cpp— match that granularity when adding new instrumented code, don't invent a different style.
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.
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.
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.
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.
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()beforeneed()— the selected resource may not be produced at all in the current graph configuration, and a hardneed()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_Renderinsources/RenderSystem/GUI/Base.cppis the reference: theDebugModeswitch picks the source once increate_graph, and both the setup and render sides use onlyresult_texture_handler.