Init Repo

2026-06-03 09:00:11 +08:00
commit 9be48d8b9e
155 changed files with 14827 additions and 0 deletions
@@ -0,0 +1,64 @@
+## ADDED Requirements
+
+### Requirement: ICommand interface
+The system SHALL provide an `ICommand` pure-virtual interface with `Execute()`, `Undo()`, and `GetDescription()` methods that all reversible operations implement.
+
+#### Scenario: Execute runs the operation
+- **WHEN** `ICommand::Execute()` is called on a newly created command
+- **THEN** the operation is applied to the USD stage and the scene reflects the new state
+
+#### Scenario: Undo reverses the operation
+- **WHEN** `ICommand::Undo()` is called after `Execute()`
+- **THEN** the USD stage returns to the state it was in before `Execute()` was called
+
+### Requirement: CommandHistory stack management
+The system SHALL maintain two stacks (undo stack, redo stack). `Push(cmd)` executes the command, pushes it onto the undo stack, and clears the redo stack. `Undo()` pops from the undo stack, calls `Undo()` on the command, and pushes it onto the redo stack. `Redo()` pops from the redo stack, calls `Execute()` on the command, and pushes it back onto the undo stack.
+
+#### Scenario: Push clears redo stack
+- **WHEN** the user undoes two steps and then makes a new edit
+- **THEN** the redo stack is cleared and the new command is the top of the undo stack
+
+#### Scenario: Undo with empty stack is a no-op
+- **WHEN** `CommandHistory::Undo()` is called and the undo stack is empty
+- **THEN** no crash occurs and the scene is unchanged
+
+#### Scenario: Redo with empty stack is a no-op
+- **WHEN** `CommandHistory::Redo()` is called and the redo stack is empty
+- **THEN** no crash occurs and the scene is unchanged
+
+### Requirement: Ctrl+Z / Ctrl+Y hotkeys
+The application SHALL process `Ctrl+Z` to invoke `Undo()` and `Ctrl+Y` (and `Ctrl+Shift+Z`) to invoke `Redo()` during the ImGui main loop, unless an ImGui text input widget has keyboard focus.
+
+#### Scenario: Ctrl+Z triggers undo
+- **WHEN** the user presses `Ctrl+Z` and the undo stack is non-empty
+- **THEN** the most recent command is undone and the viewport reflects the reverted state
+
+#### Scenario: Ctrl+Y triggers redo
+- **WHEN** the user presses `Ctrl+Y` and the redo stack is non-empty
+- **THEN** the most recent undone command is reapplied and the viewport reflects the restored state
+
+#### Scenario: Hotkeys ignored in text inputs
+- **WHEN** an ImGui `InputText` widget has keyboard focus and the user presses `Ctrl+Z`
+- **THEN** ImGui handles the keypress as text-widget undo and `CommandHistory::Undo()` is NOT called
+
+### Requirement: Edit menu Undo/Redo items
+The application SHALL provide **Edit → Undo** and **Edit → Redo** menu items. Each item SHALL display the description of the command that would be affected. Items SHALL be greyed out (disabled) when the respective stack is empty.
+
+#### Scenario: Undo item shows command description
+- **WHEN** the undo stack is non-empty and the Edit menu is opened
+- **THEN** the Undo item reads "Undo: <description of top command>" and is enabled
+
+#### Scenario: Undo item disabled when stack empty
+- **WHEN** the undo stack is empty and the Edit menu is opened
+- **THEN** the Undo item is greyed out and clicking it has no effect
+
+### Requirement: History cleared on stage lifecycle events
+The system SHALL call `CommandHistory::Clear()` whenever a stage is opened, closed, or replaced, so that stale USD object references cannot be dereferenced.
+
+#### Scenario: History clears on stage open
+- **WHEN** the user opens a new USD file
+- **THEN** both undo and redo stacks are empty after the stage loads
+
+#### Scenario: History clears on stage close
+- **WHEN** the user closes the current stage
+- **THEN** both undo and redo stacks are empty
@@ -0,0 +1,19 @@
+## ADDED Requirements
+
+### Requirement: Generic attribute set is undoable
+The system SHALL push an `AttributeSetCommand` to `CommandHistory` when `PropertyManager::SetPropertyValue` or `SetPropertyValueInLayer` is called. The command SHALL capture the old value (read before the set) and the new value as `std::function<void()>` closures so it is type-agnostic. `Undo()` SHALL restore the old value; `Redo()` SHALL re-apply the new value.
+
+#### Scenario: Undo reverts attribute change
+- **WHEN** the user changes a light's intensity via the Property panel and then presses Ctrl+Z
+- **THEN** the intensity returns to its previous value
+
+#### Scenario: Redo re-applies attribute change
+- **WHEN** the user undoes an attribute change and then presses Ctrl+Y
+- **THEN** the attribute is set back to the edited value
+
+### Requirement: Attribute command preserves layer targeting
+The `AttributeSetCommand` SHALL record which `SdfLayerHandle` was the active edit target. `Undo()` and `Redo()` SHALL use `UsdEditContext` to direct the attribute write to that same layer.
+
+#### Scenario: Undo writes revert to correct layer
+- **WHEN** the user edits an attribute with a non-root layer selected and then undoes
+- **THEN** the revert opinion is written to the same non-root layer, not the root layer
@@ -0,0 +1,22 @@
+## ADDED Requirements
+
+### Requirement: Sublayer creation is undoable
+The system SHALL push a `LayerCreateCommand` to `CommandHistory` when a new sublayer is created via the Layer panel. `Undo()` SHALL remove the sublayer from the layer stack. `Redo()` SHALL re-add it at the same position.
+
+#### Scenario: Undo removes created sublayer
+- **WHEN** the user creates a sublayer and then presses Ctrl+Z
+- **THEN** the sublayer is no longer in the layer stack
+
+### Requirement: Sublayer removal is undoable
+The system SHALL push a `LayerRemoveCommand` to `CommandHistory` when a sublayer is removed via the Layer panel. `Undo()` SHALL re-insert the layer path at its original index. `Redo()` SHALL remove it again.
+
+#### Scenario: Undo restores removed sublayer
+- **WHEN** the user removes a sublayer and then presses Ctrl+Z
+- **THEN** the sublayer reappears at its original position in the stack
+
+### Requirement: Sublayer reorder is undoable
+The system SHALL push a `LayerReorderCommand` to `CommandHistory` when sublayers are reordered (moved up or moved down) in the Layer panel. The command SHALL store the full ordered list before and after. `Undo()` SHALL restore the previous order.
+
+#### Scenario: Undo reverts move-up
+- **WHEN** the user moves a sublayer up and then presses Ctrl+Z
+- **THEN** the layer returns to its previous position in the stack
@@ -0,0 +1,37 @@
+## ADDED Requirements
+
+### Requirement: Prim creation is undoable
+The system SHALL push a `CreatePrimCommand` to `CommandHistory` when a prim is created via the scene hierarchy context menu. `Undo()` SHALL remove the created prim from the stage. `Redo()` SHALL re-create the prim with the same path and type.
+
+#### Scenario: Undo removes created prim
+- **WHEN** the user creates a Sphere prim and then presses Ctrl+Z
+- **THEN** the Sphere prim no longer appears in the scene hierarchy
+
+#### Scenario: Redo re-creates the prim
+- **WHEN** the user undoes a prim creation and then presses Ctrl+Y
+- **THEN** the Sphere prim reappears at the same path with the same type
+
+### Requirement: Prim deletion is undoable
+The system SHALL push a `DeletePrimCommand` to `CommandHistory` when a prim is deleted via the scene hierarchy confirm modal. Before deletion, the command SHALL serialize the prim spec (including all authored opinions on the edit-target layer) to an in-memory string. `Undo()` SHALL restore the serialized spec to the layer.
+
+#### Scenario: Undo restores deleted prim
+- **WHEN** the user deletes a prim and then presses Ctrl+Z
+- **THEN** the prim reappears in the scene hierarchy with all its authored attributes intact
+
+#### Scenario: Redo re-deletes the prim
+- **WHEN** the user undoes a deletion and then presses Ctrl+Y
+- **THEN** the prim is deleted again
+
+### Requirement: Add-reference is undoable
+The system SHALL push an `AddReferenceCommand` to `CommandHistory` when an external USD file is added as a reference. `Undo()` SHALL remove the reference (and the wrapping Xform prim if it was created by the add-reference operation). `Redo()` SHALL re-add the reference.
+
+#### Scenario: Undo removes added reference
+- **WHEN** the user adds a reference to an external file and then presses Ctrl+Z
+- **THEN** the reference prim is removed from the scene hierarchy
+
+### Requirement: Replace-reference is undoable
+The system SHALL push a `ReplaceReferenceCommand` to `CommandHistory` when an existing reference is replaced via the scene hierarchy. `Undo()` SHALL restore the previous `SdfReference`. `Redo()` SHALL apply the replacement again.
+
+#### Scenario: Undo restores previous reference path
+- **WHEN** the user replaces a reference and then presses Ctrl+Z
+- **THEN** the prim points back to the original reference file
@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: Gizmo drag produces one atomic undo command
+The system SHALL record the pre-drag TRS state when a viewport gizmo drag begins, and push a single `TransformCommand` to `CommandHistory` when the drag ends (mouse button released). The command SHALL store the prim path, the edit-target layer, and the full TRS (translate, rotate, scale) snapshots from before and after the drag.
+
+#### Scenario: Single undo reverses entire drag
+- **WHEN** the user drags the Move gizmo to translate a prim and then presses Ctrl+Z
+- **THEN** the prim returns to the position it had before the drag started (not an intermediate position)
+
+#### Scenario: Redo restores drag result
+- **WHEN** the user undoes a gizmo drag and then presses Ctrl+Y
+- **THEN** the prim moves back to the post-drag position
+
+#### Scenario: No command pushed for zero-delta drag
+- **WHEN** the user clicks a gizmo axis but releases without moving
+- **THEN** no command is pushed to the history stack
+
+### Requirement: Property panel TRS commits produce undo commands
+The system SHALL push a `TransformCommand` to `CommandHistory` when a translate, rotate, or scale field in the Property panel loses focus after being edited (`ImGui::IsItemDeactivatedAfterEdit()`). The command SHALL store the pre-edit and post-edit TRS values.
+
+#### Scenario: Undo reverts property-panel translate edit
+- **WHEN** the user types a new X translate value in the Property panel, presses Tab to commit, then presses Ctrl+Z
+- **THEN** the prim's translate returns to the value it had before the edit
+
+#### Scenario: Typing without committing does not push a command
+- **WHEN** the user begins editing a translate field but presses Escape to cancel
+- **THEN** no new command is added to the undo stack
+
+### Requirement: Transform command respects the active edit target layer
+The `TransformCommand` SHALL store and restore the `SdfLayerHandle` that was the active edit target at the time of the edit. `Undo()` and `Redo()` SHALL direct their `UsdGeomXformCommonAPI` writes to that same layer via `UsdEditContext`.
+
+#### Scenario: Undo writes to correct layer
+- **WHEN** the user has Layer B selected as the edit target, moves a prim, then undoes
+- **THEN** the revert is written to Layer B, not to the root layer