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 /// This should be called for each frame the arrow needs to be rendered.
112 ///
113 /// # Example
114 /// ```
115 /// # use bevy_gizmos::prelude::*;
116 /// # use bevy_math::prelude::*;
117 /// # use bevy_color::palettes::basic::GREEN;
118 /// fn system(mut gizmos: Gizmos) {
119 /// gizmos.arrow(Vec3::ZERO, Vec3::ONE, GREEN);
120 /// }
121 /// # bevy_ecs::system::assert_is_system(system);
122 /// ```
123 pub fn arrow(
124 &mut self,
125 start: Vec3,
126 end: Vec3,
127 color: impl Into<Color>,
128 ) -> ArrowBuilder<'_, Config, Clear> {
129 let length = (end - start).length();
130 ArrowBuilder {
131 gizmos: self,
132 start,
133 end,
134 color: color.into(),
135 double_ended: false,
136 tip_length: length / 10.,
137 }
138 }
139
140 /// Draw an arrow in 2D (on the xy plane), from `start` to `end`.
141 ///
142 /// This should be called for each frame the arrow needs to be rendered.
143 ///
144 /// # Example
145 /// ```
146 /// # use bevy_gizmos::prelude::*;
147 /// # use bevy_math::prelude::*;
148 /// # use bevy_color::palettes::basic::GREEN;
149 /// fn system(mut gizmos: Gizmos) {
150 /// gizmos.arrow_2d(Vec2::ZERO, Vec2::X, GREEN);
151 /// }
152 /// # bevy_ecs::system::assert_is_system(system);
153 /// ```
154 pub fn arrow_2d(
155 &mut self,
156 start: Vec2,
157 end: Vec2,
158 color: impl Into<Color>,
159 ) -> ArrowBuilder<'_, Config, Clear> {
160 self.arrow(start.extend(0.), end.extend(0.), color)
161 }
162}
163
164impl<Config, Clear> GizmoBuffer<Config, Clear>
165where
166 Config: GizmoConfigGroup,
167 Clear: 'static + Send + Sync,
168{
169 /// Draw a set of axes local to the given transform (`transform`), with length scaled by a factor
170 /// of `base_length`.
171 ///
172 /// This should be called for each frame the axes need to be rendered.
173 ///
174 /// # Example
175 /// ```
176 /// # use bevy_gizmos::prelude::*;
177 /// # use bevy_ecs::prelude::*;
178 /// # use bevy_transform::components::Transform;
179 /// # #[derive(Component)]
180 /// # struct MyComponent;
181 /// fn draw_axes(
182 /// mut gizmos: Gizmos,
183 /// query: Query<&Transform, With<MyComponent>>,
184 /// ) {
185 /// for &transform in &query {
186 /// gizmos.axes(transform, 1.);
187 /// }
188 /// }
189 /// # bevy_ecs::system::assert_is_system(draw_axes);
190 /// ```
191 pub fn axes(&mut self, transform: impl TransformPoint, base_length: f32) {
192 let start = transform.transform_point(Vec3::ZERO);
193 let end_x = transform.transform_point(base_length * Vec3::X);
194 let end_y = transform.transform_point(base_length * Vec3::Y);
195 let end_z = transform.transform_point(base_length * Vec3::Z);
196
197 self.arrow(start, end_x, RED);
198 self.arrow(start, end_y, GREEN);
199 self.arrow(start, end_z, BLUE);
200 }
201
202 /// Draw a set of axes local to the given transform (`transform`), with length scaled by a factor
203 /// of `base_length`.
204 ///
205 /// This should be called for each frame the axes need to be rendered.
206 ///
207 /// # Example
208 /// ```
209 /// # use bevy_gizmos::prelude::*;
210 /// # use bevy_ecs::prelude::*;
211 /// # use bevy_transform::components::Transform;
212 /// # #[derive(Component)]
213 /// # struct AxesComponent;
214 /// fn draw_axes_2d(
215 /// mut gizmos: Gizmos,
216 /// query: Query<&Transform, With<AxesComponent>>,
217 /// ) {
218 /// for &transform in &query {
219 /// gizmos.axes_2d(transform, 1.);
220 /// }
221 /// }
222 /// # bevy_ecs::system::assert_is_system(draw_axes_2d);
223 /// ```
224 pub fn axes_2d(&mut self, transform: impl TransformPoint, base_length: f32) {
225 let start = transform.transform_point(Vec3::ZERO);
226 let end_x = transform.transform_point(base_length * Vec3::X);
227 let end_y = transform.transform_point(base_length * Vec3::Y);
228
229 self.arrow_2d(start.xy(), end_x.xy(), RED);
230 self.arrow_2d(start.xy(), end_y.xy(), GREEN);
231 }
232}