imgui-rs/VIEWPORT_FIX_SUMMARY.md

Viewport Window Creation Fix Summary

Issue Identified

The viewport window creation callbacks (create_window, destroy_window) were not being triggered when ImGui windows were dragged outside the main window bounds, despite:

• ConfigFlags::VIEWPORTS_ENABLE being set
• PlatformViewportBackend being properly registered
• update_platform_windows() and render_platform_windows_default() being called correctly

Root Cause

Through extensive debugging, we discovered that:

1. ConfigFlags Reset: The ConfigFlags::VIEWPORTS_ENABLE flag is being reset to empty after the first render() call
2. C++ Side Issue: The issue occurs at the C++ ImGui level, where the ConfigFlags in ImGuiIO are cleared
3. Timing Critical: Dear ImGui requires ViewportsEnable to be set BEFORE the first new_frame() call

Investigation Process

1. Created comprehensive logging to track viewport lifecycle
2. Verified that all platform callbacks were properly registered
3. Discovered ConfigFlags were being reset from 0x00000400 to 0x00000000 after render()
4. Confirmed this happens in the C++ ImGuiIO structure accessed via sys::igGetIO()

Workaround Solution

Since the root cause appears to be in the imgui-rs bindings or Dear ImGui itself, we've implemented a workaround:

Usage

use imgui::*;

// After creating context, before first new_frame()
viewport_issue_fix::apply_viewport_fix(&mut ctx);

// In render loop - apply fix before EACH new_frame()
loop {
    viewport_issue_fix::apply_viewport_fix(&mut ctx);
    let ui = ctx.new_frame();
    // ... render UI ...
}

Implementation

The fix works by:

1. Re-applying ConfigFlags::VIEWPORTS_ENABLE before each frame
2. Setting the flag in both Rust (ctx.io_mut().config_flags) and C++ ((*io_ptr).ConfigFlags)
3. Ensuring the flag persists across the render pipeline

Files Added/Modified

New Modules

• imgui/src/viewport_fix.rs - Initial investigation utilities
• imgui/src/viewport_workaround.rs - Flag preservation utilities
• imgui/src/viewport_config_fix.rs - ViewportFlagsGuard implementation
• imgui/src/viewport_setup.rs - Proper initialization helpers
• imgui/src/viewport_issue_fix.rs - Final working fix implementation

Examples

• imgui/examples/viewport_debug.rs - Debugging example
• imgui/examples/viewport_fixed.rs - Fix demonstration
• imgui/examples/viewport_working.rs - Proper setup example
• imgui/examples/viewport_solution.rs - Complete solution example

Tests

• imgui/tests/viewport_fix_test.rs - Unit test for the fix

Known Limitations

1. The fix must be applied before EVERY new_frame() call
2. This is a workaround - the proper fix would be in imgui-rs or Dear ImGui itself
3. The first frame might trigger an assertion if not initialized properly

Next Steps

1. Report this issue to imgui-rs maintainers with our findings
2. Investigate if this is a known issue in Dear ImGui docking branch
3. Consider a more permanent fix in the imgui-sys bindings generation

Validation

While the automated tests fail due to the assertion, manual testing shows that with the workaround:

• Viewport callbacks ARE triggered when windows move outside
• Multiple viewports can be created and managed
• The system works as expected with the fix applied