mirrors/imgui
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Moving backends code from examples/ to backends/ (step 4: update documentation, much improvement)

Browse Source
This commit is contained in:
ocornut 2020-10-12 18:57:04 +02:00
parent a7e21fb05f
commit a2d845f9dd
3 changed files with 252 additions and 146 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

154
backends/README.txt Normal file
View File

@ -0,0 +1,154 @@
-----------------------------------------------------------------------
dear imgui, v1.80 WIP
Backends
-----------------------------------------------------------------------
(See docs/ and examples/ for more documentation)
-----------------------------------------------------------------------
This folder contains backends for popular platforms/graphics API, which you can use in
your application or engine to easily integrate Dear ImGui.
- The 'Platform' backends are in charge of: mouse/keyboard/gamepad inputs, cursor shape, timing, windowing.
e.g. Windows (imgui_impl_win32.cpp), GLFW (imgui_impl_glfw.cpp), SDL2 (imgui_impl_sdl.cpp), etc.
- The 'Renderer' backends are in charge of: creating atlas texture, rendering imgui draw data.
e.g. DirectX11 (imgui_impl_dx11.cpp), OpenGL/WebGL (imgui_impl_opengl3.cpp), Vulkan (imgui_impl_vulkan.cpp), etc.
- For some high-level frameworks, a single backend usually handle both 'Platform' and 'Renderer' parts.
e.g. Allegro 5 (imgui_impl_allegro5.cpp), Marmalade (imgui_impl_marmalade5.cpp).
An application usually combines 1 Platform backend + 1 Renderer backend + main ImGui sources.
For example, the example_win32_directx11/ application combines imgui_impl_win32.cpp + imgui_impl_dx11.cpp.
See examples/README.txt for details.
---------------------------------------
WHAT ARE BACKENDS?
---------------------------------------
Dear ImGui is highly portable and only requires a few things to run and render, typically:
- Required: providing mouse/keyboard inputs.
- Required: uploading the font atlas texture into graphics memory.
- Required: rendering indexed textured triangles with a clipping rectangle.
Extra features are opt-in, our backends try to support as many as possible:
- Optional: custom texture binding support.
- Optional: clipboard support.
- Optional: gamepad support.
- Optional: mouse cursor shape support.
- Optional: IME support.
- Optional: multi-viewports support.
etc.
This is essentially what the backends 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 backends which we are describing here (backends/ folder).
- Some issues may only be backend or platform specific.
- You should be able to write backends for pretty much any platform and any 3D graphics API.
e.g. get creative and have your backend perform rendering remotely, on a different machine
than the one running Dear ImGui, etc.
-----------------------------------------------------------------------
USING A CUSTOM ENGINE?
-----------------------------------------------------------------------
You will likely be tempted to start by rewrite your own backend using your own custom/high-level facilities...
Think twice!
If you are new to Dear ImGui, first try using the existing backends as-is.
You will save lots of time integrating the library.
You can LATER decide to rewrite yourself a custom backend if you really need to.
In most situations, custom backends have less features and more bugs than the standard backends we provide.
If you want portability, you can use multiple backends and choose between them either at compile time
or at runtime.
Example A: your engine is built over Windows + DirectX11 but you have your own high-level rendering
system layered over DirectX11.
- Suggestion: try using imgui_impl_win32.cpp + imgui_impl_dx11.cpp first.
Once it works, if you really need it you can replace the imgui_impl_dx11.cpp code with a
custom renderer using your own rendering functions, and keep using the standard Win32 code etc.
Example B: your engine runs on Windows, Mac, Linux and uses DirectX11, Metal, Vulkan respectively.
- Suggestion: use multiple generic backends!
Once it works, if you really need it you can replace parts of backends with your own abstractions.
Example C: your engine runs on platforms we can't provide public backends for (e.g. PS4/PS5, Switch),
and you have high-level systems everywhere.
- Suggestion: try using a non-portable backend first (e.g. win32 + underlying graphics API) to get
your desktop builds working first. This will get you running faster and get your acquainted with
how Dear ImGui works and is setup. You can then rewrite a custom backend using your own engine API.
Also:
The multi-viewports feature of the 'docking' branch allows Dear ImGui windows to be seamlessly detached
from the main application window. This is achieved using an extra layer to the Platform and Renderer
backends, which allows Dear ImGui to communicate platform-specific requests.
Supporting the multi-viewports feature correctly using 100% of your own abstractions is more difficult
than supporting single-viewport.
If you decide to use unmodified imgui_impl_xxxx.cpp files, you can automatically benefit from
improvements and fixes related to viewports and platform windows without extra work on your side.
---------------------------------------
LIST OF BACKENDS
---------------------------------------
List of Platforms Backends in this repository:
imgui_impl_glfw.cpp ; GLFW (Windows, macOS, Linux, etc.) http://www.glfw.org/
imgui_impl_osx.mm ; macOS native API (not as feature complete as glfw/sdl backends)
imgui_impl_sdl.cpp ; SDL2 (Windows, macOS, Linux, iOS, Android) https://www.libsdl.org
imgui_impl_win32.cpp ; Win32 native API (Windows)
imgui_impl_glut.cpp ; GLUT/FreeGLUT (absolutely not recommended in 2020!)
List of Renderer Backends in this repository:
imgui_impl_dx9.cpp ; DirectX9
imgui_impl_dx10.cpp ; DirectX10
imgui_impl_dx11.cpp ; DirectX11
imgui_impl_dx12.cpp ; DirectX12
imgui_impl_metal.mm ; Metal (with ObjC)
imgui_impl_opengl2.cpp ; OpenGL 2 (legacy, fixed pipeline <- don't use with modern OpenGL context)
imgui_impl_opengl3.cpp ; OpenGL 3/4, OpenGL ES 2, OpenGL ES 3 (modern programmable pipeline)
imgui_impl_vulkan.cpp ; Vulkan
Emscripten is also supported.
The example_emscripten/ app uses imgui_impl_sdl.cpp + imgui_impl_opengl3.cpp, but other combos are possible.
List of high-level Frameworks Backends in this repository: (combine Platform + Renderer)
imgui_impl_allegro5.cpp
imgui_impl_marmalade.cpp
Backends for third-party frameworks, graphics API or other programming languages:
https://github.com/ocornut/imgui/wiki/Bindings
(AGS/Adventure Game Studio, Amethyst, bsf, Cinder, Cocos2d-x, Diligent Engine, Flexium,
GML/Game Maker Studio2, GTK3+OpenGL3, Irrlicht Engine, LÖVE+LUA, Magnum, NanoRT, Nim Game Lib,
Ogre, openFrameworks, OSG/OpenSceneGraph, Orx, px_render, Qt/QtDirect3D, SFML, Sokol,
Unreal Engine 4, vtk, Win32 GDI, etc.)
---------------------------------------
RECOMMENDED BACKENDS
---------------------------------------
Recommended platform/frameworks for portable applications:
Library: GLFW
Webpage: https://github.com/glfw/glfw
Backend: imgui_impl_glfw.cpp
Library: SDL2
Webpage: https://www.libsdl.org
Backend: imgui_impl_sdl.cpp
Library: Sokol (lower-level than GLFW/SDL)
Webpage: https://github.com/floooh/sokol
Backend: Use util/sokol_imgui.h in Sokol repository.

1
docs/CHANGELOG.txt
View File

@ -53,6 +53,7 @@ Breaking Changes:
Other Changes:
- Docs: Split Backends and Examples README and improved them.
- Docs: Consistently renamed all occurences of "binding" and "back-end" to "backend" in comments and docs.

243
examples/README.txt
View File

@ -1,33 +1,14 @@
-----------------------------------------------------------------------
dear imgui, v1.80 WIP
Examples applications
-----------------------------------------------------------------------
examples/README.txt
(This is the README file for the examples/ folder. See docs/ for more documentation)
(See docs/ and backends/ for more documentation)
-----------------------------------------------------------------------
Dear ImGui is highly portable and only requires a few things to run and render:
This folder contains example applications (standalone, ready-to-build) for variety of
platforms and graphics APIs. They all use standard backends from the backends/ folder.
- 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.
This is essentially what the example backends 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 backends which we are describing here (examples/ folder).
You should be able to write backends 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 backends 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 backends.
They are the in the XXXX_example/ sub-folders.
You can find binaries of some of those example applications at:
You can find Windows binaries for some of those example applications at:
http://www.dearimgui.org/binaries
@ -35,144 +16,72 @@ You can find binaries of some of those example applications at:
GETTING STARTED
---------------------------------------
- Please read 'PROGRAMMER GUIDE' in imgui.cpp for notes on how to setup Dear ImGui in your codebase.
Please read the comments and instruction at the top of each file.
Please read FAQ at http://www.dearimgui.org/faq
Integration in a typical existing application, should take <20 lines when using standard backends.
- If you are using of the backend provided here, you can add 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.
At initialization:
call ImGui::CreateContext()
call ImGui_ImplXXXX_Init() for each backend.
- Dear ImGui has no particular extra lag for most behaviors, e.g. the value of 'io.MousePos' provided in
NewFrame() will result at the time of EndFrame()/Render() in a moved windows rendered following that mouse
movement. At 60 FPS your experience should be pleasant.
However, consider that OS mouse cursors are typically drawn through a very specific hardware accelerated
path and will feel smoother than the majority of contents rendererd via regular graphics API (including,
but not limited to Dear ImGui windows). Because UI rendering and interaction happens on the same plane as
the mouse, that disconnect may be jarring to particularly sensitive users.
You may experiment with enabling the io.MouseDrawCursor flag to request Dear ImGui to draw a mouse cursor
using the regular graphics API, to help you visualize the difference between a "hardware" cursor and a
regularly rendered software cursor.
However, rendering a mouse cursor at 60 FPS will feel sluggish so you likely won't want to enable that at
all times. It might be beneficial for 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 display lag depending on their settings.
If you feel that dragging windows feels laggy and you are not sure what the cause is: try to build a simple
drawing a flat 2D shape directly under the mouse cursor.
At the beginning of your frame:
call ImGui_ImplXXXX_NewFrame() for each backend.
call ImGui::NewFrame()
At the end of your frame:
call ImGui::Render()
call ImGui_ImplXXXX_RenderDrawData() for your Renderer backend.
---------------------------------------
EXAMPLE BACKENDS
---------------------------------------
At shutdown:
call ImGui_ImplXXXX_Shutdown() for each backend.
call ImGui::DestroyContext()
Most the example backends are split in 2 parts:
Example (using backends/imgui_impl_win32.cpp + backends/imgui_impl_dx11.cpp):
- The "Platform" backends, 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_sdl.cpp), etc.
// Create a Dear ImGui context, setup some options
ImGui::CreateContext();
ImGuiIO& io = ImGui::GetIO();
io.ConfigFlags |= ImGuiConfigFlags_NavEnableKeyboard; // Enable some options
// Initialize Platform + Renderer backends (here: using imgui_impl_win32.cpp + imgui_impl_dx11.cpp)
ImGui_ImplWin32_Init(my_hwnd);
ImGui_ImplDX11_Init(my_d3d_device, my_d3d_device_context);
// Application main loop
while (true)
{
// Beginning of frame: update Renderer + Platform backend, start Dear ImGui frame
ImGui_ImplDX11_NewFrame();
ImGui_ImplWin32_NewFrame();
ImGui::NewFrame();
// Any application code here
ImGui::Text("Hello, world!");
// End of frame: render Dear ImGui
ImGui::Render();
ImGui_ImplDX11_RenderDrawData(ImGui::GetDrawData());
- The "Renderer" backends, 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), etc.
// Swap
g_pSwapChain->Present(1, 0);
}
- The example _applications_ usually combine 1 platform + 1 renderer backend to create a working program.
Examples: the example_win32_directx11/ application combines imgui_impl_win32.cpp + imgui_impl_dx11.cpp.
// Shutdown
ImGui_ImplDX11_Shutdown();
ImGui_ImplWin32_Shutdown();
ImGui::DestroyContext();
- Some backends 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).
Please read 'PROGRAMMER GUIDE' in imgui.cpp for notes on how to setup Dear ImGui in your codebase.
Please read the comments and instruction at the top of each file.
Please read FAQ at http://www.dearimgui.org/faq
- If you use your own engine, you may decide to use some of existing backends and/or rewrite some using
your own API. As a recommendation, if you are new to Dear ImGui, try using the existing backend 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 backends 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 backend 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.
- Road-map: Dear ImGui 1.80 (WIP currently in the "docking" branch) will allows imgui windows to be
seamlessly detached from the main application window. This is achieved using an extra layer to the
platform and renderer backends, which allows Dear ImGui to communicate platform-specific requests.
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.
List of Platforms Backends in this repository:
imgui_impl_glfw.cpp ; GLFW (Windows, macOS, Linux, etc.) http://www.glfw.org/
imgui_impl_osx.mm ; macOS native API (not as feature complete as glfw/sdl backends)
imgui_impl_sdl.cpp ; SDL2 (Windows, macOS, Linux, iOS, Android) https://www.libsdl.org
imgui_impl_win32.cpp ; Win32 native API (Windows)
imgui_impl_glut.cpp ; GLUT/FreeGLUT (absolutely not recommended in 2020!)
List of Renderer Backends in this repository:
imgui_impl_dx9.cpp ; DirectX9
imgui_impl_dx10.cpp ; DirectX10
imgui_impl_dx11.cpp ; DirectX11
imgui_impl_dx12.cpp ; DirectX12
imgui_impl_metal.mm ; Metal (with ObjC)
imgui_impl_opengl2.cpp ; OpenGL 2 (legacy, fixed pipeline <- don't use with modern OpenGL context)
imgui_impl_opengl3.cpp ; OpenGL 3/4, OpenGL ES 2, OpenGL ES 3 (modern programmable pipeline)
imgui_impl_vulkan.cpp ; Vulkan
List of high-level Frameworks Backends in this repository: (combine Platform + Renderer)
imgui_impl_allegro5.cpp
imgui_impl_marmalade.cpp
Note that Dear ImGui works with Emscripten. The examples_emscripten/ app uses imgui_impl_sdl.cpp and
imgui_impl_opengl3.cpp, but other combinations are possible.
Third-party framework, graphics API and languages backends are listed at:
https://github.com/ocornut/imgui/wiki/Bindings
Including backends for:
AGS/Adventure Game Studio, Amethyst, bsf, Cinder, Cocos2d-x, Diligent Engine, Flexium,
GML/Game Maker Studio2, GTK3+OpenGL3, Irrlicht Engine, LÖVE+LUA, Magnum, NanoRT, Nim Game Lib,
Ogre, openFrameworks, OSG/OpenSceneGraph, Orx, px_render, Qt/QtDirect3D, SFML, Sokol,
Unreal Engine 4, vtk, Win32 GDI, etc.
Not sure which to use?
Recommended platform/frameworks:
GLFW https://github.com/glfw/glfw Use imgui_impl_glfw.cpp
SDL2 https://www.libsdl.org Use imgui_impl_sdl.cpp
Sokol https://github.com/floooh/sokol Use util/sokol_imgui.h in Sokol repository.
Those will allow you to create portable applications and will solve and abstract away many issues.
If you are using of the backend provided here, you can add the backends/imgui_impl_xxxx(.cpp,.h)
files to your project and use as-in. Each imgui_impl_xxxx.cpp file comes with its own individual
Changelog, so if you want to update them later it will be easier to catch up with what changed.
---------------------------------------
EXAMPLE APPLICATIONS
---------------------------------------
Building:
Unfortunately in 2020 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 we choose to provide:
- Makefiles for Linux/OSX
- Batch files for Visual Studio 2008+
- A .sln project file for Visual Studio 2012+
- Xcode project files for the Apple examples
Please let us 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.
If you are interested in using Cmake to build and links examples, see:
https://github.com/ocornut/imgui/pull/1713 and https://github.com/ocornut/imgui/pull/3027
example_allegro5/
Allegro 5 example.
= main.cpp + imgui_impl_allegro5.cpp
@ -290,3 +199,45 @@ example_win32_directx12/
DirectX12 example, Windows only.
= main.cpp + imgui_impl_win32.cpp + imgui_impl_dx12.cpp
This is quite long and tedious, because: DirectX12.
---------------------------------------
MISCELLANEOUS
---------------------------------------
Building:
Unfortunately in 2020 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 we choose to provide:
- Makefiles for Linux/OSX
- Batch files for Visual Studio 2008+
- A .sln project file for Visual Studio 2012+
- Xcode project files for the Apple examples
Please let us 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.
If you are interested in using Cmake to build and links examples, see:
https://github.com/ocornut/imgui/pull/1713 and https://github.com/ocornut/imgui/pull/3027
Things feeling laggy?
Dear ImGui has no particular extra lag for most behaviors,
e.g. the value of 'io.MousePos' provided at the time of NewFrame() will result in windows being moved
to the right spot at the time of EndFrame()/Render(). At 60 FPS your experience should be pleasant.
However, consider that OS mouse cursors are typically drawn through a very specific hardware accelerated
path and will feel smoother than the majority of contents rendered via regular graphics API (including,
but not limited to Dear ImGui windows). Because UI rendering and interaction happens on the same plane
as the mouse, that disconnect may be jarring to particularly sensitive users.
You may experiment with enabling the io.MouseDrawCursor flag to request Dear ImGui to draw a mouse cursor
using the regular graphics API, to help you visualize the difference between a "hardware" cursor and a
regularly rendered software cursor.
However, rendering a mouse cursor at 60 FPS will feel sluggish so you likely won't want to enable that at
all times. It might be beneficial for 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 display lag depending on their settings.
If you feel that dragging windows feels laggy and you are not sure what the cause is: try to build a simple
drawing a flat 2D shape directly under the mouse cursor!