You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and dots ('.'), can be up to 35 characters long. Letters must be lowercase.
154 lines
7.2 KiB
154 lines
7.2 KiB
----------------------------------------------------------------------- |
|
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. |
|
|
|
|