Examples: Documentation

examples/README.txt

@@ -1,108 +1,229 @@
-Those are standalone ready-to-build applications to demonstrate Dear ImGui.
+---------------------------------------
-Binaries of some of those demos: http://www.miracleworld.net/imgui/binaries
+ README FIRST
+---------------------------------------
 
-Third party languages and frameworks bindings: 
+Dear ImGui is highly portable and only requires a few things to run and render:
-  https://github.com/ocornut/imgui/wiki/Links
-(languages: C, C#, ChaiScript, D, Go, Haxe, Odin, Python, Rust, Lua, Pascal)
-(other frameworks: OpenGLES, FreeGlut, Cinder, Cocos2d-x, SFML, GML/GameMaker Studio, Irrlicht,
- Ogre, OpenSceneGraph, openFrameworks, LOVE, NanoRT, Qt3d, SFML, Unreal Engine 4, etc.)
-(extras: RemoteImGui, ImWindow, imgui_wm, etc.)
 
-
-TL;DR; 
- - Newcomers, read 'PROGRAMMER GUIDE' in imgui.cpp for notes on how to setup ImGui in your codebase.
- - If you are using of the backend provided here, so you can copy the imgui_impl_xxx.cpp/h files
-   to your project and use them unmodified.
- - To LEARN how to setup imgui, you may refer to 'opengl2_example' because is the simplest one to read.
-   However, do NOT USE the 'opengl2_example' if your code is using any modern GL3+ calls.
-   Mixing old fixed-pipeline OpenGL2 and modern OpenGL3+ is going to make everything more complicated.
-   Read comments below for details. If you are not sure, in doubt, use 'opengl3_example'.
- - If you have your own engine, you probably want to read a few of the examples first then adapt it to
-   your engine. Please note that if your engine is based on OpenGL/DirectX you can perfectly use the
-   existing rendering backends, don't feel forced to rewrite them with your own engine API, or you can
-   do that later when you already got things to work.
-
-Dear ImGui is highly portable and only requires a few things to run and render.
  - Providing mouse/keyboard inputs
- - Load the font atlas texture into graphics memory
+ - Uploading the font atlas texture into graphics memory
  - Providing a render function to render indexed textured triangles
  - Optional: clipboard support, mouse cursor supports, Windows IME support, etc.
-So this is essentially what those examples are doing + the obligatory cruft for portability.
+ - Optional (Advanced,Beta): platform window API to use multi-viewport.
 
-Unfortunately in 2018 it is still tedious to create and maintain portable build files using external 
+This is essentially what the example bindings in this folder are providing + obligatory portability cruft.
-libraries (the kind we're using here to create a window and render 3D triangles) without relying on 
+
-third party software. For most examples here I choose to provide:
+It is important to understand the difference between the core Dear ImGui library (files in the root folder)
+and examples bindings which we are describing here (examples/ folder).
+You should be able to write bindings for pretty much any platform and any 3D graphics API. With some extra
+effort you can even perform the rendering remotely, on a different machine than the one running the logic.
+
+This folder contains two things:
+
+ - Example bindings for popular platforms/graphics API, which you can use as is or adapt for your own use.
+   They are the imgui_impl_XXXX files found in the examples/ folder.
+
+ - Example applications (standalone, ready-to-build) using the aforementioned bindings.
+   They are the in the XXXX_example/ sub-folders.
+
+You can find binaries of some of those example applications at: 
+  http://www.miracleworld.net/imgui/binaries
+
+
+---------------------------------------
+ MISC COMMENTS AND SUGGESTIONS
+---------------------------------------
+
+ - Newcomers, read 'PROGRAMMER GUIDE' in imgui.cpp for notes on how to setup ImGui in your codebase.
+
+ - Please read the comments and instruction at the top of each file.
+
+ - If you are using of the backend provided here, so you can copy the imgui_impl_xxx.cpp/h files
+   to your project and use them unmodified. Each imgui_impl_xxxx.cpp comes with its own individual
+   ChangeLog at the top of the .cpp files, so if you want to update them later it will be easier to
+   catch up with what changed.
+
+ - To LEARN how to setup imgui, you may refer to 'opengl2_example/' because is the simplest one to read.
+   However, do NOT USE the OpenGL2 renderer if your code is using any modern GL3+ calls.
+   Mixing old fixed-pipeline OpenGL2 and modern OpenGL3+ is going to make everything more complicated.
+   Read comments below for details. If you are not sure, in doubt, use the OpenGL3 renderer.
+
+ - Dear ImGui has 0 to 1 frame of lag for most behaviors, at 60 FPS your experience should be pleasant.
+   However, consider that OS mouse cursors are typically drawn through a specific hardware accelerated path
+   and will feel smoother than common GPU rendered contents (including Dear ImGui windows). 
+   You may experiment with the io.MouseDrawCursor flag to request ImGui to draw a mouse cursor itself, 
+   to visualize the lag between a hardware cursor and a software cursor. However, rendering a mouse cursor
+   at 60 FPS will feel slow. It might be beneficial to the user experience to switch to a software rendered
+   cursor only when an interactive drag is in progress. 
+   Note that some setup or GPU drivers are likely to be causing extra lag depending on their settings.
+   If you are not sure who to blame if you feeling that dragging something is laggy, try to build an
+   application drawing a shape directly under the mouse cursor. 
+
+
+---------------------------------------
+ EXAMPLE BINDINGS
+---------------------------------------
+
+Most the example bindings are split in 2 parts:
+
+ - The "Platform" bindings, in charge of: mouse/keyboard/gamepad inputs, cursor shape, timing, windowing.
+   Examples: Windows (imgui_impl_win32.cpp), GLFW (imgui_impl_glfw.cpp), SDL2 (imgui_impl_sdl2.cpp)
+
+ - The "Renderer" bindings, in charge of: creating the main font texture, rendering imgui draw data.
+   Examples: DirectX11 (imgui_impl_dx11.cpp), GL3 (imgui_impl_opengl3.cpp), Vulkan (imgui_impl_vulkan.cpp)
+
+ - The example _applications_ usually combine 1 platform + 1 renderer binding to create a working program.
+   Examples: the directx11_example/ application combines imgui_impl_win32.cpp + imgui_impl_dx11.cpp.
+
+ - Some bindings for higher level frameworks carry both "Platform" and "Renderer" parts in one file.
+   This is the case for Allegro 5 (imgui_impl_allegro5.cpp), Marmalade (imgui_impl_marmalade5.cpp).
+
+ - If you use your own engine, you may decide to use some of existing bindings and/or rewrite some using 
+   your own API. As a recommendation, if you are new to Dear ImGui, try using the existing binding as-is
+   first, before moving on to rewrite some of the code. Although it is tempting to rewrite both of the 
+   imgui_impl_xxxx files to fit under your coding style, consider that it is not necessary!
+   In fact, if you are new to Dear ImGui, rewriting them will almost always be harder.
+
+   Example: your engine is built over Windows + DirectX11 but you have your own high-level rendering system 
+   layered over DirectX11.
+     Suggestion: step 1: try using imgui_impl_win32.cpp + imgui_impl_dx11.cpp first. 
+     Once this work, _if_ you want you can replace the imgui_impl_dx11.cpp code with a custom renderer 
+     using your own functions, etc. 
+     Please consider using the bindings to the lower-level platform/graphics API as-is.
+
+   Example: your engine is multi-platform (consoles, phones, etc.), you have high-level systems everywhere.
+     Suggestion: step 1: try using a non-portable binding first (e.g. win32 + underlying graphics API)!
+     This is counter-intuitive, but this will get you running faster! Once you better understand how imgui
+     works and is bound, you can rewrite the code using your own systems.
+
+ - From Dear ImGui 1.XX we added an (optional) feature called "viewport" which allows imgui windows to be 
+   seamlessly detached from the main application window. This is achieved using an extra layer to the 
+   platform and renderer bindings, which allows imgui to communicate platform-specific requests such as 
+   "create an additional OS window", "create a render context", "get the OS position of this window" etc. 
+   When using this feature, the coupling with your OS/renderer becomes much tighter than a regular imgui 
+   integration. It is also much more complicated and require more work to integrate correctly.
+   If you are new to imgui and you are trying to integrate it into your application, first try to ignore
+   everything related to Viewport and Platform Windows. You'll be able to come back to it later!
+   Note that if you decide to use unmodified imgui_impl_xxxx.cpp files, you will automatically benefit from 
+   improvements and fixes related to viewports and platform windows without extra work on your side.
+   See 'ImGuiPlatformIO' for details.  
+
+List of officially maintained Platforms Bindings:
+
+    imgui_impl_glfw.cpp
+    imgui_impl_sdl2.cpp
+    imgui_impl_win32.cpp
+
+List of officially maintained Renderer Bindings:
+
+    imgui_impl_dx9.cpp
+    imgui_impl_dx10.cpp
+    imgui_impl_dx11.cpp
+    imgui_impl_dx12.cpp
+    imgui_impl_opengl2.cpp
+    imgui_impl_opengl3.cpp
+    imgui_impl_vulkan.cpp
+
+List of officially maintained high-level Frameworks Bindings (combine Platform + Renderer)
+
+    imgui_impl_allegro5.cpp
+    imgui_impl_marmalade.cpp
+
+Third-party framework, graphics API and languages bindings:
+
+    https://github.com/ocornut/imgui/wiki/Links
+
+    Languages: C, C#, ChaiScript, D, Go, Haxe, Java, Lua, Odin, Pascal, PureBasic, Python, Rust, Swift...
+    Frameworks: FreeGlut, Cinder, Cocos2d-x, Emscripten, SFML, GML/GameMaker Studio, Irrlicht, Ogre, 
+    OpenSceneGraph, openFrameworks, LOVE, NanoRT, Nim Game Lib, Qt3d, SFML, Unreal Engine 4...
+    Miscellaneous: Software Renderer, RemoteImgui, etc.
+
+
+---------------------------------------
+ EXAMPLE APPLICATIONS
+---------------------------------------
+
+Building:
+  Unfortunately in 2018 it is still tedious to create and maintain portable build files using external 
+  libraries (the kind we're using here to create a window and render 3D triangles) without relying on 
+  third party software. For most examples here I choose to provide:
    - Makefiles for Linux/OSX
    - Batch files for Visual Studio 2008+
    - A .sln project file for Visual Studio 2010+ 
-Please let me know if they don't work with your setup!
+  Please let me know if they don't work with your setup!
-You can probably just import the imgui_impl_xxx.cpp/.h files into your own codebase or compile those
+  You can probably just import the imgui_impl_xxx.cpp/.h files into your own codebase or compile those
-directly with a command-line compiler.
+  directly with a command-line compiler.
 
-Dear ImGui has zero to one frame of lag for most behaviors, at 60 FPS your experience should be pleasant.
-Consider that OS mouse cursors are typically drawn through a specific hardware accelerated route and may 
-feel smoother than other GPU rendered contents. You may experiment with the io.MouseDrawCursor flag to
-request ImGui to draw a mouse cursor itself, to visualize the lag between a hardware cursor and a software
-cursor. It might be beneficial to the user experience to switch to a software rendered cursor when an
-interactive drag is in progress. 
-Also note that some setup or GPU drivers may be causing extra lag (possibly by enforcing triple buffering),
-leaving you with little option but sadness (Intel GPU drivers were reported as such).
 
+directx9_example/
+    DirectX9 example, Windows only.
+    = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx9.cpp
+    
+directx10_example/
+    DirectX10 example, Windows only.
+    = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx10.cpp
+
+directx11_example/
+    DirectX11 example, Windows only.
+    = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx11.cpp
+    
+directx12_example/
+    DirectX12 example, Windows only.
+    This is quite long and tedious, because: DirectX12.
+    = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx12.cpp
 
 opengl2_example/
     **DO NOT USE THIS CODE IF YOUR CODE/ENGINE IS USING MODERN OPENGL (SHADERS, VBO, VAO, etc.)**
     **Prefer using the code in the opengl3_example/ folder**
     GLFW + OpenGL example (legacy, fixed pipeline).
-    This code is mostly provided as a reference to learn how ImGui integration works, because it is shorter.
+    This code is mostly provided as a reference to learn about ImGui integration, because it is shorter.
     If your code is using GL3+ context or any semi modern OpenGL calls, using this renderer is likely to
-    make things more complicated, will require your code to several OpenGL attributes to their initial state,
+    make things more complicated, will require your code to reset many OpenGL attributes to their initial
-    and might confuse your GPU driver. 
+    state, and might confuse your GPU driver. One star, not recommended.
+    = main.cpp + imgui_impl_glfw.cpp + imgui_impl_opengl2.cpp
 
 opengl3_example/
-    GLFW + OpenGL example (programmable pipeline, binding modern functions with GL3W).
+    GLFW (Win32, Mac, Linux) + OpenGL example (programmable pipeline, binding modern functions with GL3W).
     This uses more modern OpenGL calls and custom shaders. 
     Prefer using that if you are using modern OpenGL in your application (anything with shaders).
+    = main.cpp + imgui_impl_glfw.cpp + imgui_impl_opengl3.cpp
 	
-directx9_example/
+vulkan_example/
-    DirectX9 example, Windows only.
+    Vulkan example.
-	
+    This is quite long and tedious, because: Vulkan.
-directx10_example/
+    = main.cpp + imgui_impl_glfw.cpp + imgui_impl_vulkan.cpp
-    DirectX10 example, Windows only.
-    This is quite long and tedious, because: DirectX10.
-
-directx11_example/
-    DirectX11 example, Windows only.
-    This is quite long and tedious, because: DirectX11.
-	
-directx12_example/
-    DirectX12 example, Windows only.
-    This is quite longer and tedious, because: DirectX12.
-	
-apple_example/
-    OSX & iOS example.
-    On iOS, Using Synergy to access keyboard/mouse data from server computer.
-    Synergy keyboard integration is rather hacky.
 
 sdl_opengl2_example/
     **DO NOT USE THIS CODE IF YOUR CODE/ENGINE IS USING MODERN OPENGL (SHADERS, VBO, VAO, etc.)**
     **Prefer using the code in the sdl_opengl3_example/ folder**
-    SDL2 + OpenGL example (legacy, fixed pipeline).
+    SDL2 (Win32, Mac, Linux etc.) + OpenGL example (legacy, fixed pipeline).
-    This code is mostly provided as a reference to learn how ImGui integration works, because it is shorter.
+    This code is mostly provided as a reference to learn about ImGui integration, because it is shorter.
     If your code is using GL3+ context or any semi modern OpenGL calls, using this renderer is likely to
-    make things more complicated, will require your code to several OpenGL attributes to their initial state,
+    make things more complicated, will require your code to reset many OpenGL attributes to their initial
-    and might confuse your GPU driver. 
+    state, and might confuse your GPU driver. One star, not recommended. 
+    = main.cpp + imgui_impl_sdl2.cpp + imgui_impl_opengl2.cpp
 
 sdl_opengl3_example/
-    SDL2 + OpenGL3 example.
+    SDL2 (Win32, Mac, Linux, etc.) + OpenGL3 example.
     This uses more modern OpenGL calls and custom shaders. 
     Prefer using that if you are using modern OpenGL in your application (anything with shaders).
+    = main.cpp + imgui_impl_sdl2.cpp + imgui_impl_opengl3.cpp
+
+sdl_vulkan_example/
+    SDL2 (Win32, Mac, Linux, etc.) + Vulkan example.
+    This is quite long and tedious, because: Vulkan.
+    = main.cpp + imgui_impl_glfw.cpp + imgui_impl_vulkan.cpp
+
+apple_example/
+    OSX & iOS example + OpenGL2.
+    THIS EXAMPLE HAS NOT BEEN MAINTAINED PROPERLY AND NEEDS A MAINTAINER.
+    Consider using the opengl3_example/ instead.
+    On iOS, Using Synergy to access keyboard/mouse data from server computer.
+    Synergy keyboard integration is rather hacky.
 
 allegro5_example/
     Allegro 5 example.
+    = main.cpp + imgui_impl_allegro5.cpp
 
 marmalade_example/
     Marmalade example using IwGx
-    
+    = main.cpp + imgui_impl_marmalade.cpp
-vulkan_example/
-    Vulkan example.
-    This is quite longer and tedious, because: Vulkan.

imgui.h

@@ -1935,7 +1935,7 @@ struct ImGuiPlatformMonitor
     ImGuiPlatformMonitor() { MainPos = MainSize = WorkPos = WorkSize = ImVec2(0,0); DpiScale = 1.0f; }
 };
 
-// (Optional) Setup required only if (io.ConfigFlags & ImGuiConfigFlags_ViewportsEnable) is enabled
+// (Optional) Setup required only if (io.ConfigFlags & ImGuiConfigFlags_ViewportsEnable) is enabled. Access via ImGui::GetPlatformIO().
 // This is designed so we can mix and match two imgui_impl_xxxx files, one for the Platform (~window handling), one for Renderer.
 // Custom engine back-ends will often provide both Platform and Renderer interfaces and thus may not need to use all functions.
 // Platform functions are typically called before their Renderer counterpart, apart from Destroy which are called the other way.