Viewport Overlays

Viewport Overlays are specialized UI elements drawn directly on top of the 3D scene. They provide spatial context that would be lost in a traditional side panel, such as measurement labels floating over a point cloud, interactive legends, or custom handles (gizmos) for manipulating 3D objects.

Interactive 3D Interfaces

Unlike standard windows, an overlay is aware of the 3D world. It can be positioned relative to the screen (e.g., a “Tools Help” box in the bottom-right corner) or pinned to specific coordinates in the 3D world. This makes them the primary tool for building intuitive, spatially-aware interfaces.

The lifetime of an overlay is typically tied to the active Tool. When you activate a tool, the SDK automatically initializes its associated overlays; when the tool is closed, those overlays are cleaned up, ensuring the viewport remains uncluttered for the next task.

Communication Flow: Overlay to Tool

One of the most powerful uses of an overlay is capturing user intent within the 3D scene. For example, if you are building a “Wall Placement” tool, your overlay can detect where the user clicks in the viewport and send that coordinate back to the tool’s main logic.

This communication happens asynchronously:

1. The Overlay detects an action, such as a mouse click or a change to an on-screen slider.
2. The Overlay sends a message through the provided ViewportOverlayCtx.
3. The Tool receives this message in its asynchronous run method, allowing it to commit a Statement and update the project state.

Implementation with egui

Overlays are built using the same immediate-mode egui patterns as the rest of the SDK. This allows you to create highly reactive interfaces that can change their appearance based on the current state of the engine or the tool.

fn my_instruction_overlay(ui: &mut Ui, ctx: &mut Ctx, viewport_ctx: &mut ViewportOverlayCtx) -> WidgetResponse {
    // A simple floating instruction box
    egui::Area::new("instructions")
        .anchor(egui::Align2::RIGHT_TOP, egui::vec2(-10.0, 10.0))
        .show(ui.ctx(), |ui| {
            ui.label("Click to place the first anchor point.");
        })
        .response
}

Design Tips for the Viewport

Since overlays live in the same space as the 3D data, it’s important to keep them non-obtrusive. We recommend following these best practices:

• Focus on the Data: Ensure that your overlays don’t block the user’s view of the models they are currently editing. Use transparency or collapsible panels for larger UI elements.
• Maintain Frame Rate: Overlays are rendered every frame alongside the 3D engine. Keep your UI logic simple and efficient to ensure that the viewport remains smooth and responsive.
• Visual Consistency: Use the SDK’s standard widgets and the Phosphor Icon set to ensure that your custom overlays feel like a native part of the Foresight Development Kit experience.