Crate implot

Rust bindings to ImPlot

This crate contains idiomatic bindings to the C++ implot library, which use the bindings exposed by the implot-sys crate. An attempt is made to keep documentation here somewhat self-contained, but when in doubt, the documentation of implot itself (in particular also the demo code here) should help as well.

For usage examples, see the implot-examples crate - it contains standalone runnable examples that showcase the API and features of this crate. The Github readme lists the features that are already implemented as idiomatic bindings. For everything else, if you’d really like a particular feature, file an issue and it’ll be given priority for wrapping, or directly contribute a PR, or use the low-level bindings directly for the time being.

If you’ve seen a construct or feature in C++ implot and can’t find it here, try searching for the C++ name - some doc aliases are defined to increase the chances of that working. If this does not yield any results, you can also try cloning the source and doing a full-text search to see if the feature is used somewhere internally the code.

Structs

AxisFlags

Axis flags. Documentation copied from implot.h for convenience. ImPlot itself also has Lock, which combines LOCK_MIN and LOCK_MAX, and NoDecorations, which combines NO_GRID_LINES, NO_TICK_MARKS and NO_TICK_LABELS.

Context

An implot context.

ImPlotLimits

ImPlotPoint

ImPlotRange

ImVec2

ImVec4

Plot

Struct to represent an ImPlot. This is the main construct used to contain all kinds of plots in ImPlot.

PlotBars

Struct to provide bar plotting functionality.

PlotFlags

Flags for customizing plot behavior and interaction. Documentation copied from implot.h for convenience. ImPlot itself also has a “CanvasOnly” flag, which can be emulated here with the combination of NO_LEGEND, NO_MENUS, NO_BOX_SELECT and NO_MOUSE_POSITION.

PlotHeatmap

Struct to provide functionality for creating headmaps.

PlotLine

Struct to provide functionality for plotting a line in a plot.

PlotScatter

Struct to provide functionality for creating a scatter plot

PlotStairs

Struct to provide functionality for plotting a line in a plot with stairs style.

PlotStems

Struct to provide stem plotting functionality.

PlotText

Struct to provide functionality for adding text within a plot

PlotToken

Tracks a plot that must be ended by calling .end()

PlotUi

A temporary reference for building plots. This does not really do anything on its own at this point, but it is used to enforce that a context is created and active for other features, such as creating plots.

StyleColorToken

Tracks a change pushed to the style color stack

StyleVarToken

Tracks a change pushed to the style variable stack

Enums

Colormap

Colormap choice. Documentation copied from implot.h for convenience.

Condition

Condition for applying a setting

Marker

Markers, documentation copied from implot.h for convenience.

PlotColorElement

Colorable plot elements. These are called “ImPlotCol” in ImPlot itself, but I found that name somewhat confusing because we are not referring to colors, but which thing can be colored - hence I added the “Element”.

PlotLocation

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

PlotOrientation

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

StyleVar

Style variable choice, as in “which thing will be affected by a style setting”.

YAxisChoice

Choice of Y axis. This an enum instead of just an integer so as to make it impossible to select a Y axis that is not present - this makes it easier to avoid Result-type return values on functions that could otherwise not really fail.

Functions

get_plot_limits

Returns the current or most recent plot axis range for the specified choice of Y axis. If None is the Y axis choice, that means the most recently selected Y axis is chosen.

get_plot_mouse_position

Returns the mouse position in x,y coordinates of the current or most recent plot, for the specified choice of Y axis. If None is the Y axis choice, that means the most recently selected Y axis is chosen.

get_plot_query

Returns the query limits of the current or most recent plot, for the specified choice of Y axis. If None is the Y axis choice, that means the most recently selected Y axis is chosen.

is_legend_entry_hovered

Returns true if the given item in the legend of the current plot is hovered.

is_plot_hovered

Returns true if the plot area in the current or most recent plot is hovered.

is_plot_queried

Returns true if the current or most recent plot is queried

is_plot_x_axis_hovered

Returns true if the XAxis plot area in the current plot is hovered.

is_plot_y_axis_hovered

Returns true if the Y axis area of the given Y axis choice in the current plot is hovered. If None is the Y axis choice, that means the most recently selected Y axis is chosen.

pixels_to_plot_f32

Convert pixels, given as floats x and y, to a position in the current plot’s coordinate system. Uses the specified Y axis, if any, otherwise whatever was previously chosen.

pixels_to_plot_vec2

Convert pixels, given as an ImVec2, to a position in the current plot’s coordinate system. Uses the specified Y axis, if any, otherwise whatever was previously chosen.

plot_to_pixels_f32

Convert a position in the current plot’s coordinate system to pixels. Uses the specified Y axis, if any, otherwise whatever was previously chosen.

plot_to_pixels_vec2

Convert a position in the current plot’s coordinate system to pixels. Uses the specified Y axis, if any, otherwise whatever was previously chosen.

push_style_color

Push a style color to the stack, giving an element and the four components of the color. The components should be between 0.0 (no intensity) and 1.0 (full intensity). The return value is a token that gets used for removing the style color from the stack again:

push_style_var_f32

Push a f32 style variable to the stack. The returned token is used for removing the variable from the stack again:

push_style_var_i32

Push an u32 style variable to the stack. The only i32 style variable is Marker at the moment, for that, use something like

push_style_var_imvec2

Push an ImVec2 style variable to the stack. The returned token is used for removing the variable from the stack again.

set_colormap_from_preset

Switch to one of the built-in preset colormaps. If samples is greater than 1, the map will be linearly resampled.

set_colormap_from_vec

Set a custom colormap in the form of a vector of colors.

set_plot_y_axis

Set the Y axis to be used for any upcoming plot elements

show_demo_window

Show the demo window for poking around what functionality implot has to offer. Note that not all of this is necessarily implemented in implot-rs already - if you find something missing you’d really like, raise an issue.