<center><b><i>"Give someone state and they'll have a bug one day, but teach them how to represent state in two separate locations that have to be kept in sync and they'll have bugs for a lifetime."</i></b></center><ahref="https://twitter.com/rygorous/status/1507178315886444544">-ryg</a>
<sub>(This library is available under a free and permissive license, but needs financial support to sustain its continued improvements. In addition to maintenance and stability there are many desirable features yet to be added. If your company is using Dear ImGui, please consider reaching out.)</sub>
Businesses: support continued development and maintenance via invoiced technical support, maintenance, sponsoring contracts:
Individuals: support continued development and maintenance [here](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=WGHNC6MBFLZ2S).
Individuals: support continued development and maintenance [here](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=WGHNC6MBFLZ2S). Also see [Sponsors](https://github.com/ocornut/imgui/wiki/Sponsors) page.
Also see [Sponsors](https://github.com/ocornut/imgui/wiki/Sponsors) page.
Dear ImGui is a **bloat-free graphical user interface library for C++**. It outputs optimized vertex buffers that you can render anytime in your 3D-pipeline enabled application. It is fast, portable, renderer agnostic and self-contained (no external dependencies).
@ -20,10 +27,16 @@ Dear ImGui is designed to **enable fast iterations** and to **empower programmer
Dear ImGui is particularly suited to integration in games engine (for tooling), real-time 3D applications, fullscreen applications, embedded applications, or any applications on consoles platforms where operating system features are non-standard.
- Easy to use to create code-driven and data-driven tools.
- Easy to use to create ad hoc short-lived tools and long-lived, more elaborate tools.
- Easy to hack and improve.
- Minimize setup and maintenance.
- Minimize state storage on user side.
- Minimize state synchronization.
- Portable, minimize dependencies, run on target (consoles, phones, etc.).
- Efficient runtime and memory consumption.
- Battle-tested, used by many major actors in the game industry.
### Usage
@ -31,9 +44,7 @@ Dear ImGui is particularly suited to integration in games engine (for tooling),
**No specific build process is required**. You can add the .cpp files to your existing project.
You will need a backend to integrate Dear ImGui in your app. The backend passes mouse/keyboard/gamepad inputs and variety of settings to Dear ImGui, and is in charge of rendering the resulting vertices.
**Backends for a variety of graphics api and rendering platforms** are provided in the [backends/](https://github.com/ocornut/imgui/tree/master/backends) folder, along with example applications in the [examples/](https://github.com/ocornut/imgui/tree/master/examples) folder. See the [Integration](#integration) section of this document for details. You may also create your own backend. Anywhere where you can render textured triangles, you can render Dear ImGui.
You will need a backend to integrate Dear ImGui in your app. The backend passes mouse/keyboard/gamepad inputs and variety of settings to Dear ImGui, and is in charge of rendering the resulting vertices. **Backends for a variety of graphics api and rendering platforms** are provided in the [backends/](https://github.com/ocornut/imgui/tree/master/backends) folder, along with example applications in the [examples/](https://github.com/ocornut/imgui/tree/master/examples) folder. See the [Integration](#integration) section of this document for details. You may also create your own backend. Anywhere where you can render textured triangles, you can render Dear ImGui.
After Dear ImGui is setup in your application, you can use it from \_anywhere\_ in your program loop:
@ -145,10 +155,10 @@ For more user-submitted screenshots of projects using Dear ImGui, check out the
For a list of third-party widgets and extensions, check out the [Useful Extensions/Widgets](https://github.com/ocornut/imgui/wiki/Useful-Extensions) wiki page.
Custom engine
Custom engine for [Wonder Boy: The Dragon's Trap](http://www.TheDragonsTrap.com) (2017)
// This function is merely here to free heap allocations.
voidImGui::Shutdown(ImGuiContext*context)
voidImGui::Shutdown()
{
// The fonts atlas can be used prior to calling NewFrame(), so we clear it even if g.Initialized is FALSE (which would happen if we never called NewFrame)
IM_ASSERT(g.IO.KeyMap[n]>=-1&&g.IO.KeyMap[n]<ImGuiKey_LegacyNativeKey_END&&"io.KeyMap[] contains an out of bound value (need to be 0..511, or -1 for unmapped key)");
// (Integer encoded as XYYZZ for use in #if preprocessor conditionals. Work in progress versions typically starts at XYY99 then bounce up to XYY00, XYY01 etc. when release tagging happens)
IMGUI_APIboolColorButton(constchar*desc_id,constImVec4&col,ImGuiColorEditFlagsflags=0,ImVec2size=ImVec2(0,0));// display a color square/button, hover for details, return true when pressed.
IMGUI_APIboolColorButton(constchar*desc_id,constImVec4&col,ImGuiColorEditFlagsflags=0,constImVec2&size=ImVec2(0,0));// display a color square/button, hover for details, return true when pressed.
IMGUI_APIvoidSetColorEditOptions(ImGuiColorEditFlagsflags);// initialize current options (generally on application startup) if you want to select a default format, picker type, etc. User will be able to change many settings, unless you pass the _NoOptions flag to your calls.
// Widgets: Trees
@ -713,11 +713,10 @@ namespace ImGui
// Tables
// - Full-featured replacement for old Columns API.
// - See Demo->Tables for demo code.
// - See top of imgui_tables.cpp for general commentary.
// - See Demo->Tables for demo code. See top of imgui_tables.cpp for general commentary.
// - See ImGuiTableFlags_ and ImGuiTableColumnFlags_ enums for a description of available flags.
// The typical call flow is:
// - 1. Call BeginTable().
// - 1. Call BeginTable(), early out if returning false.
// - 2. Optionally call TableSetupColumn() to submit column name/flags/defaults.
// - 3. Optionally call TableSetupScrollFreeze() to request scroll freezing of columns/rows.
// - 4. Optionally call TableHeadersRow() to submit a header row. Names are pulled from TableSetupColumn() data.
@ -754,16 +753,13 @@ namespace ImGui
IMGUI_APIvoidTableHeadersRow();// submit all headers cells based on data provided to TableSetupColumn() + submit context menu
IMGUI_APIvoidTableHeader(constchar*label);// submit one header cell manually (rarely used)
// Tables: Sorting
// - Call TableGetSortSpecs() to retrieve latest sort specs for the table. NULL when not sorting.
// - When 'SpecsDirty == true' you should sort your data. It will be true when sorting specs have changed
// since last call, or the first time. Make sure to set 'SpecsDirty = false' after sorting, else you may
// wastefully sort your data every frame!
// - Lifetime: don't hold on this pointer over multiple frames or past any subsequent call to BeginTable().
IMGUI_APIImGuiTableSortSpecs*TableGetSortSpecs();// get latest sort specs for the table (NULL if not sorting).
// Tables: Miscellaneous functions
// Tables: Sorting & Miscellaneous functions
// - Sorting: call TableGetSortSpecs() to retrieve latest sort specs for the table. NULL when not sorting.
// When 'sort_specs->SpecsDirty == true' you should sort your data. It will be true when sorting specs have
// changed since last call, or the first time. Make sure to set 'SpecsDirty = false' after sorting,
// else you may wastefully sort your data every frame!
// - Functions args 'int column_n' treat the default value of -1 as the same as passing the current column index.
IMGUI_APIImGuiTableSortSpecs*TableGetSortSpecs();// get latest sort specs for the table (NULL if not sorting). Lifetime: don't hold on this pointer over multiple frames or past any subsequent call to BeginTable().
IMGUI_APIintTableGetColumnCount();// return number of columns (value passed to BeginTable)
IMGUI_APIintTableGetColumnIndex();// return current column index.
IMGUI_APIintTableGetRowIndex();// return current row index.
@ -879,15 +875,17 @@ namespace ImGui
// - In the future we will extend this concept further to also represent Platform Monitor and support a "no main platform window" operation mode.
IMGUI_APIImGuiViewport*GetMainViewport();// return primary/default viewport. This can never be NULL.
// Background/Foreground Draw Lists
IMGUI_APIImDrawList*GetBackgroundDrawList();// get background draw list for the viewport associated to the current window. this draw list will be the first rendering one. Useful to quickly draw shapes/text behind dear imgui contents.
IMGUI_APIImDrawList*GetForegroundDrawList();// get foreground draw list for the viewport associated to the current window. this draw list will be the last rendered one. Useful to quickly draw shapes/text over dear imgui contents.
IMGUI_APIImDrawList*GetBackgroundDrawList(ImGuiViewport*viewport);// get background draw list for the given viewport. this draw list will be the first rendering one. Useful to quickly draw shapes/text behind dear imgui contents.
IMGUI_APIImDrawList*GetForegroundDrawList(ImGuiViewport*viewport);// get foreground draw list for the given viewport. this draw list will be the last rendered one. Useful to quickly draw shapes/text over dear imgui contents.
// Miscellaneous Utilities
IMGUI_APIboolIsRectVisible(constImVec2&size);// test if rectangle (of given size, starting from cursor position) is visible / not clipped.
IMGUI_APIboolIsRectVisible(constImVec2&rect_min,constImVec2&rect_max);// test if rectangle (in screen space) is visible / not clipped. to perform coarse clipping on user's side.
IMGUI_APIdoubleGetTime();// get global imgui time. incremented by io.DeltaTime every frame.
IMGUI_APIintGetFrameCount();// get global imgui frame count. incremented by 1 every frame.
IMGUI_APIImDrawList*GetBackgroundDrawList();// get background draw list for the viewport associated to the current window. this draw list will be the first rendering one. Useful to quickly draw shapes/text behind dear imgui contents.
IMGUI_APIImDrawList*GetForegroundDrawList();// get foreground draw list for the viewport associated to the current window. this draw list will be the last rendered one. Useful to quickly draw shapes/text over dear imgui contents.
IMGUI_APIImDrawList*GetBackgroundDrawList(ImGuiViewport*viewport);// get background draw list for the given viewport. this draw list will be the first rendering one. Useful to quickly draw shapes/text behind dear imgui contents.
IMGUI_APIImDrawList*GetForegroundDrawList(ImGuiViewport*viewport);// get foreground draw list for the given viewport. this draw list will be the last rendered one. Useful to quickly draw shapes/text over dear imgui contents.
IMGUI_APIImDrawListSharedData*GetDrawListSharedData();// you may use this when creating your own ImDrawList instances.
IMGUI_APIconstchar*GetStyleColorName(ImGuiColidx);// get a string corresponding to the enum value (for display, saving, etc.).
IMGUI_APIvoidSetStateStorage(ImGuiStorage*storage);// replace current window storage with our own (if you want to manipulate it yourself, typically clear subsection of it)
@ -1516,13 +1514,13 @@ enum ImGuiKey_
};
// Helper "flags" version of key-mods to store and compare multiple key-mods easily. Sometimes used for storage (e.g. io.KeyMods) but otherwise not much used in public API.
floatNavInputs[ImGuiNavInput_COUNT];// Gamepad inputs. Cleared back to zero by EndFrame(). Keyboard keys will be auto-mapped and be written here by NewFrame().
// Other state maintained from data above + IO function calls
ImGuiKeyModFlagsKeyMods;// Key mods flags (same as io.KeyCtrl/KeyShift/KeyAlt/KeySuper but merged into flags), updated by NewFrame()
ImGuiModFlagsKeyMods;// Key mods flags (same as io.KeyCtrl/KeyShift/KeyAlt/KeySuper but merged into flags), updated by NewFrame()
ImGuiKeyDataKeysData[ImGuiKey_KeysData_SIZE];// Key state for all known keys. Use IsKeyXXX() functions to access this.
boolWantCaptureMouseUnlessPopupClose;// Alternative to WantCaptureMouse: (WantCaptureMouse == true && WantCaptureMouseUnlessPopupClose == false) when a click over void is expected to close a popup.
ImVec2MousePosPrev;// Previous mouse position (note that MouseDelta is not necessary == MousePos-MousePosPrev, in case either position is invalid)
IMGUI_APIvoidPushClipRect(ImVec2clip_rect_min,ImVec2clip_rect_max,boolintersect_with_current_clip_rect=false);// Render-level scissoring. This is passed down to your render function but not used for CPU-side coarse clipping. Prefer using higher-level ImGui::PushClipRect() to affect logic (hit-testing and widget culling)
IMGUI_APIvoidPushClipRect(constImVec2&clip_rect_min,constImVec2&clip_rect_max,boolintersect_with_current_clip_rect=false);// Render-level scissoring. This is passed down to your render function but not used for CPU-side coarse clipping. Prefer using higher-level ImGui::PushClipRect() to affect logic (hit-testing and widget culling)
// - Filled shapes must always use clockwise winding order. The anti-aliasing fringe depends on it. Counter-clockwise shapes will have "inward" anti-aliasing.
// - For rectangular primitives, "p_min" and "p_max" represent the upper-left and lower-right corners.
// - For circle primitives, use "num_segments == 0" to automatically calculate tessellation (preferred).
// In older versions (until Dear ImGui 1.77) the AddCircle functions defaulted to num_segments == 12.
// Stateful path API, add points then finish with PathFillConvex() or PathStroke()
// - Filled shapes must always use clockwise winding order. The anti-aliasing fringe depends on it. Counter-clockwise shapes will have "inward" anti-aliasing.
inlinevoidPathFillConvex(ImU32col){AddConvexPolyFilled(_Path.Data,_Path.Size,col);_Path.Size=0;}// Note: Anti-aliased filling requires points to be in clockwise order.
@ -588,7 +588,7 @@ int ImDrawList::_CalcCircleAutoSegmentCount(float radius) const
}
// Render-level scissoring. This is passed down to your render function but not used for CPU-side coarse clipping. Prefer using higher-level ImGui::PushClipRect() to affect logic (hit-testing and widget culling)
// We intentionally avoid using ImVec2 and its math operators here to reduce cost to a minimum for debug/non-inlined builds.
// - We intentionally avoid using ImVec2 and its math operators here to reduce cost to a minimum for debug/non-inlined builds.
// - Filled shapes must always use clockwise winding order. The anti-aliasing fringe depends on it. Counter-clockwise shapes will have "inward" anti-aliasing.
// Calculate how far we can render. Requires two passes on the string data but keeps the code simple and not intrusive for what's essentially an uncommon feature.
staticinlineImGuiIDImHash(constvoid*data,intsize,ImU32seed=0){returnsize?ImHashData(data,(size_t)size,seed):ImHashStr((constchar*)data,0,seed);}// [moved to ImHashStr/ImHashData in 1.68]
#endif
// Helpers: Sorting
#ifndef ImQsort
@ -326,7 +324,7 @@ static inline bool ImIsPowerOfTwo(int v) { return v != 0 && (v &
ImGuiWindowFlagsFlags,FlagsPreviousFrame;// See enum ImGuiWindowFlags_
ImGuiWindowClassWindowClass;// Advanced users only. Set with SetNextWindowClass()
ImGuiViewportP*Viewport;// Always set in Begin(), only inactive windows may have a NULL value here
ImGuiViewportP*Viewport;// Always set in Begin(). Inactive windows may have a NULL value here if their viewport was discarded.
ImGuiIDViewportId;// We backup the viewport id (since the viewport may disappear or never be created if the window is inactive)
ImVec2ViewportPos;// We backup the viewport position (since the viewport may disappear or never be created if the window is inactive)
intViewportAllowPlatformMonitorExtend;// Reset to -1 every frame (index is guaranteed to be valid between NewFrame..EndFrame), only used in the Appearing frame of a tooltip/popup to enforce clamping to a given monitor
IMGUI_APIvoidShutdown(ImGuiContext*context);// Since 1.60 this is a _private_ function. You can call DestroyContext() to destroy the context created by CreateContext().
IMGUI_APIvoidInitialize();
IMGUI_APIvoidShutdown();// Since 1.60 this is a _private_ function. You can call DestroyContext() to destroy the context created by CreateContext().
IM_ASSERT((size_t)(fmt_end-fmt_in+1)<fmt_out_size);// Format is too long, let us know if this happens to you!
while(fmt_in<fmt_end)
{
charc=*fmt_in++;
if(c!='\''&&c!='$'&&c!='_')// Custom flags provided by stb_sprintf.h. POSIX 2008 also supports '.
*(fmt_out++)=c;
}
*fmt_out=0;// Zero-terminate
}
// - For scanning we need to remove all width and precision fields "%3.7f" -> "%f". BUT don't strip types like "%I64d" which includes digits. ! "%07I64d" -> "%I64d"
flags|=ImGuiInputTextFlags_AutoSelectAll|ImGuiInputTextFlags_NoMarkEdited;// We call MarkItemEdited() ourselves by comparing the actual data rather than the string.
IM_ASSERT(io.KeyMods==GetMergedKeyModFlags()&&"Mismatching io.KeyCtrl/io.KeyShift/io.KeyAlt/io.KeySuper vs io.KeyMods");// We rarely do this check, but if anything let's do it here.
floatextra=ImClamp(ImFabs(ta.x-tb.x)*0.30f,ref_unit*0.5f,ref_unit*2.5f);// add a bit of extra slack.
ta.x+=(window->Pos.x<child_menu_window->Pos.x)?-0.5f:+0.5f;// to avoid numerical issues (FIXME: ??)
tb.y=ta.y+ImMax((tb.y-extra)-ta.y,-ref_unit*8.0f);// triangle is maximum 200 high to limit the slope and the bias toward large sub-menus // FIXME: Multiply by fb_scale?
tb.y=ta.y+ImMax((tb.y-extra)-ta.y,-ref_unit*8.0f);// triangle has maximum height to limit the slope and the bias toward large sub-menus
// The 'HovereWindow == window' check creates an inconsistency (e.g. moving away from menu slowly tends to hit same window, whereas moving away fast does not)
// But we also need to not close the top-menu menu when moving over void. Perhaps we should extend the triangle check to a larger polygon.
// (Remember to test this on BeginPopup("A")->BeginMenu("B") sequence which behaves slightly differently as B isn't a Child of A and hovering isn't shared.)
ocornut
ago%!(EXTRA string=3 years)