UsdLayerManager/openspec/changes/archive/2026-05-08-make-imgui-widget-dockable/design.md

Context

The application currently uses a fixed-position, fixed-size layout for all ImGui panels. Each window is placed via SetNextWindowPos/SetNextWindowSize with ImGuiCond_FirstUseEver. The imconfig.h file has docking-related macros fully commented out, and ImGuiContext::Initialize() only sets ImGuiConfigFlags_NavEnableKeyboard. A comment in the code explicitly states that docking requires a special build configuration that was intentionally deferred.

ImGui's docking branch (docking in the imgui repo) has been stable for years and is widely used. The prebuilt ImGui source in third_party/Imgui-1.92.7 may or may not include docking support — this must be verified.

Goals / Non-Goals

Goals:

• Enable ImGui docking at compile time and runtime
• Create a full-window dockspace spanning the entire application viewport
• All existing panels (Scene Hierarchy, Layer Panel, Viewport, Property Panel, Stage Info) become dockable
• Layout persists across sessions via imgui.ini
• Window visibility toggles continue to work via the View menu

Non-Goals:

• Multi-viewport support (floating OS windows) — this requires additional ImGuiConfigFlags_ViewportsEnable and is not needed
• Custom docking layout presets or saved workspace files
• Theming or styling changes beyond docking enablement
• Refactoring the panel class hierarchy — panels keep their existing Render() signatures

Decisions

1. Use ImGui::DockSpaceOverViewport over manual DockSpace

Rationale: DockSpaceOverViewport() automatically creates a dockspace that fills the main viewport and handles resizing. A manual DockSpace() requires managing the dockspace ID and the host window's position/size manually. For a single-window application, DockSpaceOverViewport is simpler and sufficient.

Alternative considered: Manual ImGui::DockSpace(ImGui::GetID("MainDockSpace")) inside a full-viewport ImGui::Begin/End block. Rejected because it requires more boilerplate with no benefit for our use case.

2. Enable docking via CMake compile definition, not imconfig.h

Rationale: Adding target_compile_definitions(... PRIVATE IMGUI_HAS_DOCK) in FindImgui.cmake keeps the configuration centralized and avoids modifying third-party header files. This is the standard approach for conditionally enabling ImGui features.

Alternative considered: Modifying imconfig.h to uncomment #define IMGUI_HAS_DOCK. Rejected because it modifies third-party source and would be lost on imgui updates.

3. Remove SetNextWindowPos/SetNextWindowSize entirely

Rationale: When docking is enabled, ImGui manages window positions. Keeping SetNextWindowPos calls could interfere with docking behavior. Windows will be created as dockable by default, and the docking system handles placement.

Alternative considered: Keeping SetNextWindowPos with ImGuiCond_FirstUseEver as fallback for undocked state. Rejected because it adds complexity with no user benefit — the docking system's layout persistence already handles first-use defaults.

4. Keep ImGuiWindowFlags_NoCollapse on main panels

Rationale: Core tool panels (Scene Hierarchy, Layer Panel, Viewport, Property Panel) should always be accessible. Allowing collapse could leave users with no visible panel. The View menu already provides show/hide toggles for optional panels.

Alternative considered: Allowing collapse on all windows. Rejected because it's easy for users to lose core panels with no obvious way to restore them.

Risks / Trade-offs

• Risk: The prebuilt imgui library in third_party/Imgui-1.92.7 may not include the docking branch source. → Mitigation: Verify the imgui source files contain DockSpaceOverViewport and related docking APIs. If not, the docking branch must be fetched.
• Risk: imgui.ini may accumulate stale docking layout data across builds/versions. → Mitigation: This is standard ImGui behavior; users can reset by deleting imgui.ini. Not a new problem.
• Risk: Docking increases per-frame CPU overhead slightly due to dock node management. → Mitigation: Negligible for the number of windows in this application (5-6 panels). No measurable performance impact expected.
• Risk: The current legacy WGL/OpenGL setup uses #version 130 which is compatible with docking. → Mitigation: Docking operates at the ImGui level (vertex data generation), not at the rendering backend level. No OpenGL version concerns.