Examples: Documentation
This commit is contained in:
omar
parent
06aa9d8d9a
commit
24fc7c30dd
@ -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:
|
||||
|
||||
|
||||
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
|
||||
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.
|
||||
This is essentially what the example bindings in this folder are providing + obligatory portability cruft.
|
||||
|
||||
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).
|
||||
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!
|
||||
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.
|
||||
|
||||
|
||||
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,
|
||||
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_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).
|
||||
|
||||
directx9_example/
|
||||
DirectX9 example, Windows only.
|
||||
= main.cpp + imgui_impl_glfw.cpp + imgui_impl_opengl3.cpp
|
||||
|
||||
directx10_example/
|
||||
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.
|
||||
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
|
||||
|
||||
2
imgui.h
2
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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user