imgui/docs/BACKENDS.md

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