Init Repo

2026-06-03 09:00:11 +08:00
commit 9be48d8b9e
155 changed files with 14827 additions and 0 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-08
@@ -0,0 +1,115 @@
+## Context
+
+The application currently has a `SceneHierarchyPanel` class (92 lines) that implements a functional tree view of USD prims:
+- Uses `PropertyManager::GetPrimPaths()` to get all prims
+- Recursively renders prims with `RenderPrimNode()` showing name, type, and selection state
+- Supports selection highlighting, tooltips with type/path, and double-click/arrow expansion
+- Has a callback mechanism (`PrimSelectCallback`) for notifying when a prim is selected
+
+However, `Application::RenderUI()` (lines 94-103) ignores this class and renders an inline placeholder instead:
+```cpp
+ImGui::Begin("Scene Hierarchy", nullptr, ImGuiWindowFlags_NoCollapse);
+if (m_stageManager->HasStage()) {
+    ImGui::Text("Stage loaded: %s", m_stageManager->GetRootLayerIdentifier().c_str());
+    ImGui::Separator();
+    ImGui::Text("Scene hierarchy will be displayed here");
+} else {
+    ImGui::TextDisabled("No stage loaded");
+    ImGui::Text("Open a USD file to view scene hierarchy");
+}
+ImGui::End();
+```
+
+Meanwhile, the `LayerPanel` class is properly wired in (lines 105-111) and functions correctly:
+```cpp
+ImGui::Begin("Layer Panel", nullptr, ImGuiWindowFlags_NoCollapse);
+if (m_stageManager->HasStage()) {
+    m_layerPanel->Render();
+} else {
+    ImGui::TextDisabled("No stage loaded");
+}
+ImGui::End();
+```
+
+The `PropertyPanel` class exists as a header only (no .cpp file) and is also rendered as a placeholder.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Wire the existing `SceneHierarchyPanel` into `Application` so it functions as a dockable panel
+- Enhance the panel with prim type icons, visibility/active state indicators, and context menus
+- Ensure prim selection drives other panels (Property Panel) via the existing callback mechanism
+- Maintain consistency with the existing `LayerPanel` wiring pattern
+
+**Non-Goals:**
+- Do not create a new panel class from scratch (the class already exists)
+- Do not modify the core USD traversal logic in `PropertyManager` (it's already functional)
+- Do not implement 3D viewport or property editing in this change
+- Do not change the docking architecture or ImGui context management
+
+## Decisions
+
+### 1. Wiring Pattern: Follow Existing LayerPanel Approach
+**Decision:** Wire `SceneHierarchyPanel` exactly like `LayerPanel` - create instance in `Application::Initialize()`, call `SetPropertyManager()`, and invoke `Render()` in `Application::RenderUI()`.
+
+**Rationale:**
+- Consistency with existing working pattern (`LayerPanel`)
+- Minimal changes required
+- Clear separation of concerns (Application manages lifecycle, panel handles rendering)
+- Avoids duplicating the placeholder code
+
+**Alternatives Considered:**
+- Inline rendering in Application (current placeholder) - rejected because it duplicates existing functionality
+- Creating panel on-demand in RenderUI - rejected because it loses state and breaks consistency
+
+### 2. Enhancement: Add Visual Indicators for Prim State
+**Decision:** Enhance `SceneHierarchyPanel::RenderPrimNode()` to show:
+- Prim type icons (using Unicode characters or colored text)
+- Visibility/inactive state indicators (eye icon or strike-through)
+- Reference/instance indicators
+- Context menu for common operations (toggle visibility, toggle active)
+
+**Rationale:**
+- Provides immediate visual feedback about prim state without opening property panel
+- Matches user expectations from similar tools (Maya Outliner, Unity Hierarchy)
+- Leverages existing USD API (`GetVisibility()`, `GetActive()`)
+- Non-invasive enhancement that builds on solid foundation
+
+**Implementation Notes:**
+- Use `prim.GetVisibility()` and `prim.GetActive()` to determine state
+- Show icons before prim name: 👁️ (visible), 👁️‍🗨️ (invisible), ○ (active), ● (inactive)
+- Context menu via `ImGui::BeginPopupContextItem()` on the tree node
+
+### 3. Integration: Connect Selection to Property Panel
+**Decision:** Implement the `PrimSelectCallback` in `Application` to update the `PropertyPanel` when selection changes (once PropertyPanel is implemented).
+
+**Rationale:**
+- Leverages existing callback mechanism in SceneHierarchyPanel
+- Enables future integration with PropertyPanel
+- Follows event-driven pattern already established
+- No changes needed to SceneHierarchyPanel itself
+
+**Note:** PropertyPanel currently doesn't exist as .cpp, so this sets up the foundation for when it's implemented.
+
+### 4. Performance: Maintain Existing Traversal Approach
+**Decision:** Keep the existing `PropertyManager::GetPrimPaths()` + recursive traversal approach.
+
+**Rationale:**
+- Already implemented and working
+- `GetPrimPaths()` uses efficient `UsdPrimRange` traversal
+- Caching isn't needed for typical scene sizes (<10k prims)
+- Premature optimization would complicate the clean implementation
+
+## Risks / Trade-offs
+
+[Performance] → Acceptable for typical USD scenes; `GetPrimPaths()` is O(N) but only called when stage changes or panel refreshes needed.
+
+[UI Clutter] → Added icons and context menus enhance usability without overwhelming the interface; users can ignore extra visual cues if not needed.
+
+[Tight Coupling] → Application now depends on SceneHierarchyPanel class; however, this follows the same pattern as LayerPanel and is acceptable for core UI components.
+
+[Missing PropertyPanel] → Selection callback won't have immediate effect until PropertyPanel is implemented; this is expected and sets up proper integration for future work.
+
+## Open Questions
+
+None - the path forward is clear: wire the existing panel, enhance it with visual indicators, and maintain consistency with existing patterns.
@@ -0,0 +1,26 @@
+## Why
+
+The application currently has a `SceneHierarchyPanel` class that renders a prim tree using USD traversal, but `Application::RenderUI()` ignores it and renders an inline placeholder instead. Users cannot browse the USD prim hierarchy in the Scene Hierarchy panel — the foundational feature for this USD editing tool.
+
+## What Changes
+
+- Wire the existing `SceneHierarchyPanel` class into `Application` so it renders in the "Scene Hierarchy" dockable window
+- Enhance the panel to display prim type icons, visibility/active state indicators, and structured prim path hierarchy
+- Support prim selection that can drive other panels (Property Panel, Layer Panel) via the existing callback mechanism
+- Add context menu support for common prim operations (toggle visibility, toggle active, show/hide children)
+
+## Capabilities
+
+### New Capabilities
+
+- `scene-hierarchy-panel`: Renders a tree view of USD prims from the loaded stage, with selection, type indicators, and prim state toggles. Wired as a dockable panel in the application layout.
+
+### Modified Capabilities
+
+<!-- No existing specs have requirement-level changes -->
+
+## Impact
+
+- **Affected code**: `src/ui/Application.h/.cpp` (wiring), `src/ui/SceneHierarchyPanel.h/.cpp` (enhancements)
+- **Dependencies**: `UsdStageManager` (stage access), `PropertyManager` (prim traversal), `LayerManager` (layer context)
+- **No breaking changes** — the existing placeholder is replaced with the functional panel
@@ -0,0 +1,38 @@
+## ADDED Requirements
+
+### Requirement: Scene hierarchy panel displays USD prim tree
+The system SHALL display a hierarchical tree view of all prims in the currently loaded USD stage, allowing users to browse and select prims.
+
+#### Scenario: Panel shows prim hierarchy when stage loaded
+- **WHEN** a USD stage is successfully loaded and the Scene Hierarchy panel is visible
+- **THEN** the panel displays a tree view containing all prims from the stage, organized by parent-child relationships
+- **AND** each prim node displays its name, type, and visual indicators for visibility/active state
+- **AND** the root prims (children of the pseudo-root) are displayed at the top level
+
+#### Scenario: Panel shows empty state when no stage loaded
+- **WHEN** no USD stage is loaded (or stage creation/opening failed) and the Scene Hierarchy panel is visible
+- **THEN** the panel displays disabled text indicating no stage is loaded
+- **AND** suggests opening a USD file to view scene hierarchy
+
+#### Scenario: Prim selection highlights in tree
+- **WHEN** a prim is selected in the scene hierarchy tree (via click)
+- **THEN** that prim's node is highlighted as selected in the tree view
+- **AND** the panel's selected prim path is updated to match the clicked prim's path
+- **AND** the prim selection callback is invoked with the selected prim's path
+
+#### Scenario: Prim type visible in tooltip
+- **WHEN** the user hovers over a prim node in the scene hierarchy tree
+- **THEN** a tooltip appears showing the prim's type name and full path
+- **AND** the tooltip disappears when the cursor leaves the prim node
+
+#### Scenario: Context menu available on prim nodes
+- **WHEN** the user right-clicks on a prim node in the scene hierarchy tree
+- **THEN** a context menu appears with options for common prim operations
+- **AND** the context menu includes options to toggle visibility and toggle active state
+- **AND** selecting a context menu option applies the corresponding operation to the prim
+
+#### Scenario: Panel integrates with application docking system
+- **WHEN** the Scene Hierarchy panel is created as part of the application UI
+- **THEN** the panel appears as a dockable window titled "Scene Hierarchy"
+- **AND** the panel can be undocked, floated, resized, and docked to other positions in the UI
+- **AND** the panel respects the NoCollapse window flag (cannot be collapsed to title bar only)
@@ -0,0 +1,31 @@
+## 1. Wire SceneHierarchyPanel into Application
+
+- [x] 1.1 Add SceneHierarchyPanel member variable to Application class
+- [x] 1.2 Create SceneHierarchyPanel instance in Application::Initialize()
+- [x] 1.3 Set PropertyManager on SceneHierarchyPanel instance
+- [x] 1.4 Replace placeholder Scene Hierarchy panel code with call to m_sceneHierarchyPanel->Render()
+- [x] 1.5 Ensure SceneHierarchyPanel is properly cleaned up in Application::Shutdown()
+
+## 2. Enhance SceneHierarchyPanel with Visual Indicators
+
+- [x] 2.1 Modify RenderPrimNode to display prim type icons before the display name
+- [x] 2.2 Add visibility state indicators (eye/open vs eye/slash) based on prim.GetVisibility()
+- [x] 2.3 Add active state indicators (circle/filled circle) based on prim.GetActive()
+- [x] 2.4 Ensure proper indentation and spacing with the added indicators
+- [x] 2.5 Update tooltip to include visibility and active state information
+
+## 3. Add Context Menu Support
+
+- [x] 3.1 Add context menu popup on right-click of prim tree nodes
+- [x] 3.2 Add "Toggle Visibility" menu item that calls prim.SetVisibility() with toggled value
+- [x] 3.3 Add "Toggle Active" menu item that calls prim.SetActive() with toggled value
+- [x] 3.4 Add "Show/Hide Children" menu item to collapse/expand tree nodes
+- [x] 3.5 Ensure context menu only appears for valid prim nodes and handles USD errors gracefully
+
+## 4. Verify Selection and Integration
+
+- [x] 4.1 Verify prim selection highlighting works correctly in enhanced tree view
+- [x] 4.2 Confirm tooltip shows all relevant information (type, path, visibility, active)
+- [x] 4.3 Test that selection callback is properly invoked when prim is clicked
+- [x] 4.4 Ensure panel updates correctly when stage changes (new/loaded/closed)
+- [x] 4.5 Verify panel integrates properly with docking system (can be undocked, floated, etc.)