Struct Mesh

Source

pub struct Mesh {
    pub asset_usage: RenderAssetUsages,
    /* private fields */
}

Expand description

A 3D object made out of vertices representing triangles, lines, or points, with “attribute” values for each vertex.

Meshes can be automatically generated by a bevy AssetLoader (generally by loading a Gltf file), or by converting a primitive using into. It is also possible to create one manually. They can be edited after creation.

Meshes can be rendered with a Mesh2d and MeshMaterial2d or Mesh3d and MeshMaterial3d for 2D and 3D respectively.

A Mesh in Bevy is equivalent to a “primitive” in the glTF format, for a glTF Mesh representation, see GltfMesh.

§Manual creation

The following function will construct a flat mesh, to be rendered with a StandardMaterial or ColorMaterial:

fn create_simple_parallelogram() -> Mesh {
    // Create a new mesh using a triangle list topology, where each set of 3 vertices composes a triangle.
    Mesh::new(PrimitiveTopology::TriangleList, RenderAssetUsages::default())
        // Add 4 vertices, each with its own position attribute (coordinate in
        // 3D space), for each of the corners of the parallelogram.
        .with_inserted_attribute(
            Mesh::ATTRIBUTE_POSITION,
            vec![[0.0, 0.0, 0.0], [1.0, 2.0, 0.0], [2.0, 2.0, 0.0], [1.0, 0.0, 0.0]]
        )
        // Assign a UV coordinate to each vertex.
        .with_inserted_attribute(
            Mesh::ATTRIBUTE_UV_0,
            vec![[0.0, 1.0], [0.5, 0.0], [1.0, 0.0], [0.5, 1.0]]
        )
        // Assign normals (everything points outwards)
        .with_inserted_attribute(
            Mesh::ATTRIBUTE_NORMAL,
            vec![[0.0, 0.0, 1.0], [0.0, 0.0, 1.0], [0.0, 0.0, 1.0], [0.0, 0.0, 1.0]]
        )
        // After defining all the vertices and their attributes, build each triangle using the
        // indices of the vertices that make it up in a counter-clockwise order.
        .with_inserted_indices(Indices::U32(vec![
            // First triangle
            0, 3, 1,
            // Second triangle
            1, 3, 2
        ]))
}

You can see how it looks like here, used in a Mesh3d with a square bevy logo texture, with added axis, points, lines and text for clarity.

§Other examples

For further visualization, explanation, and examples, see the built-in Bevy examples, and the implementation of the built-in shapes. In particular, generate_custom_mesh teaches you to access and modify the attributes of a Mesh after creating it.

§Common points of confusion

UV maps in Bevy start at the top-left, see ATTRIBUTE_UV_0, other APIs can have other conventions, OpenGL starts at bottom-left.
It is possible and sometimes useful for multiple vertices to have the same position attribute value, it’s a common technique in 3D modeling for complex UV mapping or other calculations.
Bevy performs frustum culling based on the Aabb of meshes, which is calculated and added automatically for new meshes only. If a mesh is modified, the entity’s Aabb needs to be updated manually or deleted so that it is re-calculated.

§Use with `StandardMaterial`

To render correctly with StandardMaterial, a mesh needs to have properly defined:

UVs: Bevy needs to know how to map a texture onto the mesh (also true for ColorMaterial).
Normals: Bevy needs to know how light interacts with your mesh. [0.0, 0.0, 1.0] is very common for simple flat meshes on the XY plane, because simple meshes are smooth and they don’t require complex light calculations.
Vertex winding order: by default, StandardMaterial.cull_mode is Some(Face::Back), which means that Bevy would only render the “front” of each triangle, which is the side of the triangle from where the vertices appear in a counter-clockwise order.

Fields§

§asset_usage: RenderAssetUsages

Struct MeshCopy item path

§Manual creation

§Other examples

§Common points of confusion

§Use with StandardMaterial

Fields§

Implementations§

impl Mesh

pub const ATTRIBUTE_POSITION: MeshVertexAttribute = _

pub const ATTRIBUTE_NORMAL: MeshVertexAttribute = _

pub const ATTRIBUTE_UV_0: MeshVertexAttribute = _

pub const ATTRIBUTE_UV_1: MeshVertexAttribute = _

pub const ATTRIBUTE_TANGENT: MeshVertexAttribute = _

pub const ATTRIBUTE_COLOR: MeshVertexAttribute = _

pub const ATTRIBUTE_JOINT_WEIGHT: MeshVertexAttribute = _

pub const ATTRIBUTE_JOINT_INDEX: MeshVertexAttribute = _

pub fn new( primitive_topology: PrimitiveTopology, asset_usage: RenderAssetUsages, ) -> Mesh

pub fn primitive_topology(&self) -> PrimitiveTopology

pub fn insert_attribute( &mut self, attribute: MeshVertexAttribute, values: impl Into<VertexAttributeValues>, )

§Panics

pub fn with_inserted_attribute( self, attribute: MeshVertexAttribute, values: impl Into<VertexAttributeValues>, ) -> Mesh

§Panics

pub fn remove_attribute( &mut self, attribute: impl Into<MeshVertexAttributeId>, ) -> Option<VertexAttributeValues>

pub fn with_removed_attribute( self, attribute: impl Into<MeshVertexAttributeId>, ) -> Mesh

pub fn contains_attribute(&self, id: impl Into<MeshVertexAttributeId>) -> bool

pub fn attribute( &self, id: impl Into<MeshVertexAttributeId>, ) -> Option<&VertexAttributeValues>

pub fn attribute_mut( &mut self, id: impl Into<MeshVertexAttributeId>, ) -> Option<&mut VertexAttributeValues>

pub fn attributes( &self, ) -> impl Iterator<Item = (&MeshVertexAttribute, &VertexAttributeValues)>

pub fn attributes_mut( &mut self, ) -> impl Iterator<Item = (&MeshVertexAttribute, &mut VertexAttributeValues)>

pub fn insert_indices(&mut self, indices: Indices)

pub fn with_inserted_indices(self, indices: Indices) -> Mesh

pub fn indices(&self) -> Option<&Indices>

pub fn indices_mut(&mut self) -> Option<&mut Indices>

pub fn remove_indices(&mut self) -> Option<Indices>

pub fn with_removed_indices(self) -> Mesh

pub fn get_vertex_size(&self) -> u64

pub fn get_vertex_buffer_size(&self) -> usize

pub fn get_index_buffer_bytes(&self) -> Option<&[u8]>

pub fn get_mesh_vertex_buffer_layout( &self, mesh_vertex_buffer_layouts: &mut MeshVertexBufferLayouts, ) -> MeshVertexBufferLayoutRef

pub fn count_vertices(&self) -> usize

pub fn create_packed_vertex_buffer_data(&self) -> Vec<u8> ⓘ

pub fn write_packed_vertex_buffer_data(&self, slice: &mut [u8])

pub fn duplicate_vertices(&mut self)

pub fn with_duplicated_vertices(self) -> Mesh

pub fn invert_winding(&mut self) -> Result<(), MeshWindingInvertError>

pub fn with_inverted_winding(self) -> Result<Mesh, MeshWindingInvertError>

pub fn compute_normals(&mut self)

§Panics

pub fn compute_flat_normals(&mut self)

§Panics

pub fn compute_smooth_normals(&mut self)

§Panics

pub fn with_computed_normals(self) -> Mesh

§Panics

pub fn with_computed_flat_normals(self) -> Mesh

§Panics

pub fn with_computed_smooth_normals(self) -> Mesh

§Panics

pub fn generate_tangents(&mut self) -> Result<(), GenerateTangentsError>

pub fn with_generated_tangents(self) -> Result<Mesh, GenerateTangentsError>

pub fn merge(&mut self, other: &Mesh)

§Panics

pub fn transformed_by(self, transform: Transform) -> Mesh

pub fn transform_by(&mut self, transform: Transform)

pub fn translated_by(self, translation: Vec3) -> Mesh

pub fn translate_by(&mut self, translation: Vec3)

pub fn rotated_by(self, rotation: Quat) -> Mesh

pub fn rotate_by(&mut self, rotation: Quat)

pub fn scaled_by(self, scale: Vec3) -> Mesh

pub fn scale_by(&mut self, scale: Vec3)

pub fn has_morph_targets(&self) -> bool

pub fn set_morph_targets(&mut self, morph_targets: Handle<Image>)

pub fn morph_targets(&self) -> Option<&Handle<Image>>

pub fn with_morph_targets(self, morph_targets: Handle<Image>) -> Mesh

pub fn set_morph_target_names(&mut self, names: Vec<String>)

pub fn with_morph_target_names(self, names: Vec<String>) -> Mesh

pub fn morph_target_names(&self) -> Option<&[String]>

pub fn normalize_joint_weights(&mut self)

pub fn triangles( &self, ) -> Result<impl Iterator<Item = Triangle3d>, MeshTrianglesError>

Trait Implementations§

Struct Mesh

§Use with `StandardMaterial`

impl<P> From<Extrusion<P>> for Mesh
where P: Primitive2d + Meshable, <P as Meshable>::Output: Extrudable,

impl<T> From<T> for Mesh
where T: MeshBuilder,