dear-implot3d 0.16.0-alpha.3

High-level Rust bindings to ImPlot3D with dear-imgui-rs integration
Documentation
use crate::sys;
use crate::ui::{Plot3DContextBinding, Plot3DUi};
use dear_imgui_rs::{Context, ContextBinding, Ui};

/// Plot3D context wrapper
///
/// This manages the ImPlot3D context lifetime. Create one instance per application
/// and keep it alive for the duration of your program.
///
/// # Example
///
/// ```no_run
/// use dear_imgui_rs::*;
/// use dear_implot3d::*;
///
/// let mut imgui_ctx = Context::create();
/// let plot3d_ctx = Plot3DContext::create(&imgui_ctx);
///
/// // In your main loop:
/// let ui = imgui_ctx.frame();
/// let plot_ui = plot3d_ctx.get_plot_ui(&ui);
/// ```
pub struct Plot3DContext {
    pub(crate) raw: *mut sys::ImPlot3DContext,
    pub(crate) imgui_binding: ContextBinding,
    pub(crate) owns_context: bool,
}

impl Plot3DContext {
    pub(crate) fn binding(&self) -> Plot3DContextBinding {
        Plot3DContextBinding {
            plot_ctx_raw: self.raw,
            imgui_binding: self.imgui_binding.clone(),
        }
    }

    /// Try to create a new ImPlot3D context.
    ///
    /// This should be called once after creating your ImGui context.
    pub fn try_create(imgui: &Context) -> dear_imgui_rs::ImGuiResult<Self> {
        let imgui_binding = imgui.binding();
        let ctx = imgui_binding.with_bound_context(|| unsafe {
            let prev_plot = sys::ImPlot3D_GetCurrentContext();
            let ctx = sys::ImPlot3D_CreateContext();
            if sys::ImPlot3D_GetCurrentContext() != prev_plot {
                sys::ImPlot3D_SetCurrentContext(prev_plot);
            }
            ctx
        });
        if ctx.is_null() {
            return Err(dear_imgui_rs::ImGuiError::context_creation(
                "ImPlot3D_CreateContext returned null",
            ));
        }

        Ok(Self {
            raw: ctx,
            imgui_binding,
            owns_context: true,
        })
    }

    /// Create a new ImPlot3D context (panics on error).
    pub fn create(imgui: &Context) -> Self {
        Self::try_create(imgui).expect("Failed to create ImPlot3D context")
    }

    /// Set this context as the current ImPlot3D context.
    /// Get a raw pointer to the current ImPlot3D style
    ///
    /// This is an advanced function for direct style manipulation.
    /// Prefer using the safe style functions in the `style` module.
    /// Get the raw ImPlot3D context pointer.
    ///
    /// # Safety
    ///
    /// The caller must ensure the pointer is used safely and not stored beyond the lifetime of
    /// this context wrapper.
    pub unsafe fn raw(&self) -> *mut sys::ImPlot3DContext {
        self.raw
    }

    /// Get a per-frame plotting interface
    ///
    /// Call this once per frame to get access to plotting functions.
    /// The returned `Plot3DUi` is tied to the lifetime of the `Ui` frame.
    pub fn get_plot_ui<'ui>(&self, ui: &'ui Ui) -> Plot3DUi<'ui> {
        assert_eq!(
            ui.context_id(),
            self.imgui_binding.id(),
            "dear-implot3d: Plot3DContext::get_plot_ui() requires a Ui from the owning ImGui context"
        );
        Plot3DUi {
            _ui: ui,
            binding: self.binding(),
        }
    }
}

impl Drop for Plot3DContext {
    fn drop(&mut self) {
        if !self.owns_context || self.raw.is_null() {
            return;
        }

        let _ = self.imgui_binding.try_with_bound_context(|| unsafe {
            let prev_plot = sys::ImPlot3D_GetCurrentContext();
            let restore_plot = if prev_plot == self.raw {
                std::ptr::null_mut()
            } else {
                prev_plot
            };
            sys::ImPlot3D_DestroyContext(self.raw);
            sys::ImPlot3D_SetCurrentContext(restore_plot);
        });
    }
}

#[cfg(test)]
mod tests {
    use super::Plot3DContext;
    use crate::{Context, sys};
    use std::mem::{align_of, size_of};
    use std::sync::{Mutex, OnceLock};

    fn test_guard() -> std::sync::MutexGuard<'static, ()> {
        static GUARD: OnceLock<Mutex<()>> = OnceLock::new();
        GUARD
            .get_or_init(|| Mutex::new(()))
            .lock()
            .unwrap_or_else(|err| err.into_inner())
    }

    #[test]
    fn ffi_layout_implot3d_point_is_3_f64() {
        assert_eq!(size_of::<sys::ImPlot3DPoint>(), 3 * size_of::<f64>());
        assert_eq!(align_of::<sys::ImPlot3DPoint>(), align_of::<f64>());
    }

    #[test]
    fn plot3d_ui_binds_own_context() {
        let _guard = test_guard();
        let imgui = Context::create();
        let plot_a = Plot3DContext::create(&imgui);
        let raw_a = plot_a.raw;
        let plot_b = Plot3DContext::create(&imgui);
        let raw_b = plot_b.raw;

        unsafe { sys::ImPlot3D_SetCurrentContext(raw_b) };

        plot_a.binding().with_bound_context(|| {
            assert_eq!(unsafe { sys::ImPlot3D_GetCurrentContext() }, raw_a);
        });

        assert_eq!(unsafe { sys::ImPlot3D_GetCurrentContext() }, raw_b);

        drop(plot_b);
        drop(plot_a);
    }

    #[test]
    fn plot3d_tokens_bind_own_context_before_drop() {
        let _guard = test_guard();
        let mut imgui = Context::create();
        {
            let io = imgui.io_mut();
            io.set_display_size([800.0, 600.0]);
            io.set_delta_time(1.0 / 60.0);
        }
        imgui
            .font_atlas()
            .try_claim_legacy_renderer()
            .expect("headless test requires the legacy font-atlas capability")
            .build();
        let plot_a = Plot3DContext::create(&imgui);
        let plot_b = Plot3DContext::create(&imgui);
        let raw_b = plot_b.raw;

        {
            let frame = imgui.begin_frame();
            let plot_ui = plot_a.get_plot_ui(frame.ui());
            let style = plot_ui.push_style_var_f32(crate::Plot3DStyleVar::FillAlpha, 0.5);
            unsafe { sys::ImPlot3D_SetCurrentContext(raw_b) };
            drop(style);
            assert_eq!(unsafe { sys::ImPlot3D_GetCurrentContext() }, raw_b);

            let token = plot_ui
                .begin_plot("token")
                .build()
                .expect("failed to begin 3D plot");
            unsafe { sys::ImPlot3D_SetCurrentContext(raw_b) };
            drop(token);
            assert_eq!(unsafe { sys::ImPlot3D_GetCurrentContext() }, raw_b);
        }

        drop(plot_b);
        drop(plot_a);
    }

    #[test]
    fn dropping_current_plot3d_context_clears_current_context() {
        let _guard = test_guard();
        let imgui = Context::create();
        let plot = Plot3DContext::create(&imgui);
        let raw = plot.raw;

        unsafe { sys::ImPlot3D_SetCurrentContext(raw) };
        drop(plot);

        assert!(unsafe { sys::ImPlot3D_GetCurrentContext() }.is_null());
    }

    #[test]
    fn dropping_non_current_plot3d_context_restores_previous_context() {
        let _guard = test_guard();
        let imgui = Context::create();
        let plot_a = Plot3DContext::create(&imgui);
        let plot_b = Plot3DContext::create(&imgui);
        let raw_b = plot_b.raw;

        unsafe { sys::ImPlot3D_SetCurrentContext(raw_b) };
        drop(plot_a);

        assert_eq!(unsafe { sys::ImPlot3D_GetCurrentContext() }, raw_b);
        drop(plot_b);
    }

    #[test]
    fn plot3d_ui_binds_owner_context() {
        let _guard = test_guard();
        let imgui_a = Context::create();
        let plot_a = Plot3DContext::create(&imgui_a);
        let imgui_a_raw = imgui_a.as_raw();
        let suspended_a = imgui_a.suspend_or_panic();
        let imgui_b = Context::create();

        assert_eq!(
            unsafe { dear_imgui_rs::sys::igGetCurrentContext() },
            imgui_b.as_raw()
        );
        plot_a.binding().with_bound_context(|| {
            assert_eq!(
                unsafe { dear_imgui_rs::sys::igGetCurrentContext() },
                imgui_a_raw
            );
        });
        assert_eq!(
            unsafe { dear_imgui_rs::sys::igGetCurrentContext() },
            imgui_b.as_raw()
        );
        drop(suspended_a);
        drop(plot_a);
        drop(imgui_b);
    }
}