Struct bevy_render::mesh::Mesh

pub struct Mesh { /* private fields */ }

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 shape using into. It is also possible to create one manually. They can be edited after creation.

Meshes can be rendered with a Material, like StandardMaterial in PbrBundle or ColorMaterial in ColorMesh2dBundle.

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, 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
}

You can see how it looks like here, used in a PbrBundle 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 modify a Mesh’s attributes 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 modelling for complex UV mapping or other calculations.

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.

Implementations

impl Mesh

pub const ATTRIBUTE_POSITION: MeshVertexAttribute = _

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

pub const ATTRIBUTE_NORMAL: MeshVertexAttribute = _

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

pub const ATTRIBUTE_UV_0: MeshVertexAttribute = _

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

Values are generally between 0. and 1., with StandardMaterial and ColorMaterial [0.,0.] is the top left of the texture, and [1.,1.] the bottom-right. You usually want to only use values in that range, values outside will be clamped per pixel not for the vertex, “stretching” the borders of the texture. This behavior can be useful in some cases, usually when the borders have only one color, for example a logo, and you want to “extend” those borders.

pub const ATTRIBUTE_TANGENT: MeshVertexAttribute = _

The direction of the vertex tangent. Used for normal mapping. Usually generated with generate_tangents.

pub const ATTRIBUTE_COLOR: MeshVertexAttribute = _

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

pub const ATTRIBUTE_JOINT_WEIGHT: MeshVertexAttribute = _

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

pub const ATTRIBUTE_JOINT_INDEX: MeshVertexAttribute = _

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

pub fn new(primitive_topology: PrimitiveTopology) -> Self

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) -> MeshVertexBufferLayout

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>

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.

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

Generate tangents for the mesh using the mikktspace algorithm.

Sets the Mesh::ATTRIBUTE_TANGENT attribute if successful. Requires a PrimitiveTopology::TriangleList topology and the Mesh::ATTRIBUTE_POSITION, Mesh::ATTRIBUTE_NORMAL and Mesh::ATTRIBUTE_UV_0 attributes set.

pub fn compute_aabb(&self) -> Option<Aabb>

Compute the Axis-Aligned Bounding Box of the mesh vertices in model space

pub fn has_morph_targets(&self) -> bool

Whether this mesh has morph targets.

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

Set morph targets image for this mesh. This requires a “morph target image”. See MorphTargetImage for info.

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

Sets the names of each morph target. This should correspond to the order of the morph targets in set_morph_targets.

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

Gets a list of all morph target names, if they exist.

Trait Implementations

impl Clone for Mesh

fn clone(&self) -> Mesh

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Mesh

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<Box> for Mesh

fn from(sp: Box) -> Self

Converts to this type from the input type.

impl From<Capsule> for Mesh

fn from(capsule: Capsule) -> Self

Converts to this type from the input type.

impl From<Circle> for Mesh

fn from(circle: Circle) -> Self

Converts to this type from the input type.

impl From<Cube> for Mesh

fn from(cube: Cube) -> Self

Converts to this type from the input type.

impl From<Cylinder> for Mesh

fn from(c: Cylinder) -> Self

Converts to this type from the input type.

impl From<Plane> for Mesh

fn from(plane: Plane) -> Self

Converts to this type from the input type.

impl From<Quad> for Mesh

fn from(quad: Quad) -> Self

Converts to this type from the input type.

impl From<RegularPolygon> for Mesh

fn from(polygon: RegularPolygon) -> Self

Converts to this type from the input type.

impl From<Torus> for Mesh

fn from(torus: Torus) -> Self

Converts to this type from the input type.

impl From<UVSphere> for Mesh

fn from(sphere: UVSphere) -> Self

Converts to this type from the input type.

impl RenderAsset for Mesh

fn extract_asset(&self) -> Self::ExtractedAsset

Clones the mesh.

fn prepare_asset( mesh: Self::ExtractedAsset, (render_device, images): &mut SystemParamItem<'_, '_, Self::Param> ) -> Result<Self::PreparedAsset, PrepareAssetError<Self::ExtractedAsset>>

Converts the extracted mesh a into GpuMesh.

type ExtractedAsset = Mesh

The representation of the asset in the “render world”.

type PreparedAsset = GpuMesh

The GPU-representation of the asset.

type Param = (Res<'static, RenderDevice>, Res<'static, RenderAssets<Image>>)

Specifies all ECS data required by RenderAsset::prepare_asset. For convenience use the lifetimeless SystemParam.

impl TryFrom<Icosphere> for Mesh

type Error = FromIcosphereError

The type returned in the event of a conversion error.

fn try_from(sphere: Icosphere) -> Result<Self, Self::Error>

Performs the conversion.

impl TypePath for Mesh

fn type_path() -> &'static str

Returns the fully qualified path of the underlying type.

fn short_type_path() -> &'static str

Returns a short, pretty-print enabled path to the type.

fn type_ident() -> Option<&'static str>

Returns the name of the type, or None if it is anonymous.

fn crate_name() -> Option<&'static str>

Returns the name of the crate the type is in, or None if it is anonymous.

fn module_path() -> Option<&'static str>

Returns the path to the moudle the type is in, or None if it is anonymous.

impl TypeUuid for Mesh

const TYPE_UUID: Uuid = _