Init Repo

2026-06-03 09:00:11 +08:00
commit 9be48d8b9e
155 changed files with 14827 additions and 0 deletions
@@ -0,0 +1,53 @@
+## ADDED Requirements
+
+### Requirement: Camera supports orbit, pan, and zoom interaction
+
+The system SHALL provide a turntable-style orbit camera controlled by mouse input within the Viewport panel. Left-drag orbits around a focal point, middle-drag or shift+left-drag pans, and scroll-wheel zooms.
+
+#### Scenario: Orbit the camera
+- **WHEN** the user holds the left mouse button and drags within the Viewport panel
+- **THEN** the camera orbits around the focal point
+- **AND** the view updates in real-time
+
+#### Scenario: Pan the camera
+- **WHEN** the user holds the middle mouse button (or shift+left button) and drags within the Viewport panel
+- **THEN** the camera pans horizontally and vertically relative to the view plane
+- **AND** the focal point moves with the camera
+
+#### Scenario: Zoom the camera
+- **WHEN** the user scrolls the mouse wheel within the Viewport panel
+- **THEN** the camera moves closer to or farther from the focal point
+- **AND** the zoom is proportional to the current distance from the focal point
+
+### Requirement: Camera computes view and projection matrices
+
+The system SHALL compute a view matrix from the camera's eye position, focal point, and up vector, and a perspective projection matrix from the field of view, aspect ratio, and near/far clip planes.
+
+#### Scenario: View matrix from camera parameters
+- **WHEN** the camera parameters (eye, focal point, up) are set or updated
+- **THEN** the system computes a `lookAt` view matrix
+
+#### Scenario: Projection matrix matches viewport aspect ratio
+- **WHEN** the FBO dimensions change
+- **THEN** the projection matrix is recomputed with the updated aspect ratio
+
+### Requirement: Mouse input is captured only when the viewport is hovered
+
+The system SHALL capture mouse input for camera control only when the ImGui Viewport window is hovered. Mouse events outside the viewport SHALL NOT affect the camera.
+
+#### Scenario: Mouse input captured in viewport
+- **WHEN** the mouse cursor is over the Viewport panel and the user interacts
+- **THEN** the camera responds to the input
+
+#### Scenario: Mouse input ignored outside viewport
+- **WHEN** the mouse cursor is outside the Viewport panel
+- **THEN** camera input is not processed
+
+### Requirement: Camera frames the scene automatically
+
+The system SHALL compute a default camera position that frames the bounding box of the scene when a stage is first loaded.
+
+#### Scenario: Camera frames scene on stage load
+- **WHEN** a new USD stage is opened
+- **THEN** the camera position and focal point are set so the entire scene bounding box is visible
+- **AND** the camera distance is adjusted based on the scene size
@@ -0,0 +1,49 @@
+## ADDED Requirements
+
+### Requirement: Ground grid is rendered in the viewport
+
+The system SHALL render a ground plane grid at the Y=0 plane (XZ plane) to provide spatial reference.
+
+#### Scenario: Grid visible by default
+- **WHEN** the viewport is displaying a scene
+- **THEN** a grid is drawn on the Y=0 plane with lines at regular intervals
+
+#### Scenario: Grid can be toggled off
+- **WHEN** the user toggles the grid display off via the viewport context menu
+- **THEN** the grid is no longer rendered
+
+### Requirement: Axis gizmo is rendered in the viewport corner
+
+The system SHALL render a 3D axis indicator (RGB for XYZ) in the lower-left corner of the viewport to show scene orientation.
+
+#### Scenario: Axis gizmo visible
+- **WHEN** the viewport is displaying a scene
+- **THEN** an axis gizmo is drawn in the lower-left corner with X=red, Y=green, Z=blue lines and labels
+
+#### Scenario: Axis gizmo reflects camera orientation
+- **WHEN** the camera is rotated
+- **THEN** the axis gizmo orientation updates to reflect the current view direction
+
+### Requirement: Viewport background color is configurable
+
+The system SHALL render the viewport background with a configurable color, defaulting to a dark gray (0.15, 0.15, 0.15).
+
+#### Scenario: Default background color
+- **WHEN** the viewport is rendered
+- **THEN** the background is cleared to dark gray (0.15, 0.15, 0.15)
+
+#### Scenario: Background color changed via context menu
+- **WHEN** the user selects a different background color from the viewport settings
+- **THEN** the viewport background is updated to the selected color
+
+### Requirement: Viewport context menu provides display options
+
+The system SHALL provide a right-click context menu in the viewport with toggles for grid display and background color options.
+
+#### Scenario: Right-click opens context menu
+- **WHEN** the user right-clicks within the viewport area
+- **THEN** a context menu appears with options: "Show Grid" (toggle), and "Background" submenu with color presets
+
+#### Scenario: Toggle grid from context menu
+- **WHEN** the user clicks "Show Grid" in the context menu
+- **THEN** the grid display is toggled on or off
@@ -0,0 +1,77 @@
+## ADDED Requirements
+
+### Requirement: Viewport renders USD stage geometry into an FBO-backed ImGui panel
+
+The system SHALL render USD stage geometry into an OpenGL Framebuffer Object (FBO) and display the attached color texture via `ImGui::Image()` within the "Viewport" dockable panel.
+
+#### Scenario: Viewport displays scene geometry when a stage is loaded
+- **WHEN** a USD stage is opened and the Viewport panel is visible
+- **THEN** the system traverses the stage's prim tree, extracts `UsdGeomMesh` data, and renders mesh geometry into the FBO
+- **AND** the FBO color texture is displayed as an ImGui image in the Viewport panel
+
+#### Scenario: Viewport shows empty background when no stage is loaded
+- **WHEN** no USD stage is open
+- **THEN** the Viewport panel displays a dark background with no geometry
+
+### Requirement: FBO resizes to match viewport panel dimensions
+
+The system SHALL resize the FBO color and depth attachments whenever the Viewport panel's content region dimensions change.
+
+#### Scenario: FBO resized on dock layout change
+- **WHEN** the user docks, undocks, or resizes the Viewport panel
+- **THEN** the FBO is recreated with the new width and height from `ImGui::GetContentRegionAvail()`
+- **AND** the previous FBO textures are deleted
+
+#### Scenario: No unnecessary FBO reallocation
+- **WHEN** the Viewport panel dimensions remain unchanged between frames
+- **THEN** the FBO is not recreated
+
+### Requirement: USD mesh geometry is extracted and uploaded to GPU buffers
+
+The system SHALL traverse the UsdStage, extract `UsdGeomMesh` points, face vertex counts, face vertex indices, and normals, and upload them to OpenGL VBOs/VAOs.
+
+#### Scenario: Mesh data loaded from UsdGeomMesh prims
+- **WHEN** the stage is loaded or refreshed
+- **THEN** for each `UsdGeomMesh` prim, the system reads `points`, `faceVertexCounts`, `faceVertexIndices`, and `normals` attributes
+- **AND** uploads the data to OpenGL vertex buffer objects
+
+#### Scenario: Missing normals handled gracefully
+- **WHEN** a `UsdGeomMesh` prim has no authored normals
+- **THEN** the system computes flat face normals from the triangle winding
+- **AND** renders the mesh with the computed normals
+
+### Requirement: Meshes are rendered with diffuse color from UsdShade or primvar
+
+The system SHALL apply a diffuse color to each mesh obtained from `UsdShadeMaterial` binding or a `displayColor` primvar, falling back to a default color.
+
+#### Scenario: Mesh with UsdShade material
+- **WHEN** a mesh prim has a bound `UsdShadeMaterial` with a diffuse color output
+- **THEN** the mesh is rendered with that diffuse color
+
+#### Scenario: Mesh with displayColor primvar
+- **WHEN** a mesh prim has a `primvars:displayColor` attribute and no bound material
+- **THEN** the mesh is rendered with the displayColor value
+
+#### Scenario: Mesh with no color information
+- **WHEN** a mesh prim has neither a bound material nor a displayColor primvar
+- **THEN** the mesh is rendered with a default gray color (0.7, 0.7, 0.7)
+
+### Requirement: OpenGL shaders are GLSL #version 130 compatible
+
+All viewport shaders SHALL be written in GLSL #version 130 and use the compatibility profile built-in variables (`gl_Vertex`, attribute bindings, etc.) to match the existing OpenGL context.
+
+#### Scenario: Shaders compile on legacy OpenGL context
+- **WHEN** the application initializes the viewport renderer
+- **THEN** the vertex and fragment shaders compile successfully on the existing WGL OpenGL context initialized with `#version 130`
+
+### Requirement: Scene rendering is refreshed when the stage changes
+
+The system SHALL rebuild GPU geometry buffers when the USD stage is opened, closed, or when the stage content is modified.
+
+#### Scenario: Stage opened triggers rebuild
+- **WHEN** a new USD stage is opened
+- **THEN** the renderer clears existing GPU buffers and re-traverses the new stage
+
+#### Scenario: Stage closed clears geometry
+- **WHEN** the current stage is closed
+- **THEN** the renderer clears all GPU buffers and the viewport shows an empty scene