| ----------------------------------------------------------------------- |
| dear imgui, v1.80 WIP |
| Examples applications |
| ----------------------------------------------------------------------- |
| (See docs/ and backends/ for more documentation) |
| ----------------------------------------------------------------------- |
| |
| This folder contains example applications (standalone, ready-to-build) for variety of |
| platforms and graphics APIs. They all use standard backends from the 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 + 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. |
| |
| |
| --------------------------------------- |
| EXAMPLE APPLICATIONS |
| --------------------------------------- |
| |
| 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 backends. |
| You may prefer to use the GLFW Or SDL backends, 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 backends. |
| You may prefer to use the GLFW Or SDL backends, 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. |
| |
| |
| --------------------------------------- |
| MISCELLANEOUS |
| --------------------------------------- |
| |
| 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 |
| |
| Things feeling laggy? |
| |
| 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! |
| |