diff --git a/src/context.rs b/src/context.rs index 7bc1f17..fff0835 100644 --- a/src/context.rs +++ b/src/context.rs @@ -1,25 +1,7 @@ -// TODO(4bb4) Do this properly. -// I already added a simple Context struct that can be created once and used as long as it is not -// dropped here for initial tests - this is of course neither threadsafe nor otherwise safe to use -// unless one "does it right", so it's not a real solution. -// -// The context should have to be created, and ideally it should be difficult to impossible -// to do things without having a context. implot-rs makes it so that there is a context and -// that context has a "frame()" function that returns a Ui, and that Ui is then used to create -// widgets. Windows are built with a build() function that takes a reference to that Ui as an -// argument, but also have a begin() function that take a context and put it in their token. -// -// I think I'll mirror that here, except that we don't need a frame() function, it's enough -// to create a context once and then keep passing it around. I'll hence need a mutex and -// a mechansim similar (or equal) to what imgui-rs does for making sure there can only be -// a single context. Implementation could go roughly like this: -// -// - Add a mutex for modifying context things -// - Make creation and drop functions use that mutex -// - Change Plot, PlotLine, PlotScatter, PlotBars, PlotText to all require a context. -// I think I'll call this PlotUi to mimmick imgui-rs' Ui. -// - Think about what this means in terms of the stacks and things like is_plot_hovered() - -// they should also only work when there is a context available. +//! Module for handling the ImPlot context. This is modeled quite directly after how +//! this is dealt with in imgui-rs, because it follows the same concepts and doing this +//! also helps readability if one is already familiar with the imgui code. + use parking_lot::ReentrantMutex; use crate::PlotUi; @@ -27,7 +9,9 @@ use crate::PlotUi; /// An implot context. /// /// A context is required to do most of the things this library provides. While this was created -/// implicitly in earlier versions of the library, it is now created explicitly. +/// implicitly in earlier versions of the library, it is now created explicitly. These contexts +/// cannot currently be disabled through the high level API. This could be implemented though, +/// if you need multiple contexts that you can switch around between, file an issue. pub struct Context { raw: *mut sys::ImPlotContext, } @@ -43,7 +27,8 @@ fn no_current_context() -> bool { } impl Context { - /// Create a context. + /// Create a context. This will also activate the context in ImPlot, and hence creating + /// a second context when one already exists is an error and will panic. pub fn create() -> Self { let _guard = CTX_MUTEX.lock(); assert!( @@ -58,7 +43,8 @@ impl Context { Self { raw: ctx } } - /// Get a "plot ui" struct, this will be used to build actual plots. + /// Get a "plot ui" struct, this will be used to build actual plots and is quite + /// analogous to imgui-rs' "Ui" struct. pub fn get_plot_ui(&self) -> PlotUi { PlotUi { context: self } } diff --git a/src/lib.rs b/src/lib.rs index 16e8a04..c207792 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -6,8 +6,13 @@ //! itself (in particular also the demo code [here](https://github.com/epezent/implot/blob/master/implot_demo.cpp)) //! 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](https://github.com/4bb4/implot-rs) +//! 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. //! -pub extern crate implot_sys as sys; +extern crate implot_sys as sys; #[macro_use] extern crate lazy_static; diff --git a/src/plot.rs b/src/plot.rs index a5c5477..db70964 100644 --- a/src/plot.rs +++ b/src/plot.rs @@ -79,9 +79,11 @@ bitflags! { /// `Plot` is to be used (within an imgui window) with the following pattern: /// ```no_run /// # use implot; +/// let plotting_context = implot::Context::create(); +/// let plot_ui = plotting_context.get_plot_ui(); /// implot::Plot::new("my title") /// .size(300.0, 200.0) // other things such as .x_label("some_label") can be added too -/// .build( || { +/// .build(&plot_ui, || { /// // Do things such as plotting lines /// }); /// diff --git a/src/plot_elements.rs b/src/plot_elements.rs index 7497231..58279f5 100644 --- a/src/plot_elements.rs +++ b/src/plot_elements.rs @@ -1,3 +1,8 @@ +//! # Plot elements module +//! +//! This module defines the various structs that can be used for drawing different things such +//! as lines, bars, scatter plots and text in a plot. For the module to create plots themselves, +//! see `plot`. use sys::imgui::im_str; // --- Actual plotting functionality -------------------------------------------------------------