UsdLayerManager/openspec/changes/camera-wireframe-viewport/specs/camera-frustum-overlay/spec.md

ADDED Requirements

Requirement: Camera frustum wireframe drawn every frame

For every UsdGeomCamera prim present in the current USD stage, the system SHALL draw a 3D wireframe representation into the viewport FBO each frame. The wireframe SHALL be drawn at UsdTimeCode::Default(). The wireframe SHALL consist of: (a) a small body box centred at the camera origin, (b) four lines from the camera origin to the corners of a near-clip display quad, and (c) a short up-arrow line indicating the camera's local Y axis.

Scenario: Camera wireframe appears when camera prim exists

• WHEN a UsdGeomCamera prim exists in the stage
• THEN a frustum wireframe is visible in the viewport at the camera prim's world-space position and orientation

Scenario: No wireframe when stage has no cameras

• WHEN no UsdGeomCamera prims exist in the stage
• THEN no camera wireframe is drawn

Requirement: Wireframe size scales with viewport camera distance

The wireframe scale SHALL be proportional to the current viewport camera's look-at distance (ViewportCamera::GetDist()), clamped to a maximum of 50 world units, so that camera shapes maintain a consistent apparent screen size regardless of zoom level.

Scenario: Camera wireframe stays visible when zooming out

• WHEN the viewport camera is zoomed out (increasing distance)
• THEN the camera wireframe grows proportionally so it remains visible at roughly the same screen size

Requirement: Three distinct visual states

The system SHALL draw camera wireframes using three colour states:

• Inactive (default): muted grey (0.55, 0.55, 0.55, 0.85)
• Active (the camera currently driving the viewport via the camera toolbar): cyan (0.2, 0.9, 1.0, 1.0)
• Selected (the camera prim is the current primary selection): yellow-orange (1.0, 0.75, 0.1, 1.0)

A camera that is both active and selected SHALL use the selected colour (selected takes priority).

Scenario: Active camera shown in cyan

• WHEN a USD camera prim is set as the active viewport camera via the camera toolbar
• THEN its wireframe is drawn in cyan

Scenario: Selected camera shown in yellow-orange

• WHEN a camera prim is the primary selected prim in the scene hierarchy
• THEN its wireframe is drawn in yellow-orange, overriding the cyan active colour

Requirement: Camera list cached and refreshed on stage change

The system SHALL cache the list of UsdGeomCamera prim paths to avoid re-traversing the stage every frame. The cache SHALL be invalidated whenever SetForceRefresh(true) is called or the stage pointer changes.

Scenario: Cache invalidated on stage reload

• WHEN a new USD file is opened
• THEN the camera wireframe list reflects the new stage's cameras in the next frame