vsgImGui 0.7.0
VulkanSceneGraph, ImGui and ImPlot integration library
 
Loading...
Searching...
No Matches
implot.h
1// MIT License
2
3// Copyright (c) 2023 Evan Pezent
4
5// Permission is hereby granted, free of charge, to any person obtaining a copy
6// of this software and associated documentation files (the "Software"), to deal
7// in the Software without restriction, including without limitation the rights
8// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9// copies of the Software, and to permit persons to whom the Software is
10// furnished to do so, subject to the following conditions:
11
12// The above copyright notice and this permission notice shall be included in all
13// copies or substantial portions of the Software.
14
15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21// SOFTWARE.
22
23// ImPlot v0.17
24
25// Table of Contents:
26//
27// [SECTION] Macros and Defines
28// [SECTION] Enums and Types
29// [SECTION] Callbacks
30// [SECTION] Contexts
31// [SECTION] Begin/End Plot
32// [SECTION] Begin/End Subplot
33// [SECTION] Setup
34// [SECTION] SetNext
35// [SECTION] Plot Items
36// [SECTION] Plot Tools
37// [SECTION] Plot Utils
38// [SECTION] Legend Utils
39// [SECTION] Drag and Drop
40// [SECTION] Styling
41// [SECTION] Colormaps
42// [SECTION] Input Mapping
43// [SECTION] Miscellaneous
44// [SECTION] Demo
45// [SECTION] Obsolete API
46
47#pragma once
48#include "imgui.h"
49
50//-----------------------------------------------------------------------------
51// [SECTION] Macros and Defines
52//-----------------------------------------------------------------------------
53
54// Define attributes of all API symbols declarations (e.g. for DLL under Windows)
55// Using ImPlot via a shared library is not recommended, because we don't guarantee
56// backward nor forward ABI compatibility and also function call overhead. If you
57// do use ImPlot as a DLL, be sure to call SetImGuiContext (see Miscellanous section).
58#ifndef IMPLOT_API
59#define IMPLOT_API
60#endif
61
62// ImPlot version string.
63#define IMPLOT_VERSION "0.17"
64// Indicates variable should deduced automatically.
65#define IMPLOT_AUTO -1
66// Special color used to indicate that a color should be deduced automatically.
67#define IMPLOT_AUTO_COL ImVec4(0,0,0,-1)
68// Macro for templated plotting functions; keeps header clean.
69#define IMPLOT_TMP template <typename T> IMPLOT_API
70
71//-----------------------------------------------------------------------------
72// [SECTION] Enums and Types
73//-----------------------------------------------------------------------------
74
75// Forward declarations
76struct ImPlotContext; // ImPlot context (opaque struct, see implot_internal.h)
77
78// Enums/Flags
79typedef int ImAxis; // -> enum ImAxis_
80typedef int ImPlotFlags; // -> enum ImPlotFlags_
81typedef int ImPlotAxisFlags; // -> enum ImPlotAxisFlags_
82typedef int ImPlotSubplotFlags; // -> enum ImPlotSubplotFlags_
83typedef int ImPlotLegendFlags; // -> enum ImPlotLegendFlags_
84typedef int ImPlotMouseTextFlags; // -> enum ImPlotMouseTextFlags_
85typedef int ImPlotDragToolFlags; // -> ImPlotDragToolFlags_
86typedef int ImPlotColormapScaleFlags; // -> ImPlotColormapScaleFlags_
87
88typedef int ImPlotItemFlags; // -> ImPlotItemFlags_
89typedef int ImPlotLineFlags; // -> ImPlotLineFlags_
90typedef int ImPlotScatterFlags; // -> ImPlotScatterFlags
91typedef int ImPlotStairsFlags; // -> ImPlotStairsFlags_
92typedef int ImPlotShadedFlags; // -> ImPlotShadedFlags_
93typedef int ImPlotBarsFlags; // -> ImPlotBarsFlags_
94typedef int ImPlotBarGroupsFlags; // -> ImPlotBarGroupsFlags_
95typedef int ImPlotErrorBarsFlags; // -> ImPlotErrorBarsFlags_
96typedef int ImPlotStemsFlags; // -> ImPlotStemsFlags_
97typedef int ImPlotInfLinesFlags; // -> ImPlotInfLinesFlags_
98typedef int ImPlotPieChartFlags; // -> ImPlotPieChartFlags_
99typedef int ImPlotHeatmapFlags; // -> ImPlotHeatmapFlags_
100typedef int ImPlotHistogramFlags; // -> ImPlotHistogramFlags_
101typedef int ImPlotDigitalFlags; // -> ImPlotDigitalFlags_
102typedef int ImPlotImageFlags; // -> ImPlotImageFlags_
103typedef int ImPlotTextFlags; // -> ImPlotTextFlags_
104typedef int ImPlotDummyFlags; // -> ImPlotDummyFlags_
105
106typedef int ImPlotCond; // -> enum ImPlotCond_
107typedef int ImPlotCol; // -> enum ImPlotCol_
108typedef int ImPlotStyleVar; // -> enum ImPlotStyleVar_
109typedef int ImPlotScale; // -> enum ImPlotScale_
110typedef int ImPlotMarker; // -> enum ImPlotMarker_
111typedef int ImPlotColormap; // -> enum ImPlotColormap_
112typedef int ImPlotLocation; // -> enum ImPlotLocation_
113typedef int ImPlotBin; // -> enum ImPlotBin_
114
115// Axis indices. The values assigned may change; NEVER hardcode these.
116enum ImAxis_ {
117 // horizontal axes
118 ImAxis_X1 = 0, // enabled by default
119 ImAxis_X2, // disabled by default
120 ImAxis_X3, // disabled by default
121 // vertical axes
122 ImAxis_Y1, // enabled by default
123 ImAxis_Y2, // disabled by default
124 ImAxis_Y3, // disabled by default
125 // bookeeping
126 ImAxis_COUNT
127};
128
129// Options for plots (see BeginPlot).
130enum ImPlotFlags_ {
131 ImPlotFlags_None = 0, // default
132 ImPlotFlags_NoTitle = 1 << 0, // the plot title will not be displayed (titles are also hidden if preceeded by double hashes, e.g. "##MyPlot")
133 ImPlotFlags_NoLegend = 1 << 1, // the legend will not be displayed
134 ImPlotFlags_NoMouseText = 1 << 2, // the mouse position, in plot coordinates, will not be displayed inside of the plot
135 ImPlotFlags_NoInputs = 1 << 3, // the user will not be able to interact with the plot
136 ImPlotFlags_NoMenus = 1 << 4, // the user will not be able to open context menus
137 ImPlotFlags_NoBoxSelect = 1 << 5, // the user will not be able to box-select
138 ImPlotFlags_NoFrame = 1 << 6, // the ImGui frame will not be rendered
139 ImPlotFlags_Equal = 1 << 7, // x and y axes pairs will be constrained to have the same units/pixel
140 ImPlotFlags_Crosshairs = 1 << 8, // the default mouse cursor will be replaced with a crosshair when hovered
141 ImPlotFlags_CanvasOnly = ImPlotFlags_NoTitle | ImPlotFlags_NoLegend | ImPlotFlags_NoMenus | ImPlotFlags_NoBoxSelect | ImPlotFlags_NoMouseText
142};
143
144// Options for plot axes (see SetupAxis).
145enum ImPlotAxisFlags_ {
146 ImPlotAxisFlags_None = 0, // default
147 ImPlotAxisFlags_NoLabel = 1 << 0, // the axis label will not be displayed (axis labels are also hidden if the supplied string name is nullptr)
148 ImPlotAxisFlags_NoGridLines = 1 << 1, // no grid lines will be displayed
149 ImPlotAxisFlags_NoTickMarks = 1 << 2, // no tick marks will be displayed
150 ImPlotAxisFlags_NoTickLabels = 1 << 3, // no text labels will be displayed
151 ImPlotAxisFlags_NoInitialFit = 1 << 4, // axis will not be initially fit to data extents on the first rendered frame
152 ImPlotAxisFlags_NoMenus = 1 << 5, // the user will not be able to open context menus with right-click
153 ImPlotAxisFlags_NoSideSwitch = 1 << 6, // the user will not be able to switch the axis side by dragging it
154 ImPlotAxisFlags_NoHighlight = 1 << 7, // the axis will not have its background highlighted when hovered or held
155 ImPlotAxisFlags_Opposite = 1 << 8, // axis ticks and labels will be rendered on the conventionally opposite side (i.e, right or top)
156 ImPlotAxisFlags_Foreground = 1 << 9, // grid lines will be displayed in the foreground (i.e. on top of data) instead of the background
157 ImPlotAxisFlags_Invert = 1 << 10, // the axis will be inverted
158 ImPlotAxisFlags_AutoFit = 1 << 11, // axis will be auto-fitting to data extents
159 ImPlotAxisFlags_RangeFit = 1 << 12, // axis will only fit points if the point is in the visible range of the **orthogonal** axis
160 ImPlotAxisFlags_PanStretch = 1 << 13, // panning in a locked or constrained state will cause the axis to stretch if possible
161 ImPlotAxisFlags_LockMin = 1 << 14, // the axis minimum value will be locked when panning/zooming
162 ImPlotAxisFlags_LockMax = 1 << 15, // the axis maximum value will be locked when panning/zooming
163 ImPlotAxisFlags_Lock = ImPlotAxisFlags_LockMin | ImPlotAxisFlags_LockMax,
164 ImPlotAxisFlags_NoDecorations = ImPlotAxisFlags_NoLabel | ImPlotAxisFlags_NoGridLines | ImPlotAxisFlags_NoTickMarks | ImPlotAxisFlags_NoTickLabels,
165 ImPlotAxisFlags_AuxDefault = ImPlotAxisFlags_NoGridLines | ImPlotAxisFlags_Opposite
166};
167
168// Options for subplots (see BeginSubplot)
169enum ImPlotSubplotFlags_ {
170 ImPlotSubplotFlags_None = 0, // default
171 ImPlotSubplotFlags_NoTitle = 1 << 0, // the subplot title will not be displayed (titles are also hidden if preceeded by double hashes, e.g. "##MySubplot")
172 ImPlotSubplotFlags_NoLegend = 1 << 1, // the legend will not be displayed (only applicable if ImPlotSubplotFlags_ShareItems is enabled)
173 ImPlotSubplotFlags_NoMenus = 1 << 2, // the user will not be able to open context menus with right-click
174 ImPlotSubplotFlags_NoResize = 1 << 3, // resize splitters between subplot cells will be not be provided
175 ImPlotSubplotFlags_NoAlign = 1 << 4, // subplot edges will not be aligned vertically or horizontally
176 ImPlotSubplotFlags_ShareItems = 1 << 5, // items across all subplots will be shared and rendered into a single legend entry
177 ImPlotSubplotFlags_LinkRows = 1 << 6, // link the y-axis limits of all plots in each row (does not apply to auxiliary axes)
178 ImPlotSubplotFlags_LinkCols = 1 << 7, // link the x-axis limits of all plots in each column (does not apply to auxiliary axes)
179 ImPlotSubplotFlags_LinkAllX = 1 << 8, // link the x-axis limits in every plot in the subplot (does not apply to auxiliary axes)
180 ImPlotSubplotFlags_LinkAllY = 1 << 9, // link the y-axis limits in every plot in the subplot (does not apply to auxiliary axes)
181 ImPlotSubplotFlags_ColMajor = 1 << 10 // subplots are added in column major order instead of the default row major order
182};
183
184// Options for legends (see SetupLegend)
185enum ImPlotLegendFlags_ {
186 ImPlotLegendFlags_None = 0, // default
187 ImPlotLegendFlags_NoButtons = 1 << 0, // legend icons will not function as hide/show buttons
188 ImPlotLegendFlags_NoHighlightItem = 1 << 1, // plot items will not be highlighted when their legend entry is hovered
189 ImPlotLegendFlags_NoHighlightAxis = 1 << 2, // axes will not be highlighted when legend entries are hovered (only relevant if x/y-axis count > 1)
190 ImPlotLegendFlags_NoMenus = 1 << 3, // the user will not be able to open context menus with right-click
191 ImPlotLegendFlags_Outside = 1 << 4, // legend will be rendered outside of the plot area
192 ImPlotLegendFlags_Horizontal = 1 << 5, // legend entries will be displayed horizontally
193 ImPlotLegendFlags_Sort = 1 << 6, // legend entries will be displayed in alphabetical order
194};
195
196// Options for mouse hover text (see SetupMouseText)
197enum ImPlotMouseTextFlags_ {
198 ImPlotMouseTextFlags_None = 0, // default
199 ImPlotMouseTextFlags_NoAuxAxes = 1 << 0, // only show the mouse position for primary axes
200 ImPlotMouseTextFlags_NoFormat = 1 << 1, // axes label formatters won't be used to render text
201 ImPlotMouseTextFlags_ShowAlways = 1 << 2, // always display mouse position even if plot not hovered
202};
203
204// Options for DragPoint, DragLine, DragRect
205enum ImPlotDragToolFlags_ {
206 ImPlotDragToolFlags_None = 0, // default
207 ImPlotDragToolFlags_NoCursors = 1 << 0, // drag tools won't change cursor icons when hovered or held
208 ImPlotDragToolFlags_NoFit = 1 << 1, // the drag tool won't be considered for plot fits
209 ImPlotDragToolFlags_NoInputs = 1 << 2, // lock the tool from user inputs
210 ImPlotDragToolFlags_Delayed = 1 << 3, // tool rendering will be delayed one frame; useful when applying position-constraints
211};
212
213// Flags for ColormapScale
214enum ImPlotColormapScaleFlags_ {
215 ImPlotColormapScaleFlags_None = 0, // default
216 ImPlotColormapScaleFlags_NoLabel = 1 << 0, // the colormap axis label will not be displayed
217 ImPlotColormapScaleFlags_Opposite = 1 << 1, // render the colormap label and tick labels on the opposite side
218 ImPlotColormapScaleFlags_Invert = 1 << 2, // invert the colormap bar and axis scale (this only affects rendering; if you only want to reverse the scale mapping, make scale_min > scale_max)
219};
220
221// Flags for ANY PlotX function
222enum ImPlotItemFlags_ {
223 ImPlotItemFlags_None = 0,
224 ImPlotItemFlags_NoLegend = 1 << 0, // the item won't have a legend entry displayed
225 ImPlotItemFlags_NoFit = 1 << 1, // the item won't be considered for plot fits
226};
227
228// Flags for PlotLine
229enum ImPlotLineFlags_ {
230 ImPlotLineFlags_None = 0, // default
231 ImPlotLineFlags_Segments = 1 << 10, // a line segment will be rendered from every two consecutive points
232 ImPlotLineFlags_Loop = 1 << 11, // the last and first point will be connected to form a closed loop
233 ImPlotLineFlags_SkipNaN = 1 << 12, // NaNs values will be skipped instead of rendered as missing data
234 ImPlotLineFlags_NoClip = 1 << 13, // markers (if displayed) on the edge of a plot will not be clipped
235 ImPlotLineFlags_Shaded = 1 << 14, // a filled region between the line and horizontal origin will be rendered; use PlotShaded for more advanced cases
236};
237
238// Flags for PlotScatter
239enum ImPlotScatterFlags_ {
240 ImPlotScatterFlags_None = 0, // default
241 ImPlotScatterFlags_NoClip = 1 << 10, // markers on the edge of a plot will not be clipped
242};
243
244// Flags for PlotStairs
245enum ImPlotStairsFlags_ {
246 ImPlotStairsFlags_None = 0, // default
247 ImPlotStairsFlags_PreStep = 1 << 10, // the y value is continued constantly to the left from every x position, i.e. the interval (x[i-1], x[i]] has the value y[i]
248 ImPlotStairsFlags_Shaded = 1 << 11 // a filled region between the stairs and horizontal origin will be rendered; use PlotShaded for more advanced cases
249};
250
251// Flags for PlotShaded (placeholder)
252enum ImPlotShadedFlags_ {
253 ImPlotShadedFlags_None = 0 // default
254};
255
256// Flags for PlotBars
257enum ImPlotBarsFlags_ {
258 ImPlotBarsFlags_None = 0, // default
259 ImPlotBarsFlags_Horizontal = 1 << 10, // bars will be rendered horizontally on the current y-axis
260};
261
262// Flags for PlotBarGroups
263enum ImPlotBarGroupsFlags_ {
264 ImPlotBarGroupsFlags_None = 0, // default
265 ImPlotBarGroupsFlags_Horizontal = 1 << 10, // bar groups will be rendered horizontally on the current y-axis
266 ImPlotBarGroupsFlags_Stacked = 1 << 11, // items in a group will be stacked on top of each other
267};
268
269// Flags for PlotErrorBars
270enum ImPlotErrorBarsFlags_ {
271 ImPlotErrorBarsFlags_None = 0, // default
272 ImPlotErrorBarsFlags_Horizontal = 1 << 10, // error bars will be rendered horizontally on the current y-axis
273};
274
275// Flags for PlotStems
276enum ImPlotStemsFlags_ {
277 ImPlotStemsFlags_None = 0, // default
278 ImPlotStemsFlags_Horizontal = 1 << 10, // stems will be rendered horizontally on the current y-axis
279};
280
281// Flags for PlotInfLines
282enum ImPlotInfLinesFlags_ {
283 ImPlotInfLinesFlags_None = 0, // default
284 ImPlotInfLinesFlags_Horizontal = 1 << 10 // lines will be rendered horizontally on the current y-axis
285};
286
287// Flags for PlotPieChart
288enum ImPlotPieChartFlags_ {
289 ImPlotPieChartFlags_None = 0, // default
290 ImPlotPieChartFlags_Normalize = 1 << 10, // force normalization of pie chart values (i.e. always make a full circle if sum < 0)
291 ImPlotPieChartFlags_IgnoreHidden = 1 << 11 // ignore hidden slices when drawing the pie chart (as if they were not there)
292};
293
294// Flags for PlotHeatmap
295enum ImPlotHeatmapFlags_ {
296 ImPlotHeatmapFlags_None = 0, // default
297 ImPlotHeatmapFlags_ColMajor = 1 << 10, // data will be read in column major order
298};
299
300// Flags for PlotHistogram and PlotHistogram2D
301enum ImPlotHistogramFlags_ {
302 ImPlotHistogramFlags_None = 0, // default
303 ImPlotHistogramFlags_Horizontal = 1 << 10, // histogram bars will be rendered horizontally (not supported by PlotHistogram2D)
304 ImPlotHistogramFlags_Cumulative = 1 << 11, // each bin will contain its count plus the counts of all previous bins (not supported by PlotHistogram2D)
305 ImPlotHistogramFlags_Density = 1 << 12, // counts will be normalized, i.e. the PDF will be visualized, or the CDF will be visualized if Cumulative is also set
306 ImPlotHistogramFlags_NoOutliers = 1 << 13, // exclude values outside the specifed histogram range from the count toward normalizing and cumulative counts
307 ImPlotHistogramFlags_ColMajor = 1 << 14 // data will be read in column major order (not supported by PlotHistogram)
308};
309
310// Flags for PlotDigital (placeholder)
311enum ImPlotDigitalFlags_ {
312 ImPlotDigitalFlags_None = 0 // default
313};
314
315// Flags for PlotImage (placeholder)
316enum ImPlotImageFlags_ {
317 ImPlotImageFlags_None = 0 // default
318};
319
320// Flags for PlotText
321enum ImPlotTextFlags_ {
322 ImPlotTextFlags_None = 0, // default
323 ImPlotTextFlags_Vertical = 1 << 10 // text will be rendered vertically
324};
325
326// Flags for PlotDummy (placeholder)
327enum ImPlotDummyFlags_ {
328 ImPlotDummyFlags_None = 0 // default
329};
330
331// Represents a condition for SetupAxisLimits etc. (same as ImGuiCond, but we only support a subset of those enums)
332enum ImPlotCond_
333{
334 ImPlotCond_None = ImGuiCond_None, // No condition (always set the variable), same as _Always
335 ImPlotCond_Always = ImGuiCond_Always, // No condition (always set the variable)
336 ImPlotCond_Once = ImGuiCond_Once, // Set the variable once per runtime session (only the first call will succeed)
337};
338
339// Plot styling colors.
340enum ImPlotCol_ {
341 // item styling colors
342 ImPlotCol_Line, // plot line/outline color (defaults to next unused color in current colormap)
343 ImPlotCol_Fill, // plot fill color for bars (defaults to the current line color)
344 ImPlotCol_MarkerOutline, // marker outline color (defaults to the current line color)
345 ImPlotCol_MarkerFill, // marker fill color (defaults to the current line color)
346 ImPlotCol_ErrorBar, // error bar color (defaults to ImGuiCol_Text)
347 // plot styling colors
348 ImPlotCol_FrameBg, // plot frame background color (defaults to ImGuiCol_FrameBg)
349 ImPlotCol_PlotBg, // plot area background color (defaults to ImGuiCol_WindowBg)
350 ImPlotCol_PlotBorder, // plot area border color (defaults to ImGuiCol_Border)
351 ImPlotCol_LegendBg, // legend background color (defaults to ImGuiCol_PopupBg)
352 ImPlotCol_LegendBorder, // legend border color (defaults to ImPlotCol_PlotBorder)
353 ImPlotCol_LegendText, // legend text color (defaults to ImPlotCol_InlayText)
354 ImPlotCol_TitleText, // plot title text color (defaults to ImGuiCol_Text)
355 ImPlotCol_InlayText, // color of text appearing inside of plots (defaults to ImGuiCol_Text)
356 ImPlotCol_AxisText, // axis label and tick lables color (defaults to ImGuiCol_Text)
357 ImPlotCol_AxisGrid, // axis grid color (defaults to 25% ImPlotCol_AxisText)
358 ImPlotCol_AxisTick, // axis tick color (defaults to AxisGrid)
359 ImPlotCol_AxisBg, // background color of axis hover region (defaults to transparent)
360 ImPlotCol_AxisBgHovered, // axis hover color (defaults to ImGuiCol_ButtonHovered)
361 ImPlotCol_AxisBgActive, // axis active color (defaults to ImGuiCol_ButtonActive)
362 ImPlotCol_Selection, // box-selection color (defaults to yellow)
363 ImPlotCol_Crosshairs, // crosshairs color (defaults to ImPlotCol_PlotBorder)
364 ImPlotCol_COUNT
365};
366
367// Plot styling variables.
368enum ImPlotStyleVar_ {
369 // item styling variables
370 ImPlotStyleVar_LineWeight, // float, plot item line weight in pixels
371 ImPlotStyleVar_Marker, // int, marker specification
372 ImPlotStyleVar_MarkerSize, // float, marker size in pixels (roughly the marker's "radius")
373 ImPlotStyleVar_MarkerWeight, // float, plot outline weight of markers in pixels
374 ImPlotStyleVar_FillAlpha, // float, alpha modifier applied to all plot item fills
375 ImPlotStyleVar_ErrorBarSize, // float, error bar whisker width in pixels
376 ImPlotStyleVar_ErrorBarWeight, // float, error bar whisker weight in pixels
377 ImPlotStyleVar_DigitalBitHeight, // float, digital channels bit height (at 1) in pixels
378 ImPlotStyleVar_DigitalBitGap, // float, digital channels bit padding gap in pixels
379 // plot styling variables
380 ImPlotStyleVar_PlotBorderSize, // float, thickness of border around plot area
381 ImPlotStyleVar_MinorAlpha, // float, alpha multiplier applied to minor axis grid lines
382 ImPlotStyleVar_MajorTickLen, // ImVec2, major tick lengths for X and Y axes
383 ImPlotStyleVar_MinorTickLen, // ImVec2, minor tick lengths for X and Y axes
384 ImPlotStyleVar_MajorTickSize, // ImVec2, line thickness of major ticks
385 ImPlotStyleVar_MinorTickSize, // ImVec2, line thickness of minor ticks
386 ImPlotStyleVar_MajorGridSize, // ImVec2, line thickness of major grid lines
387 ImPlotStyleVar_MinorGridSize, // ImVec2, line thickness of minor grid lines
388 ImPlotStyleVar_PlotPadding, // ImVec2, padding between widget frame and plot area, labels, or outside legends (i.e. main padding)
389 ImPlotStyleVar_LabelPadding, // ImVec2, padding between axes labels, tick labels, and plot edge
390 ImPlotStyleVar_LegendPadding, // ImVec2, legend padding from plot edges
391 ImPlotStyleVar_LegendInnerPadding, // ImVec2, legend inner padding from legend edges
392 ImPlotStyleVar_LegendSpacing, // ImVec2, spacing between legend entries
393 ImPlotStyleVar_MousePosPadding, // ImVec2, padding between plot edge and interior info text
394 ImPlotStyleVar_AnnotationPadding, // ImVec2, text padding around annotation labels
395 ImPlotStyleVar_FitPadding, // ImVec2, additional fit padding as a percentage of the fit extents (e.g. ImVec2(0.1f,0.1f) adds 10% to the fit extents of X and Y)
396 ImPlotStyleVar_PlotDefaultSize, // ImVec2, default size used when ImVec2(0,0) is passed to BeginPlot
397 ImPlotStyleVar_PlotMinSize, // ImVec2, minimum size plot frame can be when shrunk
398 ImPlotStyleVar_COUNT
399};
400
401// Axis scale
402enum ImPlotScale_ {
403 ImPlotScale_Linear = 0, // default linear scale
404 ImPlotScale_Time, // date/time scale
405 ImPlotScale_Log10, // base 10 logartithmic scale
406 ImPlotScale_SymLog, // symmetric log scale
407};
408
409// Marker specifications.
410enum ImPlotMarker_ {
411 ImPlotMarker_None = -1, // no marker
412 ImPlotMarker_Circle, // a circle marker (default)
413 ImPlotMarker_Square, // a square maker
414 ImPlotMarker_Diamond, // a diamond marker
415 ImPlotMarker_Up, // an upward-pointing triangle marker
416 ImPlotMarker_Down, // an downward-pointing triangle marker
417 ImPlotMarker_Left, // an leftward-pointing triangle marker
418 ImPlotMarker_Right, // an rightward-pointing triangle marker
419 ImPlotMarker_Cross, // a cross marker (not fillable)
420 ImPlotMarker_Plus, // a plus marker (not fillable)
421 ImPlotMarker_Asterisk, // a asterisk marker (not fillable)
422 ImPlotMarker_COUNT
423};
424
425// Built-in colormaps
426enum ImPlotColormap_ {
427 ImPlotColormap_Deep = 0, // a.k.a. seaborn deep (qual=true, n=10) (default)
428 ImPlotColormap_Dark = 1, // a.k.a. matplotlib "Set1" (qual=true, n=9 )
429 ImPlotColormap_Pastel = 2, // a.k.a. matplotlib "Pastel1" (qual=true, n=9 )
430 ImPlotColormap_Paired = 3, // a.k.a. matplotlib "Paired" (qual=true, n=12)
431 ImPlotColormap_Viridis = 4, // a.k.a. matplotlib "viridis" (qual=false, n=11)
432 ImPlotColormap_Plasma = 5, // a.k.a. matplotlib "plasma" (qual=false, n=11)
433 ImPlotColormap_Hot = 6, // a.k.a. matplotlib/MATLAB "hot" (qual=false, n=11)
434 ImPlotColormap_Cool = 7, // a.k.a. matplotlib/MATLAB "cool" (qual=false, n=11)
435 ImPlotColormap_Pink = 8, // a.k.a. matplotlib/MATLAB "pink" (qual=false, n=11)
436 ImPlotColormap_Jet = 9, // a.k.a. MATLAB "jet" (qual=false, n=11)
437 ImPlotColormap_Twilight = 10, // a.k.a. matplotlib "twilight" (qual=false, n=11)
438 ImPlotColormap_RdBu = 11, // red/blue, Color Brewer (qual=false, n=11)
439 ImPlotColormap_BrBG = 12, // brown/blue-green, Color Brewer (qual=false, n=11)
440 ImPlotColormap_PiYG = 13, // pink/yellow-green, Color Brewer (qual=false, n=11)
441 ImPlotColormap_Spectral = 14, // color spectrum, Color Brewer (qual=false, n=11)
442 ImPlotColormap_Greys = 15, // white/black (qual=false, n=2 )
443};
444
445// Used to position items on a plot (e.g. legends, labels, etc.)
446enum ImPlotLocation_ {
447 ImPlotLocation_Center = 0, // center-center
448 ImPlotLocation_North = 1 << 0, // top-center
449 ImPlotLocation_South = 1 << 1, // bottom-center
450 ImPlotLocation_West = 1 << 2, // center-left
451 ImPlotLocation_East = 1 << 3, // center-right
452 ImPlotLocation_NorthWest = ImPlotLocation_North | ImPlotLocation_West, // top-left
453 ImPlotLocation_NorthEast = ImPlotLocation_North | ImPlotLocation_East, // top-right
454 ImPlotLocation_SouthWest = ImPlotLocation_South | ImPlotLocation_West, // bottom-left
455 ImPlotLocation_SouthEast = ImPlotLocation_South | ImPlotLocation_East // bottom-right
456};
457
458// Enums for different automatic histogram binning methods (k = bin count or w = bin width)
459enum ImPlotBin_ {
460 ImPlotBin_Sqrt = -1, // k = sqrt(n)
461 ImPlotBin_Sturges = -2, // k = 1 + log2(n)
462 ImPlotBin_Rice = -3, // k = 2 * cbrt(n)
463 ImPlotBin_Scott = -4, // w = 3.49 * sigma / cbrt(n)
464};
465
466// Double precision version of ImVec2 used by ImPlot. Extensible by end users.
467IM_MSVC_RUNTIME_CHECKS_OFF
468struct ImPlotPoint {
469 double x, y;
470 constexpr ImPlotPoint() : x(0.0), y(0.0) { }
471 constexpr ImPlotPoint(double _x, double _y) : x(_x), y(_y) { }
472 constexpr ImPlotPoint(const ImVec2& p) : x((double)p.x), y((double)p.y) { }
473 double& operator[] (size_t idx) { IM_ASSERT(idx == 0 || idx == 1); return ((double*)(void*)(char*)this)[idx]; }
474 double operator[] (size_t idx) const { IM_ASSERT(idx == 0 || idx == 1); return ((const double*)(const void*)(const char*)this)[idx]; }
475#ifdef IMPLOT_POINT_CLASS_EXTRA
476 IMPLOT_POINT_CLASS_EXTRA // Define additional constructors and implicit cast operators in imconfig.h
477 // to convert back and forth between your math types and ImPlotPoint.
478#endif
479};
480IM_MSVC_RUNTIME_CHECKS_RESTORE
481
482// Range defined by a min/max value.
483struct ImPlotRange {
484 double Min, Max;
485 constexpr ImPlotRange() : Min(0.0), Max(0.0) { }
486 constexpr ImPlotRange(double _min, double _max) : Min(_min), Max(_max) { }
487 bool Contains(double value) const { return value >= Min && value <= Max; }
488 double Size() const { return Max - Min; }
489 double Clamp(double value) const { return (value < Min) ? Min : (value > Max) ? Max : value; }
490};
491
492// Combination of two range limits for X and Y axes. Also an AABB defined by Min()/Max().
493struct ImPlotRect {
494 ImPlotRange X, Y;
495 constexpr ImPlotRect() : X(0.0,0.0), Y(0.0,0.0) { }
496 constexpr ImPlotRect(double x_min, double x_max, double y_min, double y_max) : X(x_min, x_max), Y(y_min, y_max) { }
497 bool Contains(const ImPlotPoint& p) const { return Contains(p.x, p.y); }
498 bool Contains(double x, double y) const { return X.Contains(x) && Y.Contains(y); }
499 ImPlotPoint Size() const { return ImPlotPoint(X.Size(), Y.Size()); }
500 ImPlotPoint Clamp(const ImPlotPoint& p) { return Clamp(p.x, p.y); }
501 ImPlotPoint Clamp(double x, double y) { return ImPlotPoint(X.Clamp(x),Y.Clamp(y)); }
502 ImPlotPoint Min() const { return ImPlotPoint(X.Min, Y.Min); }
503 ImPlotPoint Max() const { return ImPlotPoint(X.Max, Y.Max); }
504};
505
506// Plot style structure
507struct ImPlotStyle {
508 // item styling variables
509 float LineWeight; // = 1, item line weight in pixels
510 int Marker; // = ImPlotMarker_None, marker specification
511 float MarkerSize; // = 4, marker size in pixels (roughly the marker's "radius")
512 float MarkerWeight; // = 1, outline weight of markers in pixels
513 float FillAlpha; // = 1, alpha modifier applied to plot fills
514 float ErrorBarSize; // = 5, error bar whisker width in pixels
515 float ErrorBarWeight; // = 1.5, error bar whisker weight in pixels
516 float DigitalBitHeight; // = 8, digital channels bit height (at y = 1.0f) in pixels
517 float DigitalBitGap; // = 4, digital channels bit padding gap in pixels
518 // plot styling variables
519 float PlotBorderSize; // = 1, line thickness of border around plot area
520 float MinorAlpha; // = 0.25 alpha multiplier applied to minor axis grid lines
521 ImVec2 MajorTickLen; // = 10,10 major tick lengths for X and Y axes
522 ImVec2 MinorTickLen; // = 5,5 minor tick lengths for X and Y axes
523 ImVec2 MajorTickSize; // = 1,1 line thickness of major ticks
524 ImVec2 MinorTickSize; // = 1,1 line thickness of minor ticks
525 ImVec2 MajorGridSize; // = 1,1 line thickness of major grid lines
526 ImVec2 MinorGridSize; // = 1,1 line thickness of minor grid lines
527 ImVec2 PlotPadding; // = 10,10 padding between widget frame and plot area, labels, or outside legends (i.e. main padding)
528 ImVec2 LabelPadding; // = 5,5 padding between axes labels, tick labels, and plot edge
529 ImVec2 LegendPadding; // = 10,10 legend padding from plot edges
530 ImVec2 LegendInnerPadding; // = 5,5 legend inner padding from legend edges
531 ImVec2 LegendSpacing; // = 5,0 spacing between legend entries
532 ImVec2 MousePosPadding; // = 10,10 padding between plot edge and interior mouse location text
533 ImVec2 AnnotationPadding; // = 2,2 text padding around annotation labels
534 ImVec2 FitPadding; // = 0,0 additional fit padding as a percentage of the fit extents (e.g. ImVec2(0.1f,0.1f) adds 10% to the fit extents of X and Y)
535 ImVec2 PlotDefaultSize; // = 400,300 default size used when ImVec2(0,0) is passed to BeginPlot
536 ImVec2 PlotMinSize; // = 200,150 minimum size plot frame can be when shrunk
537 // style colors
538 ImVec4 Colors[ImPlotCol_COUNT]; // Array of styling colors. Indexable with ImPlotCol_ enums.
539 // colormap
540 ImPlotColormap Colormap; // The current colormap. Set this to either an ImPlotColormap_ enum or an index returned by AddColormap.
541 // settings/flags
542 bool UseLocalTime; // = false, axis labels will be formatted for your timezone when ImPlotAxisFlag_Time is enabled
543 bool UseISO8601; // = false, dates will be formatted according to ISO 8601 where applicable (e.g. YYYY-MM-DD, YYYY-MM, --MM-DD, etc.)
544 bool Use24HourClock; // = false, times will be formatted using a 24 hour clock
545 IMPLOT_API ImPlotStyle();
546};
547
548// Support for legacy versions
549#if (IMGUI_VERSION_NUM < 18716) // Renamed in 1.88
550#define ImGuiMod_None 0
551#define ImGuiMod_Ctrl ImGuiKeyModFlags_Ctrl
552#define ImGuiMod_Shift ImGuiKeyModFlags_Shift
553#define ImGuiMod_Alt ImGuiKeyModFlags_Alt
554#define ImGuiMod_Super ImGuiKeyModFlags_Super
555#elif (IMGUI_VERSION_NUM < 18823) // Renamed in 1.89, sorry
556#define ImGuiMod_None 0
557#define ImGuiMod_Ctrl ImGuiModFlags_Ctrl
558#define ImGuiMod_Shift ImGuiModFlags_Shift
559#define ImGuiMod_Alt ImGuiModFlags_Alt
560#define ImGuiMod_Super ImGuiModFlags_Super
561#endif
562
563// Input mapping structure. Default values listed. See also MapInputDefault, MapInputReverse.
564struct ImPlotInputMap {
565 ImGuiMouseButton Pan; // LMB enables panning when held,
566 int PanMod; // none optional modifier that must be held for panning/fitting
567 ImGuiMouseButton Fit; // LMB initiates fit when double clicked
568 ImGuiMouseButton Select; // RMB begins box selection when pressed and confirms selection when released
569 ImGuiMouseButton SelectCancel; // LMB cancels active box selection when pressed; cannot be same as Select
570 int SelectMod; // none optional modifier that must be held for box selection
571 int SelectHorzMod; // Alt expands active box selection horizontally to plot edge when held
572 int SelectVertMod; // Shift expands active box selection vertically to plot edge when held
573 ImGuiMouseButton Menu; // RMB opens context menus (if enabled) when clicked
574 int OverrideMod; // Ctrl when held, all input is ignored; used to enable axis/plots as DND sources
575 int ZoomMod; // none optional modifier that must be held for scroll wheel zooming
576 float ZoomRate; // 0.1f zoom rate for scroll (e.g. 0.1f = 10% plot range every scroll click); make negative to invert
577 IMPLOT_API ImPlotInputMap();
578};
579
580//-----------------------------------------------------------------------------
581// [SECTION] Callbacks
582//-----------------------------------------------------------------------------
583
584// Callback signature for axis tick label formatter.
585typedef int (*ImPlotFormatter)(double value, char* buff, int size, void* user_data);
586
587// Callback signature for data getter.
588typedef ImPlotPoint (*ImPlotGetter)(int idx, void* user_data);
589
590// Callback signature for axis transform.
591typedef double (*ImPlotTransform)(double value, void* user_data);
592
593namespace ImPlot {
594
595//-----------------------------------------------------------------------------
596// [SECTION] Contexts
597//-----------------------------------------------------------------------------
598
599// Creates a new ImPlot context. Call this after ImGui::CreateContext.
600IMPLOT_API ImPlotContext* CreateContext();
601// Destroys an ImPlot context. Call this before ImGui::DestroyContext. nullptr = destroy current context.
602IMPLOT_API void DestroyContext(ImPlotContext* ctx = nullptr);
603// Returns the current ImPlot context. nullptr if no context has ben set.
604IMPLOT_API ImPlotContext* GetCurrentContext();
605// Sets the current ImPlot context.
606IMPLOT_API void SetCurrentContext(ImPlotContext* ctx);
607
608// Sets the current **ImGui** context. This is ONLY necessary if you are compiling
609// ImPlot as a DLL (not recommended) separate from your ImGui compilation. It
610// sets the global variable GImGui, which is not shared across DLL boundaries.
611// See GImGui documentation in imgui.cpp for more details.
612IMPLOT_API void SetImGuiContext(ImGuiContext* ctx);
613
614//-----------------------------------------------------------------------------
615// [SECTION] Begin/End Plot
616//-----------------------------------------------------------------------------
617
618// Starts a 2D plotting context. If this function returns true, EndPlot() MUST
619// be called! You are encouraged to use the following convention:
620//
621// if (BeginPlot(...)) {
622// PlotLine(...);
623// ...
624// EndPlot();
625// }
626//
627// Important notes:
628//
629// - #title_id must be unique to the current ImGui ID scope. If you need to avoid ID
630// collisions or don't want to display a title in the plot, use double hashes
631// (e.g. "MyPlot##HiddenIdText" or "##NoTitle").
632// - #size is the **frame** size of the plot widget, not the plot area. The default
633// size of plots (i.e. when ImVec2(0,0)) can be modified in your ImPlotStyle.
634IMPLOT_API bool BeginPlot(const char* title_id, const ImVec2& size=ImVec2(-1,0), ImPlotFlags flags=0);
635
636// Only call EndPlot() if BeginPlot() returns true! Typically called at the end
637// of an if statement conditioned on BeginPlot(). See example above.
638IMPLOT_API void EndPlot();
639
640//-----------------------------------------------------------------------------
641// [SECTION] Begin/End Subplots
642//-----------------------------------------------------------------------------
643
644// Starts a subdivided plotting context. If the function returns true,
645// EndSubplots() MUST be called! Call BeginPlot/EndPlot AT MOST [rows*cols]
646// times in between the begining and end of the subplot context. Plots are
647// added in row major order.
648//
649// Example:
650//
651// if (BeginSubplots("My Subplot",2,3,ImVec2(800,400)) {
652// for (int i = 0; i < 6; ++i) {
653// if (BeginPlot(...)) {
654// ImPlot::PlotLine(...);
655// ...
656// EndPlot();
657// }
658// }
659// EndSubplots();
660// }
661//
662// Produces:
663//
664// [0] | [1] | [2]
665// ----|-----|----
666// [3] | [4] | [5]
667//
668// Important notes:
669//
670// - #title_id must be unique to the current ImGui ID scope. If you need to avoid ID
671// collisions or don't want to display a title in the plot, use double hashes
672// (e.g. "MySubplot##HiddenIdText" or "##NoTitle").
673// - #rows and #cols must be greater than 0.
674// - #size is the size of the entire grid of subplots, not the individual plots
675// - #row_ratios and #col_ratios must have AT LEAST #rows and #cols elements,
676// respectively. These are the sizes of the rows and columns expressed in ratios.
677// If the user adjusts the dimensions, the arrays are updated with new ratios.
678//
679// Important notes regarding BeginPlot from inside of BeginSubplots:
680//
681// - The #title_id parameter of _BeginPlot_ (see above) does NOT have to be
682// unique when called inside of a subplot context. Subplot IDs are hashed
683// for your convenience so you don't have call PushID or generate unique title
684// strings. Simply pass an empty string to BeginPlot unless you want to title
685// each subplot.
686// - The #size parameter of _BeginPlot_ (see above) is ignored when inside of a
687// subplot context. The actual size of the subplot will be based on the
688// #size value you pass to _BeginSubplots_ and #row/#col_ratios if provided.
689
690IMPLOT_API bool BeginSubplots(const char* title_id,
691 int rows,
692 int cols,
693 const ImVec2& size,
694 ImPlotSubplotFlags flags = 0,
695 float* row_ratios = nullptr,
696 float* col_ratios = nullptr);
697
698// Only call EndSubplots() if BeginSubplots() returns true! Typically called at the end
699// of an if statement conditioned on BeginSublots(). See example above.
700IMPLOT_API void EndSubplots();
701
702//-----------------------------------------------------------------------------
703// [SECTION] Setup
704//-----------------------------------------------------------------------------
705
706// The following API allows you to setup and customize various aspects of the
707// current plot. The functions should be called immediately after BeginPlot
708// and before any other API calls. Typical usage is as follows:
709
710// if (BeginPlot(...)) { 1) begin a new plot
711// SetupAxis(ImAxis_X1, "My X-Axis"); 2) make Setup calls
712// SetupAxis(ImAxis_Y1, "My Y-Axis");
713// SetupLegend(ImPlotLocation_North);
714// ...
715// SetupFinish(); 3) [optional] explicitly finish setup
716// PlotLine(...); 4) plot items
717// ...
718// EndPlot(); 5) end the plot
719// }
720//
721// Important notes:
722//
723// - Always call Setup code at the top of your BeginPlot conditional statement.
724// - Setup is locked once you start plotting or explicitly call SetupFinish.
725// Do NOT call Setup code after you begin plotting or after you make
726// any non-Setup API calls (e.g. utils like PlotToPixels also lock Setup)
727// - Calling SetupFinish is OPTIONAL, but probably good practice. If you do not
728// call it yourself, then the first subsequent plotting or utility function will
729// call it for you.
730
731// Enables an axis or sets the label and/or flags for an existing axis. Leave #label = nullptr for no label.
732IMPLOT_API void SetupAxis(ImAxis axis, const char* label=nullptr, ImPlotAxisFlags flags=0);
733// 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.
734IMPLOT_API void SetupAxisLimits(ImAxis axis, double v_min, double v_max, ImPlotCond cond = ImPlotCond_Once);
735// Links an axis range limits to external values. Set to nullptr for no linkage. The pointer data must remain valid until EndPlot.
736IMPLOT_API void SetupAxisLinks(ImAxis axis, double* link_min, double* link_max);
737// Sets the format of numeric axis labels via formater specifier (default="%g"). Formated values will be double (i.e. use %f).
738IMPLOT_API void SetupAxisFormat(ImAxis axis, const char* fmt);
739// Sets the format of numeric axis labels via formatter callback. Given #value, write a label into #buff. Optionally pass user data.
740IMPLOT_API void SetupAxisFormat(ImAxis axis, ImPlotFormatter formatter, void* data=nullptr);
741// Sets an axis' ticks and optionally the labels. To keep the default ticks, set #keep_default=true.
742IMPLOT_API void SetupAxisTicks(ImAxis axis, const double* values, int n_ticks, const char* const labels[]=nullptr, bool keep_default=false);
743// Sets an axis' ticks and optionally the labels for the next plot. To keep the default ticks, set #keep_default=true.
744IMPLOT_API void SetupAxisTicks(ImAxis axis, double v_min, double v_max, int n_ticks, const char* const labels[]=nullptr, bool keep_default=false);
745// Sets an axis' scale using built-in options.
746IMPLOT_API void SetupAxisScale(ImAxis axis, ImPlotScale scale);
747// Sets an axis' scale using user supplied forward and inverse transfroms.
748IMPLOT_API void SetupAxisScale(ImAxis axis, ImPlotTransform forward, ImPlotTransform inverse, void* data=nullptr);
749// Sets an axis' limits constraints.
750IMPLOT_API void SetupAxisLimitsConstraints(ImAxis axis, double v_min, double v_max);
751// Sets an axis' zoom constraints.
752IMPLOT_API void SetupAxisZoomConstraints(ImAxis axis, double z_min, double z_max);
753
754// Sets the label and/or flags for primary X and Y axes (shorthand for two calls to SetupAxis).
755IMPLOT_API void SetupAxes(const char* x_label, const char* y_label, ImPlotAxisFlags x_flags=0, ImPlotAxisFlags y_flags=0);
756// 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).
757IMPLOT_API void SetupAxesLimits(double x_min, double x_max, double y_min, double y_max, ImPlotCond cond = ImPlotCond_Once);
758
759// Sets up the plot legend. This can also be called immediately after BeginSubplots when using ImPlotSubplotFlags_ShareItems.
760IMPLOT_API void SetupLegend(ImPlotLocation location, ImPlotLegendFlags flags=0);
761// Set the location of the current plot's mouse position text (default = South|East).
762IMPLOT_API void SetupMouseText(ImPlotLocation location, ImPlotMouseTextFlags flags=0);
763
764// Explicitly finalize plot setup. Once you call this, you cannot make anymore Setup calls for the current plot!
765// Note that calling this function is OPTIONAL; it will be called by the first subsequent setup-locking API call.
766IMPLOT_API void SetupFinish();
767
768//-----------------------------------------------------------------------------
769// [SECTION] SetNext
770//-----------------------------------------------------------------------------
771
772// Though you should default to the `Setup` API above, there are some scenarios
773// where (re)configuring a plot or axis before `BeginPlot` is needed (e.g. if
774// using a preceding button or slider widget to change the plot limits). In
775// this case, you can use the `SetNext` API below. While this is not as feature
776// rich as the Setup API, most common needs are provided. These functions can be
777// called anwhere except for inside of `Begin/EndPlot`. For example:
778
779// if (ImGui::Button("Center Plot"))
780// ImPlot::SetNextPlotLimits(-1,1,-1,1);
781// if (ImPlot::BeginPlot(...)) {
782// ...
783// ImPlot::EndPlot();
784// }
785//
786// Important notes:
787//
788// - You must still enable non-default axes with SetupAxis for these functions
789// to work properly.
790
791// Sets an upcoming axis range limits. If ImPlotCond_Always is used, the axes limits will be locked.
792IMPLOT_API void SetNextAxisLimits(ImAxis axis, double v_min, double v_max, ImPlotCond cond = ImPlotCond_Once);
793// Links an upcoming axis range limits to external values. Set to nullptr for no linkage. The pointer data must remain valid until EndPlot!
794IMPLOT_API void SetNextAxisLinks(ImAxis axis, double* link_min, double* link_max);
795// Set an upcoming axis to auto fit to its data.
796IMPLOT_API void SetNextAxisToFit(ImAxis axis);
797
798// 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).
799IMPLOT_API void SetNextAxesLimits(double x_min, double x_max, double y_min, double y_max, ImPlotCond cond = ImPlotCond_Once);
800// Sets all upcoming axes to auto fit to their data.
801IMPLOT_API void SetNextAxesToFit();
802
803//-----------------------------------------------------------------------------
804// [SECTION] Plot Items
805//-----------------------------------------------------------------------------
806
807// The main plotting API is provied below. Call these functions between
808// Begin/EndPlot and after any Setup API calls. Each plots data on the current
809// x and y axes, which can be changed with `SetAxis/Axes`.
810//
811// The templated functions are explicitly instantiated in implot_items.cpp.
812// They are not intended to be used generically with custom types. You will get
813// a linker error if you try! All functions support the following scalar types:
814//
815// float, double, ImS8, ImU8, ImS16, ImU16, ImS32, ImU32, ImS64, ImU64
816//
817//
818// If you need to plot custom or non-homogenous data you have a few options:
819//
820// 1. If your data is a simple struct/class (e.g. Vector2f), you can use striding.
821// This is the most performant option if applicable.
822//
823// struct Vector2f { float X, Y; };
824// ...
825// Vector2f data[42];
826// ImPlot::PlotLine("line", &data[0].x, &data[0].y, 42, 0, 0, sizeof(Vector2f));
827//
828// 2. Write a custom getter C function or C++ lambda and pass it and optionally your data to
829// an ImPlot function post-fixed with a G (e.g. PlotScatterG). This has a slight performance
830// cost, but probably not enough to worry about unless your data is very large. Examples:
831//
832// ImPlotPoint MyDataGetter(void* data, int idx) {
833// MyData* my_data = (MyData*)data;
834// ImPlotPoint p;
835// p.x = my_data->GetTime(idx);
836// p.y = my_data->GetValue(idx);
837// return p
838// }
839// ...
840// auto my_lambda = [](int idx, void*) {
841// double t = idx / 999.0;
842// return ImPlotPoint(t, 0.5+0.5*std::sin(2*PI*10*t));
843// };
844// ...
845// if (ImPlot::BeginPlot("MyPlot")) {
846// MyData my_data;
847// ImPlot::PlotScatterG("scatter", MyDataGetter, &my_data, my_data.Size());
848// ImPlot::PlotLineG("line", my_lambda, nullptr, 1000);
849// ImPlot::EndPlot();
850// }
851//
852// NB: All types are converted to double before plotting. You may lose information
853// if you try plotting extremely large 64-bit integral types. Proceed with caution!
854
855// Plots a standard 2D line plot.
856IMPLOT_TMP void PlotLine(const char* label_id, const T* values, int count, double xscale=1, double xstart=0, ImPlotLineFlags flags=0, int offset=0, int stride=sizeof(T));
857IMPLOT_TMP void PlotLine(const char* label_id, const T* xs, const T* ys, int count, ImPlotLineFlags flags=0, int offset=0, int stride=sizeof(T));
858IMPLOT_API void PlotLineG(const char* label_id, ImPlotGetter getter, void* data, int count, ImPlotLineFlags flags=0);
859
860// Plots a standard 2D scatter plot. Default marker is ImPlotMarker_Circle.
861IMPLOT_TMP void PlotScatter(const char* label_id, const T* values, int count, double xscale=1, double xstart=0, ImPlotScatterFlags flags=0, int offset=0, int stride=sizeof(T));
862IMPLOT_TMP void PlotScatter(const char* label_id, const T* xs, const T* ys, int count, ImPlotScatterFlags flags=0, int offset=0, int stride=sizeof(T));
863IMPLOT_API void PlotScatterG(const char* label_id, ImPlotGetter getter, void* data, int count, ImPlotScatterFlags flags=0);
864
865// 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]
866IMPLOT_TMP void PlotStairs(const char* label_id, const T* values, int count, double xscale=1, double xstart=0, ImPlotStairsFlags flags=0, int offset=0, int stride=sizeof(T));
867IMPLOT_TMP void PlotStairs(const char* label_id, const T* xs, const T* ys, int count, ImPlotStairsFlags flags=0, int offset=0, int stride=sizeof(T));
868IMPLOT_API void PlotStairsG(const char* label_id, ImPlotGetter getter, void* data, int count, ImPlotStairsFlags flags=0);
869
870// Plots a shaded (filled) region between two lines, or a line and a horizontal reference. Set yref to +/-INFINITY for infinite fill extents.
871IMPLOT_TMP void PlotShaded(const char* label_id, const T* values, int count, double yref=0, double xscale=1, double xstart=0, ImPlotShadedFlags flags=0, int offset=0, int stride=sizeof(T));
872IMPLOT_TMP void PlotShaded(const char* label_id, const T* xs, const T* ys, int count, double yref=0, ImPlotShadedFlags flags=0, int offset=0, int stride=sizeof(T));
873IMPLOT_TMP void PlotShaded(const char* label_id, const T* xs, const T* ys1, const T* ys2, int count, ImPlotShadedFlags flags=0, int offset=0, int stride=sizeof(T));
874IMPLOT_API void PlotShadedG(const char* label_id, ImPlotGetter getter1, void* data1, ImPlotGetter getter2, void* data2, int count, ImPlotShadedFlags flags=0);
875
876// Plots a bar graph. Vertical by default. #bar_size and #shift are in plot units.
877IMPLOT_TMP void PlotBars(const char* label_id, const T* values, int count, double bar_size=0.67, double shift=0, ImPlotBarsFlags flags=0, int offset=0, int stride=sizeof(T));
878IMPLOT_TMP void PlotBars(const char* label_id, const T* xs, const T* ys, int count, double bar_size, ImPlotBarsFlags flags=0, int offset=0, int stride=sizeof(T));
879IMPLOT_API void PlotBarsG(const char* label_id, ImPlotGetter getter, void* data, int count, double bar_size, ImPlotBarsFlags flags=0);
880
881// Plots a group of bars. #values is a row-major matrix with #item_count rows and #group_count cols. #label_ids should have #item_count elements.
882IMPLOT_TMP void PlotBarGroups(const char* const label_ids[], const T* values, int item_count, int group_count, double group_size=0.67, double shift=0, ImPlotBarGroupsFlags flags=0);
883
884// Plots vertical error bar. The label_id should be the same as the label_id of the associated line or bar plot.
885IMPLOT_TMP void PlotErrorBars(const char* label_id, const T* xs, const T* ys, const T* err, int count, ImPlotErrorBarsFlags flags=0, int offset=0, int stride=sizeof(T));
886IMPLOT_TMP void PlotErrorBars(const char* label_id, const T* xs, const T* ys, const T* neg, const T* pos, int count, ImPlotErrorBarsFlags flags=0, int offset=0, int stride=sizeof(T));
887
888// Plots stems. Vertical by default.
889IMPLOT_TMP void PlotStems(const char* label_id, const T* values, int count, double ref=0, double scale=1, double start=0, ImPlotStemsFlags flags=0, int offset=0, int stride=sizeof(T));
890IMPLOT_TMP void PlotStems(const char* label_id, const T* xs, const T* ys, int count, double ref=0, ImPlotStemsFlags flags=0, int offset=0, int stride=sizeof(T));
891
892// Plots infinite vertical or horizontal lines (e.g. for references or asymptotes).
893IMPLOT_TMP void PlotInfLines(const char* label_id, const T* values, int count, ImPlotInfLinesFlags flags=0, int offset=0, int stride=sizeof(T));
894
895// Plots a pie chart. Center and radius are in plot units. #label_fmt can be set to nullptr for no labels.
896IMPLOT_TMP void PlotPieChart(const char* const label_ids[], const T* values, int count, double x, double y, double radius, ImPlotFormatter fmt, void* fmt_data=nullptr, double angle0=90, ImPlotPieChartFlags flags=0);
897IMPLOT_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, ImPlotPieChartFlags flags=0);
898
899// Plots a 2D heatmap chart. Values are expected to be in row-major order by default. Leave #scale_min and scale_max both at 0 for automatic color scaling, or set them to a predefined range. #label_fmt can be set to nullptr for no labels.
900IMPLOT_TMP void PlotHeatmap(const char* label_id, const T* values, int rows, int cols, double scale_min=0, double scale_max=0, const char* label_fmt="%.1f", const ImPlotPoint& bounds_min=ImPlotPoint(0,0), const ImPlotPoint& bounds_max=ImPlotPoint(1,1), ImPlotHeatmapFlags flags=0);
901
902// 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.
903// Otherwise, outlier values outside of the range are not binned. The largest bin count or density is returned.
904IMPLOT_TMP double PlotHistogram(const char* label_id, const T* values, int count, int bins=ImPlotBin_Sturges, double bar_scale=1.0, ImPlotRange range=ImPlotRange(), ImPlotHistogramFlags flags=0);
905
906// 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
907// #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.
908IMPLOT_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(), ImPlotHistogramFlags flags=0);
909
910// Plots digital data. Digital plots do not respond to y drag or zoom, and are always referenced to the bottom of the plot.
911IMPLOT_TMP void PlotDigital(const char* label_id, const T* xs, const T* ys, int count, ImPlotDigitalFlags flags=0, int offset=0, int stride=sizeof(T));
912IMPLOT_API void PlotDigitalG(const char* label_id, ImPlotGetter getter, void* data, int count, ImPlotDigitalFlags flags=0);
913
914// Plots an axis-aligned image. #bounds_min/bounds_max are in plot coordinates (y-up) and #uv0/uv1 are in texture coordinates (y-down).
915IMPLOT_API void PlotImage(const char* label_id, ImTextureID user_texture_id, 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), ImPlotImageFlags flags=0);
916
917// Plots a centered text label at point x,y with an optional pixel offset. Text color can be changed with ImPlot::PushStyleColor(ImPlotCol_InlayText, ...).
918IMPLOT_API void PlotText(const char* text, double x, double y, const ImVec2& pix_offset=ImVec2(0,0), ImPlotTextFlags flags=0);
919
920// Plots a dummy item (i.e. adds a legend entry colored by ImPlotCol_Line)
921IMPLOT_API void PlotDummy(const char* label_id, ImPlotDummyFlags flags=0);
922
923//-----------------------------------------------------------------------------
924// [SECTION] Plot Tools
925//-----------------------------------------------------------------------------
926
927// The following can be used to render interactive elements and/or annotations.
928// Like the item plotting functions above, they apply to the current x and y
929// axes, which can be changed with `SetAxis/SetAxes`. These functions return true
930// when user interaction causes the provided coordinates to change. Additional
931// user interactions can be retrieved through the optional output parameters.
932
933// Shows a draggable point at x,y. #col defaults to ImGuiCol_Text.
934IMPLOT_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* held = nullptr);
935// Shows a draggable vertical guide line at an x-value. #col defaults to ImGuiCol_Text.
936IMPLOT_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* held = nullptr);
937// Shows a draggable horizontal guide line at a y-value. #col defaults to ImGuiCol_Text.
938IMPLOT_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* held = nullptr);
939// Shows a draggable and resizeable rectangle.
940IMPLOT_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* held = nullptr);
941
942// Shows an annotation callout at a chosen point. Clamping keeps annotations in the plot area. Annotations are always rendered on top.
943IMPLOT_API void Annotation(double x, double y, const ImVec4& col, const ImVec2& pix_offset, bool clamp, bool round = false);
944IMPLOT_API void Annotation(double x, double y, const ImVec4& col, const ImVec2& pix_offset, bool clamp, const char* fmt, ...) IM_FMTARGS(6);
945IMPLOT_API void AnnotationV(double x, double y, const ImVec4& col, const ImVec2& pix_offset, bool clamp, const char* fmt, va_list args) IM_FMTLIST(6);
946
947// Shows a x-axis tag at the specified coordinate value.
948IMPLOT_API void TagX(double x, const ImVec4& col, bool round = false);
949IMPLOT_API void TagX(double x, const ImVec4& col, const char* fmt, ...) IM_FMTARGS(3);
950IMPLOT_API void TagXV(double x, const ImVec4& col, const char* fmt, va_list args) IM_FMTLIST(3);
951
952// Shows a y-axis tag at the specified coordinate value.
953IMPLOT_API void TagY(double y, const ImVec4& col, bool round = false);
954IMPLOT_API void TagY(double y, const ImVec4& col, const char* fmt, ...) IM_FMTARGS(3);
955IMPLOT_API void TagYV(double y, const ImVec4& col, const char* fmt, va_list args) IM_FMTLIST(3);
956
957//-----------------------------------------------------------------------------
958// [SECTION] Plot Utils
959//-----------------------------------------------------------------------------
960
961// Select which axis/axes will be used for subsequent plot elements.
962IMPLOT_API void SetAxis(ImAxis axis);
963IMPLOT_API void SetAxes(ImAxis x_axis, ImAxis y_axis);
964
965// Convert pixels to a position in the current plot's coordinate system. Passing IMPLOT_AUTO uses the current axes.
966IMPLOT_API ImPlotPoint PixelsToPlot(const ImVec2& pix, ImAxis x_axis = IMPLOT_AUTO, ImAxis y_axis = IMPLOT_AUTO);
967IMPLOT_API ImPlotPoint PixelsToPlot(float x, float y, ImAxis x_axis = IMPLOT_AUTO, ImAxis y_axis = IMPLOT_AUTO);
968
969// Convert a position in the current plot's coordinate system to pixels. Passing IMPLOT_AUTO uses the current axes.
970IMPLOT_API ImVec2 PlotToPixels(const ImPlotPoint& plt, ImAxis x_axis = IMPLOT_AUTO, ImAxis y_axis = IMPLOT_AUTO);
971IMPLOT_API ImVec2 PlotToPixels(double x, double y, ImAxis x_axis = IMPLOT_AUTO, ImAxis y_axis = IMPLOT_AUTO);
972
973// Get the current Plot position (top-left) in pixels.
974IMPLOT_API ImVec2 GetPlotPos();
975// Get the curent Plot size in pixels.
976IMPLOT_API ImVec2 GetPlotSize();
977
978// Returns the mouse position in x,y coordinates of the current plot. Passing IMPLOT_AUTO uses the current axes.
979IMPLOT_API ImPlotPoint GetPlotMousePos(ImAxis x_axis = IMPLOT_AUTO, ImAxis y_axis = IMPLOT_AUTO);
980// Returns the current plot axis range.
981IMPLOT_API ImPlotRect GetPlotLimits(ImAxis x_axis = IMPLOT_AUTO, ImAxis y_axis = IMPLOT_AUTO);
982
983// Returns true if the plot area in the current plot is hovered.
984IMPLOT_API bool IsPlotHovered();
985// Returns true if the axis label area in the current plot is hovered.
986IMPLOT_API bool IsAxisHovered(ImAxis axis);
987// Returns true if the bounding frame of a subplot is hovered.
988IMPLOT_API bool IsSubplotsHovered();
989
990// Returns true if the current plot is being box selected.
991IMPLOT_API bool IsPlotSelected();
992// Returns the current plot box selection bounds. Passing IMPLOT_AUTO uses the current axes.
993IMPLOT_API ImPlotRect GetPlotSelection(ImAxis x_axis = IMPLOT_AUTO, ImAxis y_axis = IMPLOT_AUTO);
994// Cancels a the current plot box selection.
995IMPLOT_API void CancelPlotSelection();
996
997// Hides or shows the next plot item (i.e. as if it were toggled from the legend).
998// Use ImPlotCond_Always if you need to forcefully set this every frame.
999IMPLOT_API void HideNextItem(bool hidden = true, ImPlotCond cond = ImPlotCond_Once);
1000
1001// Use the following around calls to Begin/EndPlot to align l/r/t/b padding.
1002// Consider using Begin/EndSubplots first. They are more feature rich and
1003// accomplish the same behaviour by default. The functions below offer lower
1004// level control of plot alignment.
1005
1006// Align axis padding over multiple plots in a single row or column. #group_id must
1007// be unique. If this function returns true, EndAlignedPlots() must be called.
1008IMPLOT_API bool BeginAlignedPlots(const char* group_id, bool vertical = true);
1009// Only call EndAlignedPlots() if BeginAlignedPlots() returns true!
1010IMPLOT_API void EndAlignedPlots();
1011
1012//-----------------------------------------------------------------------------
1013// [SECTION] Legend Utils
1014//-----------------------------------------------------------------------------
1015
1016// Begin a popup for a legend entry.
1017IMPLOT_API bool BeginLegendPopup(const char* label_id, ImGuiMouseButton mouse_button=1);
1018// End a popup for a legend entry.
1019IMPLOT_API void EndLegendPopup();
1020// Returns true if a plot item legend entry is hovered.
1021IMPLOT_API bool IsLegendEntryHovered(const char* label_id);
1022
1023//-----------------------------------------------------------------------------
1024// [SECTION] Drag and Drop
1025//-----------------------------------------------------------------------------
1026
1027// Turns the current plot's plotting area into a drag and drop target. Don't forget to call EndDragDropTarget!
1028IMPLOT_API bool BeginDragDropTargetPlot();
1029// Turns the current plot's X-axis into a drag and drop target. Don't forget to call EndDragDropTarget!
1030IMPLOT_API bool BeginDragDropTargetAxis(ImAxis axis);
1031// Turns the current plot's legend into a drag and drop target. Don't forget to call EndDragDropTarget!
1032IMPLOT_API bool BeginDragDropTargetLegend();
1033// Ends a drag and drop target (currently just an alias for ImGui::EndDragDropTarget).
1034IMPLOT_API void EndDragDropTarget();
1035
1036// NB: By default, plot and axes drag and drop *sources* require holding the Ctrl modifier to initiate the drag.
1037// You can change the modifier if desired. If ImGuiMod_None is provided, the axes will be locked from panning.
1038
1039// Turns the current plot's plotting area into a drag and drop source. You must hold Ctrl. Don't forget to call EndDragDropSource!
1040IMPLOT_API bool BeginDragDropSourcePlot(ImGuiDragDropFlags flags=0);
1041// Turns the current plot's X-axis into a drag and drop source. You must hold Ctrl. Don't forget to call EndDragDropSource!
1042IMPLOT_API bool BeginDragDropSourceAxis(ImAxis axis, ImGuiDragDropFlags flags=0);
1043// Turns an item in the current plot's legend into drag and drop source. Don't forget to call EndDragDropSource!
1044IMPLOT_API bool BeginDragDropSourceItem(const char* label_id, ImGuiDragDropFlags flags=0);
1045// Ends a drag and drop source (currently just an alias for ImGui::EndDragDropSource).
1046IMPLOT_API void EndDragDropSource();
1047
1048//-----------------------------------------------------------------------------
1049// [SECTION] Styling
1050//-----------------------------------------------------------------------------
1051
1052// Styling colors in ImPlot works similarly to styling colors in ImGui, but
1053// with one important difference. Like ImGui, all style colors are stored in an
1054// indexable array in ImPlotStyle. You can permanently modify these values through
1055// GetStyle().Colors, or temporarily modify them with Push/Pop functions below.
1056// However, by default all style colors in ImPlot default to a special color
1057// IMPLOT_AUTO_COL. The behavior of this color depends upon the style color to
1058// which it as applied:
1059//
1060// 1) For style colors associated with plot items (e.g. ImPlotCol_Line),
1061// IMPLOT_AUTO_COL tells ImPlot to color the item with the next unused
1062// color in the current colormap. Thus, every item will have a different
1063// color up to the number of colors in the colormap, at which point the
1064// colormap will roll over. For most use cases, you should not need to
1065// set these style colors to anything but IMPLOT_COL_AUTO; you are
1066// probably better off changing the current colormap. However, if you
1067// need to explicitly color a particular item you may either Push/Pop
1068// the style color around the item in question, or use the SetNextXXXStyle
1069// API below. If you permanently set one of these style colors to a specific
1070// color, or forget to call Pop, then all subsequent items will be styled
1071// with the color you set.
1072//
1073// 2) For style colors associated with plot styling (e.g. ImPlotCol_PlotBg),
1074// IMPLOT_AUTO_COL tells ImPlot to set that color from color data in your
1075// **ImGuiStyle**. The ImGuiCol_ that these style colors default to are
1076// detailed above, and in general have been mapped to produce plots visually
1077// consistent with your current ImGui style. Of course, you are free to
1078// manually set these colors to whatever you like, and further can Push/Pop
1079// them around individual plots for plot-specific styling (e.g. coloring axes).
1080
1081// Provides access to plot style structure for permanant modifications to colors, sizes, etc.
1082IMPLOT_API ImPlotStyle& GetStyle();
1083
1084// Style plot colors for current ImGui style (default).
1085IMPLOT_API void StyleColorsAuto(ImPlotStyle* dst = nullptr);
1086// Style plot colors for ImGui "Classic".
1087IMPLOT_API void StyleColorsClassic(ImPlotStyle* dst = nullptr);
1088// Style plot colors for ImGui "Dark".
1089IMPLOT_API void StyleColorsDark(ImPlotStyle* dst = nullptr);
1090// Style plot colors for ImGui "Light".
1091IMPLOT_API void StyleColorsLight(ImPlotStyle* dst = nullptr);
1092
1093// Use PushStyleX to temporarily modify your ImPlotStyle. The modification
1094// will last until the matching call to PopStyleX. You MUST call a pop for
1095// every push, otherwise you will leak memory! This behaves just like ImGui.
1096
1097// Temporarily modify a style color. Don't forget to call PopStyleColor!
1098IMPLOT_API void PushStyleColor(ImPlotCol idx, ImU32 col);
1099IMPLOT_API void PushStyleColor(ImPlotCol idx, const ImVec4& col);
1100// Undo temporary style color modification(s). Undo multiple pushes at once by increasing count.
1101IMPLOT_API void PopStyleColor(int count = 1);
1102
1103// Temporarily modify a style variable of float type. Don't forget to call PopStyleVar!
1104IMPLOT_API void PushStyleVar(ImPlotStyleVar idx, float val);
1105// Temporarily modify a style variable of int type. Don't forget to call PopStyleVar!
1106IMPLOT_API void PushStyleVar(ImPlotStyleVar idx, int val);
1107// Temporarily modify a style variable of ImVec2 type. Don't forget to call PopStyleVar!
1108IMPLOT_API void PushStyleVar(ImPlotStyleVar idx, const ImVec2& val);
1109// Undo temporary style variable modification(s). Undo multiple pushes at once by increasing count.
1110IMPLOT_API void PopStyleVar(int count = 1);
1111
1112// The following can be used to modify the style of the next plot item ONLY. They do
1113// NOT require calls to PopStyleX. Leave style attributes you don't want modified to
1114// IMPLOT_AUTO or IMPLOT_AUTO_COL. Automatic styles will be deduced from the current
1115// values in your ImPlotStyle or from Colormap data.
1116
1117// Set the line color and weight for the next item only.
1118IMPLOT_API void SetNextLineStyle(const ImVec4& col = IMPLOT_AUTO_COL, float weight = IMPLOT_AUTO);
1119// Set the fill color for the next item only.
1120IMPLOT_API void SetNextFillStyle(const ImVec4& col = IMPLOT_AUTO_COL, float alpha_mod = IMPLOT_AUTO);
1121// Set the marker style for the next item only.
1122IMPLOT_API void SetNextMarkerStyle(ImPlotMarker marker = IMPLOT_AUTO, float size = IMPLOT_AUTO, const ImVec4& fill = IMPLOT_AUTO_COL, float weight = IMPLOT_AUTO, const ImVec4& outline = IMPLOT_AUTO_COL);
1123// Set the error bar style for the next item only.
1124IMPLOT_API void SetNextErrorBarStyle(const ImVec4& col = IMPLOT_AUTO_COL, float size = IMPLOT_AUTO, float weight = IMPLOT_AUTO);
1125
1126// Gets the last item primary color (i.e. its legend icon color)
1127IMPLOT_API ImVec4 GetLastItemColor();
1128
1129// Returns the null terminated string name for an ImPlotCol.
1130IMPLOT_API const char* GetStyleColorName(ImPlotCol idx);
1131// Returns the null terminated string name for an ImPlotMarker.
1132IMPLOT_API const char* GetMarkerName(ImPlotMarker idx);
1133
1134//-----------------------------------------------------------------------------
1135// [SECTION] Colormaps
1136//-----------------------------------------------------------------------------
1137
1138// Item styling is based on colormaps when the relevant ImPlotCol_XXX is set to
1139// IMPLOT_AUTO_COL (default). Several built-in colormaps are available. You can
1140// add and then push/pop your own colormaps as well. To permanently set a colormap,
1141// modify the Colormap index member of your ImPlotStyle.
1142
1143// Colormap data will be ignored and a custom color will be used if you have done one of the following:
1144// 1) Modified an item style color in your ImPlotStyle to anything other than IMPLOT_AUTO_COL.
1145// 2) Pushed an item style color using PushStyleColor().
1146// 3) Set the next item style with a SetNextXXXStyle function.
1147
1148// Add a new colormap. The color data will be copied. The colormap can be used by pushing either the returned index or the
1149// string name with PushColormap. The colormap name must be unique and the size must be greater than 1. You will receive
1150// an assert otherwise! By default colormaps are considered to be qualitative (i.e. discrete). If you want to create a
1151// continuous colormap, set #qual=false. This will treat the colors you provide as keys, and ImPlot will build a linearly
1152// interpolated lookup table. The memory footprint of this table will be exactly ((size-1)*255+1)*4 bytes.
1153IMPLOT_API ImPlotColormap AddColormap(const char* name, const ImVec4* cols, int size, bool qual=true);
1154IMPLOT_API ImPlotColormap AddColormap(const char* name, const ImU32* cols, int size, bool qual=true);
1155
1156// Returns the number of available colormaps (i.e. the built-in + user-added count).
1157IMPLOT_API int GetColormapCount();
1158// Returns a null terminated string name for a colormap given an index. Returns nullptr if index is invalid.
1159IMPLOT_API const char* GetColormapName(ImPlotColormap cmap);
1160// Returns an index number for a colormap given a valid string name. Returns -1 if name is invalid.
1161IMPLOT_API ImPlotColormap GetColormapIndex(const char* name);
1162
1163// 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!
1164IMPLOT_API void PushColormap(ImPlotColormap cmap);
1165// Push a colormap by string name. Use built-in names such as "Default", "Deep", "Jet", etc. or a string you provided to AddColormap. Don't forget to call PopColormap!
1166IMPLOT_API void PushColormap(const char* name);
1167// Undo temporary colormap modification(s). Undo multiple pushes at once by increasing count.
1168IMPLOT_API void PopColormap(int count = 1);
1169
1170// Returns the next color from the current colormap and advances the colormap for the current plot.
1171// Can also be used with no return value to skip colors if desired. You need to call this between Begin/EndPlot!
1172IMPLOT_API ImVec4 NextColormapColor();
1173
1174// Colormap utils. If cmap = IMPLOT_AUTO (default), the current colormap is assumed.
1175// Pass an explicit colormap index (built-in or user-added) to specify otherwise.
1176
1177// Returns the size of a colormap.
1178IMPLOT_API int GetColormapSize(ImPlotColormap cmap = IMPLOT_AUTO);
1179// Returns a color from a colormap given an index >= 0 (modulo will be performed).
1180IMPLOT_API ImVec4 GetColormapColor(int idx, ImPlotColormap cmap = IMPLOT_AUTO);
1181// Sample a color from the current colormap given t between 0 and 1.
1182IMPLOT_API ImVec4 SampleColormap(float t, ImPlotColormap cmap = IMPLOT_AUTO);
1183
1184// 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.
1185IMPLOT_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);
1186// Shows a horizontal slider with a colormap gradient background. Optionally returns the color sampled at t in [0 1].
1187IMPLOT_API bool ColormapSlider(const char* label, float* t, ImVec4* out = nullptr, const char* format = "", ImPlotColormap cmap = IMPLOT_AUTO);
1188// Shows a button with a colormap gradient brackground.
1189IMPLOT_API bool ColormapButton(const char* label, const ImVec2& size = ImVec2(0,0), ImPlotColormap cmap = IMPLOT_AUTO);
1190
1191// When items in a plot sample their color from a colormap, the color is cached and does not change
1192// unless explicitly overriden. Therefore, if you change the colormap after the item has already been plotted,
1193// item colors will NOT update. If you need item colors to resample the new colormap, then use this
1194// function to bust the cached colors. If #plot_title_id is nullptr, then every item in EVERY existing plot
1195// will be cache busted. Otherwise only the plot specified by #plot_title_id will be busted. For the
1196// latter, this function must be called in the same ImGui ID scope that the plot is in. You should rarely if ever
1197// need this function, but it is available for applications that require runtime colormap swaps (e.g. Heatmaps demo).
1198IMPLOT_API void BustColorCache(const char* plot_title_id = nullptr);
1199
1200//-----------------------------------------------------------------------------
1201// [SECTION] Input Mapping
1202//-----------------------------------------------------------------------------
1203
1204// Provides access to input mapping structure for permanant modifications to controls for pan, select, etc.
1205IMPLOT_API ImPlotInputMap& GetInputMap();
1206
1207// Default input mapping: pan = LMB drag, box select = RMB drag, fit = LMB double click, context menu = RMB click, zoom = scroll.
1208IMPLOT_API void MapInputDefault(ImPlotInputMap* dst = nullptr);
1209// Reverse input mapping: pan = RMB drag, box select = LMB drag, fit = LMB double click, context menu = RMB click, zoom = scroll.
1210IMPLOT_API void MapInputReverse(ImPlotInputMap* dst = nullptr);
1211
1212//-----------------------------------------------------------------------------
1213// [SECTION] Miscellaneous
1214//-----------------------------------------------------------------------------
1215
1216// Render icons similar to those that appear in legends (nifty for data lists).
1217IMPLOT_API void ItemIcon(const ImVec4& col);
1218IMPLOT_API void ItemIcon(ImU32 col);
1219IMPLOT_API void ColormapIcon(ImPlotColormap cmap);
1220
1221// Get the plot draw list for custom rendering to the current plot area. Call between Begin/EndPlot.
1222IMPLOT_API ImDrawList* GetPlotDrawList();
1223// Push clip rect for rendering to current plot area. The rect can be expanded or contracted by #expand pixels. Call between Begin/EndPlot.
1224IMPLOT_API void PushPlotClipRect(float expand=0);
1225// Pop plot clip rect. Call between Begin/EndPlot.
1226IMPLOT_API void PopPlotClipRect();
1227
1228// Shows ImPlot style selector dropdown menu.
1229IMPLOT_API bool ShowStyleSelector(const char* label);
1230// Shows ImPlot colormap selector dropdown menu.
1231IMPLOT_API bool ShowColormapSelector(const char* label);
1232// Shows ImPlot input map selector dropdown menu.
1233IMPLOT_API bool ShowInputMapSelector(const char* label);
1234// Shows ImPlot style editor block (not a window).
1235IMPLOT_API void ShowStyleEditor(ImPlotStyle* ref = nullptr);
1236// Add basic help/info block for end users (not a window).
1237IMPLOT_API void ShowUserGuide();
1238// Shows ImPlot metrics/debug information window.
1239IMPLOT_API void ShowMetricsWindow(bool* p_popen = nullptr);
1240
1241//-----------------------------------------------------------------------------
1242// [SECTION] Demo
1243//-----------------------------------------------------------------------------
1244
1245// Shows the ImPlot demo window (add implot_demo.cpp to your sources!)
1246IMPLOT_API void ShowDemoWindow(bool* p_open = nullptr);
1247
1248} // namespace ImPlot
1249
1250//-----------------------------------------------------------------------------
1251// [SECTION] Obsolete API
1252//-----------------------------------------------------------------------------
1253
1254// The following functions will be removed! Keep your copy of implot up to date!
1255// Occasionally set '#define IMPLOT_DISABLE_OBSOLETE_FUNCTIONS' to stay ahead.
1256// If you absolutely must use these functions and do not want to receive compiler
1257// warnings, set '#define IMPLOT_DISABLE_OBSOLETE_WARNINGS'.
1258
1259#ifndef IMPLOT_DISABLE_OBSOLETE_FUNCTIONS
1260
1261#ifndef IMPLOT_DISABLE_DEPRECATED_WARNINGS
1262#if __cplusplus > 201402L
1263#define IMPLOT_DEPRECATED(method) [[deprecated]] method
1264#elif defined( __GNUC__ ) && !defined( __INTEL_COMPILER ) && ( __GNUC__ > 3 || ( __GNUC__ == 3 && __GNUC_MINOR__ >= 1 ) )
1265#define IMPLOT_DEPRECATED(method) method __attribute__( ( deprecated ) )
1266#elif defined( _MSC_VER )
1267#define IMPLOT_DEPRECATED(method) __declspec(deprecated) method
1268#else
1269#define IMPLOT_DEPRECATED(method) method
1270#endif
1271#else
1272#define IMPLOT_DEPRECATED(method) method
1273#endif
1274
1275enum ImPlotFlagsObsolete_ {
1276 ImPlotFlags_YAxis2 = 1 << 20,
1277 ImPlotFlags_YAxis3 = 1 << 21,
1278};
1279
1280namespace ImPlot {
1281
1282// OBSOLETED in v0.13 -> PLANNED REMOVAL in v1.0
1283IMPLOT_DEPRECATED( IMPLOT_API bool BeginPlot(const char* title_id,
1284 const char* x_label, // = nullptr,
1285 const char* y_label, // = nullptr,
1286 const ImVec2& size = ImVec2(-1,0),
1287 ImPlotFlags flags = ImPlotFlags_None,
1288 ImPlotAxisFlags x_flags = 0,
1289 ImPlotAxisFlags y_flags = 0,
1290 ImPlotAxisFlags y2_flags = ImPlotAxisFlags_AuxDefault,
1291 ImPlotAxisFlags y3_flags = ImPlotAxisFlags_AuxDefault,
1292 const char* y2_label = nullptr,
1293 const char* y3_label = nullptr) );
1294
1295} // namespace ImPlot
1296
1297#endif
Definition imgui.h:3052
Definition imgui_internal.h:2030
Definition implot_internal.h:1204
Definition implot.h:564
Definition implot.h:468
Definition implot.h:483
Definition implot.h:493
Definition implot.h:507
Definition imgui.h:292
Definition imgui.h:305