Struct bevy::prelude::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 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 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 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.

Fields§

§asset_usage: RenderAssetUsages

Struct bevy::prelude::Mesh

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

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

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 = (MeshVertexAttributeId, &VertexAttributeValues)>

pub fn attributes_mut( &mut self ) -> impl Iterator<Item = (MeshVertexAttributeId, &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_index_buffer_bytes(&self) -> Option<&[u8]>

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

pub fn count_vertices(&self) -> usize

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

pub fn duplicate_vertices(&mut self)

pub fn with_duplicated_vertices(self) -> Mesh

pub fn compute_flat_normals(&mut self)

pub fn with_computed_flat_normals(self) -> Mesh

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

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

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

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 compute_aabb(&self) -> Option<Aabb>

pub fn has_morph_targets(&self) -> bool

pub fn set_morph_targets(&mut self, morph_targets: 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)

Trait Implementations§

impl Clone for Mesh

fn clone(&self) -> Mesh

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

impl Debug for Mesh

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

impl From<Box> for Mesh

fn from(sp: Box) -> Mesh

impl From<Capsule> for Mesh

fn from(capsule: Capsule) -> Mesh

impl From<Capsule2d> for Mesh

fn from(capsule: Capsule2d) -> Mesh

impl From<Capsule2dMeshBuilder> for Mesh

fn from(capsule: Capsule2dMeshBuilder) -> Mesh

impl From<Capsule3d> for Mesh

fn from(capsule: Capsule3d) -> Mesh

impl From<Capsule3dMeshBuilder> for Mesh

fn from(capsule: Capsule3dMeshBuilder) -> Mesh

impl From<Circle> for Mesh

fn from(circle: Circle) -> Mesh

impl From<Circle> for Mesh

fn from(circle: Circle) -> Mesh

impl From<CircleMeshBuilder> for Mesh

fn from(circle: CircleMeshBuilder) -> Mesh

impl FromReflect for Mesh
where Mesh: Any + Send + Sync, Option<Indices>: FromReflect + TypePath, Option<Handle<Image>>: FromReflect + TypePath, Option<Vec<String>>: FromReflect + TypePath, RenderAssetUsages: FromReflect + TypePath,

impl GetTypeRegistration for Mesh
where Mesh: Any + Send + Sync, Option<Indices>: FromReflect + TypePath, Option<Handle<Image>>: FromReflect + TypePath, Option<Vec<String>>: FromReflect + TypePath, RenderAssetUsages: FromReflect + TypePath,

impl Reflect for Mesh
where Mesh: Any + Send + Sync, Option<Indices>: FromReflect + TypePath, Option<Handle<Image>>: FromReflect + TypePath, Option<Vec<String>>: FromReflect + TypePath, RenderAssetUsages: FromReflect + TypePath,