Merge branch 'master' into docking
# Conflicts: # backends/imgui_impl_dx10.cpp # backends/imgui_impl_dx10.h # backends/imgui_impl_vulkan.h # backends/imgui_impl_win32.cpp # docs/CHANGELOG.txt # examples/README.txt # examples/example_glfw_opengl2/main.cpp # examples/example_glfw_opengl3/main.cpp # examples/example_glfw_vulkan/main.cpp # examples/example_sdl_directx11/main.cpp # examples/example_sdl_opengl2/main.cpp # examples/example_sdl_opengl3/main.cpp # examples/example_sdl_vulkan/main.cpp # examples/example_win32_directx10/main.cpp # examples/example_win32_directx11/main.cpp # examples/example_win32_directx12/main.cpp # examples/example_win32_directx9/main.cpp # imgui.cpp # imgui.h # imgui_demo.cpp # imgui_internal.hdocking
ocornut
4 years ago
commit
042a3b01d2
@ -1,14 +1,14 @@
|
||||
// dear imgui: Renderer for DirectX10
|
||||
// This needs to be used along with a Platform Binding (e.g. Win32)
|
||||
// dear imgui: Renderer Backend for DirectX10
|
||||
// This needs to be used along with a Platform Backend (e.g. Win32)
|
||||
|
||||
// Implemented features:
|
||||
// [X] Renderer: User texture binding. Use 'ID3D10ShaderResourceView*' as ImTextureID. Read the FAQ about ImTextureID!
|
||||
// [X] Renderer: Multi-viewport support. Enable with 'io.ConfigFlags |= ImGuiConfigFlags_ViewportsEnable'.
|
||||
// [X] Renderer: Support for large meshes (64k+ vertices) with 16-bit indices.
|
||||
|
||||
// You can copy and use unmodified imgui_impl_* files in your project. See main.cpp for an example of using this.
|
||||
// If you are new to dear imgui, read examples/README.txt and read the documentation at the top of imgui.cpp.
|
||||
// https://github.com/ocornut/imgui
|
||||
// You can copy and use unmodified imgui_impl_* files in your project. See examples/ folder for examples of using this.
|
||||
// If you are new to Dear ImGui, read documentation from the docs/ folder + read the top of imgui.cpp.
|
||||
// Read online: https://github.com/ocornut/imgui/tree/master/docs
|
||||
|
||||
#pragma once
|
||||
#include "imgui.h" // IMGUI_IMPL_API
|
||||
@ -1,14 +1,14 @@
|
||||
// dear imgui: Renderer for DirectX11
|
||||
// This needs to be used along with a Platform Binding (e.g. Win32)
|
||||
// dear imgui: Renderer Backend for DirectX11
|
||||
// This needs to be used along with a Platform Backend (e.g. Win32)
|
||||
|
||||
// Implemented features:
|
||||
// [X] Renderer: User texture binding. Use 'ID3D11ShaderResourceView*' as ImTextureID. Read the FAQ about ImTextureID!
|
||||
// [X] Renderer: Multi-viewport support. Enable with 'io.ConfigFlags |= ImGuiConfigFlags_ViewportsEnable'.
|
||||
// [X] Renderer: Support for large meshes (64k+ vertices) with 16-bit indices.
|
||||
|
||||
// You can copy and use unmodified imgui_impl_* files in your project. See main.cpp for an example of using this.
|
||||
// If you are new to dear imgui, read examples/README.txt and read the documentation at the top of imgui.cpp.
|
||||
// https://github.com/ocornut/imgui
|
||||
// You can copy and use unmodified imgui_impl_* files in your project. See examples/ folder for examples of using this.
|
||||
// If you are new to Dear ImGui, read documentation from the docs/ folder + read the top of imgui.cpp.
|
||||
// Read online: https://github.com/ocornut/imgui/tree/master/docs
|
||||
|
||||
#pragma once
|
||||
#include "imgui.h" // IMGUI_IMPL_API
|
||||
@ -1,18 +1,18 @@
|
||||
// dear imgui: Renderer for DirectX12
|
||||
// This needs to be used along with a Platform Binding (e.g. Win32)
|
||||
// dear imgui: Renderer Backend for DirectX12
|
||||
// This needs to be used along with a Platform Backend (e.g. Win32)
|
||||
|
||||
// Implemented features:
|
||||
// [X] Renderer: User texture binding. Use 'D3D12_GPU_DESCRIPTOR_HANDLE' as ImTextureID. Read the FAQ about ImTextureID!
|
||||
// [X] Renderer: Multi-viewport support. Enable with 'io.ConfigFlags |= ImGuiConfigFlags_ViewportsEnable'.
|
||||
// [X] Renderer: Support for large meshes (64k+ vertices) with 16-bit indices.
|
||||
|
||||
// Important: to compile on 32-bit systems, this back-end requires code to be compiled with '#define ImTextureID ImU64'.
|
||||
// Important: to compile on 32-bit systems, this backend requires code to be compiled with '#define ImTextureID ImU64'.
|
||||
// This is because we need ImTextureID to carry a 64-bit value and by default ImTextureID is defined as void*.
|
||||
// This define is done in the example .vcxproj file and need to be replicated in your app (by e.g. editing imconfig.h)
|
||||
|
||||
// You can copy and use unmodified imgui_impl_* files in your project. See main.cpp for an example of using this.
|
||||
// If you are new to dear imgui, read examples/README.txt and read the documentation at the top of imgui.cpp.
|
||||
// https://github.com/ocornut/imgui
|
||||
// You can copy and use unmodified imgui_impl_* files in your project. See examples/ folder for examples of using this.
|
||||
// If you are new to Dear ImGui, read documentation from the docs/ folder + read the top of imgui.cpp.
|
||||
// Read online: https://github.com/ocornut/imgui/tree/master/docs
|
||||
|
||||
#pragma once
|
||||
#include "imgui.h" // IMGUI_IMPL_API
|
||||
@ -1,14 +1,14 @@
|
||||
// dear imgui: Renderer for DirectX9
|
||||
// This needs to be used along with a Platform Binding (e.g. Win32)
|
||||
// dear imgui: Renderer Backend for DirectX9
|
||||
// This needs to be used along with a Platform Backend (e.g. Win32)
|
||||
|
||||
// Implemented features:
|
||||
// [X] Renderer: User texture binding. Use 'LPDIRECT3DTEXTURE9' as ImTextureID. Read the FAQ about ImTextureID!
|
||||
// [X] Renderer: Multi-viewport support. Enable with 'io.ConfigFlags |= ImGuiConfigFlags_ViewportsEnable'.
|
||||
// [X] Renderer: Support for large meshes (64k+ vertices) with 16-bit indices.
|
||||
|
||||
// You can copy and use unmodified imgui_impl_* files in your project. See main.cpp for an example of using this.
|
||||
// If you are new to dear imgui, read examples/README.txt and read the documentation at the top of imgui.cpp.
|
||||
// https://github.com/ocornut/imgui
|
||||
// You can copy and use unmodified imgui_impl_* files in your project. See examples/ folder for examples of using this.
|
||||
// If you are new to Dear ImGui, read documentation from the docs/ folder + read the top of imgui.cpp.
|
||||
// Read online: https://github.com/ocornut/imgui/tree/master/docs
|
||||
|
||||
#pragma once
|
||||
#include "imgui.h" // IMGUI_IMPL_API
|
||||
@ -1,12 +1,12 @@
|
||||
// dear imgui: Renderer + Platform Binding for Marmalade + IwGx
|
||||
// dear imgui: Renderer + Platform Backend for Marmalade + IwGx
|
||||
// Marmalade code: Copyright (C) 2015 by Giovanni Zito (this file is part of Dear ImGui)
|
||||
|
||||
// Implemented features:
|
||||
// [X] Renderer: User texture binding. Use 'CIwTexture*' as ImTextureID. Read the FAQ about ImTextureID!
|
||||
|
||||
// You can copy and use unmodified imgui_impl_* files in your project. See main.cpp for an example of using this.
|
||||
// If you are new to dear imgui, read examples/README.txt and read the documentation at the top of imgui.cpp.
|
||||
// https://github.com/ocornut/imgui
|
||||
// You can copy and use unmodified imgui_impl_* files in your project. See examples/ folder for examples of using this.
|
||||
// If you are new to Dear ImGui, read documentation from the docs/ folder + read the top of imgui.cpp.
|
||||
// Read online: https://github.com/ocornut/imgui/tree/master/docs
|
||||
|
||||
#pragma once
|
||||
#include "imgui.h" // IMGUI_IMPL_API
|
||||
@ -1,13 +1,13 @@
|
||||
// dear imgui: Renderer for OpenGL2 (legacy OpenGL, fixed pipeline)
|
||||
// This needs to be used along with a Platform Binding (e.g. GLFW, SDL, Win32, custom..)
|
||||
// dear imgui: Renderer Backend for OpenGL2 (legacy OpenGL, fixed pipeline)
|
||||
// This needs to be used along with a Platform Backend (e.g. GLFW, SDL, Win32, custom..)
|
||||
|
||||
// Implemented features:
|
||||
// [X] Renderer: User texture binding. Use 'GLuint' OpenGL texture identifier as void*/ImTextureID. Read the FAQ about ImTextureID!
|
||||
// [X] Renderer: Multi-viewport support. Enable with 'io.ConfigFlags |= ImGuiConfigFlags_ViewportsEnable'.
|
||||
|
||||
// You can copy and use unmodified imgui_impl_* files in your project. See main.cpp for an example of using this.
|
||||
// If you are new to dear imgui, read examples/README.txt and read the documentation at the top of imgui.cpp.
|
||||
// https://github.com/ocornut/imgui
|
||||
// You can copy and use unmodified imgui_impl_* files in your project. See examples/ folder for examples of using this.
|
||||
// If you are new to Dear ImGui, read documentation from the docs/ folder + read the top of imgui.cpp.
|
||||
// Read online: https://github.com/ocornut/imgui/tree/master/docs
|
||||
|
||||
// **DO NOT USE THIS CODE IF YOUR CODE/ENGINE IS USING MODERN OPENGL (SHADERS, VBO, VAO, etc.)**
|
||||
// **Prefer using the code in imgui_impl_opengl3.cpp**
|
||||
@ -1,16 +1,16 @@
|
||||
// dear imgui: Renderer for modern OpenGL with shaders / programmatic pipeline
|
||||
// dear imgui: Renderer Backend for modern OpenGL with shaders / programmatic pipeline
|
||||
// - Desktop GL: 2.x 3.x 4.x
|
||||
// - Embedded GL: ES 2.0 (WebGL 1.0), ES 3.0 (WebGL 2.0)
|
||||
// This needs to be used along with a Platform Binding (e.g. GLFW, SDL, Win32, custom..)
|
||||
// This needs to be used along with a Platform Backend (e.g. GLFW, SDL, Win32, custom..)
|
||||
|
||||
// Implemented features:
|
||||
// [X] Renderer: User texture binding. Use 'GLuint' OpenGL texture identifier as void*/ImTextureID. Read the FAQ about ImTextureID!
|
||||
// [X] Renderer: Multi-viewport support. Enable with 'io.ConfigFlags |= ImGuiConfigFlags_ViewportsEnable'.
|
||||
// [x] Renderer: Desktop GL only: Support for large meshes (64k+ vertices) with 16-bit indices.
|
||||
|
||||
// You can copy and use unmodified imgui_impl_* files in your project. See main.cpp for an example of using this.
|
||||
// If you are new to dear imgui, read examples/README.txt and read the documentation at the top of imgui.cpp.
|
||||
// https://github.com/ocornut/imgui
|
||||
// You can copy and use unmodified imgui_impl_* files in your project. See examples/ folder for examples of using this.
|
||||
// If you are new to Dear ImGui, read documentation from the docs/ folder + read the top of imgui.cpp.
|
||||
// Read online: https://github.com/ocornut/imgui/tree/master/docs
|
||||
|
||||
// About Desktop OpenGL function loaders:
|
||||
// Modern Desktop OpenGL doesn't have a standard portable header file to load OpenGL function pointers.
|
||||
@ -1,14 +1,18 @@
|
||||
// dear imgui: Platform Binding for OSX / Cocoa
|
||||
// dear imgui: Platform Backend for OSX / Cocoa
|
||||
// This needs to be used along with a Renderer (e.g. OpenGL2, OpenGL3, Vulkan, Metal..)
|
||||
// [ALPHA] Early bindings, not well tested. If you want a portable application, prefer using the GLFW or SDL platform bindings on Mac.
|
||||
// [ALPHA] Early backend, not well tested. If you want a portable application, prefer using the GLFW or SDL platform Backends on Mac.
|
||||
|
||||
// Implemented features:
|
||||
// [X] Platform: Mouse cursor shape and visibility. Disable with 'io.ConfigFlags |= ImGuiConfigFlags_NoMouseCursorChange'.
|
||||
// [X] Platform: OSX clipboard is supported within core Dear ImGui (no specific code in this back-end).
|
||||
// [X] Platform: OSX clipboard is supported within core Dear ImGui (no specific code in this backend).
|
||||
// Issues:
|
||||
// [ ] Platform: Keys are all generally very broken. Best using [event keycode] and not [event characters]..
|
||||
// [ ] Platform: Multi-viewport / platform windows.
|
||||
|
||||
// You can copy and use unmodified imgui_impl_* files in your project. See examples/ folder for examples of using this.
|
||||
// If you are new to Dear ImGui, read documentation from the docs/ folder + read the top of imgui.cpp.
|
||||
// Read online: https://github.com/ocornut/imgui/tree/master/docs
|
||||
|
||||
#include "imgui.h" // IMGUI_IMPL_API
|
||||
|
||||
@class NSEvent;
|
||||
@ -1,24 +1,24 @@
|
||||
// dear imgui: Renderer for Vulkan
|
||||
// This needs to be used along with a Platform Binding (e.g. GLFW, SDL, Win32, custom..)
|
||||
// dear imgui: Renderer Backend for Vulkan
|
||||
// This needs to be used along with a Platform Backend (e.g. GLFW, SDL, Win32, custom..)
|
||||
|
||||
// Implemented features:
|
||||
// [X] Renderer: Support for large meshes (64k+ vertices) with 16-bit indices.
|
||||
// Missing features:
|
||||
// [ ] Platform: Multi-viewport / platform windows.
|
||||
// [ ] Renderer: User texture binding. Changes of ImTextureID aren't supported by this binding! See https://github.com/ocornut/imgui/pull/914
|
||||
// [ ] Renderer: User texture binding. Changes of ImTextureID aren't supported by this backend! See https://github.com/ocornut/imgui/pull/914
|
||||
|
||||
// You can copy and use unmodified imgui_impl_* files in your project. See main.cpp for an example of using this.
|
||||
// If you are new to dear imgui, read examples/README.txt and read the documentation at the top of imgui.cpp.
|
||||
// https://github.com/ocornut/imgui
|
||||
// You can copy and use unmodified imgui_impl_* files in your project. See examples/ folder for examples of using this.
|
||||
// If you are new to Dear ImGui, read documentation from the docs/ folder + read the top of imgui.cpp.
|
||||
// Read online: https://github.com/ocornut/imgui/tree/master/docs
|
||||
|
||||
// The aim of imgui_impl_vulkan.h/.cpp is to be usable in your engine without any modification.
|
||||
// IF YOU FEEL YOU NEED TO MAKE ANY CHANGE TO THIS CODE, please share them and your feedback at https://github.com/ocornut/imgui/
|
||||
|
||||
// Important note to the reader who wish to integrate imgui_impl_vulkan.cpp/.h in their own engine/app.
|
||||
// - Common ImGui_ImplVulkan_XXX functions and structures are used to interface with imgui_impl_vulkan.cpp/.h.
|
||||
// You will use those if you want to use this rendering back-end in your engine/app.
|
||||
// You will use those if you want to use this rendering backend in your engine/app.
|
||||
// - Helper ImGui_ImplVulkanH_XXX functions and structures are only used by this example (main.cpp) and by
|
||||
// the back-end itself (imgui_impl_vulkan.cpp), but should PROBABLY NOT be used by your own engine/app code.
|
||||
// the backend itself (imgui_impl_vulkan.cpp), but should PROBABLY NOT be used by your own engine/app code.
|
||||
// Read comments in imgui_impl_vulkan.h.
|
||||
|
||||
#pragma once
|
||||
@ -1,3 +1,6 @@
|
||||
#!/bin/bash
|
||||
## -V: create SPIR-V binary
|
||||
## -x: save binary output as text-based 32-bit hexadecimal numbers
|
||||
## -o: output file
|
||||
glslangValidator -V -x -o glsl_shader.frag.u32 glsl_shader.frag
|
||||
glslangValidator -V -x -o glsl_shader.vert.u32 glsl_shader.vert
|
||||
@ -0,0 +1,160 @@
|
||||
_(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.
|
||||
|
||||
- The 'Platform' backends are in charge of: mouse/keyboard/gamepad inputs, cursor shape, timing, windowing.<BR>
|
||||
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.
|
||||
|
||||
- The 'Renderer' backends are in charge of: creating atlas texture, rendering imgui draw data.<BR>
|
||||
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.
|
||||
|
||||
- For some high-level frameworks, a single backend usually handle both 'Platform' and 'Renderer' parts.<BR>
|
||||
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.
|
||||
|
||||
An application usually combines 1 Platform backend + 1 Renderer backend + main Dear ImGui sources.
|
||||
For 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. See [EXAMPLES.MD](https://github.com/ocornut/imgui/blob/master/docs/EXAMPLES.md) 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 (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 backends are doing + 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. you can get creative and use software rendering or render remotely on a different machine.
|
||||
|
||||
|
||||
### List of backends
|
||||
|
||||
In the [backends/](https://github.com/ocornut/imgui/blob/master/backends) folder:
|
||||
|
||||
List of Platforms Backends:
|
||||
|
||||
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:
|
||||
|
||||
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
|
||||
|
||||
List of high-level Frameworks Backends (combining Platform + Renderer):
|
||||
|
||||
imgui_impl_allegro5.cpp
|
||||
imgui_impl_marmalade.cpp
|
||||
|
||||
Emscripten is also supported.
|
||||
The [example_emscripten](https://github.com/ocornut/imgui/tree/master/examples/example_emscripten) app uses imgui_impl_sdl.cpp + imgui_impl_opengl3.cpp, but other combos are possible.
|
||||
|
||||
### Backends for third-party frameworks, graphics API or other languages
|
||||
|
||||
See 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
|
||||
- Unity
|
||||
- Unreal Engine 4
|
||||
- vtk
|
||||
- Win32 GDI
|
||||
etc.
|
||||
|
||||
|
||||
### Recommended Backends
|
||||
|
||||
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_sdl.cpp | |
|
||||
| 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 |
|
||||
|
||||
|
||||
### Using a custom engine?
|
||||
|
||||
You will likely be tempted to start by rewrite your own backend using your own custom/high-level facilities...<BR>
|
||||
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.<BR>
|
||||
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.<BR>
|
||||
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.<BR>
|
||||
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](https://github.com/ocornut/imgui/issues/1542) 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.
|
||||
@ -0,0 +1,235 @@
|
||||
_(You may browse this at https://github.com/ocornut/imgui/blob/master/docs/EXAMPLES.md or view this file with any Markdown viewer)_
|
||||
|
||||
## Dear ImGui: Examples
|
||||
|
||||
**The [examples/](https://github.com/ocornut/imgui/blob/master/examples) folder example applications (standalone, ready-to-build) for variety of
|
||||
platforms and graphics APIs.** They all use standard backends from the [backends/](https://github.com/ocornut/imgui/blob/master/backends) folder.
|
||||
|
||||
You can find Windows binaries for some of those example applications at:
|
||||
http://www.dearimgui.org/binaries
|
||||
|
||||
|
||||
### Getting Started
|
||||
|
||||
Integration in a typical existing application, should take <20 lines when using standard backends.
|
||||
|
||||
At initialization:
|
||||
call ImGui::CreateContext()
|
||||
call ImGui_ImplXXXX_Init() for each backend.
|
||||
|
||||
At the beginning of your frame:
|
||||
call ImGui_ImplXXXX_NewFrame() for each backend.
|
||||
call ImGui::NewFrame()
|
||||
|
||||
At the end of your frame:
|
||||
call ImGui::Render()
|
||||
call ImGui_ImplXXXX_RenderDrawData() for your Renderer backend.
|
||||
|
||||
At shutdown:
|
||||
call ImGui_ImplXXXX_Shutdown() for each backend.
|
||||
call ImGui::DestroyContext()
|
||||
|
||||
Example (using [backends/imgui_impl_win32.cpp](https://github.com/ocornut/imgui/blob/master/backends/imgui_impl_win32.cpp) + [backends/imgui_impl_dx11.cpp](https://github.com/ocornut/imgui/blob/master/backends/imgui_impl_dx11.cpp)):
|
||||
|
||||
// Create a Dear ImGui context, setup some options
|
||||
ImGui::CreateContext();
|
||||
ImGuiIO& io = ImGui::GetIO();
|
||||
io.ConfigFlags |= ImGuiConfigFlags_NavEnableKeyboard; // Enable some options
|
||||
|
||||
// Initialize Platform + Renderer backends (here: using imgui_impl_win32.cpp + imgui_impl_dx11.cpp)
|
||||
ImGui_ImplWin32_Init(my_hwnd);
|
||||
ImGui_ImplDX11_Init(my_d3d_device, my_d3d_device_context);
|
||||
|
||||
// Application main loop
|
||||
while (true)
|
||||
{
|
||||
// Beginning of frame: update Renderer + Platform backend, start Dear ImGui frame
|
||||
ImGui_ImplDX11_NewFrame();
|
||||
ImGui_ImplWin32_NewFrame();
|
||||
ImGui::NewFrame();
|
||||
|
||||
// Any application code here
|
||||
ImGui::Text("Hello, world!");
|
||||
|
||||
// End of frame: render Dear ImGui
|
||||
ImGui::Render();
|
||||
ImGui_ImplDX11_RenderDrawData(ImGui::GetDrawData());
|
||||
|
||||
// Swap
|
||||
g_pSwapChain->Present(1, 0);
|
||||
}
|
||||
|
||||
// Shutdown
|
||||
ImGui_ImplDX11_Shutdown();
|
||||
ImGui_ImplWin32_Shutdown();
|
||||
ImGui::DestroyContext();
|
||||
|
||||
Please read 'PROGRAMMER GUIDE' in imgui.cpp for notes on how to setup Dear ImGui in your codebase.
|
||||
Please read the comments and instruction at the top of each file.
|
||||
Please read FAQ at http://www.dearimgui.org/faq
|
||||
|
||||
If you are using of the backend provided here, you can add the backends/imgui_impl_xxxx(.cpp,.h)
|
||||
files to your project and use as-in. Each imgui_impl_xxxx.cpp file comes with its own individual
|
||||
Changelog, so if you want to update them later it will be easier to catch up with what changed.
|
||||
|
||||
|
||||
### Examples Applications
|
||||
|
||||
[example_allegro5/](https://github.com/ocornut/imgui/blob/master/examples/example_allegro5/) <BR>
|
||||
Allegro 5 example. <BR>
|
||||
= main.cpp + imgui_impl_allegro5.cpp
|
||||
|
||||
[example_apple_metal/](https://github.com/ocornut/imgui/blob/master/examples/example_metal/) <BR>
|
||||
OSX & iOS + Metal example. <BR>
|
||||
= main.m + imgui_impl_osx.mm + imgui_impl_metal.mm <BR>
|
||||
It is based on the "cross-platform" game template provided with Xcode as of Xcode 9.
|
||||
(NB: imgui_impl_osx.mm is currently not as feature complete as other platforms backends.
|
||||
You may prefer to use the GLFW Or SDL backends, which will also support Windows and Linux.)
|
||||
|
||||
[example_apple_opengl2/](https://github.com/ocornut/imgui/blob/master/examples/example_apple_opengl2/) <BR>
|
||||
OSX + OpenGL2 example. <BR>
|
||||
= main.mm + imgui_impl_osx.mm + imgui_impl_opengl2.cpp <BR>
|
||||
(NB: imgui_impl_osx.mm is currently not as feature complete as other platforms backends.
|
||||
You may prefer to use the GLFW Or SDL backends, which will also support Windows and Linux.)
|
||||
|
||||
[example_emscripten/](https://github.com/ocornut/imgui/blob/master/examples/example_emscripten/) <BR>
|
||||
Emcripten + SDL2 + OpenGL3+/ES2/ES3 example. <BR>
|
||||
= main.cpp + imgui_impl_sdl.cpp + imgui_impl_opengl3.cpp <BR>
|
||||
Note that other examples based on SDL or GLFW + OpenGL could easily be modified to work with Emscripten.
|
||||
We provide this to make the Emscripten differences obvious, and have them not pollute all other examples.
|
||||
|
||||
[example_glfw_metal/](https://github.com/ocornut/imgui/blob/master/examples/example_glfw_metal/) <BR>
|
||||
GLFW (Mac) + Metal example. <BR>
|
||||
= main.mm + imgui_impl_glfw.cpp + imgui_impl_metal.mm
|
||||
|
||||
[example_glfw_opengl2/](https://github.com/ocornut/imgui/blob/master/examples/example_glfw_opengl2/) <BR>
|
||||
GLFW + OpenGL2 example (legacy, fixed pipeline). <BR>
|
||||
= main.cpp + imgui_impl_glfw.cpp + imgui_impl_opengl2.cpp <BR>
|
||||
**DO NOT USE OPENGL2 CODE IF YOUR CODE/ENGINE IS USING MODERN OPENGL (SHADERS, VBO, VAO, etc.)** <BR>
|
||||
**Prefer using OPENGL3 code (with gl3w/glew/glad/glad2/glbinding, you can replace the OpenGL function loader)** <BR>
|
||||
This code is mostly provided as a reference to learn about Dear ImGui integration, because it is shorter.
|
||||
If your code is using GL3+ context or any semi modern OpenGL calls, using this renderer is likely to
|
||||
make things more complicated, will require your code to reset many OpenGL attributes to their initial
|
||||
state, and might confuse your GPU driver. One star, not recommended.
|
||||
|
||||
[example_glfw_opengl3/](https://github.com/ocornut/imgui/blob/master/examples/example_glfw_opengl3/) <BR>
|
||||
GLFW (Win32, Mac, Linux) + OpenGL3+/ES2/ES3 example (programmable pipeline). <BR>
|
||||
= main.cpp + imgui_impl_glfw.cpp + imgui_impl_opengl3.cpp <BR>
|
||||
This uses more modern OpenGL calls and custom shaders. <BR>
|
||||
Prefer using that if you are using modern OpenGL in your application (anything with shaders).
|
||||
(Please be mindful that accessing OpenGL3+ functions requires a function loader, which are a frequent
|
||||
source for confusion for new users. We use a loader in imgui_impl_opengl3.cpp which may be different
|
||||
from the one your app normally use. Read imgui_impl_opengl3.h for details and how to change it.)
|
||||
|
||||
[example_glfw_vulkan/](https://github.com/ocornut/imgui/blob/master/examples/example_glfw_vulkan/) <BR>
|
||||
GLFW (Win32, Mac, Linux) + Vulkan example. <BR>
|
||||
= main.cpp + imgui_impl_glfw.cpp + imgui_impl_vulkan.cpp <BR>
|
||||
This is quite long and tedious, because: Vulkan.
|
||||
For this example, the main.cpp file exceptionally use helpers function from imgui_impl_vulkan.h/cpp.
|
||||
|
||||
[example_glut_opengl2/](https://github.com/ocornut/imgui/blob/master/examples/example_glut_opengl2/) <BR>
|
||||
GLUT (e.g., FreeGLUT on Linux/Windows, GLUT framework on OSX) + OpenGL2 example. <BR>
|
||||
= main.cpp + imgui_impl_glut.cpp + imgui_impl_opengl2.cpp <BR>
|
||||
Note that GLUT/FreeGLUT is largely obsolete software, prefer using GLFW or SDL.
|
||||
|
||||
[example_marmalade/](https://github.com/ocornut/imgui/blob/master/examples/example_marmalade/) <BR>
|
||||
Marmalade example using IwGx. <BR>
|
||||
= main.cpp + imgui_impl_marmalade.cpp
|
||||
|
||||
[example_null/](https://github.com/ocornut/imgui/blob/master/examples/example_null/) <BR>
|
||||
Null example, compile and link imgui, create context, run headless with no inputs and no graphics output. <BR>
|
||||
= main.cpp <BR>
|
||||
This is used to quickly test compilation of core imgui files in as many setups as possible.
|
||||
Because this application doesn't create a window nor a graphic context, there's no graphics output.
|
||||
|
||||
[example_sdl_directx11/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl_directx11/) <BR>
|
||||
SDL2 + DirectX11 example, Windows only. <BR>
|
||||
= main.cpp + imgui_impl_sdl.cpp + imgui_impl_dx11.cpp <BR>
|
||||
This to demonstrate usage of DirectX with SDL.
|
||||
|
||||
[example_sdl_metal/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl_metal/) <BR>
|
||||
SDL2 (Mac) + Metal example. <BR>
|
||||
= main.mm + imgui_impl_sdl.cpp + imgui_impl_metal.mm
|
||||
|
||||
[example_sdl_opengl2/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl_opengl2/) <BR>
|
||||
SDL2 (Win32, Mac, Linux etc.) + OpenGL example (legacy, fixed pipeline). <BR>
|
||||
= main.cpp + imgui_impl_sdl.cpp + imgui_impl_opengl2.cpp <BR>
|
||||
**DO NOT USE OPENGL2 CODE IF YOUR CODE/ENGINE IS USING MODERN OPENGL (SHADERS, VBO, VAO, etc.)** <BR>
|
||||
**Prefer using OPENGL3 code (with gl3w/glew/glad/glad2/glbinding, you can replace the OpenGL function loader)** <BR>
|
||||
This code is mostly provided as a reference to learn about Dear ImGui integration, because it is shorter.
|
||||
If your code is using GL3+ context or any semi modern OpenGL calls, using this renderer is likely to
|
||||
make things more complicated, will require your code to reset many OpenGL attributes to their initial
|
||||
state, and might confuse your GPU driver. One star, not recommended.
|
||||
|
||||
[example_sdl_opengl3/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl_opengl3/) <BR>
|
||||
SDL2 (Win32, Mac, Linux, etc.) + OpenGL3+/ES2/ES3 example. <BR>
|
||||
= main.cpp + imgui_impl_sdl.cpp + imgui_impl_opengl3.cpp <BR>
|
||||
This uses more modern OpenGL calls and custom shaders. <BR>
|
||||
Prefer using that if you are using modern OpenGL in your application (anything with shaders).
|
||||
(Please be mindful that accessing OpenGL3+ functions requires a function loader, which are a frequent
|
||||
source for confusion for new users. We use a loader in imgui_impl_opengl3.cpp which may be different
|
||||
from the one your app normally use. Read imgui_impl_opengl3.h for details and how to change it.)
|
||||
|
||||
[example_sdl_vulkan/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl_vulkan/) <BR>
|
||||
SDL2 (Win32, Mac, Linux, etc.) + Vulkan example. <BR>
|
||||
= main.cpp + imgui_impl_sdl.cpp + imgui_impl_vulkan.cpp <BR>
|
||||
This is quite long and tedious, because: Vulkan. <BR>
|
||||
For this example, the main.cpp file exceptionally use helpers function from imgui_impl_vulkan.h/cpp.
|
||||
|
||||
[example_win32_directx9/](https://github.com/ocornut/imgui/blob/master/examples/example_win32_directx9/) <BR>
|
||||
DirectX9 example, Windows only. <BR>
|
||||
= main.cpp + imgui_impl_win32.cpp + imgui_impl_dx9.cpp
|
||||
|
||||
[example_win32_directx10/](https://github.com/ocornut/imgui/blob/master/examples/example_win32_directx10/) <BR>
|
||||
DirectX10 example, Windows only. <BR>
|
||||
= main.cpp + imgui_impl_win32.cpp + imgui_impl_dx10.cpp
|
||||
|
||||
[example_win32_directx11/](https://github.com/ocornut/imgui/blob/master/examples/example_win32_directx11/) <BR>
|
||||
DirectX11 example, Windows only. <BR>
|
||||
= main.cpp + imgui_impl_win32.cpp + imgui_impl_dx11.cpp
|
||||
|
||||
[example_win32_directx12/](https://github.com/ocornut/imgui/blob/master/examples/example_win32_directx12/) <BR>
|
||||
DirectX12 example, Windows only. <BR>
|
||||
= main.cpp + imgui_impl_win32.cpp + imgui_impl_dx12.cpp <BR>
|
||||
This is quite long and tedious, because: DirectX12.
|
||||
|
||||
|
||||
### Miscallaneous
|
||||
|
||||
**Building**
|
||||
|
||||
Unfortunately in 2020 it is still tedious to create and maintain portable build files using external
|
||||
libraries (the kind we're using here to create a window and render 3D triangles) without relying on
|
||||
third party software. For most examples here we choose to provide:
|
||||
- Makefiles for Linux/OSX
|
||||
- Batch files for Visual Studio 2008+
|
||||
- A .sln project file for Visual Studio 2012+
|
||||
- Xcode project files for the Apple examples
|
||||
Please let us know if they don't work with your setup!
|
||||
You can probably just import the imgui_impl_xxx.cpp/.h files into your own codebase or compile those
|
||||
directly with a command-line compiler.
|
||||
|
||||
If you are interested in using Cmake to build and links examples, see:
|
||||
https://github.com/ocornut/imgui/pull/1713 and https://github.com/ocornut/imgui/pull/3027
|
||||
|
||||
**About mouse cursor latency**
|
||||
|
||||
Dear ImGui has no particular extra lag for most behaviors,
|
||||
e.g. the value of 'io.MousePos' provided at the time of NewFrame() will result in windows being moved
|
||||
to the right spot at the time of EndFrame()/Render(). At 60 FPS your experience should be pleasant.
|
||||
|
||||
However, consider that OS mouse cursors are typically drawn through a very specific hardware accelerated
|
||||
path and will feel smoother than the majority of contents rendered via regular graphics API (including,
|
||||
but not limited to Dear ImGui windows). Because UI rendering and interaction happens on the same plane
|
||||
as the mouse, that disconnect may be jarring to particularly sensitive users.
|
||||
You may experiment with enabling the io.MouseDrawCursor flag to request Dear ImGui to draw a mouse cursor
|
||||
using the regular graphics API, to help you visualize the difference between a "hardware" cursor and a
|
||||
regularly rendered software cursor.
|
||||
However, rendering a mouse cursor at 60 FPS will feel sluggish so you likely won't want to enable that at
|
||||
all times. It might be beneficial for the user experience to switch to a software rendered cursor _only_
|
||||
when an interactive drag is in progress.
|
||||
|
||||
Note that some setup or GPU drivers are likely to be causing extra display lag depending on their settings.
|
||||
If you feel that dragging windows feels laggy and you are not sure what the cause is: try to build a simple
|
||||
drawing a flat 2D shape directly under the mouse cursor!
|
||||
|
||||
@ -1,299 +1 @@
|
||||
-----------------------------------------------------------------------
|
||||
dear imgui, v1.79
|
||||
-----------------------------------------------------------------------
|
||||
examples/README.txt
|
||||
(This is the README file for the examples/ folder. See docs/ for more documentation)
|
||||
-----------------------------------------------------------------------
|
||||
|
||||
Dear ImGui is highly portable and only requires a few things to run and render:
|
||||
|
||||
- Providing mouse/keyboard inputs
|
||||
- Uploading the font atlas texture into graphics memory
|
||||
- Providing a render function to render indexed textured triangles
|
||||
- Optional: clipboard support, mouse cursor supports, Windows IME support, etc.
|
||||
- Optional (Advanced,Beta): platform window API to use multi-viewport.
|
||||
|
||||
This is essentially what the example bindings 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 examples bindings which we are describing here (examples/ folder).
|
||||
You should be able to write bindings for pretty much any platform and any 3D graphics API. With some extra
|
||||
effort you can even perform the rendering remotely, on a different machine than the one running the logic.
|
||||
|
||||
This folder contains two things:
|
||||
|
||||
- Example bindings for popular platforms/graphics API, which you can use as is or adapt for your own use.
|
||||
They are the imgui_impl_XXXX files found in the examples/ folder.
|
||||
|
||||
- Example applications (standalone, ready-to-build) using the aforementioned bindings.
|
||||
They are the in the XXXX_example/ sub-folders.
|
||||
|
||||
You can find binaries of some of those example applications at:
|
||||
http://www.dearimgui.org/binaries
|
||||
|
||||
|
||||
---------------------------------------
|
||||
GETTING STARTED
|
||||
---------------------------------------
|
||||
|
||||
- Please read 'PROGRAMMER GUIDE' in imgui.cpp for notes on how to setup Dear ImGui in your codebase.
|
||||
Please read the comments and instruction at the top of each file.
|
||||
Please read FAQ at http://www.dearimgui.org/faq
|
||||
|
||||
- If you are using of the backend provided here, you can add the imgui_impl_xxx.cpp/h files
|
||||
to your project and use them unmodified. Each imgui_impl_xxxx.cpp comes with its own individual
|
||||
Changelog at the top of the .cpp files, so if you want to update them later it will be easier to
|
||||
catch up with what changed.
|
||||
|
||||
- Dear ImGui has no particular extra lag for most behaviors, e.g. the value of 'io.MousePos' provided in
|
||||
NewFrame() will result at the time of EndFrame()/Render() in a moved windows rendered following that mouse
|
||||
movement. At 60 FPS your experience should be pleasant.
|
||||
However, consider that OS mouse cursors are typically drawn through a very specific hardware accelerated
|
||||
path and will feel smoother than the majority of contents rendererd via regular graphics API (including,
|
||||
but not limited to Dear ImGui windows). Because UI rendering and interaction happens on the same plane as
|
||||
the mouse, that disconnect may be jarring to particularly sensitive users.
|
||||
You may experiment with enabling the io.MouseDrawCursor flag to request Dear ImGui to draw a mouse cursor
|
||||
using the regular graphics API, to help you visualize the difference between a "hardware" cursor and a
|
||||
regularly rendered software cursor.
|
||||
However, rendering a mouse cursor at 60 FPS will feel sluggish so you likely won't want to enable that at
|
||||
all times. It might be beneficial for the user experience to switch to a software rendered cursor _only_
|
||||
when an interactive drag is in progress.
|
||||
Note that some setup or GPU drivers are likely to be causing extra display lag depending on their settings.
|
||||
If you feel that dragging windows feels laggy and you are not sure what the cause is: try to build a simple
|
||||
drawing a flat 2D shape directly under the mouse cursor.
|
||||
|
||||
|
||||
---------------------------------------
|
||||
EXAMPLE BINDINGS
|
||||
---------------------------------------
|
||||
|
||||
Most the example bindings are split in 2 parts:
|
||||
|
||||
- The "Platform" bindings, in charge of: mouse/keyboard/gamepad inputs, cursor shape, timing, windowing.
|
||||
Examples: Windows (imgui_impl_win32.cpp), GLFW (imgui_impl_glfw.cpp), SDL2 (imgui_impl_sdl.cpp), etc.
|
||||
|
||||
- The "Renderer" bindings, in charge of: creating the main font texture, rendering imgui draw data.
|
||||
Examples: DirectX11 (imgui_impl_dx11.cpp), GL3 (imgui_impl_opengl3.cpp), Vulkan (imgui_impl_vulkan.cpp), etc.
|
||||
|
||||
- The example _applications_ usually combine 1 platform + 1 renderer binding to create a working program.
|
||||
Examples: the example_win32_directx11/ application combines imgui_impl_win32.cpp + imgui_impl_dx11.cpp.
|
||||
|
||||
- Some bindings for higher level frameworks carry both "Platform" and "Renderer" parts in one file.
|
||||
This is the case for Allegro 5 (imgui_impl_allegro5.cpp), Marmalade (imgui_impl_marmalade5.cpp).
|
||||
|
||||
- If you use your own engine, you may decide to use some of existing bindings and/or rewrite some using
|
||||
your own API. As a recommendation, if you are new to Dear ImGui, try using the existing binding as-is
|
||||
first, before moving on to rewrite some of the code. Although it is tempting to rewrite both of the
|
||||
imgui_impl_xxxx files to fit under your coding style, consider that it is not necessary!
|
||||
In fact, if you are new to Dear ImGui, rewriting them will almost always be harder.
|
||||
|
||||
Example: your engine is built over Windows + DirectX11 but you have your own high-level rendering
|
||||
system layered over DirectX11.
|
||||
Suggestion: step 1: try using imgui_impl_win32.cpp + imgui_impl_dx11.cpp first.
|
||||
Once this work, _if_ you want you can replace the imgui_impl_dx11.cpp code with a custom renderer
|
||||
using your own functions, etc.
|
||||
Please consider using the bindings to the lower-level platform/graphics API as-is.
|
||||
|
||||
Example: your engine is multi-platform (consoles, phones, etc.), you have high-level systems everywhere.
|
||||
Suggestion: step 1: try using a non-portable binding first (e.g. win32 + underlying graphics API)!
|
||||
This is counter-intuitive, but this will get you running faster! Once you better understand how imgui
|
||||
works and is bound, you can rewrite the code using your own systems.
|
||||
|
||||
- Road-map: Dear ImGui 1.80 (WIP currently in the "docking" branch) will allows imgui windows to be
|
||||
seamlessly detached from the main application window. This is achieved using an extra layer to the
|
||||
platform and renderer bindings, 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.
|
||||
When using this feature, the coupling with your OS/renderer becomes much tighter than a regular imgui
|
||||
integration. It is also much more complicated and require more work to integrate correctly.
|
||||
If you are new to imgui and you are trying to integrate it into your application, first try to ignore
|
||||
everything related to Viewport and Platform Windows. You'll be able to come back to it later!
|
||||
Note that if you decide to use unmodified imgui_impl_xxxx.cpp files, you will automatically benefit
|
||||
from improvements and fixes related to viewports and platform windows without extra work on your side.
|
||||
See 'ImGuiPlatformIO' for details.
|
||||
|
||||
|
||||
List of Platforms Bindings 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 back-ends)
|
||||
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 Bindings 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
|
||||
|
||||
List of high-level Frameworks Bindings in this repository: (combine Platform + Renderer)
|
||||
|
||||
imgui_impl_allegro5.cpp
|
||||
imgui_impl_marmalade.cpp
|
||||
|
||||
Note that Dear ImGui works with Emscripten. The examples_emscripten/ app uses imgui_impl_sdl.cpp and
|
||||
imgui_impl_opengl3.cpp, but other combinations are possible.
|
||||
|
||||
Third-party framework, graphics API and languages bindings are listed at:
|
||||
|
||||
https://github.com/ocornut/imgui/wiki/Bindings
|
||||
|
||||
Including backends for:
|
||||
|
||||
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.
|
||||
|
||||
Not sure which to use?
|
||||
Recommended platform/frameworks:
|
||||
|
||||
GLFW https://github.com/glfw/glfw Use imgui_impl_glfw.cpp
|
||||
SDL2 https://www.libsdl.org Use imgui_impl_sdl.cpp
|
||||
Sokol https://github.com/floooh/sokol Use util/sokol_imgui.h in Sokol repository.
|
||||
|
||||
Those will allow you to create portable applications and will solve and abstract away many issues.
|
||||
|
||||
|
||||
---------------------------------------
|
||||
EXAMPLE APPLICATIONS
|
||||
---------------------------------------
|
||||
|
||||
Building:
|
||||
Unfortunately in 2020 it is still tedious to create and maintain portable build files using external
|
||||
libraries (the kind we're using here to create a window and render 3D triangles) without relying on
|
||||
third party software. For most examples here we choose to provide:
|
||||
- Makefiles for Linux/OSX
|
||||
- Batch files for Visual Studio 2008+
|
||||
- A .sln project file for Visual Studio 2012+
|
||||
- Xcode project files for the Apple examples
|
||||
Please let us know if they don't work with your setup!
|
||||
You can probably just import the imgui_impl_xxx.cpp/.h files into your own codebase or compile those
|
||||
directly with a command-line compiler.
|
||||
|
||||
If you are interested in using Cmake to build and links examples, see:
|
||||
https://github.com/ocornut/imgui/pull/1713 and https://github.com/ocornut/imgui/pull/3027
|
||||
|
||||
|
||||
example_allegro5/
|
||||
Allegro 5 example.
|
||||
= main.cpp + imgui_impl_allegro5.cpp
|
||||
|
||||
example_apple_metal/
|
||||
OSX & iOS + Metal.
|
||||
= main.m + imgui_impl_osx.mm + imgui_impl_metal.mm
|
||||
It is based on the "cross-platform" game template provided with Xcode as of Xcode 9.
|
||||
(NB: imgui_impl_osx.mm is currently not as feature complete as other platforms back-ends.
|
||||
You may prefer to use the GLFW Or SDL back-ends, which will also support Windows and Linux.)
|
||||
|
||||
example_apple_opengl2/
|
||||
OSX + OpenGL2.
|
||||
= main.mm + imgui_impl_osx.mm + imgui_impl_opengl2.cpp
|
||||
(NB: imgui_impl_osx.mm is currently not as feature complete as other platforms back-ends.
|
||||
You may prefer to use the GLFW Or SDL back-ends, which will also support Windows and Linux.)
|
||||
|
||||
example_empscripten:
|
||||
Emcripten + SDL2 + OpenGL3+/ES2/ES3 example.
|
||||
= main.cpp + imgui_impl_sdl.cpp + imgui_impl_opengl3.cpp
|
||||
Note that other examples based on SDL or GLFW + OpenGL could easily be modified to work with Emscripten.
|
||||
We provide this to make the Emscripten differences obvious, and have them not pollute all other examples.
|
||||
|
||||
example_glfw_metal/
|
||||
GLFW (Mac) + Metal example.
|
||||
= main.mm + imgui_impl_glfw.cpp + imgui_impl_metal.mm
|
||||
|
||||
example_glfw_opengl2/
|
||||
GLFW + OpenGL2 example (legacy, fixed pipeline).
|
||||
= main.cpp + imgui_impl_glfw.cpp + imgui_impl_opengl2.cpp
|
||||
**DO NOT USE OPENGL2 CODE IF YOUR CODE/ENGINE IS USING MODERN OPENGL (SHADERS, VBO, VAO, etc.)**
|
||||
**Prefer using OPENGL3 code (with gl3w/glew/glad/glad2/glbinding, you can replace the OpenGL function loader)**
|
||||
This code is mostly provided as a reference to learn about Dear ImGui integration, because it is shorter.
|
||||
If your code is using GL3+ context or any semi modern OpenGL calls, using this renderer is likely to
|
||||
make things more complicated, will require your code to reset many OpenGL attributes to their initial
|
||||
state, and might confuse your GPU driver. One star, not recommended.
|
||||
|
||||
example_glfw_opengl3/
|
||||
GLFW (Win32, Mac, Linux) + OpenGL3+/ES2/ES3 example (programmable pipeline).
|
||||
= main.cpp + imgui_impl_glfw.cpp + imgui_impl_opengl3.cpp
|
||||
This uses more modern OpenGL calls and custom shaders.
|
||||
Prefer using that if you are using modern OpenGL in your application (anything with shaders).
|
||||
(Please be mindful that accessing OpenGL3+ functions requires a function loader, which are a frequent
|
||||
source for confusion for new users. We use a loader in imgui_impl_opengl3.cpp which may be different
|
||||
from the one your app normally use. Read imgui_impl_opengl3.h for details and how to change it.)
|
||||
|
||||
example_glfw_vulkan/
|
||||
GLFW (Win32, Mac, Linux) + Vulkan example.
|
||||
= main.cpp + imgui_impl_glfw.cpp + imgui_impl_vulkan.cpp
|
||||
This is quite long and tedious, because: Vulkan.
|
||||
For this example, the main.cpp file exceptionally use helpers function from imgui_impl_vulkan.h/cpp.
|
||||
|
||||
example_glut_opengl2/
|
||||
GLUT (e.g., FreeGLUT on Linux/Windows, GLUT framework on OSX) + OpenGL2.
|
||||
= main.cpp + imgui_impl_glut.cpp + imgui_impl_opengl2.cpp
|
||||
Note that GLUT/FreeGLUT is largely obsolete software, prefer using GLFW or SDL.
|
||||
|
||||
example_marmalade/
|
||||
Marmalade example using IwGx.
|
||||
= main.cpp + imgui_impl_marmalade.cpp
|
||||
|
||||
example_null
|
||||
Null example, compile and link imgui, create context, run headless with no inputs and no graphics output.
|
||||
= main.cpp
|
||||
This is used to quickly test compilation of core imgui files in as many setups as possible.
|
||||
Because this application doesn't create a window nor a graphic context, there's no graphics output.
|
||||
|
||||
example_sdl_directx11/
|
||||
SDL2 + DirectX11 example, Windows only.
|
||||
= main.cpp + imgui_impl_sdl.cpp + imgui_impl_dx11.cpp
|
||||
This to demonstrate usage of DirectX with SDL.
|
||||
|
||||
example_sdl_metal/
|
||||
SDL2 (Mac) + Metal example.
|
||||
= main.mm + imgui_impl_sdl.cpp + imgui_impl_metal.mm
|
||||
|
||||
example_sdl_opengl2/
|
||||
SDL2 (Win32, Mac, Linux etc.) + OpenGL example (legacy, fixed pipeline).
|
||||
= main.cpp + imgui_impl_sdl.cpp + imgui_impl_opengl2.cpp
|
||||
**DO NOT USE OPENGL2 CODE IF YOUR CODE/ENGINE IS USING MODERN OPENGL (SHADERS, VBO, VAO, etc.)**
|
||||
**Prefer using OPENGL3 code (with gl3w/glew/glad/glad2/glbinding, you can replace the OpenGL function loader)**
|
||||
This code is mostly provided as a reference to learn about Dear ImGui integration, because it is shorter.
|
||||
If your code is using GL3+ context or any semi modern OpenGL calls, using this renderer is likely to
|
||||
make things more complicated, will require your code to reset many OpenGL attributes to their initial
|
||||
state, and might confuse your GPU driver. One star, not recommended.
|
||||
|
||||
example_sdl_opengl3/
|
||||
SDL2 (Win32, Mac, Linux, etc.) + OpenGL3+/ES2/ES3 example.
|
||||
= main.cpp + imgui_impl_sdl.cpp + imgui_impl_opengl3.cpp
|
||||
This uses more modern OpenGL calls and custom shaders.
|
||||
Prefer using that if you are using modern OpenGL in your application (anything with shaders).
|
||||
(Please be mindful that accessing OpenGL3+ functions requires a function loader, which are a frequent
|
||||
source for confusion for new users. We use a loader in imgui_impl_opengl3.cpp which may be different
|
||||
from the one your app normally use. Read imgui_impl_opengl3.h for details and how to change it.)
|
||||
|
||||
example_sdl_vulkan/
|
||||
SDL2 (Win32, Mac, Linux, etc.) + Vulkan example.
|
||||
= main.cpp + imgui_impl_sdl.cpp + imgui_impl_vulkan.cpp
|
||||
This is quite long and tedious, because: Vulkan.
|
||||
For this example, the main.cpp file exceptionally use helpers function from imgui_impl_vulkan.h/cpp.
|
||||
|
||||
example_win32_directx9/
|
||||
DirectX9 example, Windows only.
|
||||
= main.cpp + imgui_impl_win32.cpp + imgui_impl_dx9.cpp
|
||||
|
||||
example_win32_directx10/
|
||||
DirectX10 example, Windows only.
|
||||
= main.cpp + imgui_impl_win32.cpp + imgui_impl_dx10.cpp
|
||||
|
||||
example_win32_directx11/
|
||||
DirectX11 example, Windows only.
|
||||
= main.cpp + imgui_impl_win32.cpp + imgui_impl_dx11.cpp
|
||||
|
||||
example_win32_directx12/
|
||||
DirectX12 example, Windows only.
|
||||
= main.cpp + imgui_impl_win32.cpp + imgui_impl_dx12.cpp
|
||||
This is quite long and tedious, because: DirectX12.
|
||||
See EXAMPLES and BACKENDS files in the docs/ folder.
|
||||
|
||||
@ -1,3 +1,3 @@
|
||||
@REM Build for Visual Studio compiler. Run your copy of vcvars32.bat or vcvarsall.bat to setup command-line compiler.
|
||||
mkdir Debug
|
||||
cl /nologo /Zi /MD /I .. /I ..\.. /I ..\libs\glfw\include *.cpp ..\imgui_impl_opengl2.cpp ..\imgui_impl_glfw.cpp ..\..\imgui*.cpp /FeDebug/example_glfw_opengl2.exe /FoDebug/ /link /LIBPATH:..\libs\glfw\lib-vc2010-32 glfw3.lib opengl32.lib gdi32.lib shell32.lib
|
||||
cl /nologo /Zi /MD /I .. /I ..\.. /I ..\libs\glfw\include *.cpp ..\..\backends\imgui_impl_opengl2.cpp ..\..\backends\imgui_impl_glfw.cpp ..\..\imgui*.cpp /FeDebug/example_glfw_opengl2.exe /FoDebug/ /link /LIBPATH:..\libs\glfw\lib-vc2010-32 glfw3.lib opengl32.lib gdi32.lib shell32.lib
|
||||
|
||||
@ -1,3 +1,3 @@
|
||||
@REM Build for Visual Studio compiler. Run your copy of vcvars32.bat or vcvarsall.bat to setup command-line compiler.
|
||||
mkdir Debug
|
||||
cl /nologo /Zi /MD /I .. /I ..\.. /I ..\libs\glfw\include /I ..\libs\gl3w *.cpp ..\imgui_impl_glfw.cpp ..\imgui_impl_opengl3.cpp ..\..\imgui*.cpp ..\libs\gl3w\GL\gl3w.c /FeDebug/example_glfw_opengl3.exe /FoDebug/ /link /LIBPATH:..\libs\glfw\lib-vc2010-32 glfw3.lib opengl32.lib gdi32.lib shell32.lib
|
||||
cl /nologo /Zi /MD /I .. /I ..\.. /I ..\libs\glfw\include /I ..\libs\gl3w *.cpp ..\..\backends\imgui_impl_glfw.cpp ..\..\backends\imgui_impl_opengl3.cpp ..\..\imgui*.cpp ..\libs\gl3w\GL\gl3w.c /FeDebug/example_glfw_opengl3.exe /FoDebug/ /link /LIBPATH:..\libs\glfw\lib-vc2010-32 glfw3.lib opengl32.lib gdi32.lib shell32.lib
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
@REM Build for Visual Studio compiler. Run your copy of vcvars32.bat or vcvarsall.bat to setup command-line compiler.
|
||||
|
||||
mkdir Debug
|
||||
cl /nologo /Zi /MD /I .. /I ..\.. /I ..\libs\glfw\include /I %VULKAN_SDK%\include *.cpp ..\imgui_impl_vulkan.cpp ..\imgui_impl_glfw.cpp ..\..\imgui*.cpp /FeDebug/example_glfw_vulkan.exe /FoDebug/ /link /LIBPATH:..\libs\glfw\lib-vc2010-32 /libpath:%VULKAN_SDK%\lib32 glfw3.lib opengl32.lib gdi32.lib shell32.lib vulkan-1.lib
|
||||
cl /nologo /Zi /MD /I .. /I ..\.. /I ..\libs\glfw\include /I %VULKAN_SDK%\include *.cpp ..\..\backends\imgui_impl_vulkan.cpp ..\..\backends\imgui_impl_glfw.cpp ..\..\imgui*.cpp /FeDebug/example_glfw_vulkan.exe /FoDebug/ /link /LIBPATH:..\libs\glfw\lib-vc2010-32 /libpath:%VULKAN_SDK%\lib32 glfw3.lib opengl32.lib gdi32.lib shell32.lib vulkan-1.lib
|
||||
|
||||
mkdir Release
|
||||
cl /nologo /Zi /MD /Ox /Oi /I .. /I ..\.. /I ..\libs\glfw\include /I %VULKAN_SDK%\include *.cpp ..\imgui_impl_vulkan.cpp ..\imgui_impl_glfw.cpp ..\..\imgui*.cpp /FeRelease/example_glfw_vulkan.exe /FoRelease/ /link /LIBPATH:..\libs\glfw\lib-vc2010-32 /libpath:%VULKAN_SDK%\lib32 glfw3.lib opengl32.lib gdi32.lib shell32.lib vulkan-1.lib
|
||||
cl /nologo /Zi /MD /Ox /Oi /I .. /I ..\.. /I ..\libs\glfw\include /I %VULKAN_SDK%\include *.cpp ..\..\backends\imgui_impl_vulkan.cpp ..\..\backends\imgui_impl_glfw.cpp ..\..\imgui*.cpp /FeRelease/example_glfw_vulkan.exe /FoRelease/ /link /LIBPATH:..\libs\glfw\lib-vc2010-32 /libpath:%VULKAN_SDK%\lib32 glfw3.lib opengl32.lib gdi32.lib shell32.lib vulkan-1.lib
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
@REM Build for Visual Studio compiler. Run your copy of amd64/vcvars32.bat to setup 64-bit command-line compiler.
|
||||
|
||||
mkdir Debug
|
||||
cl /nologo /Zi /MD /I .. /I ..\.. /I ..\libs\glfw\include /I %VULKAN_SDK%\include *.cpp ..\imgui_impl_vulkan.cpp ..\imgui_impl_glfw.cpp ..\..\imgui*.cpp /FeDebug/example_glfw_vulkan.exe /FoDebug/ /link /LIBPATH:..\libs\glfw\lib-vc2010-64 /libpath:%VULKAN_SDK%\lib glfw3.lib opengl32.lib gdi32.lib shell32.lib vulkan-1.lib
|
||||
cl /nologo /Zi /MD /I .. /I ..\.. /I ..\libs\glfw\include /I %VULKAN_SDK%\include *.cpp ..\..\backends\imgui_impl_vulkan.cpp ..\..\backends\imgui_impl_glfw.cpp ..\..\imgui*.cpp /FeDebug/example_glfw_vulkan.exe /FoDebug/ /link /LIBPATH:..\libs\glfw\lib-vc2010-64 /libpath:%VULKAN_SDK%\lib glfw3.lib opengl32.lib gdi32.lib shell32.lib vulkan-1.lib
|
||||
|
||||
mkdir Release
|
||||
cl /nologo /Zi /MD /Ox /Oi /I .. /I ..\.. /I ..\libs\glfw\include /I %VULKAN_SDK%\include *.cpp ..\imgui_impl_vulkan.cpp ..\imgui_impl_glfw.cpp ..\..\imgui*.cpp /FeRelease/example_glfw_vulkan.exe /FoRelease/ /link /LIBPATH:..\libs\glfw\lib-vc2010-64 /libpath:%VULKAN_SDK%\lib glfw3.lib opengl32.lib gdi32.lib shell32.lib vulkan-1.lib
|
||||
cl /nologo /Zi /MD /Ox /Oi /I .. /I ..\.. /I ..\libs\glfw\include /I %VULKAN_SDK%\include *.cpp ..\..\backends\imgui_impl_vulkan.cpp ..\..\backends\imgui_impl_glfw.cpp ..\..\imgui*.cpp /FeRelease/example_glfw_vulkan.exe /FoRelease/ /link /LIBPATH:..\libs\glfw\lib-vc2010-64 /libpath:%VULKAN_SDK%\lib glfw3.lib opengl32.lib gdi32.lib shell32.lib vulkan-1.lib
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
@REM Build for Visual Studio compiler. Run your copy of vcvars32.bat or vcvarsall.bat to setup command-line compiler.
|
||||
mkdir Debug
|
||||
cl /nologo /Zi /MD /I .. /I ..\.. /I "%WindowsSdkDir%Include\um" /I "%WindowsSdkDir%Include\shared" /I "%DXSDK_DIR%Include" /D UNICODE /D _UNICODE *.cpp ..\imgui_impl_win32.cpp ..\imgui_impl_dx10.cpp ..\..\imgui*.cpp /FeDebug/example_win32_directx10.exe /FoDebug/ /link /LIBPATH:"%DXSDK_DIR%/Lib/x86" d3d10.lib d3dcompiler.lib
|
||||
cl /nologo /Zi /MD /I .. /I ..\.. /I "%WindowsSdkDir%Include\um" /I "%WindowsSdkDir%Include\shared" /I "%DXSDK_DIR%Include" /D UNICODE /D _UNICODE *.cpp ..\..\backends\imgui_impl_win32.cpp ..\..\backends\imgui_impl_dx10.cpp ..\..\imgui*.cpp /FeDebug/example_win32_directx10.exe /FoDebug/ /link /LIBPATH:"%DXSDK_DIR%/Lib/x86" d3d10.lib d3dcompiler.lib
|
||||
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue