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 using a triangle list topology, where each set of 3 vertices composes a triangle.
    Mesh::new(PrimitiveTopology::TriangleList)
        // 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_indices(Some(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.

Implementations

impl Mesh

pub const ATTRIBUTE_POSITION: MeshVertexAttribute = _

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

pub const ATTRIBUTE_NORMAL: MeshVertexAttribute = _

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

pub const ATTRIBUTE_UV_0: MeshVertexAttribute = _

Texture coordinates for the vertex. Use in conjunction with Mesh::insert_attribute or Mesh::with_inserted_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_UV_1: MeshVertexAttribute = _

Alternate texture coordinates for the vertex. Use in conjunction with Mesh::insert_attribute or Mesh::with_inserted_attribute.

Typically, these are used for lightmaps, textures that provide precomputed illumination.

pub const ATTRIBUTE_TANGENT: MeshVertexAttribute = _

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

pub const ATTRIBUTE_COLOR: MeshVertexAttribute = _

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

pub const ATTRIBUTE_JOINT_WEIGHT: MeshVertexAttribute = _

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

pub const ATTRIBUTE_JOINT_INDEX: MeshVertexAttribute = _

Per vertex joint transform matrix index. Use in conjunction with Mesh::insert_attribute or Mesh::with_inserted_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 with_inserted_attribute( self, attribute: MeshVertexAttribute, values: impl Into<VertexAttributeValues> ) -> Self

Consumes the mesh and returns a mesh with data set for a vertex attribute (position, normal etc.). The name will often be one of the associated constants such as Mesh::ATTRIBUTE_POSITION.

(Alternatively, you can use Mesh::insert_attribute to mutate an existing mesh in-place)

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 with_removed_attribute( self, attribute: impl Into<MeshVertexAttributeId> ) -> Self

Consumes the mesh and returns a mesh without the data for a vertex attribute

(Alternatively, you can use Mesh::remove_attribute to mutate an existing mesh in-place)

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 with_indices(self, indices: Option<Indices>) -> Self

Consumes the mesh and returns a mesh with the given vertex indices. They describe how triangles are constructed out of the vertex attributes and are therefore only useful for the PrimitiveTopology variants that use triangles.

(Alternatively, you can use Mesh::set_indices to mutate an existing mesh in-place)

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.

If the attributes have different vertex counts, the smallest is returned.

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.

If the vertex attributes have different lengths, they are all truncated to the length of the smallest.

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 with_duplicated_vertices(self) -> Self

Consumes the mesh and returns a mesh with no shared vertices.

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

(Alternatively, you can use Mesh::duplicate_vertices to mutate an existing mesh in-place)

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 with_computed_flat_normals(self) -> Self

Consumes the mesh and returns a mesh with calculated Mesh::ATTRIBUTE_NORMAL.

(Alternatively, you can use Mesh::compute_flat_normals to mutate an existing mesh in-place)

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::with_duplicated_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 with_generated_tangents(self) -> Result<Mesh, GenerateTangentsError>

Consumes the mesh and returns a mesh with tangents generated using the mikktspace algorithm.

The resulting mesh will have the Mesh::ATTRIBUTE_TANGENT attribute if successful.

(Alternatively, you can use Mesh::generate_tangents to mutate an existing mesh in-place)

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 with_morph_targets(self, morph_targets: Handle<Image>) -> Self

Consumes the mesh and returns a mesh with the given morph targets.

This requires a “morph target image”. See MorphTargetImage for info.

(Alternatively, you can use Mesh::set_morph_targets to mutate an existing mesh in-place)

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 with_morph_target_names(self, names: Vec<String>) -> Self

Consumes the mesh and returns a mesh with morph target names. Names should correspond to the order of the morph targets in set_morph_targets.

(Alternatively, you can use Mesh::set_morph_target_names to mutate an existing mesh in-place)

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 FromReflect for Meshwhere Option<Indices>: FromReflect, Option<Handle<Image>>: FromReflect, Option<Vec<String>>: FromReflect, PrimitiveTopology: Any + Send + Sync + Default, BTreeMap<MeshVertexAttributeId, MeshAttributeData>: Any + Send + Sync + Default,

fn from_reflect(reflect: &dyn Reflect) -> Option<Self>

Constructs a concrete instance of Self from a reflected value.

fn take_from_reflect( reflect: Box<dyn Reflect> ) -> Result<Self, Box<dyn Reflect>>

Attempts to downcast the given value to Self using, constructing the value using from_reflect if that fails.

impl GetTypeRegistration for Meshwhere Option<Indices>: FromReflect, Option<Handle<Image>>: FromReflect, Option<Vec<String>>: FromReflect, PrimitiveTopology: Any + Send + Sync, BTreeMap<MeshVertexAttributeId, MeshAttributeData>: Any + Send + Sync,

fn get_type_registration() -> TypeRegistration

impl Reflect for Meshwhere Option<Indices>: FromReflect, Option<Handle<Image>>: FromReflect, Option<Vec<String>>: FromReflect, PrimitiveTopology: Any + Send + Sync, BTreeMap<MeshVertexAttributeId, MeshAttributeData>: Any + Send + Sync,

fn get_represented_type_info(&self) -> Option<&'static TypeInfo>

Returns the TypeInfo of the type represented by this value.

fn into_any(self: Box<Self>) -> Box<dyn Any>

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &dyn Any

Returns the value as a &dyn Any.

fn as_any_mut(&mut self) -> &mut dyn Any

Returns the value as a &mut dyn Any.

fn into_reflect(self: Box<Self>) -> Box<dyn Reflect>

Casts this type to a boxed reflected value.

fn as_reflect(&self) -> &dyn Reflect

Casts this type to a reflected value.

fn as_reflect_mut(&mut self) -> &mut dyn Reflect

Casts this type to a mutable reflected value.

fn clone_value(&self) -> Box<dyn Reflect>

Clones the value as a Reflect trait object.

fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>

Performs a type-checked assignment of a reflected value to this value.

fn apply(&mut self, value: &dyn Reflect)

Applies a reflected value to this value.

fn reflect_ref(&self) -> ReflectRef<'_>

Returns an enumeration of “kinds” of type.

fn reflect_mut(&mut self) -> ReflectMut<'_>

Returns a mutable enumeration of “kinds” of type.

fn reflect_owned(self: Box<Self>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn reflect_partial_eq(&self, value: &dyn Reflect) -> Option<bool>

Returns a “partial equality” comparison result.

fn type_name(&self) -> &str

👎Deprecated since 0.12.0: view the method documentation to find alternatives to this method.

Returns the type path of the underlying type.

fn reflect_hash(&self) -> Option<u64>

Returns a hash of the value (which includes the type).

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

Debug formatter for the value.

fn serializable(&self) -> Option<Serializable<'_>>

Returns a serializable version of the value.

fn is_dynamic(&self) -> bool

Indicates whether or not this type is a dynamic 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 Struct for Meshwhere Option<Indices>: FromReflect, Option<Handle<Image>>: FromReflect, Option<Vec<String>>: FromReflect, PrimitiveTopology: Any + Send + Sync, BTreeMap<MeshVertexAttributeId, MeshAttributeData>: Any + Send + Sync,

fn field(&self, name: &str) -> Option<&dyn Reflect>

Returns a reference to the value of the field named name as a &dyn Reflect.

fn field_mut(&mut self, name: &str) -> Option<&mut dyn Reflect>

Returns a mutable reference to the value of the field named name as a &mut dyn Reflect.

fn field_at(&self, index: usize) -> Option<&dyn Reflect>

Returns a reference to the value of the field with index index as a &dyn Reflect.

fn field_at_mut(&mut self, index: usize) -> Option<&mut dyn Reflect>

Returns a mutable reference to the value of the field with index index as a &mut dyn Reflect.

fn name_at(&self, index: usize) -> Option<&str>

Returns the name of the field with index index.

fn field_len(&self) -> usize

Returns the number of fields in the struct.

fn iter_fields(&self) -> FieldIter<'_>

Returns an iterator over the values of the reflectable fields for this struct.

fn clone_dynamic(&self) -> DynamicStruct

Clones the struct into a DynamicStruct.

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 Meshwhere Option<Indices>: FromReflect, Option<Handle<Image>>: FromReflect, Option<Vec<String>>: FromReflect, PrimitiveTopology: Any + Send + Sync, BTreeMap<MeshVertexAttributeId, MeshAttributeData>: Any + Send + Sync,

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 module the type is in, or None if it is anonymous.

impl Typed for Meshwhere Option<Indices>: FromReflect, Option<Handle<Image>>: FromReflect, Option<Vec<String>>: FromReflect, PrimitiveTopology: Any + Send + Sync, BTreeMap<MeshVertexAttributeId, MeshAttributeData>: Any + Send + Sync,

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.

impl VisitAssetDependencies for Mesh

fn visit_dependencies(&self, _visit: &mut impl FnMut(UntypedAssetId))

impl Asset for Mesh