ImGui is a bloat-free graphical user interface library for C++. It outputs vertex buffers that you can render in your 3D-pipeline enabled application. It is portable, renderer agnostic and carries minimal amount of dependencies. It is based on an "immediate" graphical user interface paradigm which allows you to build user interfaces with ease.
ImGui is a bloat-free graphical user interface library for C++. It outputs vertex buffers that you can render in your 3D-pipeline enabled application. It is portable, renderer agnostic and carries minimal amount of dependencies. It is based on an "immediate" graphical user interface paradigm which enables you to build user interfaces with ease.
ImGui is designed to enable fast iteration and allow programmers to create "content creation" or "debug" tools (as opposed to UI for the average end-user). It favors simplicity and productivity toward this goal, and thus lacks certain features normally found in more high-level libraries.
ImGui is particularly suited to integration in 3D applications, fullscreen applications, embedded applications, games, or any applications on consoles platforms where operating system features are non-standard.
ImGui is particularly suited to integration in realtime 3D applications, fullscreen applications, embedded applications, games, or any applications on consoles platforms where operating system features are non-standard. pa
ImGui is self-contained within 6 files that you can easily copy and compile into your application/engine:
@ -88,7 +88,9 @@ In your Render function, try translating your projection matrix by (0.5f,0.5f) o
<b>Can you create elaborate/serious tools with ImGui?</b>
Yes. I have written data browsers, debuggers, profilers and all sort of non-trivial tools with the library. In my experience the simplicity of the API is very empowering. However note that ImGui is programmer centric and the immediate-mode GUI paradigm might requires a bit of adaptation before you can realize its full potential.
Yes. I have written data browsers, debuggers, profilers and all sort of non-trivial tools with the library. In my experience the simplicity of the API is very empowering. Your UI runs close to your live data. Make the tools always-on and everybody in the team will be inclined to create new tools (as opposed to more "offline" UI toolkits where only a fraction of your team effectively creates tools).
However note that ImGui is programmer centric and the immediate-mode GUI paradigm might requires a bit of adaptation before you can realize its full potential. Many programmers have unfortunately been taught by their environment to make complicated things instead of simple things. Strip yourself out of all those heavy layers and start making tools!
<b>Is ImGui fast?</b>
@ -100,7 +102,7 @@ Mileage may vary but the following screenshot can give you a rough idea of the c
This is showing framerate for the full application loop on my 2011 iMac running Windows 7, OpenGL, AMD Radeon HD 6700M with an optimized executable. In contrast, librairies featuring higher-quality rendering and layouting techniques may have a higher resources footprint.
If you intend to display large lists of items (say, 1000+) it can be beneficial for your code to perform clipping manually - using helpers such as CalcListClipping() - in order to avoid submitting them to ImGui in the first place. Even though ImGui will discard your clipped items it still needs to calculate their size and that overhead will add up if you have thousands of items. If you can handle clipping and height positionning yourself then browsing a list with millions of items isn't a problem.
If you intend to display large lists of items (say, 1000+) it can be beneficial for your code to perform clipping manually - using helpers such as ImGuiListClipper - in order to avoid submitting them to ImGui in the first place. Even though ImGui will discard your clipped items it still needs to calculate their size and that overhead will add up if you have thousands of items. If you can handle clipping and height positionning yourself then browsing a list with millions of items isn't a problem.
<b>Can you reskin the look of ImGui?</b>
@ -110,7 +112,7 @@ You can alter the look of the interface to some degree: changing colors, sizes,
ImGui takes advantage of a few C++ features for convenience but nothing anywhere Boost-insanity/quagmire. In particular, function overloading and default parameters are used to make the API easier to use and code more terse. Doing so I believe the API is sitting on a sweet spot and giving up on those features would make the API more cumbersome. Other features such as namespace, constructors and templates (in the case of the ImVector<> class) are also relied on as a convenience but could be removed.
Shall someone wants to use ImGui from another language, it should be possible to wrap ImGui to be used from a raw C API in the future.
Shall someone really need to use ImGui from another language, there is an unofficial but reasonably maintained [c-api for ImGui](https://github.com/Extrawurst/cimgui) by Stephan Dilly. I would suggest using your target language functionality to try replicating the function overloading and default parameters used in C++ else the API may be harder to use. It was really designed with C++ in mind and may not make the same amount of sense with another language.
ImVec2WindowPadding;// Window padding at the time of begin. We need to lock it, in particular manipulation of the ShowBorder would have an effect
ImGuiIDMoveID;// == window->GetID("#MOVE")
floatScrollY;
floatScrollTargetRelY;// target scroll position. stored as cursor position with scrolling canceled out, so the highest point is always 0.0f. (-1.0f for no change)
floatScrollTargetRelY;// target scroll position. stored as cursor position with scrolling canceled out, so the highest point is always 0.0f. (FLT_MAX for no change)
floatScrollTargetCenterRatioY;// 0.0f = scroll so that target position is at top, 0.5f = scroll so that target position is centered
// NB: internally we store CursorPos in absolute screen coordinates because it is more convenient.
// Conversion happens as we pass the value to user, but it makes our naming convention dodgy. May want to rename 'DC.CursorPos'.
// User generally sees positions in window coordinates. Internally we store CursorPos in absolute screen coordinates because it is more convenient.
// Conversion happens as we pass the value to user, but it makes our naming convention confusing because GetCursorPos() == (DC.CursorPos - window.Pos). May want to rename 'DC.CursorPos'.
if(center_y_ratio<=0.0f&&window->ScrollTargetRelY<=window->WindowPadding.y)// Minor hack to make "scroll to top" take account of WindowPadding, else it would scroll to (WindowPadding.y - ItemSpacing.y)
window->ScrollTargetRelY=0.0f;
window->ScrollTargetCenterRatioY=center_y_ratio;
}
voidImGui::SetScrollHere(floatcenter_y_ratio)
{
ImGuiWindow*window=GetCurrentWindow();
floattarget_y=window->DC.CursorPosPrevLine.y+(window->DC.PrevLineHeight*center_y_ratio)+(GImGui->Style.ItemSpacing.y*(center_y_ratio-0.5f)*2.0f);// Precisely aim above, in the middle or below the last line.
IMGUI_APIvoidShowMetricsWindow(bool*opened=NULL);// metrics window for debugging imgui
// Window
// See implementation in .cpp for details
IMGUI_APIboolBegin(constchar*name="Debug",bool*p_opened=NULL,ImGuiWindowFlagsflags=0);// return false when window is collapsed, so you can early out in your code. 'bool* p_opened' creates a widget on the upper-right to close the window (which sets your bool to false).
IMGUI_APIboolBegin(constchar*name="Debug",bool*p_opened=NULL,ImGuiWindowFlagsflags=0);// see .cpp for details. return false when window is collapsed, so you can early out in your code. 'bool* p_opened' creates a widget on the upper-right to close the window (which sets your bool to false).
IMGUI_APIboolBegin(constchar*name,bool*p_opened,constImVec2&size_on_first_use,floatbg_alpha=-1.0f,ImGuiWindowFlagsflags=0);// this is the older/longer API. call SetNextWindowSize() instead if you want to set a window size. For regular windows, 'size_on_first_use' only applies to the first time EVER the window is created and probably not what you want! maybe obsolete this API eventually.
IMGUI_APIvoidEnd();
IMGUI_APIboolBeginChild(constchar*str_id,constImVec2&size=ImVec2(0,0),boolborder=false,ImGuiWindowFlagsextra_flags=0);// size==0.0f: use remaining window size, size<0.0f: use remaining window size minus abs(size). size>0.0f: fixed size. each axis can use a different mode, e.g. ImVec2(0,400).
IMGUI_APIboolBeginChild(constchar*str_id,constImVec2&size=ImVec2(0,0),boolborder=false,ImGuiWindowFlagsextra_flags=0);// begin a scrolling region. size==0.0f: use remaining window size, size<0.0f: use remaining window size minus abs(size). size>0.0f: fixed size. each axis can use a different mode, e.g. ImVec2(0,400).
IMGUI_APIImVec2GetContentRegionMax();// window or current column boundaries, in windows coordinates
@ -136,9 +135,11 @@ namespace ImGui
IMGUI_APIvoidSetWindowCollapsed(constchar*name,boolcollapsed,ImGuiSetCondcond=0);// set named window collapsed state
IMGUI_APIvoidSetWindowFocus(constchar*name);// set named window to be focused / front-most. use NULL to remove focus.
IMGUI_APIfloatGetScrollPosY();// get scrolling position [0..GetScrollMaxY()]
IMGUI_APIfloatGetScrollMaxY();// get maximum scrolling position == ContentSize.Y - WindowSize.Y
IMGUI_APIvoidSetScrollPosHere(floatcenter_y_ratio=0.5f);// adjust scrolling position to make the current cursor position visible. center_y_ratio=0.0: top, =0.5: center, =1.0: bottom.
IMGUI_APIfloatGetScrollY();// get scrolling amount [0..GetScrollMaxY()]
IMGUI_APIfloatGetScrollMaxY();// get maximum scrolling amount == ContentSize.Y - WindowSize.Y
IMGUI_APIvoidSetScrollY(floatscroll_y);// set scrolling amount [0..GetScrollMaxY()]
IMGUI_APIvoidSetScrollHere(floatcenter_y_ratio=0.5f);// adjust scrolling amount to make current cursor position visible. center_y_ratio=0.0: top, 0.5: center, 1.0: bottom.
IMGUI_APIvoidSetScrollFromPosY(floatpos_y,floatcenter_y_ratio=0.5f);// adjust scrolling amount to make given position valid. use GetCursorPos() or GetCursorStartPos()+offset to get valid positions.
IMGUI_APIvoidSetKeyboardFocusHere(intoffset=0);// focus keyboard on the next widget. Use positive 'offset' to access sub components of a multiple component widget
IMGUI_APIvoidSetStateStorage(ImGuiStorage*tree);// replace tree state storage with our own (if you want to manipulate it yourself, typically clear subsection of it)
IMGUI_APIImGuiStorage*GetStateStorage();
@ -163,22 +164,6 @@ namespace ImGui
IMGUI_APIvoidPushButtonRepeat(boolrepeat);// in 'repeat' mode, Button*() functions return true multiple times as you hold them (uses io.KeyRepeatDelay/io.KeyRepeatRate for now)
IMGUI_APIvoidPopButtonRepeat();
// Tooltip
IMGUI_APIvoidSetTooltip(constchar*fmt,...);// set tooltip under mouse-cursor, typically use with ImGui::IsHovered(). last call wins
IMGUI_APIvoidBeginTooltip();// use to create full-featured tooltip windows that aren't just text
IMGUI_APIvoidEndTooltip();
// Popup
IMGUI_APIvoidOpenPopup(constchar*str_id);// mark popup as open. popup identifiers are relative to the current ID-stack (so OpenPopup and BeginPopup needs to be at the same level). close childs popups if any. will close popup when user click outside, or activate a pressable item, or CloseCurrentPopup() is called within a BeginPopup()/EndPopup() block.
IMGUI_APIboolBeginPopup(constchar*str_id);// return true if popup if opened and start outputting to it. only call EndPopup() if BeginPopup() returned true!
IMGUI_APIboolBeginPopupModal(constchar*name,bool*p_opened=NULL,ImGuiWindowFlagsextra_flags=0);// modal dialog (can't close them by clicking outside)
IMGUI_APIboolBeginPopupContextItem(constchar*str_id,intmouse_button=1);// helper to open and begin popup when clicked on last item
IMGUI_APIboolBeginPopupContextWindow(boolalso_over_items=true,constchar*str_id=NULL,intmouse_button=1);// helper to open and begin popup when clicked on current window
IMGUI_APIboolBeginPopupContextVoid(constchar*str_id=NULL,intmouse_button=1);// helper to open and begin popup when clicked in void (no window)
IMGUI_APIvoidEndPopup();
IMGUI_APIvoidCloseCurrentPopup();// close the popup we have begin-ed into. clicking on a MenuItem or Selectable automatically close the current popup.
// Cursor / Layout
IMGUI_APIvoidBeginGroup();// once closing a group it is seen as a single item (so you can use IsItemHovered() on a group, SameLine() between groups, etc.
IMGUI_APIvoidEndGroup();
@ -201,6 +186,7 @@ namespace ImGui
IMGUI_APIvoidSetCursorPos(constImVec2&pos);// "
IMGUI_APIvoidSetCursorPosX(floatx);// "
IMGUI_APIvoidSetCursorPosY(floaty);// "
IMGUI_APIImVec2GetCursorStartPos();// initial cursor position
IMGUI_APIImVec2GetCursorScreenPos();// cursor position in absolute screen coordinates [0..io.DisplaySize]
IMGUI_APIvoidSetCursorScreenPos(constImVec2&pos);// cursor position in absolute screen coordinates [0..io.DisplaySize]
IMGUI_APIvoidAlignFirstTextHeightToWidgets();// call once if the first item on the line is a Text() item and you want to vertically lower it to match subsequent (bigger) widgets
IMGUI_APIvoidListBoxFooter();// terminate the scrolling region
// Widgets: Menus
// Widgets: Value() Helpers. Output single value in "name: value" format (tip: freely declare more in your code to handle your types. you can add functions to the ImGui namespace)
IMGUI_APIvoidBeginTooltip();// use to create full-featured tooltip windows that aren't just text
IMGUI_APIvoidEndTooltip();
// Menus
IMGUI_APIboolBeginMainMenuBar();// create and append to a full screen menu-bar. only call EndMainMenuBar() if this returns true!
IMGUI_APIvoidEndMainMenuBar();
IMGUI_APIboolBeginMenuBar();// append to menu-bar of current window (requires ImGuiWindowFlags_MenuBar flag set). only call EndMenuBar() if this returns true!
@ -322,13 +322,15 @@ namespace ImGui
IMGUI_APIboolMenuItem(constchar*label,constchar*shortcut=NULL,boolselected=false,boolenabled=true);// return true when activated. shortcuts are displayed for convenience but not processed by ImGui at the moment
IMGUI_APIboolMenuItem(constchar*label,constchar*shortcut,bool*p_selected,boolenabled=true);// return true when activated + toggle (*p_selected) if p_selected != NULL
// Widgets: Value() Helpers. Output single value in "name: value" format (tip: freely declare more in your code to handle your types. you can add functions to the ImGui namespace)
IMGUI_APIvoidOpenPopup(constchar*str_id);// mark popup as open. popup identifiers are relative to the current ID-stack (so OpenPopup and BeginPopup needs to be at the same level). close childs popups if any. will close popup when user click outside, or activate a pressable item, or CloseCurrentPopup() is called within a BeginPopup()/EndPopup() block.
IMGUI_APIboolBeginPopup(constchar*str_id);// return true if popup if opened and start outputting to it. only call EndPopup() if BeginPopup() returned true!
IMGUI_APIboolBeginPopupModal(constchar*name,bool*p_opened=NULL,ImGuiWindowFlagsextra_flags=0);// modal dialog (can't close them by clicking outside)
IMGUI_APIboolBeginPopupContextItem(constchar*str_id,intmouse_button=1);// helper to open and begin popup when clicked on last item
IMGUI_APIboolBeginPopupContextWindow(boolalso_over_items=true,constchar*str_id=NULL,intmouse_button=1);// helper to open and begin popup when clicked on current window
IMGUI_APIboolBeginPopupContextVoid(constchar*str_id=NULL,intmouse_button=1);// helper to open and begin popup when clicked in void (no window)
IMGUI_APIvoidEndPopup();
IMGUI_APIvoidCloseCurrentPopup();// close the popup we have begin-ed into. clicking on a MenuItem or Selectable automatically close the current popup.
// Logging: all text output from interface is redirected to tty/file/clipboard. Tree nodes are automatically opened.
IMGUI_APIvoidLogToTTY(intmax_depth=-1);// start logging to tty
IMGUI_APIboolIsKeyDown(intkey_index);// key_index into the keys_down[512] array, imgui doesn't know the semantic of each entry, uses your own indices!
IMGUI_APIboolIsKeyPressed(intkey_index,boolrepeat=true);// if repeat=true. uses io.KeyRepeatDelay / KeyRepeatRate
IMGUI_APIintGetKeyIndex(ImGuiKeykey);// map ImGuiKey_* values into user's key index. == io.KeyMap[key]
IMGUI_APIboolIsKeyDown(intkey_index);// key_index into the keys_down[] array, imgui doesn't know the semantic of each entry, uses your own indices!
IMGUI_APIboolIsKeyPressed(intkey_index,boolrepeat=true);// uses user's key indices as stored in the keys_down[] array. if repeat=true. uses io.KeyRepeatDelay / KeyRepeatRate
IMGUI_APIboolIsKeyReleased(intkey_index);// "
IMGUI_APIboolIsMouseDown(intbutton);// is mouse button held
IMGUI_APIboolIsMouseClicked(intbutton,boolrepeat=false);// did mouse button clicked (went from !Down to Down)
ocornut
10 years ago