diff --git a/README.md b/README.md index 3970942..998c60e 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,27 @@ # USD Layer Manager -A C++17 / Windows desktop application providing a **Maya Render Layers-style** USD scene editor using **OpenUSD v25.05**, **ImGui 1.92.7** (docking branch), and **OpenGL 3.3** (via GLAD). Users can open, edit, and save USD files, manage layered stage overrides, inspect and edit prim properties, and interact with 3D scenes through a Hydra viewport. +A C++17 / Windows desktop application providing a **Maya-style** USD scene and look-dev editor using **OpenUSD v25.05**, **ImGui 1.92.7** (docking branch), and **OpenGL 3.3** (via GLAD). Users can open, edit, and save USD files, manage layered stage overrides, inspect and edit prim properties, author UsdShade material graphs with a live shader-ball preview, animate with a Bezier curve editor, and interact with 3D scenes through a multi-viewport Hydra renderer with OCIO color management. ![Screenshot](docs/icons/screenshot_01.png) ## Features -- **Layer Stack Management** — Create, reorder, mute/unmute sublayers with full undo support -- **Scene Hierarchy** — Browse prim tree with per-type SVG icons; create, delete, rename prims; add/replace references +- **Layer Stack Management** — `StageEditorPanel`: create, reorder, mute/unmute sublayers, set the edit target, add existing files as sublayers, with full undo support +- **Scene Hierarchy** — Browse prim tree with per-type SVG icons; create, delete, rename, reparent, and group prims; add/replace references - **Property Editor** — Maya Channel Box-style attribute editing with type-aware drag inputs, color pickers, and undoable transforms -- **3D Viewport** — Hydra rendering via `UsdImagingGLEngine` into an offscreen FBO; switchable render delegates (Storm, Embree, Arnold, Cycles); grid overlay; selection bounding boxes; camera wireframes -- **Multi-Viewport** — Single, horizontal split, vertical split, and quad layouts; per-tile camera and render settings; Space to maximize/restore +- **Material Editor** — Hypershade-style node-graph editor for UsdShade/MaterialX networks (`MaterialEditorPanel`): material browser, drag-to-connect node canvas, per-node/per-pin display modes, Sdr-driven node creation menu and enum dropdowns, colorSpace authoring on texture inputs, and a live shader-ball preview (`MaterialPreviewRenderer`) with its own renderer/HDRI/preview-shape controls. In-canvas node thumbnails (`NodeThumbnailCache`) show texture previews and per-node shader-ball renders, amortized across frames and re-rendered until progressive delegates (Arnold/Cycles/Embree) fully converge +- **Timeline & Curve Editor** — Transport controls with loop/bounce and Auto-Key (`TimelinePanel`); a Maya-style F-curve editor (`CurveEditorPanel`) with Bezier round-trip to USD time samples; Playblast export to MP4 via `MovieEncoder` (libavcodec) +- **3D Viewport** — Hydra rendering via `UsdImagingGLEngine` into an offscreen FBO; switchable render delegates (Storm, Embree, Arnold, Cycles); OCIO-based color management (sRGB or full display/view/look pipeline) applied as a post-Hydra GL pass; grid overlay; selection bounding boxes; camera/light wireframes +- **Multi-Viewport** — Single, horizontal split, vertical split, and quad layouts; per-tile camera, render delegate, and AOV; Space to maximize/restore - **Camera Control** — Free orbital camera (tumble/truck/dolly) or drive from USD camera prims; auto near/far clipping; frame selection; correct camera prim orientation for Y-up and Z-up stages - **Transform Gizmo** — Pure ImDrawList-based manipulator (translate/rotate/scale) in object or world space -- **Undo/Redo** — Full command history for prim creation/deletion, attribute edits, transform changes, and layer operations; Ctrl+Z / Ctrl+Y hotkeys; Edit menu integration +- **Undo/Redo** — Full command history (`ICommand` subclasses under `src/core/commands/`) covering prim creation/deletion/reparenting/grouping, attribute edits, transform changes, shader-node creation/connection, and layer operations; Ctrl+Z / Ctrl+Y hotkeys; Edit menu integration - **Multi-select** — Rectangular selection in viewport with cross-panel syncing +| Material Editor (Arnold) | Curve Editor | Quad Viewport (4 delegates) | MaterialX import | +|---|---|---|---| +| ![Material Editor](docs/icons/screenshot_06.png) | ![Curve Editor](docs/icons/screenshot_02.png) | ![Quad Viewport](docs/icons/screenshot_03.png) | ![MaterialX](docs/icons/screenshot_04.png) | + ## Dependencies | Dependency | Version | Notes | @@ -53,7 +59,7 @@ cmake --install build --config Release The installed executable lives in `install/bin/`. -**Presets** — `default` (Release + tests), `debug`, `release`, `no-tests`. +**Presets** — `default` (`Release`, `WITH_CYCLES=ON`, all render delegates), `debug` (`Debug`), `release` (`RelWithDebInfo`, installs), `no-tests` (`Release`). All presets currently build with `BUILD_TESTS=OFF`. ### Building with Cycles @@ -63,10 +69,7 @@ Cycles runtime dependencies (`embree4.dll`, `openvdb.dll`, `OpenImageDenoise.dll ### Tests -```powershell -cmake --build build --config Release -ctest --test-dir build -C Release -``` +There is currently no working test runner: `BUILD_TESTS` is `OFF` in every preset. The two test executables (`ViewportDisplayTest`, `RendererDiagnosticTest`) have stale USD include paths and don't build — fix those before turning `BUILD_TESTS` on. ## Architecture @@ -77,31 +80,46 @@ src/ │ ├── UsdStageManager — Stage open/create/save/close lifecycle │ ├── LayerManager — Layer stack introspection and mutation │ ├── PropertyManager — Property read/write via edit target with undo +│ ├── MaterialManager — UsdShade graph introspection + Sdr node-type/enum discovery │ ├── CommandHistory — Undo/redo stack for ICommand instances -│ ├── UsdSceneRenderer — Hydra rendering + picking + overlays +│ ├── UsdSceneRenderer — Hydra rendering + picking + overlays + OCIO color correction │ ├── ViewportCamera — Free / USD-camera-driven orbital camera │ └── commands/ — ICommand subclasses for all mutable operations -│ ├── TransformCommand — Undoable translate/rotate/scale -│ ├── CreatePrimCommand — Undoable prim creation (with camera orientation) -│ ├── DeletePrimCommand — Undoable prim deletion (SdfCopySpec snapshot) -│ ├── AttributeSetCommand — Type-agnostic undoable attribute writes -│ ├── AddReferenceCommand — Undoable reference addition -│ ├── ReplaceReferenceCommand — Undoable reference replacement -│ └── LayerCommands — Create, remove, reorder sublayers +│ ├── TransformCommand — Undoable translate/rotate/scale +│ ├── CreatePrimCommand — Undoable prim creation (with camera orientation) +│ ├── DeletePrimCommand — Undoable prim deletion (SdfCopySpec snapshot) +│ ├── RenamePrimCommand — Undoable prim rename +│ ├── ReparentPrimCommand — Undoable reparent via UsdNamespaceEditor +│ ├── GroupPrimsCommand — Group selected prims under a new Xform +│ ├── AttributeSetCommand — Type-agnostic undoable attribute writes +│ ├── AddReferenceCommand — Undoable reference addition +│ ├── ReplaceReferenceCommand — Undoable reference replacement +│ ├── CreateShaderNodeCommand — Undoable UsdShadeShader creation (Material Editor) +│ ├── ConnectShaderAttrsCommand — Undoable shader input↔output connection +│ ├── DisconnectShaderAttrCommand — Undoable shader connection removal +│ └── LayerCommands — Create, remove, reorder sublayers ├── ui/ — ImGui panels and application shell -│ ├── Application — App shell (owns managers/panels, docking, menus) -│ ├── ImGuiContext — Win32+OpenGL+ImGui initialization and loop -│ ├── ViewportPanel — Viewport container (layout, divider drag, maximize) -│ ├── ViewportTile — Single viewport tile (camera, rendering, overlays, picking) -│ ├── SceneHierarchyPanel — Prim tree browser with context menus -│ ├── PropertyPanel — Attribute/transform editor (channel box-style) -│ ├── LayerPanel — Layer stack editor with modal dialogs -│ ├── TransformManipulator — ImDrawList gizmo (move/rotate/scale) -│ └── IconManager — SVG icon rasterization via NanoSVG +│ ├── Application — App shell (owns managers/panels, docking, menus) +│ ├── ImGuiContext — Win32+OpenGL+ImGui initialization and loop +│ ├── ViewportPanel — Viewport container (layout, divider drag, maximize) +│ ├── ViewportTile — Single viewport tile (camera, rendering, overlays, picking) +│ ├── SceneHierarchyPanel — Prim tree browser with context menus +│ ├── PropertyPanel — Attribute/transform editor (channel box-style) +│ ├── StageEditorPanel — Layer stack editor (edit target, dirty state, drag-drop ordering) +│ ├── TimelinePanel — Transport controls, loop/bounce, frame scrub, Playblast +│ ├── CurveEditorPanel — Maya-style F-curve editor (Bezier ↔ USD time samples) +│ ├── MaterialEditorPanel — Hypershade-style UsdShade node-graph editor +│ ├── MaterialPreviewRenderer — Shader-ball preview: independent Hydra instance + scratch stage +│ ├── NodeThumbnailCache — Async texture decode + amortized shader-ball thumbnails for the node canvas +│ ├── TransformManipulator — ImDrawList gizmo (move/rotate/scale) +│ ├── IconManager — SVG icon rasterization via NanoSVG +│ └── NodeEditor/ — Vendored/patched imgui-node-editor └── utils/ — Cross-cutting utilities - ├── Logger — Thread-safe logging (file + console) + ├── Logger — Thread-safe logging (file + console); also sinks USD TF_WARN/TF_ERROR ├── FileDialog — Win32 file open/save dialogs ├── PathUtils — Exe-relative path resolution + ├── OcioConfigParser — Enumerates displays/views/colorspaces/looks from the active OCIO config + ├── MovieEncoder — Streams RGBA frames to H.264/MP4 via libavcodec (Playblast) └── GLExt — GLAD extension initialization ``` @@ -111,6 +129,7 @@ src/ - **Panel-Manager Separation** — UI panels hold pointers to core managers but contain no USD layer/prim logic - **Callback Wiring** — Cross-panel communication via `std::function` callbacks (e.g. viewport pick → hierarchy select → property panel update) - **Render-Delegate Plugability** — `UsdSceneRenderer` can switch Hydra render plugins at runtime +- **Own Color Correction Pass** — Hydra's `HdxColorCorrectionTask` is bypassed; a file-local `ViewportColorCorrector` (inside `UsdSceneRenderer.cpp`) applies sRGB/OCIO as a fullscreen GL pass after Hydra renders linear (see `docs/adr/0001-viewport-color-correction.md`) - **Gizmo as 2D Overlay** — `TransformManipulator` uses pure `ImDrawList` calls (no GL resources), same approach as ImGuizmo ## Project Configuration @@ -121,6 +140,7 @@ src/ | `cmake/modules/FindImgui.cmake` | ImGui source integration | | `cmake/modules/FindGlad.cmake` | GLAD loader setup | | `CMakePresets.json` | Build presets (VS 17 2022, x64) | +| `docs/adr/` | Architecture decision records | | `AGENTS.md` | AI agent build/architecture guide | | `.kilo/` | Kilo AI configuration (commands, agents, skills) | | `openspec/changes/` | Feature proposals and implementation tracking | @@ -149,12 +169,11 @@ Before writing any OpenUSD API call, verify the API exists in the actual SDK: findstr /r /s "FunctionName" third_party\OpenUSD_v25.05\include\ ``` -Always build and install before running tests: +Always build and install before manually verifying a change: ```powershell cmake --build build --config Release cmake --install build --config Release -ctest --test-dir build -C Release ``` ## License