3.1 KiB

Raw Blame History

AGENTS.md

Project

C++17 / Windows desktop app using OpenUSD + ImGui + OpenGL. USD scene editor with layer-based overrides for lights, geometry, and materials — similar to Maya Render Layers.

Build Commands

# Configure (Visual Studio 17 2022, outputs to ./build, installs to ./install)
cmake --preset default

# Build Release
cmake --build build --config Release

# Install
cmake --install build --config Release

# Build & run tests
cmake --build build --config Release
ctest --test-dir build -C Release

Always use cmake --preset default — do not invoke CMake manually with ad-hoc -G flags.
Build output: ./build/ | Install prefix: ./install/
The installed App.exe lives in install/bin/.

Key Paths

What	Where
OpenUSD SDK	`third_party/OpenUSD_v25.05/`
ImGui source	`third_party/imgui-1.92.7/`
GLAD loader	`third_party/glad/`
Inter font	`third_party/Inter/Inter.ttc`
CMake Find modules	`cmake/modules/` (`FindOpenUSD.cmake`, `FindImgui.cmake`, `FindGlad.cmake`)
USD business logic	`src/core/`
ImGui panels	`src/ui/`
Utilities	`src/utils/`
Tests	`tests/`
OpenSpec specs/changes	`openspec/changes/`

Note: AGENTS.md previously listed OpenUSD_v25.08 — the actual SDK on disk is OpenUSD_v25.05. Trust CMakePresets.json / third_party/ over prose.

Architecture Notes

Namespace: all project code uses namespace UsdLayerManager.
USD plugin registry: at runtime the app scans <exe_dir>/usd/ for plugInfo.json and registers plugins via pxr::PlugRegistry.
Renderer uses UsdImagingGLEngine into a GlfDrawTarget FBO; viewport picking done via engine ray-cast.
ViewportCamera mirrors usdview's FreeCamera.py (Tumble/Truck/AdjustDistance/FrameSelection); supports both Free and USD camera-prim modes.
ImGui docking branch is used; docking enabled via IMGUI_HAS_DOCK.
Python 3.12 (python312.dll) must be present — OpenUSD runtime requires it. CMake copies it to output via POST_BUILD.
Windows-only: uses imgui_impl_win32 + imgui_impl_opengl3.

Critical Rules

API Pre-check: Before writing any OpenUSD API call, scan headers first:
```
findstr /r /s "FunctionName" third_party\OpenUSD_v25.05\include\
```
Never assume an API exists — the actual SDK version may differ from docs.
Build before test: Complete cmake --build + cmake --install before running App.exe or CTest. Tests copy USD/Python DLLs via POST_BUILD; skipping the build step breaks DLL resolution.
Self-healing: If compilation fails, extract the MSBuild error log and fix the root cause. Do not retry the same approach more than once.
No CI: There are no GitHub Actions workflows. Validation is manual via CTest and running App.exe.

Feature Workflow (OpenSpec)

Feature proposals live under openspec/changes/<name>/ with proposal.md, design.md, specs/, and tasks.md (checkbox-tracked). Use the openspec-* skills (via Kilo) to propose, implement, and archive changes.

3.1 KiB Raw Blame History