| 1 | _(You may browse this at https://github.com/ocornut/imgui/blob/master/docs/EXAMPLES.md or view this file with any Markdown viewer)_ |
| 2 | |
| 3 | ## Dear ImGui: Examples |
| 4 | |
| 5 | **The [examples/](https://github.com/ocornut/imgui/blob/master/examples) folder example applications (standalone, ready-to-build) for variety of |
| 6 | platforms and graphics APIs.** They all use standard backends from the [backends/](https://github.com/ocornut/imgui/blob/master/backends) folder (see [docs/BACKENDS.md](https://github.com/ocornut/imgui/blob/master/docs/BACKENDS.md)). |
| 7 | |
| 8 | The purpose of Examples is to showcase integration with backends, let you try Dear ImGui, and guide you toward |
| 9 | integrating Dear ImGui in your own application/game/engine. |
| 10 | **Once Dear ImGui is setup and running, run and refer to `ImGui::ShowDemoWindow()` in imgui_demo.cpp for usage of the end-user API.** |
| 11 | |
| 12 | You can find Windows binaries for some of those example applications at: |
| 13 | https://www.dearimgui.com/binaries |
| 14 | |
| 15 | |
| 16 | ### Getting Started |
| 17 | |
| 18 | Integration in a typical existing application, should take <20 lines when using standard backends. |
| 19 | |
| 20 | ```cpp |
| 21 | At initialization: |
| 22 | call ImGui::CreateContext() |
| 23 | call ImGui_ImplXXXX_Init() for each backend. |
| 24 | |
| 25 | At the beginning of your frame: |
| 26 | call ImGui_ImplXXXX_NewFrame() for each backend. |
| 27 | call ImGui::NewFrame() |
| 28 | |
| 29 | At the end of your frame: |
| 30 | call ImGui::Render() |
| 31 | call ImGui_ImplXXXX_RenderDrawData() for your Renderer backend. |
| 32 | |
| 33 | At shutdown: |
| 34 | call ImGui_ImplXXXX_Shutdown() for each backend. |
| 35 | call ImGui::DestroyContext() |
| 36 | ``` |
| 37 | |
| 38 | Main resource: |
| 39 | - Read **[Getting Started](https://github.com/ocornut/imgui/wiki/Getting-Started) wiki guide** for detailed examples of how to integrate Dear ImGui in an existing application. |
| 40 | |
| 41 | Additional resources: |
| 42 | - Read FAQ at https://www.dearimgui.com/faq |
| 43 | - Read 'PROGRAMMER GUIDE' section in imgui.cpp. |
| 44 | - Read the comments and instruction at the top of each file. |
| 45 | |
| 46 | If you are using any of the backends provided here, you can add the backends/imgui_impl_xxxx(.cpp,.h) |
| 47 | files to your project and use as-in. Each imgui_impl_xxxx.cpp file comes with its own individual |
| 48 | Changelog, so if you want to update them later it will be easier to catch up with what changed. |
| 49 | |
| 50 | |
| 51 | ### Examples Applications |
| 52 | |
| 53 | [example_allegro5/](https://github.com/ocornut/imgui/blob/master/examples/example_allegro5/) <BR> |
| 54 | Allegro 5 example. <BR> |
| 55 | = main.cpp + imgui_impl_allegro5.cpp |
| 56 | |
| 57 | [example_android_opengl3/](https://github.com/ocornut/imgui/blob/master/examples/example_android_opengl3/) <BR> |
| 58 | Android + OpenGL3 (ES) example. <BR> |
| 59 | = main.cpp + imgui_impl_android.cpp + imgui_impl_opengl3.cpp |
| 60 | |
| 61 | [example_apple_metal/](https://github.com/ocornut/imgui/tree/master/examples/example_apple_metal/) <BR> |
| 62 | OSX & iOS + Metal example. <BR> |
| 63 | = main.m + imgui_impl_osx.mm + imgui_impl_metal.mm <BR> |
| 64 | It is based on the "cross-platform" game template provided with Xcode as of Xcode 9. |
| 65 | (NB: imgui_impl_osx.mm is currently not as feature complete as other platforms backends. |
| 66 | You may prefer to use the GLFW Or SDL backends, which will also support Windows and Linux.) |
| 67 | |
| 68 | [example_apple_opengl2/](https://github.com/ocornut/imgui/blob/master/examples/example_apple_opengl2/) <BR> |
| 69 | OSX + OpenGL2 example. <BR> |
| 70 | = main.mm + imgui_impl_osx.mm + imgui_impl_opengl2.cpp <BR> |
| 71 | (NB: imgui_impl_osx.mm is currently not as feature complete as other platforms backends. |
| 72 | You may prefer to use the GLFW Or SDL backends, which will also support Windows and Linux.) |
| 73 | |
| 74 | [example_glfw_wgpu/](https://github.com/ocornut/imgui/blob/master/examples/example_glfw_wgpu/) <BR> |
| 75 | GLFW + WebGPU example. Supports Emscripten (web), Dawn (native), WGPU (native). <BR> |
| 76 | = main.cpp + imgui_impl_glfw.cpp + imgui_impl_wgpu.cpp |
| 77 | Note that the 'example_glfw_opengl3' and 'example_sdl2_opengl3' examples also supports Emscripten! |
| 78 | |
| 79 | [example_glfw_metal/](https://github.com/ocornut/imgui/blob/master/examples/example_glfw_metal/) <BR> |
| 80 | GLFW (Mac) + Metal example. <BR> |
| 81 | = main.mm + imgui_impl_glfw.cpp + imgui_impl_metal.mm |
| 82 | |
| 83 | [example_glfw_opengl2/](https://github.com/ocornut/imgui/blob/master/examples/example_glfw_opengl2/) <BR> |
| 84 | GLFW + OpenGL2 example (legacy, fixed pipeline). <BR> |
| 85 | = main.cpp + imgui_impl_glfw.cpp + imgui_impl_opengl2.cpp <BR> |
| 86 | **DO NOT USE THIS IF YOUR CODE/ENGINE IS USING MODERN GL or WEBGL (SHADERS, VBO, VAO, etc.)** <BR> |
| 87 | This code is mostly provided as a reference to learn about Dear ImGui integration, because it is shorter. |
| 88 | If your code is using GL3+ context or any semi modern GL calls, using this renderer is likely to |
| 89 | make things more complicated, will require your code to reset many GL attributes to their initial |
| 90 | state, and might confuse your GPU driver. One star, not recommended. |
| 91 | |
| 92 | [example_glfw_opengl3/](https://github.com/ocornut/imgui/blob/master/examples/example_glfw_opengl3/) <BR> |
| 93 | GLFW (Win32, Mac, Linux) + OpenGL3+/ES2/ES3 example (modern, programmable pipeline). <BR> |
| 94 | = main.cpp + imgui_impl_glfw.cpp + imgui_impl_opengl3.cpp <BR> |
| 95 | This uses more modern GL calls and custom shaders.<BR> |
| 96 | This support building with Emscripten and targeting WebGL.<BR> |
| 97 | Prefer using that if you are using modern GL or WebGL in your application. |
| 98 | |
| 99 | [example_glfw_vulkan/](https://github.com/ocornut/imgui/blob/master/examples/example_glfw_vulkan/) <BR> |
| 100 | GLFW (Win32, Mac, Linux) + Vulkan example. <BR> |
| 101 | = main.cpp + imgui_impl_glfw.cpp + imgui_impl_vulkan.cpp <BR> |
| 102 | This is quite long and tedious, because: Vulkan. |
| 103 | For this example, the main.cpp file exceptionally use helpers function from imgui_impl_vulkan.h/cpp. |
| 104 | |
| 105 | [example_glut_opengl2/](https://github.com/ocornut/imgui/blob/master/examples/example_glut_opengl2/) <BR> |
| 106 | GLUT (e.g., FreeGLUT on Linux/Windows, GLUT framework on OSX) + OpenGL2 example. <BR> |
| 107 | = main.cpp + imgui_impl_glut.cpp + imgui_impl_opengl2.cpp <BR> |
| 108 | Note that GLUT/FreeGLUT is largely obsolete software, prefer using GLFW or SDL. |
| 109 | |
| 110 | [example_null/](https://github.com/ocornut/imgui/blob/master/examples/example_null/) <BR> |
| 111 | Null example, compile and link imgui, create context, run headless with no inputs and no graphics output. <BR> |
| 112 | = main.cpp + imgui_impl_null.cpp<BR> |
| 113 | This is used to quickly test compilation of core imgui files in as many setups as possible. |
| 114 | Because this application doesn't create a window nor a graphic context, there's no graphics output. |
| 115 | Please note that imgui_impl_null itself is a rather empty backend. We provide it for consistency but |
| 116 | it is similarly easy to create a skeleton application without the null backend. |
| 117 | |
| 118 | [example_sdl2_directx11/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl2_directx11/) <BR> |
| 119 | SDL2 + DirectX11 example, Windows only. <BR> |
| 120 | = main.cpp + imgui_impl_sdl2.cpp + imgui_impl_dx11.cpp <BR> |
| 121 | This to demonstrate usage of DirectX with SDL2. |
| 122 | |
| 123 | [example_sdl2_metal/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl2_metal/) <BR> |
| 124 | SDL2 + Metal example, Mac only. <BR> |
| 125 | = main.mm + imgui_impl_sdl2.cpp + imgui_impl_metal.mm |
| 126 | |
| 127 | [example_sdl2_opengl2/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl2_opengl2/) <BR> |
| 128 | SDL2 (Win32, Mac, Linux etc.) + OpenGL example (legacy, fixed pipeline). <BR> |
| 129 | = main.cpp + imgui_impl_sdl2.cpp + imgui_impl_opengl2.cpp <BR> |
| 130 | **DO NOT USE OPENGL2 CODE IF YOUR CODE/ENGINE IS USING GL OR WEBGL (SHADERS, VBO, VAO, etc.)** <BR> |
| 131 | This code is mostly provided as a reference to learn about Dear ImGui integration, because it is shorter. |
| 132 | If your code is using GL3+ context or any semi modern GL calls, using this renderer is likely to |
| 133 | make things more complicated, will require your code to reset many GL attributes to their initial |
| 134 | state, and might confuse your GPU driver. One star, not recommended. |
| 135 | |
| 136 | [example_sdl2_opengl3/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl2_opengl3/) <BR> |
| 137 | SDL2 (Win32, Mac, Linux, etc.) + OpenGL3+/ES2/ES3 example. <BR> |
| 138 | = main.cpp + imgui_impl_sdl2.cpp + imgui_impl_opengl3.cpp <BR> |
| 139 | This uses more modern GL calls and custom shaders. <BR> |
| 140 | This support building with Emscripten and targeting WebGL.<BR> |
| 141 | Prefer using that if you are using modern GL or WebGL in your application. |
| 142 | |
| 143 | [example_sdl2_sdlrenderer2/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl2_sdlrenderer2/) <BR> |
| 144 | SDL2 (Win32, Mac, Linux, etc.) + SDL_Renderer for SDL2 example.<BR> |
| 145 | = main.cpp + imgui_impl_sdl2.cpp + imgui_impl_sdlrenderer2.cpp <BR> |
| 146 | This requires SDL 2.0.18+ (released November 2021) <BR> |
| 147 | |
| 148 | [example_sdl2_vulkan/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl2_vulkan/) <BR> |
| 149 | SDL2 (Win32, Mac, Linux, etc.) + Vulkan example. <BR> |
| 150 | = main.cpp + imgui_impl_sdl2.cpp + imgui_impl_vulkan.cpp <BR> |
| 151 | This is quite long and tedious, because: Vulkan. <BR> |
| 152 | For this example, the main.cpp file exceptionally use helpers function from imgui_impl_vulkan.h/cpp. |
| 153 | |
| 154 | [example_sdl2_wgpu/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl2_wgpu/) <BR> |
| 155 | SDL2 + WebGPU example. Supports Emscripten (web), Dawn (native), WGPU (native). <BR> |
| 156 | = main.cpp + imgui_impl_sdl2.cpp + imgui_impl_wgpu.cpp |
| 157 | (note that the 'example_sdl2_opengl3' example also supports Emscripten!) |
| 158 | |
| 159 | [example_sdl3_directx11/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl3_directx11/) <BR> |
| 160 | SDL3 + DirectX11 examples, Windows only. <BR> |
| 161 | = main.cpp + imgui_impl_sdl3.cpp + imgui_impl_dx11.cpp <BR> |
| 162 | |
| 163 | [example_sdl3_metal/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl3_metal/) <BR> |
| 164 | SDL3 + Metal example, Mac only. <BR> |
| 165 | = main.cpp + imgui_impl_sdl3.cpp + imgui_impl_metal.mm <BR> |
| 166 | |
| 167 | [example_sdl3_opengl3/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl3_opengl3/) <BR> |
| 168 | SDL3 (Win32, Mac, Linux, etc.) + OpenGL3+/ES2/ES3 example. <BR> |
| 169 | = main.cpp + imgui_impl_sdl3.cpp + imgui_impl_opengl3.cpp <BR> |
| 170 | This uses more modern GL calls and custom shaders. <BR> |
| 171 | This support building with Emscripten and targeting WebGL.<BR> |
| 172 | |
| 173 | [example_sdl3_sdlgpu3/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl3_sdlgpu3/) <BR> |
| 174 | SDL3 (Win32, Mac, Linux, etc.) + SDL_GPU for SDL3 example.<BR> |
| 175 | = main.cpp + imgui_impl_sdl3.cpp + imgui_impl_sdlrenderer3.cpp <BR> |
| 176 | |
| 177 | [example_sdl3_sdlrenderer3/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl3_sdlrenderer3/) <BR> |
| 178 | SDL3 (Win32, Mac, Linux, etc.) + SDL_Renderer for SDL3 example.<BR> |
| 179 | = main.cpp + imgui_impl_sdl3.cpp + imgui_impl_sdlrenderer3.cpp <BR> |
| 180 | |
| 181 | [example_sdl3_vulkan/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl3_vulkan/) <BR> |
| 182 | SDL3 (Win32, Mac, Linux, etc.) + Vulkan example. <BR> |
| 183 | = main.cpp + imgui_impl_sdl3.cpp + imgui_impl_vulkan.cpp <BR> |
| 184 | This is quite long and tedious, because: Vulkan. <BR> |
| 185 | For this example, the main.cpp file exceptionally use helpers function from imgui_impl_vulkan.h/cpp. |
| 186 | |
| 187 | [example_sdl3_wgpu/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl3_wgpu/) <BR> |
| 188 | SDL3 + WebGPU example. Supports Emscripten (web), Dawn (native), WGPU (native). <BR> |
| 189 | = main.cpp + imgui_impl_sdl3.cpp + imgui_impl_wgpu.cpp |
| 190 | (note that the 'example_sdl3_opengl3' example also supports Emscripten!) |
| 191 | |
| 192 | [example_win32_directx9/](https://github.com/ocornut/imgui/blob/master/examples/example_win32_directx9/) <BR> |
| 193 | DirectX9 example, Windows only. <BR> |
| 194 | = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx9.cpp |
| 195 | |
| 196 | [example_win32_directx10/](https://github.com/ocornut/imgui/blob/master/examples/example_win32_directx10/) <BR> |
| 197 | DirectX10 example, Windows only. <BR> |
| 198 | = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx10.cpp |
| 199 | |
| 200 | [example_win32_directx11/](https://github.com/ocornut/imgui/blob/master/examples/example_win32_directx11/) <BR> |
| 201 | DirectX11 example, Windows only. <BR> |
| 202 | = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx11.cpp |
| 203 | |
| 204 | [example_win32_directx12/](https://github.com/ocornut/imgui/blob/master/examples/example_win32_directx12/) <BR> |
| 205 | DirectX12 example, Windows only. <BR> |
| 206 | = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx12.cpp <BR> |
| 207 | This is quite long and tedious, because: DirectX12. |
| 208 | |
| 209 | [example_win32_opengl3/](https://github.com/ocornut/imgui/blob/master/examples/example_win32_opengl3/) <BR> |
| 210 | Raw Windows + OpenGL3 example (modern, programmable pipeline) <BR> |
| 211 | = main.cpp + imgui_impl_win32.cpp + imgui_impl_opengl3.cpp <BR> |
| 212 | |
| 213 | [example_win32_vulkan/](https://github.com/ocornut/imgui/blob/master/examples/example_win32_vulkan/) <BR> |
| 214 | Raw Windows + Vulkan example <BR> |
| 215 | = main.cpp + imgui_impl_win32.cpp + imgui_impl_vulkan.cpp <BR> |
| 216 | |
| 217 | |
| 218 | ### Miscellaneous |
| 219 | |
| 220 | **Building** |
| 221 | |
| 222 | Unfortunately, nowadays it is still tedious to create and maintain portable build files using external |
| 223 | libraries (the kind we're using here to create a window and render 3D triangles) without relying on |
| 224 | third party software and build systems. For most examples here we choose to provide: |
| 225 | - Makefiles for Linux/OSX |
| 226 | - Batch files for Visual Studio 2008+ |
| 227 | - A .sln project file for Visual Studio 2012+ |
| 228 | - Xcode project files for the Apple examples |
| 229 | Please let us know if they don't work with your setup! |
| 230 | You can probably just import the imgui_impl_xxx.cpp/.h files into your own codebase or compile those |
| 231 | directly with a command-line compiler. |
| 232 | |
| 233 | If you are interested in using Cmake to build and links examples, see: |
| 234 | https://github.com/ocornut/imgui/pull/1713 and https://github.com/ocornut/imgui/pull/3027 |
| 235 | |
| 236 | **About mouse cursor latency** |
| 237 | |
| 238 | Dear ImGui does not introduce significant extra lag for most behaviors, |
| 239 | e.g. the last value passed to 'io.AddMousePosEvent()' before NewFrame() will result in windows being moved |
| 240 | to the right spot at the time of EndFrame()/Render(). At 60 FPS your experience should be pleasant. |
| 241 | |
| 242 | However, consider that OS mouse cursors are typically rendered through a very specific hardware-accelerated |
| 243 | path, which makes them feel smoother than the majority of content rendered via regular graphics API (including, |
| 244 | but not limited to Dear ImGui windows). Because UI rendering and interaction happens on the same plane |
| 245 | as the mouse, that disconnect may be jarring to particularly sensitive users. |
| 246 | You may experiment with enabling the io.MouseDrawCursor flag to request Dear ImGui to draw a mouse cursor |
| 247 | using the regular graphics API, to help you visualize the difference between a "hardware" cursor and a |
| 248 | regularly rendered software cursor. |
| 249 | However, rendering a mouse cursor at 60 FPS will feel sluggish, so you likely won't want to enable that at |
| 250 | all times. It might be beneficial for the user experience to switch to a software rendered cursor _only_ |
| 251 | when an interactive drag is in progress. |
| 252 | |
| 253 | Note that some setup configurations or GPU drivers may introduce additional display lag depending on their settings. |
| 254 | If you notice that dragging windows is laggy and you are not sure what the cause is: try drawing a simple |
| 255 | 2D shape directly under the mouse cursor to help identify the issue! |
| 256 | |