# What Are Draw Lists in Dear ImGui? Core Rendering Architecture Explained > Understand ImDrawList, the core rendering architecture in Dear ImGui. Learn how it collects vertex and index buffers and GPU draw commands to render widget geometry. - Repository: [omar/imgui](https://github.com/ocornut/imgui) - Tags: internals - Published: 2026-07-27 --- **ImDrawList is the fundamental render-command collector in Dear ImGui that aggregates vertex buffers, index buffers, and GPU draw commands to transform widget geometry into executable rendering instructions.** In the `ocornut/imgui` repository, draw lists serve as the bridge between immediate-mode UI construction and GPU execution. Every window maintains its own `ImDrawList` instance, while global lists handle background and foreground layers, collectively forming the complete rendering pipeline that backends translate into OpenGL, Vulkan, or DirectX draw calls. ## Core Data Structures of ImDrawList An `ImDrawList` instance aggregates three essential data components that work together to describe renderable geometry. ### Vertex and Index Buffers The `VtxBuffer` and `IdxBuffer` members are dynamic arrays that store the actual geometry generated by ImGui widgets and user code. Located in [`imgui_draw.cpp`](https://github.com/ocornut/imgui/blob/main/imgui_draw.cpp), these buffers accumulate position, texture coordinate, and color data for every primitive drawn during the frame. ### Command Buffer Architecture The `CmdBuffer` stores a sequential list of `ImDrawCmd` structs, with each command describing a single GPU draw operation. As implemented in [`imgui_draw.cpp`](https://github.com/ocornut/imgui/blob/main/imgui_draw.cpp), every command specifies the clip rectangle, texture ID, vertex offset, and element count required by the backend to issue the actual draw call. ### Shared Context Data `ImDrawListSharedData` holds data common to all draw lists within an `ImGuiContext`, including font atlases, default UV coordinates, and adaptive circle tessellation tables. This shared structure is defined in [`imgui_internal.h`](https://github.com/ocornut/imgui/blob/main/imgui_internal.h) and initialized when the context is created in [`imgui.cpp`](https://github.com/ocornut/imgui/blob/main/imgui.cpp). ## Draw List Lifecycle and Frame Management The rendering pipeline follows a strict lifecycle that ensures clean state transitions between frames. ### Creation and Context Initialization When `ImGuiContext` is constructed in [`imgui.cpp`](https://github.com/ocornut/imgui/blob/main/imgui.cpp), the system allocates `ImDrawListSharedData` and initializes each window's `ImDrawList` with a pointer to this shared data. This establishes the memory layout and default flags that persist throughout the application's lifetime. ### Per-Frame Reset and Command Building At the beginning of each frame, `ImDrawList::_ResetForNewFrame()` clears the command, vertex, and index buffers, then pushes a fresh `ImDrawCmd` as the current command. During widget rendering, functions like `AddRect`, `AddText`, and `AddImage` reserve buffer space via `PrimReserve` and write vertices directly, while internal methods such as `_OnChangedClipRect` and `_OnChangedTexture` automatically update the current command metadata. ### End Frame and Draw Data Aggregation When the frame concludes, all draw lists are gathered into an `ImDrawData` object accessible via `ImGui::GetDrawData()`. The backend receives this aggregated structure containing the vertex/index arrays and command list, then issues the final GPU draw calls as defined in [`imgui.cpp`](https://github.com/ocornut/imgui/blob/main/imgui.cpp). ## Advanced Rendering Features Dear ImGui implements several optimizations and extension mechanisms within the draw list system. ### Command Merging for Performance `ImDrawList::_TryMergeDrawCmds()` automatically merges consecutive commands that share identical clip rectangles, textures, and vertex offsets. This reduction in draw call count minimizes CPU overhead and GPU state changes during rendering. ### Layering with ImDrawListSplitter The `ImDrawListSplitter` utility, defined in [`imgui_internal.h`](https://github.com/ocornut/imgui/blob/main/imgui_internal.h), enables temporary channel separation within a single draw list. This mechanism supports complex rendering scenarios such as per-column rendering in tables, where geometry must be sorted before final submission. After rendering completes, the `Merge` method flattens the channels back into a unified command sequence. ### Large Mesh Support and Index Limits When the backend reports `ImGuiBackendFlags_RendererHasVtxOffset`, draw lists can emit `VtxOffset > 0` to bypass the 16-bit index limit. The `ImDrawListFlags_AllowVtxOffset` flag controls this behavior, enabling rendering of meshes containing more than 65,536 vertices without index overflow. ### Anti-Aliasing Configuration Draw lists respect the `ImDrawListFlags_AntiAliasedLines` and `ImDrawListFlags_AntiAliasedFill` flags, which are copied from `ImGuiIO` at frame start. These flags govern tessellation quality for lines and filled shapes, allowing applications to balance visual quality against performance. ### Custom Render Callbacks Individual draw commands may store a user-provided `ImDrawCallback` function pointer that the backend executes instead of a standard draw. This mechanism enables custom GPU state changes, shader switches, or specialized rendering effects without breaking the draw list abstraction. ## Practical Implementation Examples ### Drawing Custom Shapes Access the window's draw list to render thick, anti-aliased lines or shapes between widgets: ```cpp ImDrawList* draw = ImGui::GetWindowDrawList(); ImVec2 p0 = ImGui::GetCursorScreenPos(); ImVec2 p1 = ImVec2(p0.x + 200.0f, p0.y + 100.0f); draw->AddLine(p0, p1, IM_COL32(255, 0, 0, 255), 4.0f); ``` The `AddLine` function reserves vertices in `VtxBuffer`, updates the current `ImDrawCmd` with the active clip rectangle, and writes the line geometry directly into the buffers. ### Constructing Custom Meshes For arbitrary geometry, use low-level primitive functions to build triangle fans while maintaining automatic command merging: ```cpp ImDrawList* draw = ImGui::GetWindowDrawList(); ImVec2 centre = ImGui::GetCursorScreenPos() + ImVec2(60, 60); float radius = 50.0f; int segs = 12; ImU32 col = IM_COL32(0, 255, 0, 200); draw->PrimReserve(segs * 3, segs + 2); draw->PrimWriteIdx(draw->PrimGetIdx()); draw->PrimWriteVtx(centre, draw->_Data->TexUvWhitePixel, col); for (int i = 0; i <= segs; ++i) { float a = IM_PI * 2.0f * (float)i / (float)segs; ImVec2 pos = centre + ImVec2(ImCos(a) * radius, ImSin(a) * radius); draw->PrimWriteIdx(draw->PrimGetIdx() + i); draw->PrimWriteVtx(pos, draw->_Data->TexUvWhitePixel, col); } draw->AddDrawCmd(); ``` This approach leverages `PrimReserve`, `PrimWriteIdx`, and `PrimWriteVtx` to construct geometry while the draw list handles buffer management and command optimization. ### Implementing Draw Callbacks Inject custom rendering logic using callback commands for specialized GPU operations: ```cpp ImDrawList* draw = ImGui::GetWindowDrawList(); ImDrawCmd cmd; cmd.ElemCount = 0; cmd.Callback = [](const ImDrawList* parent, const ImDrawCmd* cmd) { MyRenderCustomTexture(); }; cmd.CallbackUserData = nullptr; draw->CmdBuffer.push_back(cmd); ``` The backend invokes this callback instead of issuing a regular draw call, providing full control over GPU state for custom textures or shaders. ## Summary - **ImDrawList** serves as the core render-command collector in Dear ImGui, owned by each window and aggregated into `ImDrawData` at frame end. - Each draw list maintains **vertex buffers**, **index buffers**, and a **command buffer** (`CmdBuffer`) that stores `ImDrawCmd` structures describing GPU operations. - The **`_ResetForNewFrame`** method clears buffers and initializes the command state, while **`_TryMergeDrawCmds`** optimizes performance by merging compatible commands. - **ImDrawListSplitter** enables temporary channel separation for complex layering scenarios like table columns. - Developers can access draw lists via **`ImGui::GetWindowDrawList()`** to inject custom geometry using high-level helpers like `AddLine` or low-level primitives like `PrimWriteVtx`. - **Custom callbacks** allow insertion of arbitrary GPU code within the draw command sequence for advanced rendering effects. ## Frequently Asked Questions ### How do I access the draw list for the current window in Dear ImGui? Call `ImGui::GetWindowDrawList()` to obtain a pointer to the active window's `ImDrawList` instance. This function returns the draw list currently being populated during the frame, allowing you to add custom primitives, lines, or text that render as part of that window. ### What is the difference between ImDrawList and ImDrawData? An `ImDrawList` represents the command and geometry buffers for a single window or layer, while `ImDrawData` is a container that aggregates all draw lists at frame end. The backend receives `ImDrawData` via `ImGui::GetDrawData()` and iterates through its collection of draw lists to execute the final rendering commands. ### How does Dear ImGui optimize GPU draw calls using draw lists? Dear ImGui implements command merging through `ImDrawList::_TryMergeDrawCmds()`, which automatically combines consecutive `ImDrawCmd` entries that share identical clip rectangles, texture IDs, and vertex offsets. This optimization reduces the number of expensive GPU state changes and draw calls issued by the backend. ### Can I render meshes larger than 65,536 vertices with Dear ImGui draw lists? Yes, when the backend supports `ImGuiBackendFlags_RendererHasVtxOffset`, you can enable `ImDrawListFlags_AllowVtxOffset` on the draw list. This allows the `VtxOffset` field in `ImDrawCmd` to exceed zero, bypassing the 16-bit index limit and supporting arbitrarily large meshes without index buffer overflow.