tomato/docs/EXAMPLES.md
Green Sky 293f4fd0a0 Squashed 'external/imgui/imgui/' changes from 6ccc561a2ab..00ad3c65bc2
00ad3c65bc2 Version 1.90.7
f814ef816fb Commented out CaptureKeyboardFromApp(), CaptureMouseFromApp(). Commented out obsolete IsKeyPressedMap() from imgui_internal.h (can call IsKeyPressed). Comments
b9084949bd7 Fixed typo in IsMouseDragging and GetMouseDragDelta's documentation. (#7620)
86931393a36 Shortcuts: Revert "SetShortcutRouting: require explicit routing. (#456)
7832e6a70e6 Shortcuts: Routing: fixed mixed keys<>chars filtering not applying on global routes. (#456, #7618)
85d982011e9 Shortcuts: fixed priority of route calculation (higher first). (#456, #7618)
ce4e210dcb6 Shotcuts: renamed ImGuiInputFlags_RouteGlobalOverFocused -> ImGuiInputFlags_RouteOverFocused, ImGuiInputFlags_RouteGlobalOverActive -> ImGuiInputFlags_RouteOverActive in previsiion of using them with a Hovered route. (#456)
5ce3d299555 Shortcuts: rename ImGuiInputFlags_RouteGlobalHighest to ImGuiInputFlags_RouteGlobalOverActive, made ImGuiInputFlags_RouteGlobalOverFocused and ImGuiInputFlags_RouteGlobalOverActive flags. (#456)
650cb51bf10 Shortcuts: renamed ImGuiInputFlags_RouteActiveItem to ImGuiInputFlags_RouteActive. (#456, #7618)
ef9d525f02c Shortcuts: added ImGuiInputFlags_RouteActiveItem. (#456, #7618) + rearrange Changelog
16b72f2d210 Comments
29439bdd27c Windows: BeginChild(): fixed auto-fit calculation when using either (not both) ResizeX/ResizeY and double-clicking on a border. (#1710)
374b9a7fb43 Demo: Documents: refactor + add Renaming option. (#7233)
c150ad50c46 Shortcuts: claim mods ownership once pressed. (#456, #2637, #2620, #2891, #3370, #3724, #4828, #5108, #5242, #5641)
1002cfa6d2d Demo, Shortcut(): amend Shortcuts demo. (#456)
7c71e66370d Shortcuts, SetShortcutRouting: move ImGuiInputFlags_RouteFromRootWindow evaluation to SetShortcutRouting() for now. (#456)
d5a600e9c64 Shortcuts, SetShortcutRouting: added ImGuiInputFlags_RouteFromRootWindow. Made it possible for SetShortcutRouting() to query for another location.
0eb025f4847 Internals: move ItemHandleShortcut() next to Shortcut(), it's calling it anyhow. (#456)
a689fa262ae SetShortcutRouting: require explicit routing. (#456)
c06e6340cde Shortcuts: added ImGuiInputFlags_Tooltip. (#456)
77e41718940 Shortcuts: added flags to SetNextItemShortcut(). (#456)
197f8904fe8 Shortcuts, Nav: make SetNextItemShortcut() work when another item is active. Made NavCalcPreferredRefPos() take account for remote activation. (#456)
dc5caa483cd Demo: added "Shortcuts" section. (#456, #2637)
fc512a24741 Inputs: Added Shortcut(), SetNextItemShortcut(). Added ImGuiInputFlags, ImGuiInputFlags_RouteXXXX. (#456, #2637)
85513de2476 Internals, Inputs: *Breaking* Swapped parameter order of owner-aware versions of IsKeyPressed(), IsKeyChordPressed(), IsMouseClicked(). (#456)
900b29055c5 Internals, Inputs: *Breaking* Swapped parameter order of Shortcut(). (#456)
55748cdbe12 Internals, Inputs: *Breaking* Renamed ImGuiKeyOwner_None to ImGuiKeyOwner_NoOwner: avoid confusion with non zero value, makes IsKeyPressed() calls using ImGuiKeyOwner_NoOwner more explicit.
ec1d2be96f3 Examples: Win32+DX9,DX10,DX11,DX12: rework main loop to handle minimization and screen locking. (#2496, #3907, #6308, #7615)
6d1a6f1c748 Internals, Inputs: Comments, alignment.
4c3eac2c10e Backends: OpenGL3: Fixed zealous warning by initializing last_pixel_unpack_buffer. (#7614)
a1566c5e1ba Tables: fixed 28a283b breaking PageDown on tables with no interactive items.
aa725ca79dc Inputs: moving ImGuiInputFlags_RouteAlways into ImGuiInputFlags_RouteTypeMask_
cd48059dc53 Tables: comments about skipping access to table data in coarse clipping path.
28a283b4603 Windows: BeginChild(), Tables:fixed visibility of fully clipped child windows and tables to Test Engine.
aa5a6098ee2 Fixed typos in comments (#7599)
d39ca33b63a Fixed false positive with PVS-Studio.
ae8218a3eaf Inputs, Shortcut: fixes some edge cases for GetKeyChordName(), clarify that it is aimed at display. (#456)
25e279ee73f Inputs: Treat ctrl-left-click as right click when ConfigMacOSXBehaviors is set. (#2343)
b4f564c1ed7 Internals: Shortcuts: *Breaking* : rename ImGuiInputFlags_RouteGlobalLow -> ImGuiInputFlags_RouteGlobal, ImGuiInputFlags_RouteGlobal -> ImGuiInputFlags_RouteGlobalOverFocused, ImGuiInputFlags_RouteGlobalHigh -> ImGuiInputFlags_RouteGlobalHighest (#456)
5107e58b0f3 Inputs: amend changelog and clarify how the swap might be a breaking change for a minority of users. (#2343)
8bd5d1d42f0 Inputs: Fixed swapping of keys associated to mods. Fixed warnings. (#2343, #4084, #5923, #456)
77471066471 Inputs: swap Ctrl and Cmd on macOS X, remove ImGuiMod_Shortcut. (#2343, #4084, #5923, #456)
07dbcf1f70d Fixed typos. (#7593)
93daf232233 Examples: SDL3: updates for latest SDL3 API changes.
e45efa9951a Backends: SDL3: Rename SDLK_QUOTE and SDLK_BACKQUOTE to SDLK_APOSTROPHE and SDLK_GRAVE. (#7580)
5d973a87d45 Backends: SDL_Renderer2/SDL_Renderer3: and ImGui_ImplSDLRenderer2_RenderDrawData() and ImGui_ImplSDLRenderer3_RenderDrawData() now takes a SDL_Renderer* parameter.
af2fbf043df Backends/Internals: Don't use IME and clipboard default win32 functions when WINAPI_FAMILY_GAMES (#7585)
e4576914cb9 Internals: amend f806c76 to better match docking + fixed unused static forward declaration warning.
d0524df8879 Internals: slight refactor FindHoveredWindow() -> FindHoveredWindowEx() toward reducing far-away code duplication.
f806c76e97b Tables, Dpi: added dummy g.DpiScale storage (to be altered in docking), using to scale tables border hit thickness.
f0912833ba9 Update FAQ.md (#7581)
ac90e1bd5bd Backends: Win32: replace bd != nullptr assert with early out. (#6275)
0a5d40a0161 Update FAQ.md
d06b8b58d84 Nav: fixed holding Ctrl or gamepad L1 from not slowing down keyboard/gamepad tweak speed.
5e236804541 Backends: all backends + demo now call IMGUI_CHECKVERSION() to verify ABI compatibility between caller code and compiled version of dear imgui. (#7568)
510eb8f4801 Tables: fixed cell background of fully clipped row overlapping with header. (#7575, #7041)
f48aae600a2 Version 1.90.7 WIP

git-subtree-dir: external/imgui/imgui
git-subtree-split: 00ad3c65bc256a16521288505f26fb335440f8f5
2024-05-28 17:12:43 +02:00

13 KiB

(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/ folder example applications (standalone, ready-to-build) for variety of platforms and graphics APIs. They all use standard backends from the backends/ folder (see BACKENDS.md).

The purpose of Examples is to showcase integration with backends, let you try Dear ImGui, and guide you toward integrating Dear ImGui in your own application/game/engine. Once Dear ImGui is setup and running, run and refer to ImGui::ShowDemoWindow() in imgui_demo.cpp for usage of the end-user API.

You can find Windows binaries for some of those example applications at: https://www.dearimgui.com/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 https://www.dearimgui.com/faq

If you are using any of the backends 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/
Allegro 5 example.
= main.cpp + imgui_impl_allegro5.cpp

example_android_opengl3/
Android + OpenGL3 (ES) example.
= main.cpp + imgui_impl_android.cpp + imgui_impl_opengl3.cpp

example_apple_metal/
OSX & iOS + Metal example.
= 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 example.
= 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_glfw_wgpu/
GLFW + WebGPU example. Supports Emscripten (web) or Dawn (desktop)
= main.cpp + imgui_impl_glfw.cpp + imgui_impl_wgpu.cpp Note that the 'example_glfw_opengl3' and 'example_sdl2_opengl3' examples also supports Emscripten!

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 THIS IF YOUR CODE/ENGINE IS USING MODERN GL or WEBGL (SHADERS, VBO, VAO, etc.)
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 GL calls, using this renderer is likely to make things more complicated, will require your code to reset many GL 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 (modern, programmable pipeline).
= main.cpp + imgui_impl_glfw.cpp + imgui_impl_opengl3.cpp
This uses more modern GL calls and custom shaders.
This support building with Emscripten and targeting WebGL.
Prefer using that if you are using modern GL or WebGL in your application.

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 example.
= main.cpp + imgui_impl_glut.cpp + imgui_impl_opengl2.cpp
Note that GLUT/FreeGLUT is largely obsolete software, prefer using GLFW or SDL.

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_sdl2_directx11/
SDL2 + DirectX11 example, Windows only.
= main.cpp + imgui_impl_sdl2.cpp + imgui_impl_dx11.cpp
This to demonstrate usage of DirectX with SDL2.

example_sdl2_metal/
SDL2 + Metal example, Mac only.
= main.mm + imgui_impl_sdl2.cpp + imgui_impl_metal.mm

example_sdl2_opengl2/
SDL2 (Win32, Mac, Linux etc.) + OpenGL example (legacy, fixed pipeline).
= main.cpp + imgui_impl_sdl2.cpp + imgui_impl_opengl2.cpp
DO NOT USE OPENGL2 CODE IF YOUR CODE/ENGINE IS USING GL OR WEBGL (SHADERS, VBO, VAO, etc.)
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 GL calls, using this renderer is likely to make things more complicated, will require your code to reset many GL attributes to their initial state, and might confuse your GPU driver. One star, not recommended.

example_sdl2_opengl3/
SDL2 (Win32, Mac, Linux, etc.) + OpenGL3+/ES2/ES3 example.
= main.cpp + imgui_impl_sdl2.cpp + imgui_impl_opengl3.cpp
This uses more modern GL calls and custom shaders.
This support building with Emscripten and targeting WebGL.
Prefer using that if you are using modern GL or WebGL in your application.

example_sdl2_sdlrenderer2/
SDL2 (Win32, Mac, Linux, etc.) + SDL_Renderer for SDL2 (most graphics backends are supported underneath)
= main.cpp + imgui_impl_sdl2.cpp + imgui_impl_sdlrenderer.cpp
This requires SDL 2.0.18+ (released November 2021)

example_sdl2_vulkan/
SDL2 (Win32, Mac, Linux, etc.) + Vulkan example.
= main.cpp + imgui_impl_sdl2.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.

example_win32_opengl3/
Raw Windows + OpenGL3 + example (modern, programmable pipeline)
= main.cpp + imgui_impl_win32.cpp + imgui_impl_opengl3.cpp

Miscellaneous

Building

Unfortunately nowadays 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 and build systems. 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 last value passed to 'io.AddMousePosEvent()' before 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!