implot (C++)

ImPlot: 2D plots for Dear ImGui: lines, scatter, bars, shaded areas, heatmaps, histograms, pie charts, real-time data.

Start with: ImPlot::BeginPlot, ImPlot::EndPlot, ImPlot::PlotLine, ImPlot::PlotScatter, ImPlot::SetupAxes.

implot.h¶

BoxedValue (struct)¶

Enums and Types¶

Forward declarations¶

Enums/Flags

ImAxis_ (enum)¶

Axis indices. The values assigned may change; NEVER hardcode these.

Prop_ (enum)¶

Plotting properties. These provide syntactic sugar for creating ImPlotSpecs from (ImPlotProp,value) pairs. See ImPlotSpec documentation.

Flags_ (enum)¶

Options for plots (see BeginPlot).

AxisFlags_ (enum)¶

Options for plot axes (see SetupAxis).

SubplotFlags_ (enum)¶

Options for subplots (see BeginSubplot)

LegendFlags_ (enum)¶

Options for legends (see SetupLegend)

MouseTextFlags_ (enum)¶

Options for mouse hover text (see SetupMouseText)

DragToolFlags_ (enum)¶

Options for DragPoint, DragLine, DragRect

ColormapScaleFlags_ (enum)¶

Flags for ColormapScale

ItemFlags_ (enum)¶

Flags for ANY PlotX function. Used by setting ImPlotSpec::Flags.

LineFlags_ (enum)¶

Flags for PlotLine. Used by setting ImPlotSpec::Flags.

ScatterFlags_ (enum)¶

Flags for PlotScatter. Used by setting ImPlotSpec::Flags.

BubblesFlags_ (enum)¶

Flags for PlotBubbles. Used by setting ImPlotSpec::Flags.

PolygonFlags_ (enum)¶

Flags for PlotPolygon. Used by setting ImPlotSpec::Flags.

StairsFlags_ (enum)¶

Flags for PlotStairs. Used by setting ImPlotSpec::Flags.

ShadedFlags_ (enum)¶

Flags for PlotShaded (placeholder). Used by setting ImPlotSpec::Flags.

BarsFlags_ (enum)¶

Flags for PlotBars. Used by setting ImPlotSpec::Flags.

BarGroupsFlags_ (enum)¶

Flags for PlotBarGroups. Used by setting ImPlotSpec::Flags.

ErrorBarsFlags_ (enum)¶

Flags for PlotErrorBars. Used by setting ImPlotSpec::Flags.

StemsFlags_ (enum)¶

Flags for PlotStems. Used by setting ImPlotSpec::Flags.

InfLinesFlags_ (enum)¶

Flags for PlotInfLines. Used by setting ImPlotSpec::Flags.

PieChartFlags_ (enum)¶

Flags for PlotPieChart. Used by setting ImPlotSpec::Flags.

HeatmapFlags_ (enum)¶

Flags for PlotHeatmap. Used by setting ImPlotSpec::Flags.

HistogramFlags_ (enum)¶

Flags for PlotHistogram and PlotHistogram2D. Used by setting ImPlotSpec::Flags.

DigitalFlags_ (enum)¶

Flags for PlotDigital (placeholder). Used by setting ImPlotSpec::Flags.

ImageFlags_ (enum)¶

Flags for PlotImage (placeholder). Used by setting ImPlotSpec::Flags.

TextFlags_ (enum)¶

Flags for PlotText. Used by setting ImPlotSpec::Flags.

DummyFlags_ (enum)¶

Flags for PlotDummy (placeholder). Used by setting ImPlotSpec::Flags.

Cond_ (enum)¶

Represents a condition for SetupAxisLimits etc. (same as ImGuiCond, but we only support a subset of those enums)

Col_ (enum)¶

Plot styling colors.

StyleVar_ (enum)¶

Plot styling variables.

Scale_ (enum)¶

Axis scale

Marker_ (enum)¶

Marker specifications.

Colormap_ (enum)¶

Built-in colormaps

Location_ (enum)¶

Used to position items on a plot (e.g. legends, labels, etc.)

Bin_ (enum)¶

Enums for different automatic histogram binning methods (k = bin count or w = bin width)

Spec (struct)¶

Plot item styling specification. Provide these to PlotX functions to override styling, specify offsetting or stride, or set optional flags. This struct can be used in the following ways:

1. By declaring and defining a struct instance:

   ImPlotSpec spec;
   spec.LineColor = ImVec4(1,0,0,1);
   spec.LineWeight = 2.0;
   spec.Marker = ImPlotMarker_Circle;
   spec.Flags = ImPlotItemFlags_NoLegend | ImPlotLineFlags_Segments;
   ImPlot::PlotLine("MyLine", xs, ys, 100, spec);

2. Inline using (ImPlotProp,value) pairs (order does NOT matter):

   ImPlot::PlotLine(“MyLine”, xs, ys, 100, { ImPlotProp_LineColor, ImVec4(1,0,0,1),
   ImPlotProp_LineWeight, 2.0,
   ImPlotProp_Marker, ImPlotMarker_Circle,
   ImPlotProp_Flags, ImPlotItemFlags_NoLegend | ImPlotLineFlags_Segments

   });

Point (struct)¶

Point::ImPlotPoint¶

constexpr ImPlotPoint() : x(0.0), y(0.0);

constexpr ImPlotPoint(double _x, double _y) : x(_x), y(_y);

constexpr ImPlotPoint(const ImVec2& p) : x((double)p.x), y((double)p.y);

Range (struct)¶

Range defined by a min/max value.

Range::ImPlotRange¶

constexpr ImPlotRange() : Min(0.0), Max(0.0);

constexpr ImPlotRange(double _min, double _max) : Min(_min), Max(_max);

Range::Contains¶

IMPLOT_API bool Contains(double value) const;

Range::Size¶

IMPLOT_API double Size() const;

Range::Clamp¶

IMPLOT_API double Clamp(double value) const;

Rect (struct)¶

Combination of two range limits for X and Y axes. Also an AABB defined by Min()/Max().

Rect::ImPlotRect¶

constexpr ImPlotRect() : X(0.0,0.0), Y(0.0,0.0);

constexpr ImPlotRect(double x_min, double x_max, double y_min, double y_max) : X(x_min, x_max), Y(y_min, y_max);

Rect::Contains¶

IMPLOT_API bool Contains(const ImPlotPoint& p) const;

IMPLOT_API bool Contains(double x, double y) const;

Rect::Size¶

IMPLOT_API ImPlotPoint Size() const;

Rect::Clamp¶

IMPLOT_API ImPlotPoint Clamp(const ImPlotPoint& p) const;

IMPLOT_API ImPlotPoint Clamp(double x, double y) const;

Rect::Min¶

IMPLOT_API ImPlotPoint Min() const;

Rect::Max¶

IMPLOT_API ImPlotPoint Max() const;

Style (struct)¶

Plot style structure (has support for copy.copy)

Style::Color_¶

inline IMPLOT_API ImVec4& Color_(size_t idxColor);

Array of styling colors (index from implot.Col_.xxx)

Style::SetColor_¶

inline IMPLOT_API void SetColor_(size_t idxColor, ImVec4 color);

Array of styling colors (index from implot.Col_.xxx)

Style::ImPlotStyle¶

IMPLOT_API ImPlotStyle();

Support for legacy versions¶

InputMap (struct)¶

Input mapping structure. Default values listed. See also MapInputDefault, MapInputReverse.

InputMap::ImPlotInputMap¶

IMPLOT_API ImPlotInputMap();

Contexts¶

ImPlot::CreateContext¶

IMPLOT_API ImPlotContext* CreateContext();

Creates a new ImPlot context. Call this after ImGui::CreateContext.

ImPlot::DestroyContext¶

IMPLOT_API void DestroyContext(ImPlotContext* ctx = nullptr);

Destroys an ImPlot context. Call this before ImGui::DestroyContext. None = destroy current context.

ImPlot::GetCurrentContext¶

IMPLOT_API ImPlotContext* GetCurrentContext();

Returns the current ImPlot context. None if no context has ben set.

ImPlot::SetCurrentContext¶

IMPLOT_API void SetCurrentContext(ImPlotContext* ctx);

Sets the current ImPlot context.

ImPlot::SetImGuiContext¶

IMPLOT_API void SetImGuiContext(ImGuiContext* ctx);

Sets the current ImGui context. This is ONLY necessary if you are compiling
ImPlot as a DLL (not recommended) separate from your ImGui compilation. It sets the global variable GImGui, which is not shared across DLL boundaries.
See GImGui documentation in imgui.cpp for more details.

Begin/End Plot¶

ImPlot::BeginPlot¶

IMPLOT_API bool BeginPlot(const char* title_id, const ImVec2& size=ImVec2(-1,0), ImPlotFlags flags=0);

Starts a 2D plotting context. If this function returns True, EndPlot() MUST be called! You are encouraged to use the following convention:

 if (BeginPlot(...)) {
     PlotLine(...);
     ...
     EndPlot();
 }

Important notes:

• #title_id must be unique to the current ImGui ID scope. If you need to avoid ID collisions or don’t want to display a title in the plot, use double hashes (e.g. “MyPlot##HiddenIdText” or “##NoTitle”).

• #size is the frame size of the plot widget, not the plot area. The default size of plots (i.e. when ImVec2(0,0)) can be modified in your ImPlotStyle.

ImPlot::EndPlot¶

IMPLOT_API void EndPlot();

Only call EndPlot() if BeginPlot() returns True! Typically called at the end of an if statement conditioned on BeginPlot(). See example above.

Begin/End Subplots¶

SubplotsRowColRatios (struct)¶

ImPlot::BeginSubplotsWithRatios¶

IMPLOT_API inline bool BeginSubplotsWithRatios(const char* title_id, int rows, int cols, const ImVec2& size, ImPlotSubplotFlags flags = 0, SubplotsRowColRatios* row_col_ratios = nullptr);

ImPlot::EndSubplots¶

IMPLOT_API void EndSubplots();

Only call EndSubplots() if BeginSubplots() returns True! Typically called at the end of an if statement conditioned on BeginSubplots(). See example above.

Setup¶

ImPlot::SetupAxis¶

IMPLOT_API void SetupAxis(ImAxis axis, const char* label=nullptr, ImPlotAxisFlags flags=0);

Enables an axis or sets the label and/or flags for an existing axis. Leave #label = None for no label.

The following API allows you to setup and customize various aspects of the current plot. The functions should be called immediately after BeginPlot and before any other API calls. Typical usage is as follows:

if (BeginPlot(...)) {                     1) begin a new plot
    SetupAxis(ImAxis_X1, "My X-Axis");    2) make Setup calls
    SetupAxis(ImAxis_Y1, "My Y-Axis");
    SetupLegend(ImPlotLocation_North);
    ...
    SetupFinish();                        3) [optional] explicitly finish setup
    PlotLine(...);                        4) plot items
    ...
    EndPlot();                            5) end the plot
}

Important notes:

• Always call Setup code at the top of your BeginPlot conditional statement.

• Setup is locked once you start plotting or explicitly call SetupFinish.
  Do NOT call Setup code after you begin plotting or after you make any non-Setup API calls (e.g. utils like PlotToPixels also lock Setup)

• Calling SetupFinish is OPTIONAL, but probably good practice. If you do not call it yourself, then the first subsequent plotting or utility function will call it for you.

ImPlot::SetupAxisLimits¶

IMPLOT_API void SetupAxisLimits(ImAxis axis, double v_min, double v_max, ImPlotCond cond = ImPlotCond_Once);

Sets an axis range limits. If ImPlotCond_Always is used, the axes limits will be locked. Inversion with v_min > v_max is not supported; use SetupAxisLimits instead.

ImPlot::SetupAxisLinks¶

IMPLOT_API inline void SetupAxisLinks(ImAxis axis, BoxedValue* link_min, BoxedValue* link_max);

Links an axis range limits to external values. Use BoxedValue to transmit values (which will be updated after EndPlot).

ImPlot::SetupAxisFormat¶

IMPLOT_API void SetupAxisFormat(ImAxis axis, const char* fmt);

Sets the format of numeric axis labels via formatter specifier (default=“%g”). Formatted values will be double (i.e. use %f).

ImPlot::SetupAxisScale¶

IMPLOT_API void SetupAxisScale(ImAxis axis, ImPlotScale scale);

Sets an axis’ scale using built-in options.

ImPlot::SetupAxisLimitsConstraints¶

IMPLOT_API void SetupAxisLimitsConstraints(ImAxis axis, double v_min, double v_max);

Sets an axis’ limits constraints.

ImPlot::SetupAxisZoomConstraints¶

IMPLOT_API void SetupAxisZoomConstraints(ImAxis axis, double z_min, double z_max);

Sets an axis’ zoom constraints.

ImPlot::SetupAxes¶

IMPLOT_API void SetupAxes(const char* x_label, const char* y_label, ImPlotAxisFlags x_flags=0, ImPlotAxisFlags y_flags=0);

Sets the label and/or flags for primary X and Y axes (shorthand for two calls to SetupAxis).

ImPlot::SetupAxesLimits¶

IMPLOT_API void SetupAxesLimits(double x_min, double x_max, double y_min, double y_max, ImPlotCond cond = ImPlotCond_Once);

Sets the primary X and Y axes range limits. If ImPlotCond_Always is used, the axes limits will be locked (shorthand for two calls to SetupAxisLimits).

ImPlot::SetupLegend¶

IMPLOT_API void SetupLegend(ImPlotLocation location, ImPlotLegendFlags flags=0);

Sets up the plot legend. This can also be called immediately after BeginSubplots when using ImPlotSubplotFlags_ShareItems.

ImPlot::SetupMouseText¶

IMPLOT_API void SetupMouseText(ImPlotLocation location, ImPlotMouseTextFlags flags=0);

Set the location of the current plot’s mouse position text (default = South|East).

ImPlot::SetupFinish¶

IMPLOT_API void SetupFinish();

Explicitly finalize plot setup. Once you call this, you cannot make anymore Setup calls for the current plot!
Note that calling this function is OPTIONAL; it will be called by the first subsequent setup-locking API call.

SetNext¶

ImPlot::SetNextAxisLimits¶

IMPLOT_API void SetNextAxisLimits(ImAxis axis, double v_min, double v_max, ImPlotCond cond = ImPlotCond_Once);

Sets an upcoming axis range limits. If ImPlotCond_Always is used, the axes limits will be locked.

Though you should default to the Setup API above, there are some scenarios where (re)configuring a plot or axis before BeginPlot is needed (e.g. if using a preceding button or slider widget to change the plot limits). In this case, you can use the SetNext API below. While this is not as feature rich as the Setup API, most common needs are provided. These functions can be called anywhere except for inside of Begin/EndPlot. For example: if (ImGui::Button(“Center Plot”))

    ImPlot::SetNextPlotLimits(-1,1,-1,1);
if (ImPlot::BeginPlot(...)) {
    ...
    ImPlot::EndPlot();
}

Important notes:

• You must still enable non-default axes with SetupAxis for these functions to work properly.

ImPlot::SetNextAxisLinks¶

IMPLOT_API inline void SetNextAxisLinks(ImAxis axis, BoxedValue* link_min, BoxedValue* link_max);

Links an upcoming axis range limits to external values. Use BoxedValue to transmit values (which will be updated after EndPlot).

ImPlot::SetNextAxisToFit¶

IMPLOT_API void SetNextAxisToFit(ImAxis axis);

Set an upcoming axis to auto fit to its data.

ImPlot::SetNextAxesLimits¶

IMPLOT_API void SetNextAxesLimits(double x_min, double x_max, double y_min, double y_max, ImPlotCond cond = ImPlotCond_Once);

Sets the upcoming primary X and Y axes range limits. If ImPlotCond_Always is used, the axes limits will be locked (shorthand for two calls to SetupAxisLimits).

ImPlot::SetNextAxesToFit¶

IMPLOT_API void SetNextAxesToFit();

Sets all upcoming axes to auto fit to their data.

Plot Items¶

ImPlot::PlotLine¶

IMPLOT_TMP void PlotLine(const char* label_id, const T* values, int count, double xscale=1, double xstart=0, const ImPlotSpec& spec=ImPlotSpec());

IMPLOT_TMP void PlotLine(const char* label_id, const T* xs, const T* ys, int count, const ImPlotSpec& spec=ImPlotSpec());

The main plotting API is provided below. Call these functions between
Begin/EndPlot and after any Setup API calls. Each plots data on the current x and y axes, which can be changed with SetAxis/Axes.
The templated functions are explicitly instantiated in implot_items.cpp.
They are not intended to be used generically with custom types. You will get a linker error if you try! All functions support the following scalar types: float, double, ImS8, ImU8, ImS16, ImU16, ImS32, ImU32, ImS64, ImU64
If you need to plot custom or non-homogenous data you have a few options:

1. If your data is a simple struct/class (e.g. Vector2f), you can use striding in your ImPlotSpec.
   This is the most performant option if applicable.

   struct Vector2f { float X, Y; };
   ...
   Vector2f data[42];
   ImPlot::PlotLine("line", &data[0].x, &data[0].y, 42, {ImPlotProp_Stride, sizeof(Vector2f});

2. Write a custom getter C function or C++ lambda and pass it and optionally your data to an ImPlot function post-fixed with a G (e.g. PlotScatterG). This has a slight performance cost, but probably not enough to worry about unless your data is very large. Examples:

   ImPlotPoint MyDataGetter(int idx, None* data) {
       MyData* my_data = (MyData*)data;
       ImPlotPoint p;
       p.x = my_data->GetTime(idx);
       p.y = my_data->GetValue(idx);

   return p

   }
   ...
   auto my_lambda = [](int idx, None*) {
       double t = idx / 999.0;
       return ImPlotPoint(t, 0.5+0.5*std::sin(2*PI*10*t));
   };
   ...
   if (ImPlot::BeginPlot("MyPlot")) {
       MyData my_data;
       ImPlot::PlotScatterG("scatter", MyDataGetter, &my_data, my_data.Size());
       ImPlot::PlotLineG("line", my_lambda, None, 1000);
       ImPlot::EndPlot();
   }

NB: All types are converted to double before plotting. You may lose information if you try plotting extremely large 64-bit integral types. Proceed with caution!
Plots a standard 2D line plot.

ImPlot::PlotScatter¶

IMPLOT_TMP void PlotScatter(const char* label_id, const T* values, int count, double xscale=1, double xstart=0, const ImPlotSpec& spec=ImPlotSpec());

IMPLOT_TMP void PlotScatter(const char* label_id, const T* xs, const T* ys, int count, const ImPlotSpec& spec=ImPlotSpec());

Plots a standard 2D scatter plot. Default marker is ImPlotMarker_Circle.

ImPlot::PlotBubbles¶

IMPLOT_TMP void PlotBubbles(const char* label_id, const T* values, const T* szs, int count, double xscale=1, double xstart=0, const ImPlotSpec& spec=ImPlotSpec());

IMPLOT_TMP void PlotBubbles(const char* label_id, const T* xs, const T* ys, const T* szs, int count, const ImPlotSpec& spec=ImPlotSpec());

Note: all array arguments must share the same dtype (e.g. xs = xs.astype(ys.dtype)).

Plots a bubble graph. #szs are the radius of each bubble in plot units.

ImPlot::PlotPolygon¶

IMPLOT_TMP void PlotPolygon(const char* label_id, const T* xs, const T* ys, int count, const ImPlotSpec& spec=ImPlotSpec());

Plots a polygon. Points are specified in counter-clockwise order. If concave, make sure to set the Concave flag.

Note: all array arguments must share the same dtype (e.g. xs = xs.astype(ys.dtype)).

ImPlot::PlotStairs¶

IMPLOT_TMP void PlotStairs(const char* label_id, const T* values, int count, double xscale=1, double xstart=0, const ImPlotSpec& spec=ImPlotSpec());

IMPLOT_TMP void PlotStairs(const char* label_id, const T* xs, const T* ys, int count, const ImPlotSpec& spec=ImPlotSpec());

Plots a a stairstep graph. The y value is continued constantly to the right from every x position, i.e. the interval [x[i], x[i+1]) has the value y[i]

ImPlot::PlotShaded¶

IMPLOT_TMP void PlotShaded(const char* label_id, const T* values, int count, double yref=0, double xscale=1, double xstart=0, const ImPlotSpec& spec=ImPlotSpec());

IMPLOT_TMP void PlotShaded(const char* label_id, const T* xs, const T* ys, int count, double yref=0, const ImPlotSpec& spec=ImPlotSpec());

IMPLOT_TMP void PlotShaded(const char* label_id, const T* xs, const T* ys1, const T* ys2, int count, const ImPlotSpec& spec=ImPlotSpec());

Plots a shaded (filled) region between two lines, or a line and a horizontal reference. Set yref to +/-INFINITY for infinite fill extents.

ImPlot::PlotBars¶

IMPLOT_TMP void PlotBars(const char* label_id, const T* values, int count, double bar_size=0.67, double shift=0, const ImPlotSpec& spec=ImPlotSpec());

IMPLOT_TMP void PlotBars(const char* label_id, const T* xs, const T* ys, int count, double bar_size, const ImPlotSpec& spec=ImPlotSpec());

Plots a bar graph. Vertical by default. #bar_size and #shift are in plot units.

ImPlot::PlotBarGroups¶

IMPLOT_TMP void PlotBarGroups(const std::vector<std::string>& label_ids, const T* values, int count, double group_size=0.67, double shift=0, const ImPlotSpec& spec=ImPlotSpec());

Plots a group of bars.

• values should be a 1 dimension numpy array of values.

• label_ids should be a list of strings corresponding to bars labels

ImPlot::PlotErrorBars¶

IMPLOT_TMP void PlotErrorBars(const char* label_id, const T* xs, const T* ys, const T* err, int count, const ImPlotSpec& spec=ImPlotSpec());

IMPLOT_TMP void PlotErrorBars(const char* label_id, const T* xs, const T* ys, const T* neg, const T* pos, int count, const ImPlotSpec& spec=ImPlotSpec());

Note: all array arguments must share the same dtype (e.g. xs = xs.astype(ys.dtype)).

Plots vertical error bar. The label_id should be the same as the label_id of the associated line or bar plot.

ImPlot::PlotStems¶

IMPLOT_TMP void PlotStems(const char* label_id, const T* values, int count, double ref=0, double scale=1, double start=0, const ImPlotSpec& spec=ImPlotSpec());

IMPLOT_TMP void PlotStems(const char* label_id, const T* xs, const T* ys, int count, double ref=0, const ImPlotSpec& spec=ImPlotSpec());

Plots stems. Vertical by default.

ImPlot::PlotInfLines¶

IMPLOT_TMP void PlotInfLines(const char* label_id, const T* values, int count, const ImPlotSpec& spec=ImPlotSpec());

Plots infinite vertical or horizontal lines (e.g. for references or asymptotes).

ImPlot::PlotPieChart¶

IMPLOT_TMP void PlotPieChart(const char* const label_ids[], const T* values, int count, double x, double y, double radius, const char* label_fmt="%.1f", double angle0=90, const ImPlotSpec& spec=ImPlotSpec());

Plots a pie chart. Center and radius are in plot units. #label_fmt can be set to None for no labels.

ImPlot::PlotHistogram¶

IMPLOT_TMP double PlotHistogram(const char* label_id, const T* values, int count, int bins=ImPlotBin_Sturges, double bar_scale=1.0, ImPlotRange range=ImPlotRange(), const ImPlotSpec& spec=ImPlotSpec());

Plots a horizontal histogram. #bins can be a positive integer or an ImPlotBin_ method. If #range is left unspecified, the min/max of #values will be used as the range.
Otherwise, outlier values outside of the range are not binned. The largest bin count or density is returned.

ImPlot::PlotHistogram2D¶

IMPLOT_TMP double PlotHistogram2D(const char* label_id, const T* xs, const T* ys, int count, int x_bins=ImPlotBin_Sturges, int y_bins=ImPlotBin_Sturges, ImPlotRect range=ImPlotRect(), const ImPlotSpec& spec=ImPlotSpec());

Plots two dimensional, bivariate histogram as a heatmap. #x_bins and #y_bins can be a positive integer or an ImPlotBin. If #range is left unspecified, the min/max of
#xs an #ys will be used as the ranges. Otherwise, outlier values outside of range are not binned. The largest bin count or density is returned.

Note: all array arguments must share the same dtype (e.g. xs = xs.astype(ys.dtype)).

ImPlot::PlotDigital¶

IMPLOT_TMP void PlotDigital(const char* label_id, const T* xs, const T* ys, int count, const ImPlotSpec& spec=ImPlotSpec());

Note: all array arguments must share the same dtype (e.g. xs = xs.astype(ys.dtype)).

Plots digital data. Digital plots do not respond to y drag or zoom, and are always referenced to the bottom of the plot.

ImPlot::PlotImage¶

IMPLOT_API void PlotImage(const char* label_id, ImTextureRef tex_ref, const ImPlotPoint& bounds_min, const ImPlotPoint& bounds_max, const ImVec2& uv0 = ImVec2(0, 0), const ImVec2& uv1 = ImVec2(1, 1), const ImVec4& tint_col = ImVec4(1, 1, 1, 1), const ImPlotSpec& spec=ImPlotSpec());

Plots an axis-aligned image. #bounds_min/bounds_max are in plot coordinates (y-up) and #uv0/uv1 are in texture coordinates (y-down).

ImPlot::PlotText¶

IMPLOT_API void PlotText(const char* text, double x, double y, const ImVec2& pix_offset=ImVec2(0,0), const ImPlotSpec& spec=ImPlotSpec());

Plots a centered text label at point x,y with an optional pixel offset. Text color can be changed with ImPlot::PushStyleColor(ImPlotCol_InlayText, ...).

ImPlot::PlotDummy¶

IMPLOT_API void PlotDummy(const char* label_id, const ImPlotSpec& spec=ImPlotSpec());

Plots a dummy item (i.e. adds a legend entry colored by ImPlotCol_Line)

Plot Tools¶

ImPlot::DragPoint¶

IMPLOT_API bool DragPoint(int id, double* x, double* y, const ImVec4& col, float size = 4, ImPlotDragToolFlags flags = 0, bool* out_clicked = nullptr, bool* out_hovered = nullptr, bool* out_held = nullptr);

Shows a draggable point at x,y. #col defaults to ImGuiCol_Text.

The following can be used to render interactive elements and/or annotations.
Like the item plotting functions above, they apply to the current x and y axes, which can be changed with SetAxis/SetAxes. These functions return True when user interaction causes the provided coordinates to change. Additional user interactions can be retrieved through the optional output parameters.

ImPlot::DragLineX¶

IMPLOT_API bool DragLineX(int id, double* x, const ImVec4& col, float thickness = 1, ImPlotDragToolFlags flags = 0, bool* out_clicked = nullptr, bool* out_hovered = nullptr, bool* out_held = nullptr);

Shows a draggable vertical guide line at an x-value. #col defaults to ImGuiCol_Text.

ImPlot::DragLineY¶

IMPLOT_API bool DragLineY(int id, double* y, const ImVec4& col, float thickness = 1, ImPlotDragToolFlags flags = 0, bool* out_clicked = nullptr, bool* out_hovered = nullptr, bool* out_held = nullptr);

Shows a draggable horizontal guide line at a y-value. #col defaults to ImGuiCol_Text.

ImPlot::DragRect¶

IMPLOT_API bool DragRect(int id, double* x1, double* y1, double* x2, double* y2, const ImVec4& col, ImPlotDragToolFlags flags = 0, bool* out_clicked = nullptr, bool* out_hovered = nullptr, bool* out_held = nullptr);

Shows a draggable and resizeable rectangle.

ImPlot::Annotation¶

IMPLOT_API void Annotation(double x, double y, const ImVec4& col, const ImVec2& pix_offset, bool clamp, bool round = false);

IMPLOT_API void Annotation(double x, double y, const ImVec4& col, const ImVec2& pix_offset, bool clamp, const char* fmt, ...) ;

Shows an annotation callout at a chosen point. Clamping keeps annotations in the plot area. Annotations are always rendered on top.

ImPlot::TagX¶

IMPLOT_API void TagX(double x, const ImVec4& col, bool round = false);

IMPLOT_API void TagX(double x, const ImVec4& col, const char* fmt, ...) ;

Shows a x-axis tag at the specified coordinate value.

ImPlot::TagY¶

IMPLOT_API void TagY(double y, const ImVec4& col, bool round = false);

IMPLOT_API void TagY(double y, const ImVec4& col, const char* fmt, ...) ;

Shows a y-axis tag at the specified coordinate value.

Plot Utils¶

ImPlot::SetAxis¶

IMPLOT_API void SetAxis(ImAxis axis);

Select which axis/axes will be used for subsequent plot elements.

ImPlot::SetAxes¶

IMPLOT_API void SetAxes(ImAxis x_axis, ImAxis y_axis);

ImPlot::PixelsToPlot¶

IMPLOT_API ImPlotPoint PixelsToPlot(const ImVec2& pix, ImAxis x_axis = IMPLOT_AUTO, ImAxis y_axis = IMPLOT_AUTO);

IMPLOT_API ImPlotPoint PixelsToPlot(float x, float y, ImAxis x_axis = IMPLOT_AUTO, ImAxis y_axis = IMPLOT_AUTO);

Convert pixels to a position in the current plot’s coordinate system. Passing IMPLOT_AUTO uses the current axes.

ImPlot::PlotToPixels¶

IMPLOT_API ImVec2 PlotToPixels(const ImPlotPoint& plt, ImAxis x_axis = IMPLOT_AUTO, ImAxis y_axis = IMPLOT_AUTO);

IMPLOT_API ImVec2 PlotToPixels(double x, double y, ImAxis x_axis = IMPLOT_AUTO, ImAxis y_axis = IMPLOT_AUTO);

Convert a position in the current plot’s coordinate system to pixels. Passing IMPLOT_AUTO uses the current axes.

ImPlot::GetPlotPos¶

IMPLOT_API ImVec2 GetPlotPos();

Get the current Plot position (top-left) in pixels.

ImPlot::GetPlotSize¶

IMPLOT_API ImVec2 GetPlotSize();

Get the current Plot size in pixels.

ImPlot::GetPlotMousePos¶

IMPLOT_API ImPlotPoint GetPlotMousePos(ImAxis x_axis = IMPLOT_AUTO, ImAxis y_axis = IMPLOT_AUTO);

Returns the mouse position in x,y coordinates of the current plot. Passing IMPLOT_AUTO uses the current axes.

ImPlot::GetPlotLimits¶

IMPLOT_API ImPlotRect GetPlotLimits(ImAxis x_axis = IMPLOT_AUTO, ImAxis y_axis = IMPLOT_AUTO);

Returns the current plot axis range.

ImPlot::IsPlotHovered¶

IMPLOT_API bool IsPlotHovered();

Returns True if the plot area in the current plot is hovered.

ImPlot::IsAxisHovered¶

IMPLOT_API bool IsAxisHovered(ImAxis axis);

Returns True if the axis label area in the current plot is hovered.

ImPlot::IsSubplotsHovered¶

IMPLOT_API bool IsSubplotsHovered();

Returns True if the bounding frame of a subplot is hovered.

ImPlot::IsPlotSelected¶

IMPLOT_API bool IsPlotSelected();

Returns True if the current plot is being box selected.

ImPlot::GetPlotSelection¶

IMPLOT_API ImPlotRect GetPlotSelection(ImAxis x_axis = IMPLOT_AUTO, ImAxis y_axis = IMPLOT_AUTO);

Returns the current plot box selection bounds. Passing IMPLOT_AUTO uses the current axes.

ImPlot::CancelPlotSelection¶

IMPLOT_API void CancelPlotSelection();

Cancels a the current plot box selection.

ImPlot::HideNextItem¶

IMPLOT_API void HideNextItem(bool hidden = true, ImPlotCond cond = ImPlotCond_Once);

Hides or shows the next plot item (i.e. as if it were toggled from the legend).
Use ImPlotCond_Always if you need to forcefully set this every frame.

ImPlot::BeginAlignedPlots¶

IMPLOT_API bool BeginAlignedPlots(const char* group_id, bool vertical = true);

Align axis padding over multiple plots in a single row or column. #group_id must be unique. If this function returns True, EndAlignedPlots() must be called.

Use the following around calls to Begin/EndPlot to align l/r/t/b padding.
Consider using Begin/EndSubplots first. They are more feature rich and accomplish the same behaviour by default. The functions below offer lower level control of plot alignment.

ImPlot::EndAlignedPlots¶

IMPLOT_API void EndAlignedPlots();

Only call EndAlignedPlots() if BeginAlignedPlots() returns True!

Legend Utils¶

ImPlot::BeginLegendPopup¶

IMPLOT_API bool BeginLegendPopup(const char* label_id, ImGuiMouseButton mouse_button=1);

Begin a popup for a legend entry.

ImPlot::EndLegendPopup¶

IMPLOT_API void EndLegendPopup();

End a popup for a legend entry.

ImPlot::IsLegendEntryHovered¶

IMPLOT_API bool IsLegendEntryHovered(const char* label_id);

Returns True if a plot item legend entry is hovered.

Drag and Drop¶

ImPlot::BeginDragDropTargetPlot¶

IMPLOT_API bool BeginDragDropTargetPlot();

Turns the current plot’s plotting area into a drag and drop target. Don’t forget to call EndDragDropTarget!

ImPlot::BeginDragDropTargetAxis¶

IMPLOT_API bool BeginDragDropTargetAxis(ImAxis axis);

Turns the current plot’s X-axis into a drag and drop target. Don’t forget to call EndDragDropTarget!

ImPlot::BeginDragDropTargetLegend¶

IMPLOT_API bool BeginDragDropTargetLegend();

Turns the current plot’s legend into a drag and drop target. Don’t forget to call EndDragDropTarget!

ImPlot::EndDragDropTarget¶

IMPLOT_API void EndDragDropTarget();

Ends a drag and drop target (currently just an alias for ImGui::EndDragDropTarget).

ImPlot::BeginDragDropSourcePlot¶

IMPLOT_API bool BeginDragDropSourcePlot(ImGuiDragDropFlags flags=0);

Turns the current plot’s plotting area into a drag and drop source. You must hold Ctrl. Don’t forget to call EndDragDropSource!

NB: By default, plot and axes drag and drop sources require holding the Ctrl modifier to initiate the drag.
You can change the modifier if desired. If ImGuiMod_None is provided, the axes will be locked from panning.

ImPlot::BeginDragDropSourceAxis¶

IMPLOT_API bool BeginDragDropSourceAxis(ImAxis axis, ImGuiDragDropFlags flags=0);

Turns the current plot’s X-axis into a drag and drop source. You must hold Ctrl. Don’t forget to call EndDragDropSource!

ImPlot::BeginDragDropSourceItem¶

IMPLOT_API bool BeginDragDropSourceItem(const char* label_id, ImGuiDragDropFlags flags=0);

Turns an item in the current plot’s legend into drag and drop source. Don’t forget to call EndDragDropSource!

ImPlot::EndDragDropSource¶

IMPLOT_API void EndDragDropSource();

Ends a drag and drop source (currently just an alias for ImGui::EndDragDropSource).

Styling¶

ImPlot::GetStyle¶

IMPLOT_API ImPlotStyle& GetStyle();

Styling colors in ImPlot works similarly to styling colors in ImGui, but with one important difference. Like ImGui, all style colors are stored in an indexable array in ImPlotStyle. You can permanently modify these values through
GetStyle().Colors, or temporarily modify them with Push/Pop functions below.
However, by default all style colors in ImPlot default to a special color
IMPLOT_AUTO_COL. IMPLOT_AUTO_COL tells ImPlot to set that color from color data in your ImGuiStyle. The ImGuiCol_ that these style colors default to are detailed above, and in general have been mapped to produce plots visually consistent with your current ImGui style. Of course, you are free to manually set these colors to whatever you like, and further can Push/Pop them around individual plots for plot-specific styling (e.g. coloring axes).
Provides access to plot style structure for permanent modifications to colors, sizes, etc.

ImPlot::SetStyle¶

IMPLOT_API void SetStyle(const ImPlotStyle& style);

ImPlot::StyleColorsAuto¶

IMPLOT_API void StyleColorsAuto(ImPlotStyle* dst = nullptr);

Style plot colors for current ImGui style (default).

ImPlot::StyleColorsClassic¶

IMPLOT_API void StyleColorsClassic(ImPlotStyle* dst = nullptr);

Style plot colors for ImGui “Classic”.

ImPlot::StyleColorsDark¶

IMPLOT_API void StyleColorsDark(ImPlotStyle* dst = nullptr);

Style plot colors for ImGui “Dark”.

ImPlot::StyleColorsLight¶

IMPLOT_API void StyleColorsLight(ImPlotStyle* dst = nullptr);

Style plot colors for ImGui “Light”.

ImPlot::PushStyleColor¶

IMPLOT_API void PushStyleColor(ImPlotCol idx, ImU32 col);

IMPLOT_API void PushStyleColor(ImPlotCol idx, const ImVec4& col);

Use PushStyleX to temporarily modify your ImPlotStyle. The modification will last until the matching call to PopStyleX. You MUST call a pop for every push, otherwise you will leak memory! This behaves just like ImGui.
Temporarily modify a style color. Don’t forget to call PopStyleColor!

ImPlot::PopStyleColor¶

IMPLOT_API void PopStyleColor(int count = 1);

Undo temporary style color modification(s). Undo multiple pushes at once by increasing count.

ImPlot::PushStyleVar¶

IMPLOT_API void PushStyleVar(ImPlotStyleVar idx, int val);

IMPLOT_API void PushStyleVar(ImPlotStyleVar idx, float val);

IMPLOT_API void PushStyleVar(ImPlotStyleVar idx, const ImVec2& val);

Temporarily modify a style variable of int type. Don’t forget to call PopStyleVar!

ImPlot::PopStyleVar¶

IMPLOT_API void PopStyleVar(int count = 1);

Undo temporary style variable modification(s). Undo multiple pushes at once by increasing count.

ImPlot::GetLastItemColor¶

IMPLOT_API ImVec4 GetLastItemColor();

Gets the last item primary color (i.e. its legend icon color)

ImPlot::GetStyleColorName¶

IMPLOT_API const char* GetStyleColorName(ImPlotCol idx);

Returns the null terminated string name for an ImPlotCol.

ImPlot::GetMarkerName¶

IMPLOT_API const char* GetMarkerName(ImPlotMarker idx);

Returns the null terminated string name for an ImPlotMarker.

ImPlot::NextMarker¶

IMPLOT_API ImPlotMarker NextMarker();

Returns the next marker and advances the marker for the current plot. You need to call this between Begin/EndPlot!

Colormaps¶

ImPlot::GetColormapCount¶

IMPLOT_API int GetColormapCount();

Returns the number of available colormaps (i.e. the built-in + user-added count).

Item styling is based on colormaps when the relevant ImPlotCol_XXX is set to
IMPLOT_AUTO_COL (default). Several built-in colormaps are available. You can add and then push/pop your own colormaps as well. To permanently set a colormap, modify the Colormap index member of your ImPlotStyle.
Colormap data will be ignored and a custom color will be used if you have done one of the following: 1) Modified an item style color in your ImPlotStyle to anything other than IMPLOT_AUTO_COL. 2) Pushed an item style color using PushStyleColor(). 3) Set the next item style with a SetNextXXXStyle function.
Add a new colormap. The color data will be copied. The colormap can be used by pushing either the returned index or the string name with PushColormap. The colormap name must be unique and the size must be greater than 1. You will receive an assert otherwise! By default colormaps are considered to be qualitative (i.e. discrete). If you want to create a continuous colormap, set #qual=False. This will treat the colors you provide as keys, and ImPlot will build a linearly interpolated lookup table. The memory footprint of this table will be exactly ((size-1)*255+1)*4 bytes.

ImPlot::GetColormapName¶

IMPLOT_API const char* GetColormapName(ImPlotColormap cmap);

Returns a null terminated string name for a colormap given an index. Returns None if index is invalid.

ImPlot::GetColormapIndex¶

IMPLOT_API ImPlotColormap GetColormapIndex(const char* name);

Returns an index number for a colormap given a valid string name. Returns -1 if name is invalid.

ImPlot::PushColormap¶

IMPLOT_API void PushColormap(ImPlotColormap cmap);

IMPLOT_API void PushColormap(const char* name);

Temporarily switch to one of the built-in (i.e. ImPlotColormap_XXX) or user-added colormaps (i.e. a return value of AddColormap). Don’t forget to call PopColormap!

ImPlot::PopColormap¶

IMPLOT_API void PopColormap(int count = 1);

Undo temporary colormap modification(s). Undo multiple pushes at once by increasing count.

ImPlot::NextColormapColor¶

IMPLOT_API ImVec4 NextColormapColor();

Returns the next color from the current colormap and advances the colormap for the current plot.
Can also be used with no return value to skip colors if desired. You need to call this between Begin/EndPlot!

ImPlot::GetColormapSize¶

IMPLOT_API int GetColormapSize(ImPlotColormap cmap = IMPLOT_AUTO);

Returns the size of a colormap.

Colormap utils. If cmap = IMPLOT_AUTO (default), the current colormap is assumed.
Pass an explicit colormap index (built-in or user-added) to specify otherwise.

ImPlot::GetColormapColor¶

IMPLOT_API ImVec4 GetColormapColor(int idx, ImPlotColormap cmap = IMPLOT_AUTO);

Returns a color from a colormap given an index >= 0 (modulo will be performed).

ImPlot::SampleColormap¶

IMPLOT_API ImVec4 SampleColormap(float t, ImPlotColormap cmap = IMPLOT_AUTO);

Sample a color from the current colormap given t between 0 and 1.

ImPlot::ColormapScale¶

IMPLOT_API void ColormapScale(const char* label, double scale_min, double scale_max, const ImVec2& size = ImVec2(0,0), const char* format = "%g", ImPlotColormapScaleFlags flags = 0, ImPlotColormap cmap = IMPLOT_AUTO);

Shows a vertical color scale with linear spaced ticks using the specified color map. Use double hashes to hide label (e.g. “##NoLabel”). If scale_min > scale_max, the scale to color mapping will be reversed.

ImPlot::ColormapSlider¶

IMPLOT_API bool ColormapSlider(const char* label, float* t, ImVec4* out = nullptr, const char* format = "", ImPlotColormap cmap = IMPLOT_AUTO);

Shows a horizontal slider with a colormap gradient background. Optionally returns the color sampled at t in [0 1].

ImPlot::ColormapButton¶

IMPLOT_API bool ColormapButton(const char* label, const ImVec2& size = ImVec2(0,0), ImPlotColormap cmap = IMPLOT_AUTO);

Shows a button with a colormap gradient background.

ImPlot::BustColorCache¶

IMPLOT_API void BustColorCache(const char* plot_title_id = nullptr);

When items in a plot sample their color from a colormap, the color is cached and does not change unless explicitly overridden. Therefore, if you change the colormap after the item has already been plotted, item colors will NOT update. If you need item colors to resample the new colormap, then use this function to bust the cached colors. If #plot_title_id is None, then every item in EVERY existing plot will be cache busted. Otherwise only the plot specified by #plot_title_id will be busted. For the latter, this function must be called in the same ImGui ID scope that the plot is in. You should rarely if ever need this function, but it is available for applications that require runtime colormap swaps (e.g. Heatmaps demo).

Input Mapping¶

ImPlot::GetInputMap¶

IMPLOT_API ImPlotInputMap& GetInputMap();

Provides access to input mapping structure for permanent modifications to controls for pan, select, etc.

ImPlot::MapInputDefault¶

IMPLOT_API void MapInputDefault(ImPlotInputMap* dst = nullptr);

Default input mapping: pan = LMB drag, box select = RMB drag, fit = LMB double click, context menu = RMB click, zoom = scroll.

ImPlot::MapInputReverse¶

IMPLOT_API void MapInputReverse(ImPlotInputMap* dst = nullptr);

Reverse input mapping: pan = RMB drag, box select = LMB drag, fit = LMB double click, context menu = RMB click, zoom = scroll.

Miscellaneous¶

ImPlot::ItemIcon¶

IMPLOT_API void ItemIcon(const ImVec4& col);

IMPLOT_API void ItemIcon(ImU32 col);

Render icons similar to those that appear in legends (nifty for data lists).

ImPlot::ColormapIcon¶

IMPLOT_API void ColormapIcon(ImPlotColormap cmap);

ImPlot::GetPlotDrawList¶

IMPLOT_API ImDrawList* GetPlotDrawList();

Get the plot draw list for custom rendering to the current plot area. Call between Begin/EndPlot.

ImPlot::PushPlotClipRect¶

IMPLOT_API void PushPlotClipRect(float expand=0);

Push clip rect for rendering to current plot area. The rect can be expanded or contracted by #expand pixels. Call between Begin/EndPlot.

ImPlot::PopPlotClipRect¶

IMPLOT_API void PopPlotClipRect();

Pop plot clip rect. Call between Begin/EndPlot.

ImPlot::ShowStyleSelector¶

IMPLOT_API bool ShowStyleSelector(const char* label);

Shows ImPlot style selector dropdown menu.

ImPlot::ShowColormapSelector¶

IMPLOT_API bool ShowColormapSelector(const char* label);

Shows ImPlot colormap selector dropdown menu.

ImPlot::ShowInputMapSelector¶

IMPLOT_API bool ShowInputMapSelector(const char* label);

Shows ImPlot input map selector dropdown menu.

ImPlot::ShowStyleEditor¶

IMPLOT_API void ShowStyleEditor(ImPlotStyle* ref = nullptr);

Shows ImPlot style editor block (not a window).

ImPlot::ShowUserGuide¶

IMPLOT_API void ShowUserGuide();

Add basic help/info block for end users (not a window).

ImPlot::ShowMetricsWindow¶

IMPLOT_API void ShowMetricsWindow(bool* p_popen = nullptr);

Shows ImPlot metrics/debug information window.

Demo¶

ImPlot::ShowDemoWindow¶

IMPLOT_API void ShowDemoWindow(bool* p_open = nullptr);

Shows the ImPlot demo window (add implot_demo.cpp to your sources!)

ImPlot::ShowDemoWindow_MaybeDocked¶

IMPLOT_API void ShowDemoWindow_MaybeDocked(bool create_window, bool* p_open = NULL, ImGuiWindowFlags initial_extra_flags = 0, ImVec2 window_pos = ImVec2(0, 0), ImVec2 window_size = ImVec2(0, 0));

Bundle: ShowDemoWindow_MaybeDocked is ShowDemoWindow, but can be used without creating an ImGui window.