mirror of
https://github.com/ocornut/imgui.git
synced 2026-01-11 00:04:24 +00:00
Moving backends code from examples/ to backends/ (step 6: update markdown documentation)
This commit is contained in:
ocornut
parent
a2a3d80f04
commit
b1a18d82e3
56 changed files with 395 additions and 360 deletions
188
docs/BACKENDS.md
188
docs/BACKENDS.md
|
|
@ -1,34 +1,28 @@
|
|||
-----------------------------------------------------------------------
|
||||
dear imgui, v1.80 WIP
|
||||
Backends
|
||||
-----------------------------------------------------------------------
|
||||
(See docs/ and examples/ for more documentation)
|
||||
-----------------------------------------------------------------------
|
||||
_(You may browse this at https://github.com/ocornut/imgui/blob/master/docs/BACKENDS.md or view this file with any Markdown viewer)_
|
||||
|
||||
This folder contains backends for popular platforms/graphics API, which you can use in
|
||||
your application or engine to easily integrate Dear ImGui.
|
||||
## Dear ImGui: Backends
|
||||
|
||||
- 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 backends/ folder contains backends for popular platforms/graphics API, which you can use in
|
||||
your application or engine to easily integrate Dear ImGui.** Each backend is typically self-contained in a pair of files: imgui_impl_XXXX.cpp + imgui_impl_XXXX.h.
|
||||
|
||||
- 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.
|
||||
- The 'Platform' backends are in charge of: mouse/keyboard/gamepad inputs, cursor shape, timing, windowing.<BR>
|
||||
e.g. Windows ([imgui_impl_win32.cpp](https://github.com/ocornut/imgui/blob/master/backends/imgui_impl_win32.cpp)), GLFW ([imgui_impl_glfw.cpp](https://github.com/ocornut/imgui/blob/master/backends/imgui_impl_glfw.cpp)), SDL2 ([imgui_impl_sdl.cpp](https://github.com/ocornut/imgui/blob/master/backends/imgui_impl_sdl.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).
|
||||
- The 'Renderer' backends are in charge of: creating atlas texture, rendering imgui draw data.<BR>
|
||||
e.g. DirectX11 ([imgui_impl_dx11.cpp](https://github.com/ocornut/imgui/blob/master/backends/imgui_impl_dx11.cpp)), OpenGL/WebGL ([imgui_impl_opengl3.cpp]((https://github.com/ocornut/imgui/blob/master/backends/imgui_impl_opengl3.cpp)), Vulkan ([imgui_impl_vulkan.cpp]((https://github.com/ocornut/imgui/blob/master/backends/imgui_impl_vulkan.cpp)), etc.
|
||||
|
||||
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.
|
||||
- For some high-level frameworks, a single backend usually handle both 'Platform' and 'Renderer' parts.<BR>
|
||||
e.g. Allegro 5 ([imgui_impl_allegro5.cpp](https://github.com/ocornut/imgui/blob/master/backends/imgui_impl_allegro5.cpp)), Marmalade ([imgui_impl_marmalade.cpp](https://github.com/ocornut/imgui/blob/master/backends/imgui_impl_marmalade.cpp)). If you end up creating a custom backend for your engine, you may want to do the same.
|
||||
|
||||
An application usually combines 1 Platform backend + 1 Renderer backend + main Dear ImGui sources.
|
||||
For example, the [example_win32_directx11](https://github.com/ocornut/imgui/tree/master/examples/example_win32_directx11) application combines imgui_impl_win32.cpp + imgui_impl_dx11.cpp. See [EXAMPLES.MD](https://github.com/ocornut/imgui/blob/master/docs/EXAMPLES.md) for details.
|
||||
|
||||
|
||||
---------------------------------------
|
||||
WHAT ARE BACKENDS?
|
||||
---------------------------------------
|
||||
### 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: providing mouse/keyboard inputs (fed into the `ImGuiIO` structure).
|
||||
- Required: uploading the font atlas texture into graphics memory.
|
||||
- Required: rendering indexed textured triangles with a clipping rectangle.
|
||||
|
||||
|
|
@ -42,62 +36,21 @@ Dear ImGui is highly portable and only requires a few things to run and render,
|
|||
- Optional: multi-viewports support.
|
||||
etc.
|
||||
|
||||
This is essentially what the backends in this folder are providing + obligatory portability cruft.
|
||||
This is essentially what each backends are doing + 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.
|
||||
e.g. you can get creative and use software rendering or render remotely on a different machine.
|
||||
|
||||
|
||||
-----------------------------------------------------------------------
|
||||
USING A CUSTOM ENGINE?
|
||||
-----------------------------------------------------------------------
|
||||
### List of backends
|
||||
|
||||
You will likely be tempted to start by rewrite your own backend using your own custom/high-level facilities...
|
||||
Think twice!
|
||||
In the [backends/](https://github.com/ocornut/imgui/blob/master/backends) folder:
|
||||
|
||||
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:
|
||||
List of Platforms Backends:
|
||||
|
||||
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)
|
||||
|
|
@ -105,7 +58,7 @@ List of Platforms Backends in this repository:
|
|||
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:
|
||||
List of Renderer Backends:
|
||||
|
||||
imgui_impl_dx9.cpp ; DirectX9
|
||||
imgui_impl_dx10.cpp ; DirectX10
|
||||
|
|
@ -116,39 +69,92 @@ List of Renderer Backends in this repository:
|
|||
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)
|
||||
List of high-level Frameworks Backends (combining Platform + Renderer):
|
||||
|
||||
imgui_impl_allegro5.cpp
|
||||
imgui_impl_marmalade.cpp
|
||||
|
||||
Backends for third-party frameworks, graphics API or other programming languages:
|
||||
Emscripten is also supported.
|
||||
The [example_emscripten](https://github.com/ocornut/imgui/tree/master/examples/example_emscripten) app uses imgui_impl_sdl.cpp + imgui_impl_opengl3.cpp, but other combos are possible.
|
||||
|
||||
https://github.com/ocornut/imgui/wiki/Bindings
|
||||
### Backends for third-party frameworks, graphics API or other languages
|
||||
|
||||
(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.)
|
||||
See 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
|
||||
- Unity
|
||||
- Unreal Engine 4
|
||||
- vtk
|
||||
- Win32 GDI
|
||||
etc.
|
||||
|
||||
|
||||
---------------------------------------
|
||||
RECOMMENDED BACKENDS
|
||||
---------------------------------------
|
||||
### Recommended Backends
|
||||
|
||||
Recommended platform/frameworks for portable applications:
|
||||
If you are not sure which backend to use, the recommended platform/frameworks for portable applications:
|
||||
|
||||
Library: GLFW
|
||||
Webpage: https://github.com/glfw/glfw
|
||||
Backend: imgui_impl_glfw.cpp
|
||||
|Library |Website |Backend |Note |
|
||||
|--------|--------|--------|-----|
|
||||
| GLFW | https://github.com/glfw/glfw | imgui_impl_glfw.cpp | |
|
||||
| SDL2 | https://www.libsdl.org | imgui_impl_sdl.cpp | |
|
||||
| Sokol | https://github.com/floooh/sokol | [util/sokol_imgui.h](https://github.com/floooh/sokol/blob/master/util/sokol_imgui.h) | Lower-level than GLFW/SDL |
|
||||
|
||||
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.
|
||||
### Using a custom engine?
|
||||
|
||||
You will likely be tempted to start by rewrite your own backend using your own custom/high-level facilities...<BR>
|
||||
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.<BR>
|
||||
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.<BR>
|
||||
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.<BR>
|
||||
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](https://github.com/ocornut/imgui/issues/1542) 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 such as: "create an additional OS window", "create a render context", "get the OS position of this
|
||||
window" etc. See 'ImGuiPlatformIO' for details.
|
||||
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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue