1-----------------------------------------------------------------------
2 examples/README.txt
3 (This is the README file for the examples/ folder. See docs/ for more documentation)
4-----------------------------------------------------------------------
5
6Dear ImGui is highly portable and only requires a few things to run and render:
7
8 - Providing mouse/keyboard inputs
9 - Uploading the font atlas texture into graphics memory
10 - Providing a render function to render indexed textured triangles
11 - Optional: clipboard support, mouse cursor supports, Windows IME support, etc.
12
13This is essentially what the example bindings in this folder are providing + obligatory portability cruft.
14
15It is important to understand the difference between the core Dear ImGui library (files in the root folder)
16and examples bindings which we are describing here (examples/ folder).
17You should be able to write bindings for pretty much any platform and any 3D graphics API. With some extra
18effort you can even perform the rendering remotely, on a different machine than the one running the logic.
19
20This folder contains two things:
21
22 - Example bindings for popular platforms/graphics API, which you can use as is or adapt for your own use.
23 They are the imgui_impl_XXXX files found in the examples/ folder.
24
25 - Example applications (standalone, ready-to-build) using the aforementioned bindings.
26 They are the in the XXXX_example/ sub-folders.
27
28You can find binaries of some of those example applications at:
29 http://www.miracleworld.net/imgui/binaries
30
31
32---------------------------------------
33 MISC COMMENTS AND SUGGESTIONS
34---------------------------------------
35
36 - Please read 'PROGRAMMER GUIDE' in imgui.cpp for notes on how to setup Dear ImGui in your codebase.
37 Please read the comments and instruction at the top of each file.
38
39 - If you are using of the backend provided here, so you can copy the imgui_impl_xxx.cpp/h files
40 to your project and use them unmodified. Each imgui_impl_xxxx.cpp comes with its own individual
41 ChangeLog at the top of the .cpp files, so if you want to update them later it will be easier to
42 catch up with what changed.
43
44 - Dear ImGui has 0 to 1 frame of lag for most behaviors, at 60 FPS your experience should be pleasant.
45 However, consider that OS mouse cursors are typically drawn through a specific hardware accelerated path
46 and will feel smoother than common GPU rendered contents (including Dear ImGui windows).
47 You may experiment with the io.MouseDrawCursor flag to request Dear ImGui to draw a mouse cursor itself,
48 to visualize the lag between a hardware cursor and a software cursor. However, rendering a mouse cursor
49 at 60 FPS will feel slow. It might be beneficial to the user experience to switch to a software rendered
50 cursor only when an interactive drag is in progress.
51 Note that some setup or GPU drivers are likely to be causing extra lag depending on their settings.
52 If you feel that dragging windows feels laggy and you are not sure who to blame: try to build an
53 application drawing a shape directly under the mouse cursor.
54
55
56---------------------------------------
57 EXAMPLE BINDINGS
58---------------------------------------
59
60Most the example bindings are split in 2 parts:
61
62 - The "Platform" bindings, in charge of: mouse/keyboard/gamepad inputs, cursor shape, timing, windowing.
63 Examples: Windows (imgui_impl_win32.cpp), GLFW (imgui_impl_glfw.cpp), SDL2 (imgui_impl_sdl.cpp)
64
65 - The "Renderer" bindings, in charge of: creating the main font texture, rendering imgui draw data.
66 Examples: DirectX11 (imgui_impl_dx11.cpp), GL3 (imgui_impl_opengl3.cpp), Vulkan (imgui_impl_vulkan.cpp)
67
68 - The example _applications_ usually combine 1 platform + 1 renderer binding to create a working program.
69 Examples: the example_win32_directx11/ application combines imgui_impl_win32.cpp + imgui_impl_dx11.cpp.
70
71 - Some bindings for higher level frameworks carry both "Platform" and "Renderer" parts in one file.
72 This is the case for Allegro 5 (imgui_impl_allegro5.cpp), Marmalade (imgui_impl_marmalade5.cpp).
73
74 - If you use your own engine, you may decide to use some of existing bindings and/or rewrite some using
75 your own API. As a recommendation, if you are new to Dear ImGui, try using the existing binding as-is
76 first, before moving on to rewrite some of the code. Although it is tempting to rewrite both of the
77 imgui_impl_xxxx files to fit under your coding style, consider that it is not necessary!
78 In fact, if you are new to Dear ImGui, rewriting them will almost always be harder.
79
80 Example: your engine is built over Windows + DirectX11 but you have your own high-level rendering
81 system layered over DirectX11.
82 Suggestion: step 1: try using imgui_impl_win32.cpp + imgui_impl_dx11.cpp first.
83 Once this work, _if_ you want you can replace the imgui_impl_dx11.cpp code with a custom renderer
84 using your own functions, etc.
85 Please consider using the bindings to the lower-level platform/graphics API as-is.
86
87 Example: your engine is multi-platform (consoles, phones, etc.), you have high-level systems everywhere.
88 Suggestion: step 1: try using a non-portable binding first (e.g. win32 + underlying graphics API)!
89 This is counter-intuitive, but this will get you running faster! Once you better understand how imgui
90 works and is bound, you can rewrite the code using your own systems.
91
92 - Road-map: Dear ImGui 1.70 (WIP currently in the "viewport" branch) will allows imgui windows to be
93 seamlessly detached from the main application window. This is achieved using an extra layer to the
94 platform and renderer bindings, which allows imgui to communicate platform-specific requests.
95 If you decide to use unmodified imgui_impl_xxxx.cpp files, you will automatically benefit from
96 improvements and fixes related to viewports and platform windows without extra work on your side.
97
98
99List of Platforms Bindings in this repository:
100
101 imgui_impl_glfw.cpp ; GLFW (Windows, macOS, Linux, etc.) http://www.glfw.org/
102 imgui_impl_osx.mm ; macOS native API
103 imgui_impl_sdl.cpp ; SDL2 (Windows, macOS, Linux, iOS, Android) https://www.libsdl.org
104 imgui_impl_win32.cpp ; Win32 native API (Windows)
105 imgui_impl_freeglut.cpp ; FreeGLUT (if you really miss the 90's)
106
107List of Renderer Bindings in this repository:
108
109 imgui_impl_dx9.cpp ; DirectX9
110 imgui_impl_dx10.cpp ; DirectX10
111 imgui_impl_dx11.cpp ; DirectX11
112 imgui_impl_dx12.cpp ; DirectX12
113 imgui_impl_metal.mm ; Metal (with ObjC)
114 imgui_impl_opengl2.cpp ; OpenGL2 (legacy, fixed pipeline <- don't use with modern OpenGL context)
115 imgui_impl_opengl3.cpp ; OpenGL3, OpenGL ES 2, OpenGL ES 3 (modern programmable pipeline)
116 imgui_impl_vulkan.cpp ; Vulkan
117
118List of high-level Frameworks Bindings in this repository: (combine Platform + Renderer)
119
120 imgui_impl_allegro5.cpp
121 imgui_impl_marmalade.cpp
122
123Third-party framework, graphics API and languages bindings are listed at:
124
125 https://github.com/ocornut/imgui/wiki/Bindings
126
127 Languages: C, C#, ChaiScript, D, Go, Haxe, Java, Lua, Odin, Pascal, PureBasic, Python, Rust, Swift...
128 Frameworks: Cinder, Cocoa (OSX), Cocos2d-x, Emscripten, SFML, GML/GameMaker Studio, Irrlicht, Ogre,
129 OpenSceneGraph, openFrameworks, LOVE, NanoRT, Nim Game Lib, Qt3d, SFML, Unreal Engine 4...
130 Miscellaneous: Software Renderer, RemoteImgui, etc.
131
132
133---------------------------------------
134 EXAMPLE APPLICATIONS
135---------------------------------------
136
137Building:
138 Unfortunately in 2018 it is still tedious to create and maintain portable build files using external
139 libraries (the kind we're using here to create a window and render 3D triangles) without relying on
140 third party software. For most examples here I choose to provide:
141 - Makefiles for Linux/OSX
142 - Batch files for Visual Studio 2008+
143 - A .sln project file for Visual Studio 2010+
144 - Xcode project files for the Apple examples
145 Please let me know if they don't work with your setup!
146 You can probably just import the imgui_impl_xxx.cpp/.h files into your own codebase or compile those
147 directly with a command-line compiler.
148
149
150example_win32_directx9/
151 DirectX9 example, Windows only.
152 = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx9.cpp
153
154example_win32_directx10/
155 DirectX10 example, Windows only.
156 = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx10.cpp
157
158example_win32_directx11/
159 DirectX11 example, Windows only.
160 = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx11.cpp
161
162example_win32_directx12/
163 DirectX12 example, Windows only.
164 This is quite long and tedious, because: DirectX12.
165 = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx12.cpp
166
167example_apple_metal/
168 OSX & iOS + Metal.
169 It is based on the "cross-platform" game template provided with Xcode as of Xcode 9.
170 (NB: you may still want to use GLFW or SDL which will also support Windows, Linux along with OSX.)
171 = game template + imgui_impl_osx.mm + imgui_impl_metal.mm
172
173example_apple_opengl2/
174 OSX + OpenGL2.
175 (NB: you may still want to use GLFW or SDL which will also support Windows, Linux along with OSX.)
176 = main.mm + imgui_impl_osx.mm + imgui_impl_opengl2.cpp
177
178example_glfw_opengl2/
179 **DO NOT USE OPENGL2 CODE IF YOUR CODE/ENGINE IS USING MODERN OPENGL (SHADERS, VBO, VAO, etc.)**
180 **Prefer using OPENGL3 code (with gl3w/glew/glad, you can replace the OpenGL function loader)**
181 GLFW + OpenGL2 example (legacy, fixed pipeline).
182 This code is mostly provided as a reference to learn about Dear ImGui integration, because it is shorter.
183 If your code is using GL3+ context or any semi modern OpenGL calls, using this renderer is likely to
184 make things more complicated, will require your code to reset many OpenGL attributes to their initial
185 state, and might confuse your GPU driver. One star, not recommended.
186 = main.cpp + imgui_impl_glfw.cpp + imgui_impl_opengl2.cpp
187
188example_glfw_opengl3/
189 GLFW (Win32, Mac, Linux) + OpenGL3+/ES2/ES3 example (programmable pipeline, binding modern functions with GL3W).
190 This uses more modern OpenGL calls and custom shaders.
191 Prefer using that if you are using modern OpenGL in your application (anything with shaders).
192 = main.cpp + imgui_impl_glfw.cpp + imgui_impl_opengl3.cpp
193
194example_glfw_vulkan/
195 GLFW (Win32, Mac, Linux) + Vulkan example.
196 This is quite long and tedious, because: Vulkan.
197 = main.cpp + imgui_impl_glfw.cpp + imgui_impl_vulkan.cpp
198
199example_sdl_opengl2/
200 **DO NOT USE OPENGL2 CODE IF YOUR CODE/ENGINE IS USING MODERN OPENGL (SHADERS, VBO, VAO, etc.)**
201 **Prefer using OPENGL3 code (with gl3w/glew/glad, you can replace the OpenGL function loader)**
202 SDL2 (Win32, Mac, Linux etc.) + OpenGL example (legacy, fixed pipeline).
203 This code is mostly provided as a reference to learn about Dear ImGui integration, because it is shorter.
204 If your code is using GL3+ context or any semi modern OpenGL calls, using this renderer is likely to
205 make things more complicated, will require your code to reset many OpenGL attributes to their initial
206 state, and might confuse your GPU driver. One star, not recommended.
207 = main.cpp + imgui_impl_sdl.cpp + imgui_impl_opengl2.cpp
208
209example_sdl_opengl3/
210 SDL2 (Win32, Mac, Linux, etc.) + OpenGL3+/ES2/ES3 example.
211 This uses more modern OpenGL calls and custom shaders.
212 Prefer using that if you are using modern OpenGL in your application (anything with shaders).
213 = main.cpp + imgui_impl_sdl.cpp + imgui_impl_opengl3.cpp
214
215example_sdl_vulkan/
216 SDL2 (Win32, Mac, Linux, etc.) + Vulkan example.
217 This is quite long and tedious, because: Vulkan.
218 = main.cpp + imgui_impl_sdl.cpp + imgui_impl_vulkan.cpp
219
220example_allegro5/
221 Allegro 5 example.
222 = main.cpp + imgui_impl_allegro5.cpp
223
224example_freeglut_opengl2/
225 FreeGLUT + OpenGL2.
226 = main.cpp + imgui_impl_freeglut.cpp + imgui_impl_opengl2.cpp
227
228example_marmalade/
229 Marmalade example using IwGx.
230 = main.cpp + imgui_impl_marmalade.cpp
231