imgui

FORK: Dear ImGui: Bloat-free Graphical User interface for C++ with minimal dependencies
git clone https://git.neptards.moe/neptards/imgui.git
Log | Files | Refs

EXAMPLES.md (13701B)

      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 [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   http://www.dearimgui.org/binaries
     14 
     15 
     16 ### Getting Started
     17 
     18 Integration in a typical existing application, should take <20 lines when using standard backends.
     19 
     20     At initialization:
     21       call ImGui::CreateContext()
     22       call ImGui_ImplXXXX_Init() for each backend.
     23 
     24     At the beginning of your frame:
     25       call ImGui_ImplXXXX_NewFrame() for each backend.
     26       call ImGui::NewFrame()
     27 
     28     At the end of your frame:
     29       call ImGui::Render()
     30       call ImGui_ImplXXXX_RenderDrawData() for your Renderer backend.
     31 
     32     At shutdown:
     33       call ImGui_ImplXXXX_Shutdown() for each backend.
     34       call ImGui::DestroyContext()
     35 
     36 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)):
     37 
     38     // Create a Dear ImGui context, setup some options
     39     ImGui::CreateContext();
     40     ImGuiIO& io = ImGui::GetIO();
     41     io.ConfigFlags |= ImGuiConfigFlags_NavEnableKeyboard; // Enable some options
     42 
     43     // Initialize Platform + Renderer backends (here: using imgui_impl_win32.cpp + imgui_impl_dx11.cpp)
     44     ImGui_ImplWin32_Init(my_hwnd);
     45     ImGui_ImplDX11_Init(my_d3d_device, my_d3d_device_context);
     46 
     47     // Application main loop
     48     while (true)
     49     {
     50         // Beginning of frame: update Renderer + Platform backend, start Dear ImGui frame
     51         ImGui_ImplDX11_NewFrame();
     52         ImGui_ImplWin32_NewFrame();
     53         ImGui::NewFrame();
     54 
     55         // Any application code here
     56         ImGui::Text("Hello, world!");
     57 
     58         // End of frame: render Dear ImGui
     59         ImGui::Render();
     60         ImGui_ImplDX11_RenderDrawData(ImGui::GetDrawData());
     61 
     62         // Swap
     63         g_pSwapChain->Present(1, 0);
     64     }
     65 
     66     // Shutdown
     67     ImGui_ImplDX11_Shutdown();
     68     ImGui_ImplWin32_Shutdown();
     69     ImGui::DestroyContext();
     70 
     71 Please read 'PROGRAMMER GUIDE' in imgui.cpp for notes on how to setup Dear ImGui in your codebase.
     72 Please read the comments and instruction at the top of each file.
     73 Please read FAQ at http://www.dearimgui.org/faq
     74 
     75 If you are using of the backend provided here, you can add the backends/imgui_impl_xxxx(.cpp,.h)
     76 files to your project and use as-in. Each imgui_impl_xxxx.cpp file comes with its own individual
     77 Changelog, so if you want to update them later it will be easier to catch up with what changed.
     78 
     79 
     80 ### Examples Applications
     81 
     82 [example_allegro5/](https://github.com/ocornut/imgui/blob/master/examples/example_allegro5/) <BR>
     83 Allegro 5 example. <BR>
     84 = main.cpp + imgui_impl_allegro5.cpp
     85 
     86 [example_android_opengl3/](https://github.com/ocornut/imgui/blob/master/examples/example_android_opengl3/) <BR>
     87 Android + OpenGL3 (ES) example. <BR>
     88 = main.cpp + imgui_impl_android.cpp + imgui_impl_opengl3.cpp
     89 
     90 [example_apple_metal/](https://github.com/ocornut/imgui/blob/master/examples/example_metal/) <BR>
     91 OSX & iOS + Metal example. <BR>
     92 = main.m + imgui_impl_osx.mm + imgui_impl_metal.mm <BR>
     93 It is based on the "cross-platform" game template provided with Xcode as of Xcode 9.
     94 (NB: imgui_impl_osx.mm is currently not as feature complete as other platforms backends.
     95 You may prefer to use the GLFW Or SDL backends, which will also support Windows and Linux.)
     96 
     97 [example_apple_opengl2/](https://github.com/ocornut/imgui/blob/master/examples/example_apple_opengl2/) <BR>
     98 OSX + OpenGL2 example. <BR>
     99 = main.mm + imgui_impl_osx.mm + imgui_impl_opengl2.cpp <BR>
    100 (NB: imgui_impl_osx.mm is currently not as feature complete as other platforms backends.
    101  You may prefer to use the GLFW Or SDL backends, which will also support Windows and Linux.)
    102 
    103 [example_emscripten_opengl3/](https://github.com/ocornut/imgui/blob/master/examples/example_emscripten_opengl3/) <BR>
    104 Emcripten + SDL2 + OpenGL3+/ES2/ES3 example. <BR>
    105 = main.cpp + imgui_impl_sdl.cpp + imgui_impl_opengl3.cpp <BR>
    106 Note that other examples based on SDL or GLFW + OpenGL could easily be modified to work with Emscripten.
    107 We provide this to make the Emscripten differences obvious, and have them not pollute all other examples.
    108 
    109 [example_emscripten_wgpu/](https://github.com/ocornut/imgui/blob/master/examples/example_emscripten_wgpu/) <BR>
    110 Emcripten + GLFW + WebGPU example. <BR>
    111 = main.cpp + imgui_impl_glfw.cpp + imgui_impl_wgpu.cpp
    112 
    113 [example_glfw_metal/](https://github.com/ocornut/imgui/blob/master/examples/example_glfw_metal/) <BR>
    114 GLFW (Mac) + Metal example. <BR>
    115 = main.mm + imgui_impl_glfw.cpp + imgui_impl_metal.mm
    116 
    117 [example_glfw_opengl2/](https://github.com/ocornut/imgui/blob/master/examples/example_glfw_opengl2/) <BR>
    118 GLFW + OpenGL2 example (legacy, fixed pipeline). <BR>
    119 = main.cpp + imgui_impl_glfw.cpp + imgui_impl_opengl2.cpp <BR>
    120 **DO NOT USE OPENGL2 CODE IF YOUR CODE/ENGINE IS USING MODERN OPENGL (SHADERS, VBO, VAO, etc.)** <BR>
    121 **Prefer using OPENGL3 code (with gl3w/glew/glad/glad2/glbinding, you can replace the OpenGL function loader)** <BR>
    122 This code is mostly provided as a reference to learn about Dear ImGui integration, because it is shorter.
    123 If your code is using GL3+ context or any semi modern OpenGL calls, using this renderer is likely to
    124 make things more complicated, will require your code to reset many OpenGL attributes to their initial
    125 state, and might confuse your GPU driver. One star, not recommended.
    126 
    127 [example_glfw_opengl3/](https://github.com/ocornut/imgui/blob/master/examples/example_glfw_opengl3/) <BR>
    128 GLFW (Win32, Mac, Linux) + OpenGL3+/ES2/ES3 example (programmable pipeline). <BR>
    129 = main.cpp + imgui_impl_glfw.cpp + imgui_impl_opengl3.cpp <BR>
    130 This uses more modern OpenGL calls and custom shaders. <BR>
    131 Prefer using that if you are using modern OpenGL in your application (anything with shaders).
    132 (Please be mindful that accessing OpenGL3+ functions requires a function loader, which are a frequent
    133 source for confusion for new users. We use a loader in imgui_impl_opengl3.cpp which may be different
    134 from the one your app normally use. Read imgui_impl_opengl3.h for details and how to change it.)
    135 
    136 [example_glfw_vulkan/](https://github.com/ocornut/imgui/blob/master/examples/example_glfw_vulkan/) <BR>
    137 GLFW (Win32, Mac, Linux) + Vulkan example. <BR>
    138 = main.cpp + imgui_impl_glfw.cpp + imgui_impl_vulkan.cpp <BR>
    139 This is quite long and tedious, because: Vulkan.
    140 For this example, the main.cpp file exceptionally use helpers function from imgui_impl_vulkan.h/cpp.
    141 
    142 [example_glut_opengl2/](https://github.com/ocornut/imgui/blob/master/examples/example_glut_opengl2/) <BR>
    143 GLUT (e.g., FreeGLUT on Linux/Windows, GLUT framework on OSX) + OpenGL2 example. <BR>
    144 = main.cpp + imgui_impl_glut.cpp + imgui_impl_opengl2.cpp <BR>
    145 Note that GLUT/FreeGLUT is largely obsolete software, prefer using GLFW or SDL.
    146 
    147 [example_marmalade/](https://github.com/ocornut/imgui/blob/master/examples/example_marmalade/) <BR>
    148 Marmalade example using IwGx. <BR>
    149 = main.cpp + imgui_impl_marmalade.cpp
    150 
    151 [example_null/](https://github.com/ocornut/imgui/blob/master/examples/example_null/) <BR>
    152 Null example, compile and link imgui, create context, run headless with no inputs and no graphics output. <BR>
    153 = main.cpp <BR>
    154 This is used to quickly test compilation of core imgui files in as many setups as possible.
    155 Because this application doesn't create a window nor a graphic context, there's no graphics output.
    156 
    157 [example_sdl_directx11/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl_directx11/) <BR>
    158 SDL2 + DirectX11 example, Windows only. <BR>
    159 = main.cpp + imgui_impl_sdl.cpp + imgui_impl_dx11.cpp <BR>
    160 This to demonstrate usage of DirectX with SDL.
    161 
    162 [example_sdl_metal/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl_metal/) <BR>
    163 SDL2 (Mac) + Metal example. <BR>
    164 = main.mm + imgui_impl_sdl.cpp + imgui_impl_metal.mm
    165 
    166 [example_sdl_opengl2/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl_opengl2/) <BR>
    167 SDL2 (Win32, Mac, Linux etc.) + OpenGL example (legacy, fixed pipeline). <BR>
    168 = main.cpp + imgui_impl_sdl.cpp + imgui_impl_opengl2.cpp <BR>
    169 **DO NOT USE OPENGL2 CODE IF YOUR CODE/ENGINE IS USING MODERN OPENGL (SHADERS, VBO, VAO, etc.)** <BR>
    170 **Prefer using OPENGL3 code (with gl3w/glew/glad/glad2/glbinding, you can replace the OpenGL function loader)** <BR>
    171 This code is mostly provided as a reference to learn about Dear ImGui integration, because it is shorter.
    172 If your code is using GL3+ context or any semi modern OpenGL calls, using this renderer is likely to
    173 make things more complicated, will require your code to reset many OpenGL attributes to their initial
    174 state, and might confuse your GPU driver. One star, not recommended.
    175 
    176 [example_sdl_opengl3/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl_opengl3/) <BR>
    177 SDL2 (Win32, Mac, Linux, etc.) + OpenGL3+/ES2/ES3 example. <BR>
    178 = main.cpp + imgui_impl_sdl.cpp + imgui_impl_opengl3.cpp <BR>
    179 This uses more modern OpenGL calls and custom shaders. <BR>
    180 Prefer using that if you are using modern OpenGL in your application (anything with shaders).
    181 (Please be mindful that accessing OpenGL3+ functions requires a function loader, which are a frequent
    182 source for confusion for new users. We use a loader in imgui_impl_opengl3.cpp which may be different
    183 from the one your app normally use. Read imgui_impl_opengl3.h for details and how to change it.)
    184 
    185 [example_sdl_vulkan/](https://github.com/ocornut/imgui/blob/master/examples/example_sdl_vulkan/) <BR>
    186 SDL2 (Win32, Mac, Linux, etc.) + Vulkan example. <BR>
    187 = main.cpp + imgui_impl_sdl.cpp + imgui_impl_vulkan.cpp <BR>
    188 This is quite long and tedious, because: Vulkan. <BR>
    189 For this example, the main.cpp file exceptionally use helpers function from imgui_impl_vulkan.h/cpp.
    190 
    191 [example_win32_directx9/](https://github.com/ocornut/imgui/blob/master/examples/example_win32_directx9/) <BR>
    192 DirectX9 example, Windows only. <BR>
    193 = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx9.cpp
    194 
    195 [example_win32_directx10/](https://github.com/ocornut/imgui/blob/master/examples/example_win32_directx10/) <BR>
    196 DirectX10 example, Windows only. <BR>
    197 = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx10.cpp
    198 
    199 [example_win32_directx11/](https://github.com/ocornut/imgui/blob/master/examples/example_win32_directx11/) <BR>
    200 DirectX11 example, Windows only. <BR>
    201 = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx11.cpp
    202 
    203 [example_win32_directx12/](https://github.com/ocornut/imgui/blob/master/examples/example_win32_directx12/) <BR>
    204 DirectX12 example, Windows only. <BR>
    205 = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx12.cpp <BR>
    206 This is quite long and tedious, because: DirectX12.
    207 
    208 
    209 ### Miscallaneous
    210 
    211 **Building**
    212 
    213 Unfortunately nowadays it is still tedious to create and maintain portable build files using external
    214 libraries (the kind we're using here to create a window and render 3D triangles) without relying on
    215 third party software and build systems. For most examples here we choose to provide:
    216  - Makefiles for Linux/OSX
    217  - Batch files for Visual Studio 2008+
    218  - A .sln project file for Visual Studio 2012+
    219  - Xcode project files for the Apple examples
    220 Please let us know if they don't work with your setup!
    221 You can probably just import the imgui_impl_xxx.cpp/.h files into your own codebase or compile those
    222 directly with a command-line compiler.
    223 
    224 If you are interested in using Cmake to build and links examples, see:
    225   https://github.com/ocornut/imgui/pull/1713 and https://github.com/ocornut/imgui/pull/3027
    226 
    227 **About mouse cursor latency**
    228 
    229 Dear ImGui has no particular extra lag for most behaviors,
    230 e.g. the value of 'io.MousePos' provided at the time of NewFrame() will result in windows being moved
    231 to the right spot at the time of EndFrame()/Render(). At 60 FPS your experience should be pleasant.
    232 
    233 However, consider that OS mouse cursors are typically drawn through a very specific hardware accelerated
    234 path and will feel smoother than the majority of contents rendered via regular graphics API (including,
    235 but not limited to Dear ImGui windows). Because UI rendering and interaction happens on the same plane
    236 as the mouse, that disconnect may be jarring to particularly sensitive users.
    237 You may experiment with enabling the io.MouseDrawCursor flag to request Dear ImGui to draw a mouse cursor
    238 using the regular graphics API, to help you visualize the difference between a "hardware" cursor and a
    239 regularly rendered software cursor.
    240 However, rendering a mouse cursor at 60 FPS will feel sluggish so you likely won't want to enable that at
    241 all times. It might be beneficial for the user experience to switch to a software rendered cursor _only_
    242 when an interactive drag is in progress.
    243 
    244 Note that some setup or GPU drivers are likely to be causing extra display lag depending on their settings.
    245 If you feel that dragging windows feels laggy and you are not sure what the cause is: try to build a simple
    246 drawing a flat 2D shape directly under the mouse cursor!
    247