viewport_lib/interaction/widgets/
mod.rs

1//! Interactive 3D probe and region widgets.
2//!
3//! Each widget is a pure CPU state struct (like `Gizmo`) that the host app owns.
4//! Push render items from the widget into `SceneFrame` each frame, call `update()`
5//! to advance state, and read public fields for results.
6//!
7//! Suppress orbit while a widget is active using the same pattern as
8//! `ManipulationController`:
9//!
10//! ```rust,ignore
11//! if probe.is_active() {
12//!     orbit.resolve();
13//! } else {
14//!     orbit.apply_to_camera(&mut camera);
15//! }
16//! ```
17
18pub mod box_widget;
19pub mod cylinder;
20pub mod disk;
21pub mod line_probe;
22pub mod plane;
23pub mod polyline_widget;
24pub mod sphere;
25pub mod spline;
26
27pub use box_widget::BoxWidget;
28pub use cylinder::CylinderWidget;
29pub use disk::DiskWidget;
30pub use line_probe::LineProbeWidget;
31pub use plane::PlaneWidget;
32pub use polyline_widget::PolylineWidget;
33pub use sphere::SphereWidget;
34pub use spline::SplineWidget;
35
36use crate::renderer::RenderCamera;
37
38// ---------------------------------------------------------------------------
39// WidgetContext
40// ---------------------------------------------------------------------------
41
42/// Per-frame input state passed to widget `update()` methods.
43///
44/// Build this from the `ActionFrame` and `CameraFrame` your app already has.
45/// Mirrors the shape of [`crate::ManipulationContext`].
46#[derive(Clone, Debug)]
47pub struct WidgetContext {
48    /// Camera state for this frame (used for ray construction and drag projection).
49    pub camera: RenderCamera,
50    /// Viewport width and height in pixels.
51    pub viewport_size: glam::Vec2,
52    /// Mouse cursor position relative to the viewport top-left, in pixels.
53    pub cursor_viewport: glam::Vec2,
54    /// True on the first frame that a left-button drag crosses the egui drag threshold.
55    pub drag_started: bool,
56    /// True while the left mouse button is held after crossing the drag threshold.
57    pub dragging: bool,
58    /// True on the frame the left mouse button is released.
59    pub released: bool,
60    /// True on the second click within the double-click time window.
61    ///
62    /// Used by `PolylineWidget` to insert or remove control points. Set from the
63    /// framework's double-click event (e.g. `egui::Response::double_clicked()`).
64    /// Leave `false` if the host does not need double-click interactions.
65    pub double_clicked: bool,
66}
67
68// ---------------------------------------------------------------------------
69// WidgetResult
70// ---------------------------------------------------------------------------
71
72/// Result returned by widget `update()` calls.
73#[derive(Clone, Copy, Debug, PartialEq, Eq)]
74pub enum WidgetResult {
75    /// Nothing changed this frame.
76    None,
77    /// The widget state changed (endpoint moved, size changed, point added/removed, etc.).
78    Updated,
79}
80
81// ---------------------------------------------------------------------------
82// Shared internal helpers
83// ---------------------------------------------------------------------------
84
85/// Compute a world-space radius that maps to `target_px` pixels on screen.
86///
87/// Used to keep handle spheres at a constant apparent screen size.
88pub(super) fn handle_world_radius(
89    pos: glam::Vec3,
90    camera: &RenderCamera,
91    viewport_height: f32,
92    target_px: f32,
93) -> f32 {
94    let eye = glam::Vec3::from(camera.eye_position);
95    let dist = (pos - eye).length().max(0.001);
96    let world_per_px = 2.0 * (camera.fov * 0.5).tan() * dist / viewport_height.max(1.0);
97    world_per_px * target_px
98}
99
100/// Build a ray from the context cursor position.
101pub(super) fn ctx_ray(ctx: &WidgetContext) -> (glam::Vec3, glam::Vec3) {
102    let vp = ctx.camera.projection * ctx.camera.view;
103    crate::interaction::picking::screen_to_ray(ctx.cursor_viewport, ctx.viewport_size, vp.inverse())
104}
105
106/// Shortest distance from a ray to a point.
107pub(super) fn ray_point_dist(
108    ray_origin: glam::Vec3,
109    ray_dir: glam::Vec3,
110    point: glam::Vec3,
111) -> f32 {
112    let t = (point - ray_origin).dot(ray_dir).max(0.0);
113    (ray_origin + ray_dir * t - point).length()
114}
115
116/// Returns a unit vector perpendicular to `n`.
117pub(super) fn any_perpendicular(n: glam::Vec3) -> glam::Vec3 {
118    let len = n.length();
119    if len < 1e-6 {
120        return glam::Vec3::X;
121    }
122    let n = n / len;
123    if n.x.abs() < 0.9 {
124        n.cross(glam::Vec3::X).normalize()
125    } else {
126        n.cross(glam::Vec3::Y).normalize()
127    }
128}
129
130/// Returns two unit vectors `(u, v)` that are mutually perpendicular and perpendicular to `n`.
131pub(super) fn any_perpendicular_pair(n: glam::Vec3) -> (glam::Vec3, glam::Vec3) {
132    let u = any_perpendicular(n);
133    let len = n.length();
134    let n_unit = if len > 1e-6 { n / len } else { glam::Vec3::Z };
135    let v = n_unit.cross(u);
136    (u, v)
137}
viewport_lib/interaction/widgets/mod.rs

viewport_lib/interaction/widgets/
mod.rs
