mirror of
https://github.com/Drezil/imgui.git
synced 2024-11-15 01:17:00 +00:00
155 lines
7.2 KiB
Plaintext
155 lines
7.2 KiB
Plaintext
-----------------------------------------------------------------------
|
|
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.
|
|
|