@ -27,6 +27,13 @@ ImGui outputs vertex buffers and simple command-lists that you can render in you
ImGui allows you create elaborate tools as well as very short-lived ones. On the extreme side of short-liveness: using the Edit&Continue feature of compilers you can add a few widgets to tweaks variables while your application is running, and remove the code a minute later! ImGui is not just for tweaking values. You can use it to trace a running algorithm by just emitting text commands. You can use it along with your own reflection data to browse your dataset live. You can use it to expose the internals of a subsystem in your engine, to create a logger, an inspection tool, a profiler, a debugger, etc.
ImGui allows you create elaborate tools as well as very short-lived ones. On the extreme side of short-liveness: using the Edit&Continue feature of compilers you can add a few widgets to tweaks variables while your application is running, and remove the code a minute later! ImGui is not just for tweaking values. You can use it to trace a running algorithm by just emitting text commands. You can use it along with your own reflection data to browse your dataset live. You can use it to expose the internals of a subsystem in your engine, to create a logger, an inspection tool, a profiler, a debugger, etc.
Demo
----
You should be able to build the examples from sources (tested on Winodws/Mac/Linux). If you don't, let me know! If you want to have a quick look at the features of ImGui, you can download binaries of the demo app here.
IMGUI_APIboolBegin(constchar*name="Debug",bool*p_opened=NULL,constImVec2&initial_size=ImVec2(0,0),floatbg_alpha=-1.0f,ImGuiWindowFlagsflags=0);// return false when window is collapsed, so you can early out in your code. passing 'bool* p_opened' displays a Close button on the upper-right corner of the window, the pointed value will be set to false when the button is pressed.
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,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_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). on each axis.
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). on each axis.
IMGUI_APIImVec2GetContentRegionMax();// window or current column boundaries, in windows coordinates
IMGUI_APIImVec2GetContentRegionMax();// window or current column boundaries, in windows coordinates
IMGUI_APIImVec2GetWindowContentRegionMin();// window boundaries, in windows coordinates
IMGUI_APIImVec2GetWindowContentRegionMin();// window boundaries, in windows coordinates
IMGUI_APIImVec2GetWindowContentRegionMax();
IMGUI_APIImVec2GetWindowContentRegionMax();
IMGUI_APIImDrawList*GetWindowDrawList();// get rendering command-list if you want to append your own draw primitives.
IMGUI_APIImDrawList*GetWindowDrawList();// get rendering command-list if you want to append your own draw primitives
IMGUI_APIImFont*GetWindowFont();
IMGUI_APIImFont*GetWindowFont();
IMGUI_APIfloatGetWindowFontSize();// size (also height in pixels) of current font with current scale applied
IMGUI_APIfloatGetWindowFontSize();// size (also height in pixels) of current font with current scale applied
IMGUI_APIvoidSetWindowFontScale(floatscale);// per-window font scale. Adjust IO.FontGlobalScale if you want to scale all windows.
IMGUI_APIvoidSetWindowFontScale(floatscale);// per-window font scale. Adjust IO.FontGlobalScale if you want to scale all windows
IMGUI_APIImVec2GetWindowPos();// you should rarely need/care about the window position, but it can be useful if you want to do your own drawing.
IMGUI_APIImVec2GetWindowPos();// you should rarely need/care about the window position, but it can be useful if you want to do your own drawing
IMGUI_APIImVec2GetWindowSize();// get current window position.
IMGUI_APIImVec2GetWindowSize();// get current window position
IMGUI_APIfloatGetWindowWidth();
IMGUI_APIfloatGetWindowWidth();
IMGUI_APIboolGetWindowCollapsed();
IMGUI_APIboolGetWindowCollapsed();
IMGUI_APIvoidSetNextWindowPos(constImVec2&pos,ImGuiSetCondcond=0);// set next window position - call before Begin().
IMGUI_APIvoidSetNextWindowPos(constImVec2&pos,ImGuiSetCondcond=0);// set next window position - call before Begin()
IMGUI_APIvoidSetNextWindowSize(constImVec2&size,ImGuiSetCondcond=0);// set next window size. set to ImVec2(0,0) to force an auto-fit.
IMGUI_APIvoidSetNextWindowSize(constImVec2&size,ImGuiSetCondcond=0);// set next window size. set to ImVec2(0,0) to force an auto-fit
IMGUI_APIvoidSetNextWindowCollapsed(boolcollapsed,ImGuiSetCondcond=0);// set next window collapsed state.
IMGUI_APIvoidSetNextWindowCollapsed(boolcollapsed,ImGuiSetCondcond=0);// set next window collapsed state
IMGUI_APIvoidSetNextWindowFocus();// set next window to be focused / front-most
IMGUI_APIvoidSetNextWindowFocus();// set next window to be focused / front-most
IMGUI_APIvoidSetWindowPos(constImVec2&pos,ImGuiSetCondcond=0);// set current window position - call within Begin()/End(). may incur tearing.
IMGUI_APIvoidSetWindowPos(constImVec2&pos,ImGuiSetCondcond=0);// set current window position - call within Begin()/End(). may incur tearing
IMGUI_APIvoidSetWindowSize(constImVec2&size,ImGuiSetCondcond=0);// set current window size. set to ImVec2(0,0) to force an auto-fit. may incur tearing.
IMGUI_APIvoidSetWindowSize(constImVec2&size,ImGuiSetCondcond=0);// set current window size. set to ImVec2(0,0) to force an auto-fit. may incur tearing
IMGUI_APIvoidSetWindowCollapsed(boolcollapsed,ImGuiSetCondcond=0);// set current window collapsed state.
IMGUI_APIvoidSetWindowCollapsed(boolcollapsed,ImGuiSetCondcond=0);// set current window collapsed state
IMGUI_APIvoidSetWindowFocus();// set current window to be focused / front-most
IMGUI_APIvoidSetWindowFocus();// set current window to be focused / front-most
IMGUI_APIvoidSetWindowPos(constchar*name,constImVec2&pos,ImGuiSetCondcond=0);// set named window position - call within Begin()/End(). may incur tearing.
IMGUI_APIvoidSetWindowPos(constchar*name,constImVec2&pos,ImGuiSetCondcond=0);// set named window position - call within Begin()/End(). may incur tearing
IMGUI_APIvoidSetWindowSize(constchar*name,constImVec2&size,ImGuiSetCondcond=0);// set named window size. set to ImVec2(0,0) to force an auto-fit. may incur tearing.
IMGUI_APIvoidSetWindowSize(constchar*name,constImVec2&size,ImGuiSetCondcond=0);// set named window size. set to ImVec2(0,0) to force an auto-fit. may incur tearing
IMGUI_APIvoidSetWindowCollapsed(constchar*name,boolcollapsed,ImGuiSetCondcond=0);// set named window collapsed state.
IMGUI_APIvoidSetWindowCollapsed(constchar*name,boolcollapsed,ImGuiSetCondcond=0);// set named window collapsed state
IMGUI_APIvoidSetWindowFocus(constchar*name);// set named window to be focused / front-most
IMGUI_APIvoidSetWindowFocus(constchar*name);// set named window to be focused / front-most
IMGUI_APIfloatGetScrollPosY();// get scrolling position (0..GetScrollMaxY())
IMGUI_APIfloatGetScrollPosY();// get scrolling position [0..GetScrollMaxY()]
IMGUI_APIfloatGetScrollMaxY();// get maximum scrolling position == ContentSize.Y - WindowSize.Y
IMGUI_APIfloatGetScrollMaxY();// get maximum scrolling position == ContentSize.Y - WindowSize.Y
IMGUI_APIvoidSetScrollPosHere();// adjust scrolling position to center into the current cursor position.
IMGUI_APIvoidSetScrollPosHere();// adjust scrolling position to center into the current cursor position
IMGUI_APIvoidSetKeyboardFocusHere(intoffset=0);// focus keyboard on the next widget. Use positive 'offset' to access sub components of a multiple component widget.
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_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();
IMGUI_APIImGuiStorage*GetStateStorage();
// Parameters stacks (shared)
// Parameters stacks (shared)
@ -211,17 +213,21 @@ namespace ImGui
IMGUI_APIvoidPushItemWidth(floatitem_width);// width of items for the common item+label case, pixels. 0.0f = default to ~2/3 of windows width, >0.0f: width in pixels, <0.0f align xx pixels to the right of window (so -0.01f always align width to the right side)
IMGUI_APIvoidPushItemWidth(floatitem_width);// width of items for the common item+label case, pixels. 0.0f = default to ~2/3 of windows width, >0.0f: width in pixels, <0.0f align xx pixels to the right of window (so -0.01f always align width to the right side)
IMGUI_APIvoidPopItemWidth();
IMGUI_APIvoidPopItemWidth();
IMGUI_APIfloatCalcItemWidth();// width of item given pushed settings and current cursor position
IMGUI_APIfloatCalcItemWidth();// width of item given pushed settings and current cursor position
IMGUI_APIvoidPushAllowKeyboardFocus(boolv);// allow focusing using TAB/Shift-TAB, enabled by default but you can disable it for certain widgets.
IMGUI_APIvoidPushAllowKeyboardFocus(boolv);// allow focusing using TAB/Shift-TAB, enabled by default but you can disable it for certain widgets
IMGUI_APIvoidPopAllowKeyboardFocus();
IMGUI_APIvoidPopAllowKeyboardFocus();
IMGUI_APIvoidPushTextWrapPos(floatwrap_pos_x=0.0f);// word-wrapping for Text*() commands. < 0.0f: no wrapping; 0.0f: wrap to end of window (or column); > 0.0f: wrap at 'wrap_pos_x' position in window local space.
IMGUI_APIvoidPushTextWrapPos(floatwrap_pos_x=0.0f);// word-wrapping for Text*() commands. < 0.0f: no wrapping; 0.0f: wrap to end of window (or column); > 0.0f: wrap at 'wrap_pos_x' position in window local space
IMGUI_APIvoidPopTextWrapPos();
IMGUI_APIvoidPopTextWrapPos();
// Tooltip
// Tooltip
IMGUI_APIvoidSetTooltip(constchar*fmt,...);// set tooltip under mouse-cursor, typically use with ImGui::IsHovered(). last call wins.
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_APIvoidBeginTooltip();// use to create full-featured tooltip windows that aren't just text
IMGUI_APIvoidEndTooltip();
IMGUI_APIvoidEndTooltip();
// Popup
IMGUI_APIvoidBeginPopup(bool*p_opened);
IMGUI_APIvoidEndPopup();
// Layout
// Layout
IMGUI_APIvoidBeginGroup();
IMGUI_APIvoidBeginGroup();
IMGUI_APIvoidEndGroup();
IMGUI_APIvoidEndGroup();
@ -233,8 +239,8 @@ namespace ImGui
IMGUI_APIvoidColumns(intcount=1,constchar*id=NULL,boolborder=true);// setup number of columns
IMGUI_APIvoidColumns(intcount=1,constchar*id=NULL,boolborder=true);// setup number of columns
IMGUI_APIvoidNextColumn();// next column
IMGUI_APIvoidNextColumn();// next column
IMGUI_APIintGetColumnIndex();// get current column index
IMGUI_APIintGetColumnIndex();// get current column index
IMGUI_APIfloatGetColumnOffset(intcolumn_index=-1);// get position of column line (in pixels, from the left side of the contents region). pass -1 to use current column, otherwise 0..GetcolumnsCount() inclusive. column 0 is usually 0.0f and not resizable unless you call this.
IMGUI_APIfloatGetColumnOffset(intcolumn_index=-1);// get position of column line (in pixels, from the left side of the contents region). pass -1 to use current column, otherwise 0..GetcolumnsCount() inclusive. column 0 is usually 0.0f and not resizable unless you call this
IMGUI_APIvoidSetColumnOffset(intcolumn_index,floatoffset_x);// set position of column line (in pixels, from the left side of the contents region). pass -1 to use current column.
IMGUI_APIvoidSetColumnOffset(intcolumn_index,floatoffset_x);// set position of column line (in pixels, from the left side of the contents region). pass -1 to use current column
IMGUI_APIintGetColumnsCount();// number of columns (what was passed to Columns())
IMGUI_APIintGetColumnsCount();// number of columns (what was passed to Columns())
IMGUI_APIImVec2GetCursorPos();// cursor position is relative to window position
IMGUI_APIImVec2GetCursorPos();// cursor position is relative to window position
@ -243,20 +249,20 @@ namespace ImGui
IMGUI_APIvoidSetCursorPos(constImVec2&pos);// "
IMGUI_APIvoidSetCursorPos(constImVec2&pos);// "
IMGUI_APIvoidSetCursorPosX(floatx);// "
IMGUI_APIvoidSetCursorPosX(floatx);// "
IMGUI_APIvoidSetCursorPosY(floaty);// "
IMGUI_APIvoidSetCursorPosY(floaty);// "
IMGUI_APIImVec2GetCursorScreenPos();// cursor position in absolute screen coordinates (0..io.DisplaySize)
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_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_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_APIfloatGetTextLineHeight();// height of font == GetWindowFontSize()
IMGUI_APIfloatGetTextLineHeight();// height of font == GetWindowFontSize()
IMGUI_APIfloatGetTextLineHeightWithSpacing();// spacing (in pixels) between 2 consecutive lines of text == GetWindowFontSize() + GetStyle().ItemSpacing.y
IMGUI_APIfloatGetTextLineHeightWithSpacing();// spacing (in pixels) between 2 consecutive lines of text == GetWindowFontSize() + GetStyle().ItemSpacing.y
// ID scopes
// ID scopes
// If you are creating widgets in a loop you most likely want to push a unique identifier so ImGui can differentiate them.
// If you are creating widgets in a loop you most likely want to push a unique identifier so ImGui can differentiate them
// You can also use "##extra" within your widget name to distinguish them from each others (see 'Programmer Guide')
// You can also use "##extra" within your widget name to distinguish them from each others (see 'Programmer Guide')
IMGUI_APIvoidPushID(constchar*str_id);// push identifier into the ID stack. IDs are hash of the *entire* stack!
IMGUI_APIvoidPushID(constchar*str_id);// push identifier into the ID stack. IDs are hash of the *entire* stack!
IMGUI_APIvoidPushID(constvoid*ptr_id);
IMGUI_APIvoidPushID(constvoid*ptr_id);
IMGUI_APIvoidPushID(constintint_id);
IMGUI_APIvoidPushID(constintint_id);
IMGUI_APIvoidPopID();
IMGUI_APIvoidPopID();
IMGUI_APIImGuiIDGetID(constchar*str_id);// calculate unique ID (hash of whole ID stack + given parameter). useful if you want to query into ImGuiStorage yourself. otherwise rarely needed.
IMGUI_APIImGuiIDGetID(constchar*str_id);// calculate unique ID (hash of whole ID stack + given parameter). useful if you want to query into ImGuiStorage yourself. otherwise rarely needed
IMGUI_APIvoidTextUnformatted(constchar*text,constchar*text_end=NULL);// doesn't require null terminated string if 'text_end' is specified. no copy done to any bounded stack buffer, recommended for long chunks of text.
IMGUI_APIvoidTextUnformatted(constchar*text,constchar*text_end=NULL);// doesn't require null terminated string if 'text_end' is specified. no copy done to any bounded stack buffer, recommended for long chunks of text
IMGUI_APIvoidLabelText(constchar*label,constchar*fmt,...);// display text+label aligned the same way as value+label widgets
IMGUI_APIvoidLabelText(constchar*label,constchar*fmt,...);// display text+label aligned the same way as value+label widgets
IMGUI_APIboolSliderFloat(constchar*label,float*v,floatv_min,floatv_max,constchar*display_format="%.3f",floatpower=1.0f);// adjust display_format to decorate the value with a prefix or a suffix. Use power!=1.0 for logarithmic sliders.
IMGUI_APIboolSliderFloat(constchar*label,float*v,floatv_min,floatv_max,constchar*display_format="%.3f",floatpower=1.0f);// adjust display_format to decorate the value with a prefix or a suffix. Use power!=1.0 for logarithmic sliders
IMGUI_APIboolIsItemHovered();// was the last item hovered by mouse?
IMGUI_APIboolIsItemHovered();// was the last item hovered by mouse?
IMGUI_APIboolIsItemHoveredRectOnly();// was the last item hovered by mouse? even if another item is active while we are hovering this.
IMGUI_APIboolIsItemHoveredRect();// was the last item hovered by mouse? even if another item is active while we are hovering this
IMGUI_APIboolIsItemActive();// was the last item active? (e.g. button being held, text field being edited- items that don't interact will always return false)
IMGUI_APIboolIsItemActive();// was the last item active? (e.g. button being held, text field being edited- items that don't interact will always return false)
IMGUI_APIboolIsAnyItemActive();//
IMGUI_APIboolIsAnyItemActive();//
IMGUI_APIImVec2GetItemRectMin();// get bounding rect of last item
IMGUI_APIImVec2GetItemRectMin();// get bounding rect of last item
@ -368,18 +374,20 @@ namespace ImGui
IMGUI_APIboolIsMouseHoveringWindow();// is mouse hovering current window ("window" in API names always refer to current window)
IMGUI_APIboolIsMouseHoveringWindow();// is mouse hovering current window ("window" in API names always refer to current window)
IMGUI_APIboolIsMouseHoveringAnyWindow();// is mouse hovering any active imgui window
IMGUI_APIboolIsMouseHoveringAnyWindow();// is mouse hovering any active imgui window
IMGUI_APIboolIsMouseHoveringRect(constImVec2&rect_min,constImVec2&rect_max);// is mouse hovering given bounding rect
IMGUI_APIboolIsMouseHoveringRect(constImVec2&rect_min,constImVec2&rect_max);// is mouse hovering given bounding rect
IMGUI_APIboolIsMouseDragging(intbutton=0,floatlock_threshold=-1.0f);// is mouse dragging. if lock_threshold < -1.0f uses io.MouseDraggingThreshold.
IMGUI_APIboolIsMouseDragging(intbutton=0,floatlock_threshold=-1.0f);// is mouse dragging. if lock_threshold < -1.0f uses io.MouseDraggingThreshold
IMGUI_APIboolIsPosHoveringAnyWindow(constImVec2&pos);// is given position hovering any active imgui window
IMGUI_APIboolIsPosHoveringAnyWindow(constImVec2&pos);// is given position hovering any active imgui window
IMGUI_APIImVec2GetMousePos();// shortcut to ImGui::GetIO().MousePos provided by user, to be consistent with other calls
IMGUI_APIImVec2GetMousePos();// shortcut to ImGui::GetIO().MousePos provided by user, to be consistent with other calls
IMGUI_APIImVec2GetMouseDragDelta(intbutton=0,floatlock_threshold=-1.0f);// dragging amount, also see: GetItemActiveDragDelta(). if lock_threshold < -1.0f uses io.MouseDraggingThreshold.
IMGUI_APIImVec2GetMouseDragDelta(intbutton=0,floatlock_threshold=-1.0f);// dragging amount since clicking, also see: GetItemActiveDragDelta(). if lock_threshold < -1.0f uses io.MouseDraggingThreshold
IMGUI_APIImGuiMouseCursorGetMouseCursor();// get desired cursor type, reset in ImGui::NewFrame(), this updated during the frame. valid before Render(). If you use software rendering by setting io.MouseDrawCursor ImGui will render those for you
IMGUI_APIvoidSetMouseCursor(ImGuiMouseCursortype);// set desired cursor type
IMGUI_APIfloatGetTime();
IMGUI_APIfloatGetTime();
IMGUI_APIintGetFrameCount();
IMGUI_APIintGetFrameCount();
IMGUI_APIconstchar*GetStyleColName(ImGuiColidx);
IMGUI_APIconstchar*GetStyleColName(ImGuiColidx);
IMGUI_APIImVec2CalcItemRectClosestPoint(constImVec2&pos,boolon_edge=false,floatoutward=+0.0f);// utility to find the closest point the last item bounding rectangle edge. useful to visually link items.
IMGUI_APIImVec2CalcItemRectClosestPoint(constImVec2&pos,boolon_edge=false,floatoutward=+0.0f);// utility to find the closest point the last item bounding rectangle edge. useful to visually link items
IMGUI_APIvoidCalcListClipping(intitems_count,floatitems_height,int*out_items_display_start,int*out_items_display_end);// helper to manually clip large list of items. see comments in implementation.
IMGUI_APIvoidCalcListClipping(intitems_count,floatitems_height,int*out_items_display_start,int*out_items_display_end);// helper to manually clip large list of items. see comments in implementation
IMGUI_APIvoidBeginChildFrame(ImGuiIDid,constImVec2&size);// helper to create a child window / scrolling region that looks like a normal widget frame.
IMGUI_APIvoidBeginChildFrame(ImGuiIDid,constImVec2&size);// helper to create a child window / scrolling region that looks like a normal widget frame
ocornut
10 years ago