Context and Lifecycle

Understanding Dear ImGui’s context system and the frame lifecycle from initialization to rendering

The ImGui Context

Dear ImGui uses a context to store all internal state. The context (ImGuiContext) is an opaque structure that contains:

• Window data and layout state
• Input state and event queues
• Font atlas and rendering data
• ID stack and widget state
• Navigation and focus state
• All temporary frame data

The context is intentionally opaque. You don’t need to understand its internals - just know that it exists and must be properly managed.

Context Creation and Destruction

Basic Setup

Every Dear ImGui application must create a context before using any ImGui functions:

// Application initialization
ImGui::CreateContext();
ImGuiIO& io = ImGui::GetIO();

// Configure the context
io.ConfigFlags |= ImGuiConfigFlags_NavEnableKeyboard;

// Your application loop here

// Application shutdown
ImGui::DestroyContext();

Multiple Contexts

You can create multiple contexts, but only one can be current at a time:

// Create two separate contexts
ImGuiContext* context1 = ImGui::CreateContext();
ImGuiContext* context2 = ImGui::CreateContext();

// Switch between contexts
ImGui::SetCurrentContext(context1);
ImGui::NewFrame();
// ... render UI for context1 ...
ImGui::Render();

ImGui::SetCurrentContext(context2);
ImGui::NewFrame();
// ... render UI for context2 ...
ImGui::Render();

// Cleanup
ImGui::DestroyContext(context1);
ImGui::DestroyContext(context2);

Most applications only need a single context. Multiple contexts are useful for advanced scenarios like multi-threaded rendering or isolated UI instances.

Shared Font Atlas

You can share a font atlas between contexts:

ImFontAtlas* shared_atlas = new ImFontAtlas();
shared_atlas->AddFontDefault();

ImGuiContext* ctx1 = ImGui::CreateContext(shared_atlas);
ImGuiContext* ctx2 = ImGui::CreateContext(shared_atlas);

// Both contexts use the same fonts, saving memory

The Frame Lifecycle

Each frame in Dear ImGui follows a strict lifecycle:

┌─────────────────────────────────────────┐
│  NewFrame()                             │  Start new frame
│    - Process inputs                      │
│    - Update time delta                   │
│    - Update mouse/keyboard state         │
└─────────────┬───────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────┐
│  Your UI Code                            │  Submit UI commands
│    Begin(), Button(), Text(), etc.       │
│    - Widgets read/write your data        │
│    - Layout is calculated                │
│    - Draw commands are generated         │
└─────────────┬───────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────┐
│  Render() / EndFrame()                   │  Finalize frame
│    - Finalize windows                    │
│    - Build draw data                     │
│    - Prepare for rendering               │
└─────────────┬───────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────┐
│  GetDrawData()                           │  Retrieve draw data
│    - Returns ImDrawData*                 │
│    - Ready for GPU rendering             │
└─────────────┬───────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────┐
│  Backend RenderDrawData()                │  Render to screen
│    - Upload vertex/index buffers         │
│    - Execute draw commands               │
│    - Present to screen                   │
└─────────────────────────────────────────┘

NewFrame() - Starting a Frame

ImGui::NewFrame() begins a new Dear ImGui frame. Call this as early as possible in your main loop.

void MainLoop()
{
    // Update application state
    UpdateGame();
    
    // Start Dear ImGui frame
    ImGui::NewFrame();
    
    // Now you can call any ImGui functions
    ImGui::ShowDemoWindow();
    
    // End frame and render
    ImGui::Render();
    RenderDrawData(ImGui::GetDrawData());
}

What NewFrame() Does

1. Validates state - Checks that the previous frame was properly ended
2. Updates time - Processes io.DeltaTime for animations
3. Processes inputs - Consumes events from io.AddMouseXXX(), io.AddKeyEvent(), etc.
4. Updates navigation - Handles keyboard/gamepad navigation
5. Begins layout - Resets layout state for the new frame
6. Initializes draw data - Prepares internal buffers

You must call NewFrame() before calling any widget functions. Calling widgets without NewFrame() will trigger an assert.

Submitting UI Commands

Between NewFrame() and Render(), you can call any Dear ImGui functions:

ImGui::NewFrame();

// Main window with menu bar
ImGui::Begin("My Application", nullptr, ImGuiWindowFlags_MenuBar);

if (ImGui::BeginMenuBar())
{
    if (ImGui::BeginMenu("File"))
    {
        if (ImGui::MenuItem("Open", "Ctrl+O")) { OpenFile(); }
        if (ImGui::MenuItem("Save", "Ctrl+S")) { SaveFile(); }
        ImGui::EndMenu();
    }
    ImGui::EndMenuBar();
}

// UI content
ImGui::Text("Frame time: %.3f ms", 1000.0f / ImGui::GetIO().Framerate);
ImGui::SliderFloat("Float", &my_float, 0.0f, 1.0f);

if (ImGui::Button("Click Me"))
    DoSomething();

ImGui::End();

// Another window
ImGui::Begin("Debug Info");
ImGui::Text("Mouse Position: (%.1f, %.1f)", io.MousePos.x, io.MousePos.y);
ImGui::End();

ImGui::Render();

Render() and EndFrame()

ImGui::Render() finalizes the frame and builds the draw data.

ImGui::Render();
ImDrawData* draw_data = ImGui::GetDrawData();
MyRenderFunction(draw_data);

What Render() Does

1. Calls EndFrame() internally (you can also call EndFrame() manually)
2. Finalizes windows - Completes all Begin/End pairs
3. Sorts draw data - Optimizes draw call order
4. Builds draw lists - Finalizes vertex and index buffers
5. Prepares ImDrawData - Creates the structure for rendering

Render() automatically calls EndFrame(). You only need to call EndFrame() manually if you’re skipping rendering for some reason.

EndFrame() Without Rendering

You can finalize the frame without rendering:

ImGui::NewFrame();
// ... UI code ...
ImGui::EndFrame();
// Don't call Render() - UI state updated but not rendered

This is useful if you need Dear ImGui to process inputs but don’t want to render the UI.

GetDrawData() - Retrieving Draw Commands

ImGui::GetDrawData() returns the finalized draw data after Render():

ImGui::Render();
ImDrawData* draw_data = ImGui::GetDrawData();

if (draw_data->CmdListsCount > 0)
{
    // Valid draw data - render it
    ImGui_ImplDX11_RenderDrawData(draw_data);
}

ImDrawData Structure

struct ImDrawData
{
    bool            Valid;              // Valid after Render(), invalid after next NewFrame()
    ImDrawList**    CmdLists;           // Array of ImDrawList* to render
    int             CmdListsCount;      // Number of ImDrawList* in array
    int             TotalVtxCount;      // Total vertex count
    int             TotalIdxCount;      // Total index count
    ImVec2          DisplayPos;         // Top-left position of viewport
    ImVec2          DisplaySize;        // Size of viewport
    ImVec2          FramebufferScale;   // Scale for Retina displays
};

Complete Application Skeleton

Here’s a complete minimal application:

#include "imgui.h"
#include "imgui_impl_glfw.h"
#include "imgui_impl_opengl3.h"
#include <GLFW/glfw3.h>

int main()
{
    // Initialize GLFW and create window
    glfwInit();
    GLFWwindow* window = glfwCreateWindow(1280, 720, "Dear ImGui App", NULL, NULL);
    glfwMakeContextCurrent(window);
    
    // Create Dear ImGui context
    IMGUI_CHECKVERSION();
    ImGui::CreateContext();
    ImGuiIO& io = ImGui::GetIO();
    
    // Configure Dear ImGui
    io.ConfigFlags |= ImGuiConfigFlags_NavEnableKeyboard;
    
    // Initialize backends
    ImGui_ImplGlfw_InitForOpenGL(window, true);
    ImGui_ImplOpenGL3_Init("#version 130");
    
    // Main loop
    while (!glfwWindowShouldClose(window))
    {
        // Poll events
        glfwPollEvents();
        
        // Start new Dear ImGui frame
        ImGui_ImplOpenGL3_NewFrame();
        ImGui_ImplGlfw_NewFrame();
        ImGui::NewFrame();
        
        // Your UI code here
        ImGui::ShowDemoWindow();
        
        // Render Dear ImGui
        ImGui::Render();
        
        // Clear screen and render Dear ImGui draw data
        glClear(GL_COLOR_BUFFER_BIT);
        ImGui_ImplOpenGL3_RenderDrawData(ImGui::GetDrawData());
        
        glfwSwapBuffers(window);
    }
    
    // Cleanup
    ImGui_ImplOpenGL3_Shutdown();
    ImGui_ImplGlfw_Shutdown();
    ImGui::DestroyContext();
    
    glfwDestroyWindow(window);
    glfwTerminate();
    
    return 0;
}

Using Custom Backends

If you’re implementing a custom backend, the core lifecycle remains the same:

// Application init
ImGui::CreateContext();
ImGuiIO& io = ImGui::GetIO();

// Main loop
while (running)
{
    // Setup inputs (your custom code)
    io.DeltaTime = 1.0f/60.0f;
    io.DisplaySize = ImVec2(1920, 1080);
    io.AddMousePosEvent(mouse_x, mouse_y);
    io.AddMouseButtonEvent(0, mouse_button_down);
    
    // Start frame
    ImGui::NewFrame();
    
    // Your UI code
    ImGui::ShowDemoWindow();
    
    // Finalize frame
    ImGui::Render();
    
    // Render (your custom rendering code)
    MyCustomRenderDrawData(ImGui::GetDrawData());
}

// Shutdown
ImGui::DestroyContext();

Common Lifecycle Errors

Calling End() without Begin():

// WRONG - will assert!
ImGui::Text("Hello");
ImGui::End();

Always pair Begin() with End().

Calling NewFrame() twice:

// WRONG - will assert!
ImGui::NewFrame();
ImGui::NewFrame(); // Error: previous frame not ended

Each NewFrame() must be paired with Render() or EndFrame().

Using draw data after NewFrame():

ImGui::Render();
ImDrawData* data = ImGui::GetDrawData();
ImGui::NewFrame(); // Draw data is now invalid!
RenderData(data);  // WRONG - data is stale

Draw data is only valid between Render() and the next NewFrame().

Performance Considerations

Frame Budget

Dear ImGui is designed to be fast, but you should still be mindful:

// Good: Only create UI when window is open
if (show_expensive_window)
{
    ImGui::Begin("Expensive Window", &show_expensive_window);
    // ... lots of widgets ...
    ImGui::End();
}

// Good: Early out when collapsed
if (ImGui::Begin("My Window"))
{
    // Window is visible - do expensive work
    for (int i = 0; i < 10000; i++)
        ImGui::Text("Item %d", i);
}
ImGui::End();

Memory Allocations

A well-designed Dear ImGui application should:

• Never call malloc/free in a typical idle frame
• Preallocate buffers during initialization
• Reuse temporary buffers across frames

DLL/Shared Library Considerations

DLL users: Heaps and globals are not shared across DLL boundaries!

If using Dear ImGui across DLL boundaries:

// In your DLL:
void MyDLLFunction()
{
    ImGui::SetCurrentContext(g_SharedContext);
    ImGui::SetAllocatorFunctions(MyMalloc, MyFree);
    
    // Now safe to use Dear ImGui
    ImGui::Text("From DLL");
}

You must call SetCurrentContext() and SetAllocatorFunctions() for each DLL boundary.

Next Steps

• Learn about Windows and Layout
• Understand The ID Stack System
• Read about Input Handling