bevy_gizmos/
arrows.rs

1//! Additional [`GizmoBuffer`] Functions -- Arrows
2//!
3//! Includes the implementation of [`GizmoBuffer::arrow`] and [`GizmoBuffer::arrow_2d`],
4//! and assorted support items.
5
6use crate::{gizmos::GizmoBuffer, prelude::GizmoConfigGroup};
7use bevy_color::{
8    palettes::basic::{BLUE, GREEN, RED},
9    Color,
10};
11use bevy_math::{Quat, Vec2, Vec3, Vec3Swizzles};
12use bevy_transform::TransformPoint;
13
14/// A builder returned by [`GizmoBuffer::arrow`] and [`GizmoBuffer::arrow_2d`]
15pub struct ArrowBuilder<'a, Config, Clear>
16where
17    Config: GizmoConfigGroup,
18    Clear: 'static + Send + Sync,
19{
20    gizmos: &'a mut GizmoBuffer<Config, Clear>,
21    start: Vec3,
22    end: Vec3,
23    color: Color,
24    double_ended: bool,
25    tip_length: f32,
26}
27
28impl<Config, Clear> ArrowBuilder<'_, Config, Clear>
29where
30    Config: GizmoConfigGroup,
31    Clear: 'static + Send + Sync,
32{
33    /// Change the length of the tips to be `length`.
34    /// The default tip length is [length of the arrow]/10.
35    ///
36    /// # Example
37    /// ```
38    /// # use bevy_gizmos::prelude::*;
39    /// # use bevy_math::prelude::*;
40    /// # use bevy_color::palettes::basic::GREEN;
41    /// fn system(mut gizmos: Gizmos) {
42    ///     gizmos.arrow(Vec3::ZERO, Vec3::ONE, GREEN)
43    ///         .with_tip_length(3.);
44    /// }
45    /// # bevy_ecs::system::assert_is_system(system);
46    /// ```
47    #[doc(alias = "arrow_head_length")]
48    pub fn with_tip_length(mut self, length: f32) -> Self {
49        self.tip_length = length;
50        self
51    }
52
53    /// Adds another tip to the arrow, appended in the start point.
54    /// the default is only one tip at the end point.
55    pub fn with_double_end(mut self) -> Self {
56        self.double_ended = true;
57        self
58    }
59}
60
61impl<Config, Clear> Drop for ArrowBuilder<'_, Config, Clear>
62where
63    Config: GizmoConfigGroup,
64    Clear: 'static + Send + Sync,
65{
66    /// Draws the arrow, by drawing lines with the stored [`GizmoBuffer`]
67    fn drop(&mut self) {
68        if !self.gizmos.enabled {
69            return;
70        }
71        // first, draw the body of the arrow
72        self.gizmos.line(self.start, self.end, self.color);
73        // now the hard part is to draw the head in a sensible way
74        // put us in a coordinate system where the arrow is pointing towards +x and ends at the origin
75        let pointing_end = (self.end - self.start).normalize();
76        let rotation_end = Quat::from_rotation_arc(Vec3::X, pointing_end);
77        let tips = [
78            Vec3::new(-1., 1., 0.),
79            Vec3::new(-1., 0., 1.),
80            Vec3::new(-1., -1., 0.),
81            Vec3::new(-1., 0., -1.),
82        ];
83        // - extend the vectors so their length is `tip_length`
84        // - rotate the world so +x is facing in the same direction as the arrow
85        // - translate over to the tip of the arrow
86        let tips_end = tips.map(|v| rotation_end * (v.normalize() * self.tip_length) + self.end);
87        for v in tips_end {
88            // then actually draw the tips
89            self.gizmos.line(self.end, v, self.color);
90        }
91        if self.double_ended {
92            let pointing_start = (self.start - self.end).normalize();
93            let rotation_start = Quat::from_rotation_arc(Vec3::X, pointing_start);
94            let tips_start =
95                tips.map(|v| rotation_start * (v.normalize() * self.tip_length) + self.start);
96            for v in tips_start {
97                // draw the start points tips
98                self.gizmos.line(self.start, v, self.color);
99            }
100        }
101    }
102}
103
104impl<Config, Clear> GizmoBuffer<Config, Clear>
105where
106    Config: GizmoConfigGroup,
107    Clear: 'static + Send + Sync,
108{
109    /// Draw an arrow in 3D, from `start` to `end`. Has four tips for convenient viewing from any direction.
110    ///
111    /// # Example
112    /// ```
113    /// # use bevy_gizmos::prelude::*;
114    /// # use bevy_math::prelude::*;
115    /// # use bevy_color::palettes::basic::GREEN;
116    /// fn system(mut gizmos: Gizmos) {
117    ///     gizmos.arrow(Vec3::ZERO, Vec3::ONE, GREEN);
118    /// }
119    /// # bevy_ecs::system::assert_is_system(system);
120    /// ```
121    pub fn arrow(
122        &mut self,
123        start: Vec3,
124        end: Vec3,
125        color: impl Into<Color>,
126    ) -> ArrowBuilder<'_, Config, Clear> {
127        let length = (end - start).length();
128        ArrowBuilder {
129            gizmos: self,
130            start,
131            end,
132            color: color.into(),
133            double_ended: false,
134            tip_length: length / 10.,
135        }
136    }
137
138    /// Draw an arrow in 2D (on the xy plane), from `start` to `end`.
139    ///
140    /// # Example
141    /// ```
142    /// # use bevy_gizmos::prelude::*;
143    /// # use bevy_math::prelude::*;
144    /// # use bevy_color::palettes::basic::GREEN;
145    /// fn system(mut gizmos: Gizmos) {
146    ///     gizmos.arrow_2d(Vec2::ZERO, Vec2::X, GREEN);
147    /// }
148    /// # bevy_ecs::system::assert_is_system(system);
149    /// ```
150    pub fn arrow_2d(
151        &mut self,
152        start: Vec2,
153        end: Vec2,
154        color: impl Into<Color>,
155    ) -> ArrowBuilder<'_, Config, Clear> {
156        self.arrow(start.extend(0.), end.extend(0.), color)
157    }
158}
159
160impl<Config, Clear> GizmoBuffer<Config, Clear>
161where
162    Config: GizmoConfigGroup,
163    Clear: 'static + Send + Sync,
164{
165    /// Draw a set of axes local to the given transform (`transform`), with length scaled by a factor
166    /// of `base_length`.
167    ///
168    /// # Example
169    /// ```
170    /// # use bevy_gizmos::prelude::*;
171    /// # use bevy_ecs::prelude::*;
172    /// # use bevy_transform::components::Transform;
173    /// # #[derive(Component)]
174    /// # struct MyComponent;
175    /// fn draw_axes(
176    ///     mut gizmos: Gizmos,
177    ///     query: Query<&Transform, With<MyComponent>>,
178    /// ) {
179    ///     for &transform in &query {
180    ///         gizmos.axes(transform, 1.);
181    ///     }
182    /// }
183    /// # bevy_ecs::system::assert_is_system(draw_axes);
184    /// ```
185    pub fn axes(&mut self, transform: impl TransformPoint, base_length: f32) {
186        let start = transform.transform_point(Vec3::ZERO);
187        let end_x = transform.transform_point(base_length * Vec3::X);
188        let end_y = transform.transform_point(base_length * Vec3::Y);
189        let end_z = transform.transform_point(base_length * Vec3::Z);
190
191        self.arrow(start, end_x, RED);
192        self.arrow(start, end_y, GREEN);
193        self.arrow(start, end_z, BLUE);
194    }
195
196    /// Draw a set of axes local to the given transform (`transform`), with length scaled by a factor
197    /// of `base_length`.
198    ///
199    /// # Example
200    /// ```
201    /// # use bevy_gizmos::prelude::*;
202    /// # use bevy_ecs::prelude::*;
203    /// # use bevy_transform::components::Transform;
204    /// # #[derive(Component)]
205    /// # struct AxesComponent;
206    /// fn draw_axes_2d(
207    ///     mut gizmos: Gizmos,
208    ///     query: Query<&Transform, With<AxesComponent>>,
209    /// ) {
210    ///     for &transform in &query {
211    ///         gizmos.axes_2d(transform, 1.);
212    ///     }
213    /// }
214    /// # bevy_ecs::system::assert_is_system(draw_axes_2d);
215    /// ```
216    pub fn axes_2d(&mut self, transform: impl TransformPoint, base_length: f32) {
217        let start = transform.transform_point(Vec3::ZERO);
218        let end_x = transform.transform_point(base_length * Vec3::X);
219        let end_y = transform.transform_point(base_length * Vec3::Y);
220
221        self.arrow_2d(start.xy(), end_x.xy(), RED);
222        self.arrow_2d(start.xy(), end_y.xy(), GREEN);
223    }
224}
bevy_gizmos/arrows.rs

bevy_gizmos/
arrows.rs
