1_(You may browse this at https://github.com/ocornut/imgui/blob/master/docs/BACKENDS.md or view this file with any Markdown viewer)_ 2 3## Dear ImGui: Backends 4 5**The backends/ folder contains backends for popular platforms/graphics API, which you can use in 6your 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. 7 8- The 'Platform' backends are in charge of: mouse/keyboard/gamepad inputs, cursor shape, timing, windowing.<BR> 9 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. 10 11- The 'Renderer' backends are in charge of: creating atlas texture, rendering imgui draw data.<BR> 12 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. 13 14- For some high-level frameworks, a single backend usually handle both 'Platform' and 'Renderer' parts.<BR> 15 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. 16 17An application usually combines 1 Platform backend + 1 Renderer backend + main Dear ImGui sources. 18For 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. There are 20+ examples in the [examples/](https://github.com/ocornut/imgui/blob/master/examples/) folder. See [EXAMPLES.MD](https://github.com/ocornut/imgui/blob/master/docs/EXAMPLES.md) for details. 19 20**Once Dear ImGui is setup and running, run and refer to `ImGui::ShowDemoWindow()` in imgui_demo.cpp for usage of the end-user API.** 21 22 23### What are backends 24 25Dear ImGui is highly portable and only requires a few things to run and render, typically: 26 27 - Required: providing mouse/keyboard inputs (fed into the `ImGuiIO` structure). 28 - Required: uploading the font atlas texture into graphics memory. 29 - Required: rendering indexed textured triangles with a clipping rectangle. 30 31 Extra features are opt-in, our backends try to support as many as possible: 32 33 - Optional: custom texture binding support. 34 - Optional: clipboard support. 35 - Optional: gamepad support. 36 - Optional: mouse cursor shape support. 37 - Optional: IME support. 38 - Optional: multi-viewports support. 39 etc. 40 41This is essentially what each backends are doing + obligatory portability cruft. Using default backends ensure you can get all those features including the ones that would be harder to implement on your side (e.g. multi-viewports support). 42 43It is important to understand the difference between the core Dear ImGui library (files in the root folder) 44and backends which we are describing here (backends/ folder). 45 46- Some issues may only be backend or platform specific. 47- You should be able to write backends for pretty much any platform and any 3D graphics API. 48 e.g. you can get creative and use software rendering or render remotely on a different machine. 49 50 51### Integrating a backend 52 53See "Getting Started" section of [EXAMPLES.MD](https://github.com/ocornut/imgui/blob/master/docs/EXAMPLES.md) for more details. 54 55 56### List of backends 57 58In the [backends/](https://github.com/ocornut/imgui/blob/master/backends) folder: 59 60List of Platforms Backends: 61 62 imgui_impl_android.cpp ; Android native app API 63 imgui_impl_glfw.cpp ; GLFW (Windows, macOS, Linux, etc.) http://www.glfw.org/ 64 imgui_impl_osx.mm ; macOS native API (not as feature complete as glfw/sdl backends) 65 imgui_impl_sdl.cpp ; SDL2 (Windows, macOS, Linux, iOS, Android) https://www.libsdl.org 66 imgui_impl_win32.cpp ; Win32 native API (Windows) 67 imgui_impl_glut.cpp ; GLUT/FreeGLUT (this is prehistoric software and absolutely not recommended today!) 68 69List of Renderer Backends: 70 71 imgui_impl_dx9.cpp ; DirectX9 72 imgui_impl_dx10.cpp ; DirectX10 73 imgui_impl_dx11.cpp ; DirectX11 74 imgui_impl_dx12.cpp ; DirectX12 75 imgui_impl_metal.mm ; Metal (with ObjC) 76 imgui_impl_opengl2.cpp ; OpenGL 2 (legacy, fixed pipeline <- don't use with modern OpenGL context) 77 imgui_impl_opengl3.cpp ; OpenGL 3/4, OpenGL ES 2, OpenGL ES 3 (modern programmable pipeline) 78 imgui_impl_sdlrenderer.cpp; SDL_Renderer (optional component of SDL2 available from SDL 2.0.18+) 79 imgui_impl_vulkan.cpp ; Vulkan 80 imgui_impl_wgpu.cpp ; WebGPU 81 82List of high-level Frameworks Backends (combining Platform + Renderer): 83 84 imgui_impl_allegro5.cpp 85 imgui_impl_marmalade.cpp 86 87Emscripten is also supported. 88The [example_emscripten_opengl3](https://github.com/ocornut/imgui/tree/master/examples/example_emscripten_opengl3) app uses imgui_impl_sdl.cpp + imgui_impl_opengl3.cpp, but other combos are possible. 89 90### Backends for third-party frameworks, graphics API or other languages 91 92See https://github.com/ocornut/imgui/wiki/Bindings for the full list. 93 94### Recommended Backends 95 96If you are not sure which backend to use, the recommended platform/frameworks for portable applications: 97 98|Library |Website |Backend |Note | 99|--------|--------|--------|-----| 100| GLFW | https://github.com/glfw/glfw | imgui_impl_glfw.cpp | | 101| SDL2 | https://www.libsdl.org | imgui_impl_sdl.cpp | | 102| 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 | 103 104 105### Using a custom engine? 106 107You will likely be tempted to start by rewrite your own backend using your own custom/high-level facilities...<BR> 108Think twice! 109 110If you are new to Dear ImGui, first try using the existing backends as-is. 111You will save lots of time integrating the library. 112You can LATER decide to rewrite yourself a custom backend if you really need to. 113In most situations, custom backends have less features and more bugs than the standard backends we provide. 114If you want portability, you can use multiple backends and choose between them either at compile time 115or at runtime. 116 117**Example A**: your engine is built over Windows + DirectX11 but you have your own high-level rendering 118system layered over DirectX11.<BR> 119Suggestion: try using imgui_impl_win32.cpp + imgui_impl_dx11.cpp first. 120Once it works, if you really need it you can replace the imgui_impl_dx11.cpp code with a 121custom renderer using your own rendering functions, and keep using the standard Win32 code etc. 122 123**Example B**: your engine runs on Windows, Mac, Linux and uses DirectX11, Metal, Vulkan respectively.<BR> 124Suggestion: use multiple generic backends! 125Once it works, if you really need it you can replace parts of backends with your own abstractions. 126 127**Example C**: your engine runs on platforms we can't provide public backends for (e.g. PS4/PS5, Switch), 128and you have high-level systems everywhere.<BR> 129Suggestion: try using a non-portable backend first (e.g. win32 + underlying graphics API) to get 130your desktop builds working first. This will get you running faster and get your acquainted with 131how Dear ImGui works and is setup. You can then rewrite a custom backend using your own engine API. 132 133Also: 134The [multi-viewports feature](https://github.com/ocornut/imgui/issues/1542) of the 'docking' branch allows 135Dear ImGui windows to be seamlessly detached from the main application window. This is achieved using an 136extra layer to the Platform and Renderer backends, which allows Dear ImGui to communicate platform-specific 137requests such as: "create an additional OS window", "create a render context", "get the OS position of this 138window" etc. See 'ImGuiPlatformIO' for details. 139Supporting the multi-viewports feature correctly using 100% of your own abstractions is more difficult 140than supporting single-viewport. 141If you decide to use unmodified imgui_impl_XXXX.cpp files, you can automatically benefit from 142improvements and fixes related to viewports and platform windows without extra work on your side. 143