UsdLayerManager/openspec/changes/viewport-custom-camera/specs/viewport-camera-switching/spec.md

ADDED Requirements

Requirement: Camera selector dropdown in viewport

The viewport panel SHALL display a camera selector dropdown above the rendering canvas. The dropdown SHALL list "Free Camera" as the first entry, followed by all UsdCamera-typed prims found on the current USD stage.

Scenario: Dropdown shows free camera and stage cameras

• WHEN a USD stage is loaded and contains camera prims at paths /cameras/main and /cameras/top
• THEN the camera selector dropdown lists: "Free Camera", "/cameras/main", "/cameras/top"

Scenario: Dropdown shows only free camera with no stage cameras

• WHEN a USD stage is loaded and contains no camera prims
• THEN the camera selector dropdown lists only "Free Camera"

Scenario: No stage loaded

• WHEN no USD stage is loaded
• THEN the camera selector dropdown is disabled or shows only "Free Camera"

Requirement: Switch to USD camera prim view

When the user selects a USD camera prim from the dropdown, the viewport SHALL render the scene from that camera's viewpoint by reading its transform and projection attributes.

Scenario: Select a USD camera from dropdown

• WHEN the user selects "/cameras/main" from the camera dropdown
• THEN the viewport renders the scene using the view matrix derived from that camera prim's world transform and the projection matrix derived from its focalLength, horizontalAperture, and clippingRange attributes

Scenario: USD camera attribute mapping

• WHEN the viewport is rendering through a UsdCamera prim
• THEN the projection matrix SHALL be computed from the camera's focalLength, horizontalAperture, verticalAperture, clippingRange, and projection attributes
• AND the view matrix SHALL be computed from the camera prim's world-space transform

Requirement: Free camera navigation disabled in USD camera mode

When the viewport is in USD camera mode, orbit, pan, dolly, and zoom controls SHALL be disabled.

Scenario: Attempt orbit while in USD camera mode

• WHEN the viewport is viewing through a USD camera and the user performs Alt+LMB drag
• THEN no orbit occurs and the viewport remains at the USD camera's viewpoint

Requirement: Free camera state preserved across mode switches

The free camera's position, focal point, and orientation SHALL be preserved when switching to a USD camera and restored when switching back.

Scenario: Switch to USD camera and back

• WHEN the user positions the free camera, switches to a USD camera, then switches back to "Free Camera"
• THEN the viewport returns to the exact free camera position and orientation before the switch

Requirement: Camera list refreshed on stage change

The list of available USD camera prims SHALL be refreshed when the stage changes (file open, close, or stage reload).

Scenario: Open a new stage with different cameras

• WHEN the user opens a new USD file containing cameras at different paths
• THEN the camera selector dropdown updates to reflect the new stage's camera prims

Requirement: Default camera mode is free camera

The viewport SHALL start in free camera mode every time a stage is loaded.

Scenario: Stage loaded defaults to free camera

• WHEN a USD stage is loaded
• THEN the camera selector is set to "Free Camera" and the viewport renders from the built-in free camera