82 lines
3.1 KiB
Markdown
82 lines
3.1 KiB
Markdown
# 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
|
|
|
|
```powershell
|
|
# 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
|
|
|
|
1. **API Pre-check**: Before writing any OpenUSD API call, scan headers first:
|
|
```powershell
|
|
findstr /r /s "FunctionName" third_party\OpenUSD_v25.05\include\
|
|
```
|
|
Never assume an API exists — the actual SDK version may differ from docs.
|
|
|
|
2. **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.
|
|
|
|
3. **Self-healing**: If compilation fails, extract the MSBuild error log and fix the root cause. Do not retry the same approach more than once.
|
|
|
|
4. **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.
|