silvana/implot-rs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Feature-gated doc aliases on Rust version >= 1.48

Browse source
This commit is contained in:
4bb4 2020-11-22 16:22:40 +01:00
parent e6234415ff
commit 07ff32ea2a
3 changed files with 28 additions and 31 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
Cargo.toml
View file

@ -16,6 +16,7 @@ imgui = { version = "0.5.0" }
bitflags = "1.0" bitflags = "1.0"
parking_lot = "0.11" parking_lot = "0.11"
lazy_static = "1.1" lazy_static = "1.1"
rustversion = "1.0.4"
[workspace] [workspace]

8
README.md
View file

@ -18,11 +18,7 @@ After 1.0, semver will be followed more properly.
![demo](demo.png) ![demo](demo.png)
## Requirements ## Requirements
imgui-rs requires minimum Rust version 1.43, so this project requires at least that. In imgui-rs requires minimum Rust version 1.40, so this project requires at least that.
addition, doc aliases as released in 1.48 (https://blog.rust-lang.org/2020/11/19/Rust-1.48.html)
were added, so currently the requirement is 1.48 - if that presents a problem, a workaround
good be looked for though. Open an issue if you're in that situation.
The sys crate compiles implot, so a C++ compiler will also be required. The sys crate compiles implot, so a C++ compiler will also be required.
## Examples ## Examples
@ -45,7 +41,7 @@ if documentation is unclear or lacking. Note that doc aliases are being added no
means one should be able to look for things with the name they have in the C++ code and means one should be able to look for things with the name they have in the C++ code and
rustdoc should show the correspondingly-named item. Sometimes this is just a matter of rustdoc should show the correspondingly-named item. Sometimes this is just a matter of
changing camelcase to snake case, other times the idiomatic bindings do things a bit changing camelcase to snake case, other times the idiomatic bindings do things a bit
differently. differently. These aliases only work with Rust 1.48 or newer.
## Implementation status ## Implementation status
Currently a work in progress, coverage of the C++ API is increased steadily. The author Currently a work in progress, coverage of the C++ API is increased steadily. The author

50
src/lib.rs
View file

@ -36,7 +36,7 @@ const NUMBER_OF_Y_AXES: usize = 3;
// Implementation note: This enum is converted straight to an usize index in a few places // Implementation note: This enum is converted straight to an usize index in a few places
// so we can store data about individual axes in arrays, so this pretty much should stay // so we can store data about individual axes in arrays, so this pretty much should stay
// just a mapping of words to numbers. // just a mapping of words to numbers.
#[doc(alias = "ImPlotYAxis")] #[rustversion::attr(since(1.48), doc(alias = "ImPlotYAxis"))]
#[derive(Clone)] #[derive(Clone)]
#[repr(u32)] #[repr(u32)]
pub enum YAxisChoice { pub enum YAxisChoice {
@ -62,7 +62,7 @@ pub struct PlotUi<'ui> {
// --- Markers, color maps, style variables, legend location ---------------------------------- // --- Markers, color maps, style variables, legend location ----------------------------------
/// Markers, documentation copied from implot.h for convenience. /// Markers, documentation copied from implot.h for convenience.
#[doc(alias = "ImPlotMarker")] #[rustversion::attr(since(1.48), doc(alias = "ImPlotMarker"))]
#[repr(i32)] #[repr(i32)]
#[derive(Copy, Clone, Debug)] #[derive(Copy, Clone, Debug)]
pub enum Marker { pub enum Marker {
@ -93,7 +93,7 @@ pub enum Marker {
/// Colorable plot elements. These are called "ImPlotCol" in ImPlot itself, but I found that /// 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 /// name somewhat confusing because we are not referring to colors, but _which_ thing can
/// be colored - hence I added the "Element". /// be colored - hence I added the "Element".
#[doc(alias = "ImPlotCol")] #[rustversion::attr(since(1.48), doc(alias = "ImPlotCol"))]
#[repr(u32)] #[repr(u32)]
#[derive(Copy, Clone, Debug)] #[derive(Copy, Clone, Debug)]
pub enum PlotColorElement { pub enum PlotColorElement {
@ -148,7 +148,7 @@ pub enum PlotColorElement {
} }
/// Colormap choice. Documentation copied from implot.h for convenience. /// Colormap choice. Documentation copied from implot.h for convenience.
#[doc(alias = "ImPlotColormap")] #[rustversion::attr(since(1.48), doc(alias = "ImPlotColormap"))]
#[repr(u32)] #[repr(u32)]
#[derive(Copy, Clone, Debug)] #[derive(Copy, Clone, Debug)]
pub enum Colormap { pub enum Colormap {
@ -177,7 +177,7 @@ pub enum Colormap {
} }
/// Style variable choice, as in "which thing will be affected by a style setting". /// Style variable choice, as in "which thing will be affected by a style setting".
#[doc(alias = "ImPlotStyleVar")] #[rustversion::attr(since(1.48), doc(alias = "ImPlotStyleVar"))]
#[repr(u32)] #[repr(u32)]
#[derive(Copy, Clone, Debug)] #[derive(Copy, Clone, Debug)]
pub enum StyleVar { pub enum StyleVar {
@ -236,7 +236,7 @@ pub enum StyleVar {
} }
/// Used to position items on a plot (e.g. legends, labels, etc.) /// Used to position items on a plot (e.g. legends, labels, etc.)
#[doc(alias = "ImPlotLocation")] #[rustversion::attr(since(1.48), doc(alias = "ImPlotLocation"))]
#[repr(u32)] #[repr(u32)]
#[derive(Copy, Clone, Debug)] #[derive(Copy, Clone, Debug)]
pub enum PlotLocation { pub enum PlotLocation {
@ -260,7 +260,7 @@ pub enum PlotLocation {
SouthEast = sys::ImPlotLocation__ImPlotLocation_SouthEast, SouthEast = sys::ImPlotLocation__ImPlotLocation_SouthEast,
} }
#[doc(alias = "ImPlotOrientation")] #[rustversion::attr(since(1.48), doc(alias = "ImPlotOrientation"))]
/// Used to orient items on a plot (e.g. legends, labels, etc.) /// Used to orient items on a plot (e.g. legends, labels, etc.)
#[repr(u32)] #[repr(u32)]
#[derive(Copy, Clone, Debug)] #[derive(Copy, Clone, Debug)]
@ -271,7 +271,7 @@ pub enum PlotOrientation {
/// Switch to one of the built-in preset colormaps. If samples is greater than 1, the map will be /// Switch to one of the built-in preset colormaps. If samples is greater than 1, the map will be
/// linearly resampled. /// linearly resampled.
#[doc(alias = "SetColormap")] #[rustversion::attr(since(1.48), doc(alias = "SetColormap"))]
pub fn set_colormap_from_preset(preset: Colormap, samples: u32) { pub fn set_colormap_from_preset(preset: Colormap, samples: u32) {
unsafe { unsafe {
// "as" casts saturate as of Rust 1.45. This is safe here, and at least the enum // "as" casts saturate as of Rust 1.45. This is safe here, and at least the enum
@ -282,7 +282,7 @@ pub fn set_colormap_from_preset(preset: Colormap, samples: u32) {
} }
/// Set a custom colormap in the form of a vector of colors. /// Set a custom colormap in the form of a vector of colors.
#[doc(alias = "SetColormap")] #[rustversion::attr(since(1.48), doc(alias = "SetColormap"))]
pub fn set_colormap_from_vec(colors: Vec<ImVec4>) { pub fn set_colormap_from_vec(colors: Vec<ImVec4>) {
unsafe { unsafe {
sys::ImPlot_SetColormapVec4Ptr(colors.as_ptr(), colors.len() as i32); sys::ImPlot_SetColormapVec4Ptr(colors.as_ptr(), colors.len() as i32);
@ -301,7 +301,7 @@ pub fn set_colormap_from_vec(colors: Vec<ImVec4>) {
/// // Plot some things /// // Plot some things
/// pushed_var.pop(); /// pushed_var.pop();
/// ``` /// ```
#[doc(alias = "PushStyleColor")] #[rustversion::attr(since(1.48), doc(alias = "PushStyleColor"))]
pub fn push_style_color( pub fn push_style_color(
element: &PlotColorElement, element: &PlotColorElement,
red: f32, red: f32,
@ -349,7 +349,7 @@ impl StyleColorToken {
/// // Plot some things /// // Plot some things
/// pushed_var.pop(); /// pushed_var.pop();
/// ``` /// ```
#[doc(alias = "PushStyleVar")] #[rustversion::attr(since(1.48), doc(alias = "PushStyleVar"))]
pub fn push_style_var_f32(element: &StyleVar, value: f32) -> StyleVarToken { pub fn push_style_var_f32(element: &StyleVar, value: f32) -> StyleVarToken {
unsafe { unsafe {
sys::ImPlot_PushStyleVarFloat(*element as sys::ImPlotStyleVar, value); sys::ImPlot_PushStyleVarFloat(*element as sys::ImPlotStyleVar, value);
@ -365,7 +365,7 @@ pub fn push_style_var_f32(element: &StyleVar, value: f32) -> StyleVarToken {
/// // plot things /// // plot things
/// markerchoice.pop() /// markerchoice.pop()
/// ``` /// ```
#[doc(alias = "PushStyleVar")] #[rustversion::attr(since(1.48), doc(alias = "PushStyleVar"))]
pub fn push_style_var_i32(element: &StyleVar, value: i32) -> StyleVarToken { pub fn push_style_var_i32(element: &StyleVar, value: i32) -> StyleVarToken {
unsafe { unsafe {
sys::ImPlot_PushStyleVarInt(*element as sys::ImPlotStyleVar, value); sys::ImPlot_PushStyleVarInt(*element as sys::ImPlotStyleVar, value);
@ -403,13 +403,13 @@ impl StyleVarToken {
// --- Miscellaneous ----------------------------------------------------------------------------- // --- Miscellaneous -----------------------------------------------------------------------------
/// Returns true if the plot area in the current or most recent plot is hovered. /// Returns true if the plot area in the current or most recent plot is hovered.
#[doc(alias = "IsPlotHovered")] #[rustversion::attr(since(1.48), doc(alias = "IsPlotHovered"))]
pub fn is_plot_hovered() -> bool { pub fn is_plot_hovered() -> bool {
unsafe { sys::ImPlot_IsPlotHovered() } unsafe { sys::ImPlot_IsPlotHovered() }
} }
/// Returns true if the current or most recent plot is queried /// Returns true if the current or most recent plot is queried
#[doc(alias = "IsPlotQueried")] #[rustversion::attr(since(1.48), doc(alias = "IsPlotQueried"))]
pub fn is_plot_queried() -> bool { pub fn is_plot_queried() -> bool {
unsafe { sys::ImPlot_IsPlotQueried() } unsafe { sys::ImPlot_IsPlotQueried() }
} }
@ -417,7 +417,7 @@ pub fn is_plot_queried() -> bool {
/// Returns the mouse position in x,y coordinates of the current or most recent plot, /// 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 /// for the specified choice of Y axis. If `None` is the Y axis choice, that means the
/// most recently selected Y axis is chosen. /// most recently selected Y axis is chosen.
#[doc(alias = "GetPlotMousePos")] #[rustversion::attr(since(1.48), doc(alias = "GetPlotMousePos"))]
pub fn get_plot_mouse_position(y_axis_choice: Option<YAxisChoice>) -> ImPlotPoint { pub fn get_plot_mouse_position(y_axis_choice: Option<YAxisChoice>) -> ImPlotPoint {
let y_axis_choice_i32 = y_axis_choice_option_to_i32(y_axis_choice); let y_axis_choice_i32 = y_axis_choice_option_to_i32(y_axis_choice);
let mut point = ImPlotPoint { x: 0.0, y: 0.0 }; // doesn't seem to have default() let mut point = ImPlotPoint { x: 0.0, y: 0.0 }; // doesn't seem to have default()
@ -429,7 +429,7 @@ pub fn get_plot_mouse_position(y_axis_choice: Option<YAxisChoice>) -> ImPlotPoin
/// Convert pixels, given as an `ImVec2`, to a position in the current plot's coordinate system. /// 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. /// Uses the specified Y axis, if any, otherwise whatever was previously chosen.
#[doc(alias = "PixelsToPlot")] #[rustversion::attr(since(1.48), doc(alias = "PixelsToPlot"))]
pub fn pixels_to_plot_vec2( pub fn pixels_to_plot_vec2(
pixel_position: &ImVec2, pixel_position: &ImVec2,
y_axis_choice: Option<YAxisChoice>, y_axis_choice: Option<YAxisChoice>,
@ -448,7 +448,7 @@ pub fn pixels_to_plot_vec2(
/// Convert pixels, given as floats `x` and `y`, to a position in the current plot's coordinate /// 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. /// system. Uses the specified Y axis, if any, otherwise whatever was previously chosen.
#[doc(alias = "PixelsToPlot")] #[rustversion::attr(since(1.48), doc(alias = "PixelsToPlot"))]
pub fn pixels_to_plot_f32( pub fn pixels_to_plot_f32(
pixel_position_x: f32, pixel_position_x: f32,
pixel_position_y: f32, pixel_position_y: f32,
@ -470,7 +470,7 @@ pub fn pixels_to_plot_f32(
/// Convert a position in the current plot's coordinate system to pixels. Uses the specified Y /// Convert a position in the current plot's coordinate system to pixels. Uses the specified Y
/// axis, if any, otherwise whatever was previously chosen. /// axis, if any, otherwise whatever was previously chosen.
/// ///
#[doc(alias = "PlotToPixels")] #[rustversion::attr(since(1.48), doc(alias = "PlotToPixels"))]
pub fn plot_to_pixels_vec2( pub fn plot_to_pixels_vec2(
plot_position: &ImPlotPoint, plot_position: &ImPlotPoint,
y_axis_choice: Option<YAxisChoice>, y_axis_choice: Option<YAxisChoice>,
@ -489,7 +489,7 @@ pub fn plot_to_pixels_vec2(
/// Convert a position in the current plot's coordinate system to pixels. Uses the specified Y /// Convert a position in the current plot's coordinate system to pixels. Uses the specified Y
/// axis, if any, otherwise whatever was previously chosen. /// axis, if any, otherwise whatever was previously chosen.
#[doc(alias = "PlotToPixels")] #[rustversion::attr(since(1.48), doc(alias = "PlotToPixels"))]
pub fn plot_to_pixels_f32( pub fn plot_to_pixels_f32(
plot_position_x: f64, plot_position_x: f64,
plot_position_y: f64, plot_position_y: f64,
@ -510,7 +510,7 @@ pub fn plot_to_pixels_f32(
/// Returns the current or most recent plot axis range for the specified choice of Y axis. If /// 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. /// `None` is the Y axis choice, that means the most recently selected Y axis is chosen.
#[doc(alias = "GetPlotLimits")] #[rustversion::attr(since(1.48), doc(alias = "GetPlotLimits"))]
pub fn get_plot_limits(y_axis_choice: Option<YAxisChoice>) -> ImPlotLimits { pub fn get_plot_limits(y_axis_choice: Option<YAxisChoice>) -> ImPlotLimits {
let y_axis_choice_i32 = y_axis_choice_option_to_i32(y_axis_choice); let y_axis_choice_i32 = y_axis_choice_option_to_i32(y_axis_choice);
// ImPlotLimits doesn't seem to have default() // ImPlotLimits doesn't seem to have default()
@ -526,7 +526,7 @@ pub fn get_plot_limits(y_axis_choice: Option<YAxisChoice>) -> ImPlotLimits {
/// Returns the query limits of the current or most recent plot, for the specified choice of Y /// 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. /// axis. If `None` is the Y axis choice, that means the most recently selected Y axis is chosen.
#[doc(alias = "GetPlotQuery")] #[rustversion::attr(since(1.48), doc(alias = "GetPlotQuery"))]
pub fn get_plot_query(y_axis_choice: Option<YAxisChoice>) -> ImPlotLimits { pub fn get_plot_query(y_axis_choice: Option<YAxisChoice>) -> ImPlotLimits {
let y_axis_choice_i32 = y_axis_choice_option_to_i32(y_axis_choice); let y_axis_choice_i32 = y_axis_choice_option_to_i32(y_axis_choice);
// ImPlotLimits doesn't seem to have default() // ImPlotLimits doesn't seem to have default()
@ -541,7 +541,7 @@ pub fn get_plot_query(y_axis_choice: Option<YAxisChoice>) -> ImPlotLimits {
} }
/// Set the Y axis to be used for any upcoming plot elements /// Set the Y axis to be used for any upcoming plot elements
#[doc(alias = "SetPlotYAxis")] #[rustversion::attr(since(1.48), doc(alias = "SetPlotYAxis"))]
pub fn set_plot_y_axis(y_axis_choice: YAxisChoice) { pub fn set_plot_y_axis(y_axis_choice: YAxisChoice) {
unsafe { unsafe {
sys::ImPlot_SetPlotYAxis(y_axis_choice as i32); sys::ImPlot_SetPlotYAxis(y_axis_choice as i32);
@ -549,14 +549,14 @@ pub fn set_plot_y_axis(y_axis_choice: YAxisChoice) {
} }
/// Returns true if the XAxis plot area in the current plot is hovered. /// Returns true if the XAxis plot area in the current plot is hovered.
#[doc(alias = "IsPlotXAxisHovered")] #[rustversion::attr(since(1.48), doc(alias = "IsPlotXAxisHovered"))]
pub fn is_plot_x_axis_hovered() -> bool { pub fn is_plot_x_axis_hovered() -> bool {
unsafe { sys::ImPlot_IsPlotXAxisHovered() } unsafe { sys::ImPlot_IsPlotXAxisHovered() }
} }
/// Returns true if the Y axis area of the given Y axis choice in the current plot is hovered. If /// 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. /// `None` is the Y axis choice, that means the most recently selected Y axis is chosen.
#[doc(alias = "IsPlotYAxisHovered")] #[rustversion::attr(since(1.48), doc(alias = "IsPlotYAxisHovered"))]
pub fn is_plot_y_axis_hovered(y_axis_choice: Option<YAxisChoice>) -> bool { pub fn is_plot_y_axis_hovered(y_axis_choice: Option<YAxisChoice>) -> bool {
let y_axis_choice_i32 = y_axis_choice_option_to_i32(y_axis_choice); let y_axis_choice_i32 = y_axis_choice_option_to_i32(y_axis_choice);
unsafe { sys::ImPlot_IsPlotYAxisHovered(y_axis_choice_i32) } unsafe { sys::ImPlot_IsPlotYAxisHovered(y_axis_choice_i32) }
@ -567,7 +567,7 @@ pub fn is_plot_y_axis_hovered(y_axis_choice: Option<YAxisChoice>) -> bool {
/// offer. Note that not all of this is necessarily implemented in implot-rs /// 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. /// already - if you find something missing you'd really like, raise an issue.
// This requires implot_demo.cpp to be in the list of sources in implot-sys. // This requires implot_demo.cpp to be in the list of sources in implot-sys.
#[doc(alias = "ShowDemoWindow")] #[rustversion::attr(since(1.48), doc(alias = "ShowDemoWindow"))]
pub fn show_demo_window(show: &mut bool) { pub fn show_demo_window(show: &mut bool) {
unsafe { unsafe {
implot_sys::ImPlot_ShowDemoWindow(show); implot_sys::ImPlot_ShowDemoWindow(show);