From 1a69ecc06c47c9a478a5231d4473fcda391fae64 Mon Sep 17 00:00:00 2001 From: omar Date: Mon, 9 Dec 2019 19:58:25 +0100 Subject: [PATCH] Multi-viewport Glossary --- Glossary.md | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/Glossary.md b/Glossary.md index e918bc3..a330488 100644 --- a/Glossary.md +++ b/Glossary.md @@ -1,6 +1,6 @@ (work in progress) ----- +## General **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](https://github.com/ocornut/imgui/wiki/Bindings) exists. @@ -25,3 +25,31 @@ **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). + +## Multi-viewports Feature + +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 Widnow 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). + +**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 inside of Dear ImGui. + +**Host Viewport**: A _Host Viewport_ can contains multiple root _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 _Dear 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 root _ImGui Window_. In the typical setup, dragging a _ImGui Window_ outside the boundary 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. + +**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.