From 24fc7c30dd0761014c744d0027e83ce4941c061b Mon Sep 17 00:00:00 2001 From: omar Date: Thu, 7 Jun 2018 23:48:34 +0200 Subject: [PATCH] Examples: Documentation --- examples/README.txt | 267 ++++++++++++++++++++++++++++++++------------ imgui.h | 2 +- 2 files changed, 195 insertions(+), 74 deletions(-) diff --git a/examples/README.txt b/examples/README.txt index 171c3381..960c17d7 100644 --- a/examples/README.txt +++ b/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: - 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.) +Dear ImGui is highly portable and only requires a few things to run and render: + + - Providing mouse/keyboard inputs + - 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. + - Optional (Advanced,Beta): platform window API to use multi-viewport. + +This is essentially what the example bindings in this folder are providing + obligatory portability cruft. + +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 -TL;DR; +--------------------------------------- + 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. - - 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. + 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 '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. + Read comments below for details. If you are not sure, in doubt, use the OpenGL3 renderer. -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 - - 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. - -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! -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. - -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). + - 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. -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. - 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, - and might confuse your GPU driver. +--------------------------------------- + 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! + 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. -opengl3_example/ - GLFW + 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). directx9_example/ DirectX9 example, Windows only. - + = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx9.cpp + directx10_example/ DirectX10 example, Windows only. - This is quite long and tedious, because: DirectX10. + = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx10.cpp directx11_example/ DirectX11 example, Windows only. - This is quite long and tedious, because: DirectX11. - + = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx11.cpp + directx12_example/ DirectX12 example, Windows only. - This is quite longer and tedious, because: DirectX12. + 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 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 reset many OpenGL attributes to their initial + state, and might confuse your GPU driver. One star, not recommended. + = main.cpp + imgui_impl_glfw.cpp + imgui_impl_opengl2.cpp + +opengl3_example/ + 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 -apple_example/ - OSX & iOS example. - On iOS, Using Synergy to access keyboard/mouse data from server computer. - Synergy keyboard integration is rather hacky. +vulkan_example/ + Vulkan example. + This is quite long and tedious, because: Vulkan. + = main.cpp + imgui_impl_glfw.cpp + imgui_impl_vulkan.cpp 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). - This code is mostly provided as a reference to learn how ImGui integration works, because it is shorter. + SDL2 (Win32, Mac, Linux etc.) + OpenGL example (legacy, fixed pipeline). + 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, - and might confuse your GPU driver. + make things more complicated, will require your code to reset many OpenGL attributes to their initial + 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 - -vulkan_example/ - Vulkan example. - This is quite longer and tedious, because: Vulkan. + = main.cpp + imgui_impl_marmalade.cpp diff --git a/imgui.h b/imgui.h index a520c742..a953475f 100644 --- a/imgui.h +++ b/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.