bevy_render/mesh/primitives/dim3/
sphere.rs

1use std::f32::consts::PI;
2
3use crate::{
4    mesh::{Indices, Mesh, MeshBuilder, Meshable},
5    render_asset::RenderAssetUsages,
6};
7use bevy_math::primitives::Sphere;
8use hexasphere::shapes::IcoSphere;
9use thiserror::Error;
10use wgpu::PrimitiveTopology;
11
12/// An error when creating an icosphere [`Mesh`] from a [`SphereMeshBuilder`].
13#[derive(Clone, Copy, Debug, Error)]
14pub enum IcosphereError {
15    /// The icosphere has too many vertices.
16    #[error("Cannot create an icosphere of {subdivisions} subdivisions due to there being too many vertices being generated: {number_of_resulting_points}. (Limited to 65535 vertices or 79 subdivisions)")]
17    TooManyVertices {
18        /// The number of subdivisions used. 79 is the largest allowed value for a mesh to be generated.
19        subdivisions: usize,
20        /// The number of vertices generated. 65535 is the largest allowed value for a mesh to be generated.
21        number_of_resulting_points: usize,
22    },
23}
24
25/// A type of sphere mesh.
26#[derive(Clone, Copy, Debug)]
27pub enum SphereKind {
28    /// An icosphere, a spherical mesh that consists of similar sized triangles.
29    Ico {
30        /// The number of subdivisions applied.
31        /// The number of faces quadruples with each subdivision.
32        subdivisions: usize,
33    },
34    /// A UV sphere, a spherical mesh that consists of quadrilaterals
35    /// apart from triangles at the top and bottom.
36    Uv {
37        /// The number of longitudinal sectors, aka the horizontal resolution.
38        #[doc(alias = "horizontal_resolution")]
39        sectors: usize,
40        /// The number of latitudinal stacks, aka the vertical resolution.
41        #[doc(alias = "vertical_resolution")]
42        stacks: usize,
43    },
44}
45
46impl Default for SphereKind {
47    fn default() -> Self {
48        Self::Ico { subdivisions: 5 }
49    }
50}
51
52/// A builder used for creating a [`Mesh`] with an [`Sphere`] shape.
53#[derive(Clone, Copy, Debug, Default)]
54pub struct SphereMeshBuilder {
55    /// The [`Sphere`] shape.
56    pub sphere: Sphere,
57    /// The type of sphere mesh that will be built.
58    pub kind: SphereKind,
59}
60
61impl SphereMeshBuilder {
62    /// Creates a new [`SphereMeshBuilder`] from a radius and [`SphereKind`].
63    #[inline]
64    pub const fn new(radius: f32, kind: SphereKind) -> Self {
65        Self {
66            sphere: Sphere { radius },
67            kind,
68        }
69    }
70
71    /// Sets the [`SphereKind`] that will be used for building the mesh.
72    #[inline]
73    pub const fn kind(mut self, kind: SphereKind) -> Self {
74        self.kind = kind;
75        self
76    }
77
78    /// Creates an icosphere mesh with the given number of subdivisions.
79    ///
80    /// The number of faces quadruples with each subdivision.
81    /// If there are `80` or more subdivisions, the vertex count will be too large,
82    /// and an [`IcosphereError`] is returned.
83    ///
84    /// A good default is `5` subdivisions.
85    pub fn ico(&self, subdivisions: usize) -> Result<Mesh, IcosphereError> {
86        if subdivisions >= 80 {
87            /*
88            Number of triangles:
89            N = 20
90
91            Number of edges:
92            E = 30
93
94            Number of vertices:
95            V = 12
96
97            Number of points within a triangle (triangular numbers):
98            inner(s) = (s^2 + s) / 2
99
100            Number of points on an edge:
101            edges(s) = s
102
103            Add up all vertices on the surface:
104            vertices(s) = edges(s) * E + inner(s - 1) * N + V
105
106            Expand and simplify. Notice that the triangular number formula has roots at -1, and 0, so translating it one to the right fixes it.
107            subdivisions(s) = 30s + 20((s^2 - 2s + 1 + s - 1) / 2) + 12
108            subdivisions(s) = 30s + 10s^2 - 10s + 12
109            subdivisions(s) = 10(s^2 + 2s) + 12
110
111            Factor an (s + 1) term to simplify in terms of calculation
112            subdivisions(s) = 10(s + 1)^2 + 12 - 10
113            resulting_vertices(s) = 10(s + 1)^2 + 2
114            */
115            let temp = subdivisions + 1;
116            let number_of_resulting_points = temp * temp * 10 + 2;
117            return Err(IcosphereError::TooManyVertices {
118                subdivisions,
119                number_of_resulting_points,
120            });
121        }
122        let generated = IcoSphere::new(subdivisions, |point| {
123            let inclination = point.y.acos();
124            let azimuth = point.z.atan2(point.x);
125
126            let norm_inclination = inclination / std::f32::consts::PI;
127            let norm_azimuth = 0.5 - (azimuth / std::f32::consts::TAU);
128
129            [norm_azimuth, norm_inclination]
130        });
131
132        let raw_points = generated.raw_points();
133
134        let points = raw_points
135            .iter()
136            .map(|&p| (p * self.sphere.radius).into())
137            .collect::<Vec<[f32; 3]>>();
138
139        let normals = raw_points
140            .iter()
141            .copied()
142            .map(Into::into)
143            .collect::<Vec<[f32; 3]>>();
144
145        let uvs = generated.raw_data().to_owned();
146
147        let mut indices = Vec::with_capacity(generated.indices_per_main_triangle() * 20);
148
149        for i in 0..20 {
150            generated.get_indices(i, &mut indices);
151        }
152
153        let indices = Indices::U32(indices);
154
155        Ok(Mesh::new(
156            PrimitiveTopology::TriangleList,
157            RenderAssetUsages::default(),
158        )
159        .with_inserted_indices(indices)
160        .with_inserted_attribute(Mesh::ATTRIBUTE_POSITION, points)
161        .with_inserted_attribute(Mesh::ATTRIBUTE_NORMAL, normals)
162        .with_inserted_attribute(Mesh::ATTRIBUTE_UV_0, uvs))
163    }
164
165    /// Creates a UV sphere [`Mesh`] with the given number of
166    /// longitudinal sectors and latitudinal stacks, aka horizontal and vertical resolution.
167    ///
168    /// A good default is `32` sectors and `18` stacks.
169    pub fn uv(&self, sectors: usize, stacks: usize) -> Mesh {
170        // Largely inspired from http://www.songho.ca/opengl/gl_sphere.html
171
172        let sectors_f32 = sectors as f32;
173        let stacks_f32 = stacks as f32;
174        let length_inv = 1. / self.sphere.radius;
175        let sector_step = 2. * PI / sectors_f32;
176        let stack_step = PI / stacks_f32;
177
178        let mut vertices: Vec<[f32; 3]> = Vec::with_capacity(stacks * sectors);
179        let mut normals: Vec<[f32; 3]> = Vec::with_capacity(stacks * sectors);
180        let mut uvs: Vec<[f32; 2]> = Vec::with_capacity(stacks * sectors);
181        let mut indices: Vec<u32> = Vec::with_capacity(stacks * sectors * 2 * 3);
182
183        for i in 0..stacks + 1 {
184            let stack_angle = PI / 2. - (i as f32) * stack_step;
185            let xy = self.sphere.radius * stack_angle.cos();
186            let z = self.sphere.radius * stack_angle.sin();
187
188            for j in 0..sectors + 1 {
189                let sector_angle = (j as f32) * sector_step;
190                let x = xy * sector_angle.cos();
191                let y = xy * sector_angle.sin();
192
193                vertices.push([x, y, z]);
194                normals.push([x * length_inv, y * length_inv, z * length_inv]);
195                uvs.push([(j as f32) / sectors_f32, (i as f32) / stacks_f32]);
196            }
197        }
198
199        // indices
200        //  k1--k1+1
201        //  |  / |
202        //  | /  |
203        //  k2--k2+1
204        for i in 0..stacks {
205            let mut k1 = i * (sectors + 1);
206            let mut k2 = k1 + sectors + 1;
207            for _j in 0..sectors {
208                if i != 0 {
209                    indices.push(k1 as u32);
210                    indices.push(k2 as u32);
211                    indices.push((k1 + 1) as u32);
212                }
213                if i != stacks - 1 {
214                    indices.push((k1 + 1) as u32);
215                    indices.push(k2 as u32);
216                    indices.push((k2 + 1) as u32);
217                }
218                k1 += 1;
219                k2 += 1;
220            }
221        }
222
223        Mesh::new(
224            PrimitiveTopology::TriangleList,
225            RenderAssetUsages::default(),
226        )
227        .with_inserted_indices(Indices::U32(indices))
228        .with_inserted_attribute(Mesh::ATTRIBUTE_POSITION, vertices)
229        .with_inserted_attribute(Mesh::ATTRIBUTE_NORMAL, normals)
230        .with_inserted_attribute(Mesh::ATTRIBUTE_UV_0, uvs)
231    }
232}
233
234impl MeshBuilder for SphereMeshBuilder {
235    /// Builds a [`Mesh`] according to the configuration in `self`.
236    ///
237    /// # Panics
238    ///
239    /// Panics if the sphere is a [`SphereKind::Ico`] with a subdivision count
240    /// that is greater than or equal to `80` because there will be too many vertices.
241    fn build(&self) -> Mesh {
242        match self.kind {
243            SphereKind::Ico { subdivisions } => self.ico(subdivisions).unwrap(),
244            SphereKind::Uv { sectors, stacks } => self.uv(sectors, stacks),
245        }
246    }
247}
248
249impl Meshable for Sphere {
250    type Output = SphereMeshBuilder;
251
252    fn mesh(&self) -> Self::Output {
253        SphereMeshBuilder {
254            sphere: *self,
255            ..Default::default()
256        }
257    }
258}
259
260impl From<Sphere> for Mesh {
261    fn from(sphere: Sphere) -> Self {
262        sphere.mesh().build()
263    }
264}
bevy_render/mesh/primitives/dim3/sphere.rs

bevy_render/mesh/primitives/dim3/
sphere.rs
