-
-
Notifications
You must be signed in to change notification settings - Fork 10.3k
Glossary
(work in progress)
Backends/Bindings: a piece of code that connects your OS/platform/windowing system, graphics API or programming language to Dear ImGui. In the examples/ folder we provide a bunch of imgui_impl_xxxx files which are backends for variety of platforms and graphics API. Many other third-party bindings exists.
Demo: the demo code in imgui_demo.cpp, which main entry point is the ImGui::ShowDemoWindow() function.
Docking: refer to the feature (currently available in the docking branch) where multiple windows can be combined with each others, creating tab bars, or layed out next to each others.
Draw command, ImDrawCmd: refer to one item within an ImDrawList. One draw command generally map to one draw call in the underlying graphics API. Some draw commands hold callbacks or special functions that don't necessarily map to an actual draw call in the graphics API.
Draw list, ImDrawList: refer to the low-level rendering API which you can use to submit shapes (such as rectangles, lines, circles or text elements). The ImGui API uses the ImDrawList API to draw elements. You can easily access the drawlist of the current ImGui window using ImGui::GetWindowDrawList() or access special drawlists such as ImGui::GetBackgroundDrawList() (drawn before every ImGui windows) or ImGui::GetForegroundDrawList() (drawn after every ImGui windows). A draw list is generally comprised of multi draw commands.
Examples: examples application in the sub-folders of examples/. An example application generally combines one or two backends + dear imgui code + a main.cpp file to form a running application.
Font atlas: a font atlas manage multiple fonts, which for performance reasons are generally rasterized and packed together into a single graphics texture. The font atlas also contains graphics data that are used by ImGui and ImDrawList.
Item: (same as Widget): a single ImGui element (e.g. a ImGui::Button() or ImGui::Text() call).
Navigation: refer to the subsystem in charge of allowing full control of the UI using Gamepad or Keyboard inputs. Initially Dear ImGui was mostly using mouse inputs and the "navigation" feature allowed directional navigation within a set of widgets.
Metrics: refer to the confusingly named Dear ImGui Metrics window, which main entry point is the ImGui::ShowMetricsWindow() function. The Metrics window exposes lots of internal information about the state of your Dear ImGui context. Using it can help you debug and understand many problems you may have with Dear ImGui. It may also help you better understand how Dear ImGui works.
Multi-Viewports: refer to the feature (currently available in the docking branch) where Dear ImGui window can easily be moved outside the boundaries of your main application window. The multi-viewports feature provides an interface to interact with bindings in order to create its own application windows to host the floating Dear ImGui windows.
Widgets: (same as Item): a single ImGui element (e.g. a ImGui::Button() or ImGui::Text() call).
Docking: refer to the Docking subsystem as a whole, or to the action of Docking one Window or Dock Node into another Window or Dock Node.
Dock Node: carry a Tab Bar + zero or more Windows or child dock nodes. A Dock Node can be either Floating Dock Node or a Dockspace. Dock Node are hosted by their Host Window.
Dockspace: a dock node whose Host Window has been created by the user. This imply that the position and size of the dock node is not controlled by the Docking system. This also imply that the lifetime of the dock node is not controlled by the Docking system.
Dock Node Hierarchy: a dock node and all its child dock nodes.
Floating Dock Node: a dock node whose Host Window is automatically created and managed by the Docking system. They are generally freely moveable.
Root Dock Node: a dock node that has no parent dock node.
Leaf Dock Node: a dock node that that no child dock nodes.
Host Window: the Window used to display docking decorations (Tab Bar, Close Button). In a Dock Node Hierarchy sitting over a Dockspace, the Host Window is always the window where the Dockspace was submitted. In a Dock Node Hierarchy sitting over a Floating Window, the Host Window is created thee Docking system.
Note: when talking about issues related to the multi-viewports feature, always try to remove ambiguity by specifying e.g. "Dear ImGui Window" vs "Platform Window".
Desktop: the area managed by the Operating System or Window Manager and covers all Platform Monitors.
Platform: refer to the low-level system used to interface with native windows: it could be an Operating System library (Win32) or a cross-platform library (such as SDL, GLFW, Allegro).
Platform Backend: refer to the piece of glue code used to have Dear ImGui interact with a given platform (e.g. imgui_impl_glfw.cpp file). This code typically creates and destroy Platform Windows associated to each Viewport, and setup the Platform Decorations based on Viewport flags.
Platform Decoration: refer to the frame and title bar managed and displayed by the Operating System or Window Manager.
Platform Monitor: refer to the representation of a monitor. On a modern OS, each monitor are associated to a non-overlapping set of coordinates (position, size), a work area (main area minus OS task bar) and a DPI scaling factor. Dear ImGui takes advantage of Platform Monitor knowledge for certain tasks (for exemple, tooltip windows gets clamped to fit within a single Platform Monitor and not straddle multiple monitors, new popups try to not overlap the OS task-bar).
Platform Window: a window managed by the Operating System. This is typically associated to a framebuffer, a swap chain and the machinery to perform 3D rendering via some graphics API.
ImGui Decoration: refer to the frame and title bar managed and displayed by ImGui Windows.
ImGui Window: a window managed by Dear ImGui. For the purpose of multi-viewports, we often use "ImGui Window" to refer to top-level ImGui Window only, not child or docked windows.
Host Viewport: A Host Viewport can contains multiple ImGui Windows. Currently the Main Viewport is always a Host Viewport. In the future we would like to allow application to create 0, 1 or more Host Viewports. When a Host Viewport is moved, all the ImGui Windows it contains gets moved along with it. By default, any ImGui Window overlapping a Host Viewport will be merged into it. Setting io.ConfigViewportsNoAutoMerge disable that behavior, so every ImGui Window will be hosted by their own unique Single-Window Viewport.
Single-Window Viewport, Owned Viewport: a Viewport owned by a single ImGui Window. In the typical setup, dragging a ImGui Window outside the boundaries of a Host Viewport will create a Single-Window Viewport for the purpose of allowing the ImGui Window to be displayed anywhere on the Desktop.
Main Viewport: Due to common usage and backward compatibility reason, the system currently enforce the creation of one Main Viewport which is typically the main application window created by the user application. The Main Viewport is also a Host Viewport. In most traditional application, the Main Viewport has Platform Decorations enabled when not maximized, and has Platform Decorations disabled when fullscreen. In the future we would like to completely remove the concept of a "Main Viewport" and instead allow the application to freely create 0, 1 or more Host Viewports. Most games applications will create 1 of them, whereas most desktopey applications are expected to create 0 of them. Using this scheme, an application creating no Host Viewport would have every ImGui Window showing inside an individual Platform Window with Platform Decorations disabled. It would become the application responsability to shutdown when all the windows are closed.
Viewport: The Dear ImGui representation of a Platform Window. When a Viewport is active, Dear ImGui creates a Platform Window for it. Whether the Platform Window has Platform Decorations enabled currently depends on the io.ConfigViewportsNoDecoration flag which gets turned into a ImGuiViewportFlags_NoDecoration for the Platform Backend to honor.