Struct bevy::render::mesh::Mesh

pub struct Mesh { /* private fields */ }

Implementations§

§

impl Mesh

Contains geometry in the form of a mesh.

Often meshes are automatically generated by bevy’s asset loaders or primitives, such as shape::Cube or shape::Box, but you can also construct one yourself.

Example of constructing a mesh (to be rendered with a StandardMaterial):

fn create_simple_parallelogram() -> Mesh {
    // Create a new mesh, add 4 vertices, each with its own position attribute (coordinate in
    // 3D space), for each of the corners of the parallelogram.
    let mut mesh = Mesh::new(PrimitiveTopology::TriangleList);
    mesh.insert_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.
    mesh.insert_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)
    mesh.insert_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.
    mesh.set_indices(Some(Indices::U32(vec![
        // First triangle
        0, 3, 1,
        // Second triangle
        1, 3, 2
    ])));
    mesh
    // For further visualization, explanation, and examples see the built-in Bevy examples
    // and the implementation of the built-in shapes.
}

Common points of confusion:

UV maps in Bevy are “flipped”, (0.0, 0.0) = Top-Left (not Bot-Left like OpenGL)
It is normal for multiple vertices to have the same position attribute - it’s a common technique in 3D modelling for complex UV mapping or other calculations.

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.
Normals: Bevy needs to know how light interacts with your mesh. ([0.0, 0.0, 1.0] is very common for simple meshes because simple meshes are smooth, and they don’t require complex light calculations.)
Vertex winding order - the default behavior is with StandardMaterial.cull_mode = Some(Face::Front) which means that by default Bevy would only render the front of each triangle, and the front is the side of the triangle in which the vertices appear in a counter-clockwise order.

pub const ATTRIBUTE_POSITION: MeshVertexAttribute = MeshVertexAttribute::new("Vertex_Position", 0, VertexFormat::Float32x3)

Where the vertex is located in space. Use in conjunction with Mesh::insert_attribute

pub const ATTRIBUTE_NORMAL: MeshVertexAttribute = MeshVertexAttribute::new("Vertex_Normal", 1, VertexFormat::Float32x3)

The direction the vertex normal is facing in. Use in conjunction with Mesh::insert_attribute

pub const ATTRIBUTE_UV_0: MeshVertexAttribute = MeshVertexAttribute::new("Vertex_Uv", 2, VertexFormat::Float32x2)

Texture coordinates for the vertex. Use in conjunction with Mesh::insert_attribute

pub const ATTRIBUTE_TANGENT: MeshVertexAttribute = MeshVertexAttribute::new("Vertex_Tangent", 3, VertexFormat::Float32x4)

The direction of the vertex tangent. Used for normal mapping

pub const ATTRIBUTE_COLOR: MeshVertexAttribute = MeshVertexAttribute::new("Vertex_Color", 4, VertexFormat::Float32x4)

Per vertex coloring. Use in conjunction with Mesh::insert_attribute

pub const ATTRIBUTE_JOINT_WEIGHT: MeshVertexAttribute = MeshVertexAttribute::new("Vertex_JointWeight", 5, VertexFormat::Float32x4)

Per vertex joint transform matrix weight. Use in conjunction with Mesh::insert_attribute

pub const ATTRIBUTE_JOINT_INDEX: MeshVertexAttribute = MeshVertexAttribute::new("Vertex_JointIndex", 6, VertexFormat::Uint16x4)

Per vertex joint transform matrix index. Use in conjunction with Mesh::insert_attribute

pub fn new(primitive_topology: PrimitiveTopology) -> Mesh

Construct a new mesh. You need to provide a PrimitiveTopology so that the renderer knows how to treat the vertex data. Most of the time this will be PrimitiveTopology::TriangleList.

pub fn primitive_topology(&self) -> PrimitiveTopology

Returns the topology of the mesh.

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

Sets the data for a vertex attribute (position, normal etc.). The name will often be one of the associated constants such as Mesh::ATTRIBUTE_POSITION.

Panics

Panics when the format of the values does not match the attribute’s format.

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

Removes the data for a vertex attribute

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

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

Retrieves the data currently set to the vertex attribute with the specified name.

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

Retrieves the data currently set to the vertex attribute with the specified name mutably.

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

Returns an iterator that yields references to the data of each vertex attribute.

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

Returns an iterator that yields mutable references to the data of each vertex attribute.

pub fn set_indices(&mut self, indices: Option<Indices>)

Sets the vertex indices of the mesh. They describe how triangles are constructed out of the vertex attributes and are therefore only useful for the PrimitiveTopology variants that use triangles.

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

Retrieves the vertex indices of the mesh.

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

Retrieves the vertex indices of the mesh mutably.

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

Computes and returns the index data of the mesh as bytes. This is used to transform the index data into a GPU friendly format.

pub fn get_mesh_vertex_buffer_layout( &self ) -> Hashed<InnerMeshVertexBufferLayout, FixedState>

Get this Mesh’s MeshVertexBufferLayout, used in SpecializedMeshPipeline.

pub fn count_vertices(&self) -> usize

Counts all vertices of the mesh.

Panics

Panics if the attributes have different vertex counts.

pub fn get_vertex_buffer_data(&self) -> Vec<u8, Global> ⓘ

Computes and returns the vertex data of the mesh as bytes. Therefore the attributes are located in the order of their MeshVertexAttribute::id. This is used to transform the vertex data into a GPU friendly format.

Panics

Panics if the attributes have different vertex counts.

pub fn duplicate_vertices(&mut self)

Duplicates the vertex attributes so that no vertices are shared.

This can dramatically increase the vertex count, so make sure this is what you want. Does nothing if no Indices are set.

pub fn compute_flat_normals(&mut self)

Calculates the Mesh::ATTRIBUTE_NORMAL of a mesh.

Panics

Panics if Indices are set or Mesh::ATTRIBUTE_POSITION is not of type float3 or if the mesh has any other topology than PrimitiveTopology::TriangleList. Consider calling Mesh::duplicate_vertices or export your mesh with normal attributes.