tomato-testing/docs/BACKENDS.md
Green Sky 0e1b1703f6 Squashed 'external/imgui/imgui/' changes from b475309fa1e..6ccc561a2ab
6ccc561a2ab Version 1.90.6
0d483a1c89f Backends: OpenGL3: Update loader for Linux to support EGL/GLVND. (#7562)
92df32d3390 Backends: OpenGL3: minor update of generated loader to match latest downloaded glcorearb.h/khrplatform.h files.
1ab1af80c74 Backends: Win32: Facepalm revert part of d15574c + additional commentary (#6275)
d15574ce2a5 Backends: Win32: Removed silent return when calling ImGui_ImplWin32_WndProcHandler() with no active context! (#6275)
d4495446d53 Windows, Internal: added experimental SkipRefresh mode. (#3515, #4763, #7556, #5116 , #4076, #2749, #2268)
0b309471f2e Windows: Changed default ClipRect to extend to windows' left and right borders. (#3312, #7540, #3756, #6170, #6365)
0c9c12c1bb9 InnerClipRect use ImFloor() matching docking branch (fix c41868531 for #6861, #2884, followed by rename 94da5842)
6ebbecc6a08 Realign assignments.
fc4d818e170 Tables: Angled headers: added TableAngledHeadersTextAlign, ImGuiStyleVar_TableAngledHeadersTextAlign. (#6917)
4bb75671414 Tables: Angled headers: fixed multi-line label display when angle is flipped. (#6917)
b30df8890de Table: Angled Headers: internal refactor to facilitate changing angled header bg and text colors per column. (#6917)
558c57a086c Fixed static analyzer warning "Pointer to local array 'overlay_buf' is stored outside the scope". Technically not used outside that scope, but best to play nice.
50b2ff0bf03 ImGuiIO: moved IMGUI_DISABLE_OBSOLETE_KEYIO block lower in the structure so other fields layout are not affected by it (#7534)
6ef4f67fa94 ImDrawList: moved cold fields lower in the structure so hot fields are closer to each others + better packed ImGuiNavItemData
a60387a3c25 Backends: GLFW: Add define guards for glfw native defines. (#7536)
913151caa89 Demo: move progress bars to their own section.
c895e987adf ProgressBar: added indeterminate mode by passing an animated negative value. (#5316, #5370, #1901)
b8a44b198c9 TreeNode: added ImGuiTreeNodeFlags_SpanTextWidth. (#6937)
baaaaea9e91 Demo: tweak TreeNode demo.
da18fcb7aed Internals: ensure ButtonBehavior() is called with non 0 id.
b720c0f541c Backends: Vulkan: Added convenience support for Volk via IMGUI_IMPL_VULKAN_USE_VOLK define. (#6582, #4854)
07e8ff9a8d4 Backends: Win32: Fixed a warning + moved header cruft below Changelog.
fa0120ea5ea Windows: Fixed subsequent Begin() append calls from setting last item information for title-bar. (#7506, #823)
361432a0bb2 TreeNode: fixed layout so that TreeNode("") or TreeNode("##HiddenLabel") may properly be used with SameLine(0,0). (#7505, #282)
eba46cb0d22 Drag and Drop: assert when nesting  BeginDragDropSource() and BeginDragDropTarget() (#7504) + update Gallery links
9ec299ebe31 Backends: OpenGL: Detect ES3 contexts on desktop based on version string, (#7447)
7b8107e7c84 Examples: GLFW+WebGPU: Rename example_emscripten_wgpu/ to example_glfw_wgpu/ (#7435, #7132)
648278cd62f Examples: GLFW+WebGPU: Amends. (#7435, #7132)
80a5fdb1089 Examples: GLFW+WebGPU: Fixed condition for when to recreate swapchain. (#7435, #7132)
f9df6bf6622 Examples: GLFW+WebGPU: added support for WebGPU-native/Dawn (#7435, #7132)

git-subtree-dir: external/imgui/imgui
git-subtree-split: 6ccc561a2ab497ad4ae6ee1dbd3b992ffada35cb
2024-05-15 13:22:13 +02:00

8.7 KiB

(You may browse this at https://github.com/ocornut/imgui/blob/master/docs/BACKENDS.md or view this file with any Markdown viewer)

Dear ImGui: Backends

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.

An application usually combines one Platform backend + one Renderer backend + main Dear ImGui sources. For example, the example_win32_directx11 application combines imgui_impl_win32.cpp + imgui_impl_dx11.cpp. There are 20+ examples in the examples/ folder. See EXAMPLES.MD for details.

Once Dear ImGui is setup and running, run and refer to ImGui::ShowDemoWindow() in imgui_demo.cpp for usage of the end-user API.

What are backends?

Dear ImGui is highly portable and only requires a few things to run and render, typically:

  • 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.

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 each backend is 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).

It is important to understand the difference between the core Dear ImGui library (files in the root folder) and the 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. you can get creative and use software rendering or render remotely on a different machine.

Integrating a backend

See "Getting Started" section of EXAMPLES.MD for more details.

List of backends

In the backends/ folder:

List of Platforms Backends:

imgui_impl_android.cpp    ; Android native app API
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_sdl2.cpp       ; SDL2 (Windows, macOS, Linux, iOS, Android) https://www.libsdl.org
imgui_impl_sdl3.cpp       ; SDL3 (Windows, macOS, Linux, iOS, Android) https://www.libsdl.org (*EXPERIMENTAL UNTIL SDL3 IS RELEASED*)
imgui_impl_win32.cpp      ; Win32 native API (Windows)
imgui_impl_glut.cpp       ; GLUT/FreeGLUT (this is prehistoric software and absolutely not recommended today!)

List of Renderer Backends:

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_sdlrenderer2.cpp ; SDL_Renderer (optional component of SDL2 available from SDL 2.0.18+)
imgui_impl_sdlrenderer3.cpp ; SDL_Renderer (optional component of SDL3 available from SDL 3.0.0+)
imgui_impl_vulkan.cpp     ; Vulkan
imgui_impl_wgpu.cpp       ; WebGPU (web and desktop)

List of high-level Frameworks Backends (combining Platform + Renderer):

imgui_impl_allegro5.cpp

Emscripten is also supported! The SDL+GL, GLFW+GL and GLFW+WebGPU examples are all ready to build and run with Emscripten.

Backends for third-party frameworks, graphics API or other languages

See https://github.com/ocornut/imgui/wiki/Bindings for the full list (e.g. Adventure Game Studio, Cinder, Cocos2d-x, Game Maker Studio2, Godot, LÖVE+LUA, Magnum, Monogame, Ogre, openFrameworks, OpenSceneGraph, SFML, Sokol, Unity, Unreal Engine and many others).

If you are not sure which backend to use, the recommended platform/frameworks for portable applications:

Library Website Backend Note
GLFW https://github.com/glfw/glfw imgui_impl_glfw.cpp
SDL2 https://www.libsdl.org imgui_impl_sdl2.cpp
Sokol https://github.com/floooh/sokol util/sokol_imgui.h Lower-level than GLFW/SDL

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 fewer 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, and 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...

Generally: It is unlikely you will add value to your project by creating your own backend.

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 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.