Struct MeshTag 

pub struct MeshTag {
    pub value: u32,
    /* private fields */
}

Available on crate feature bevy_mesh only.

A component that stores an arbitrary index used to identify the mesh instance when rendering.

You can fetch the value of the tag in the shader using the tag field on bevy_pbr::mesh_bindings::mesh.

When using a GpuComponentArrayBuffer, the tag represents the index of the mesh instance data in the buffer. In this case, Bevy automatically manages the tag, keeping it up to date as component data are extracted to and removed from the buffer. If you aren’t using a GpuComponentArrayBuffer, the tag is free for you to use for whatever purpose you wish.

You may optionally supply a TypeId to accompany the mesh tag. Bevy ignores this type and treats it only as an opaque marker. It’s not stored except in debug mode. Its only purpose is to provide diagnostics so that GpuComponentArrayBuffer can emit warnings if it overwrites a mesh tag. Examples of misuse that GpuComponentArrayBuffer can detect are cases in which you were using a MeshTag for application-specific purposes in addition to storing a component backed by a GpuComponentArrayBuffer on your mesh and cases in which you attempted to store multiple components backed by GpuComponentArrayBuffers on the same mesh.

Fields

value: u32

The value made available to the shader.

Implementations

impl MeshTag

pub const fn new(value: u32) -> MeshTag

Creates a new MeshTag with the given value.

No type ID is specified.

Examples found in repository

examples/shader/storage_buffer.rs (line 53)

fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut buffers: ResMut<Assets<ShaderBuffer>>,
    mut materials: ResMut<Assets<CustomMaterial>>,
) {
    // Example data for the storage buffer
    let color_data: Vec<[f32; 4]> = vec![
        [1.0, 0.0, 0.0, 1.0],
        [0.0, 1.0, 0.0, 1.0],
        [0.0, 0.0, 1.0, 1.0],
        [1.0, 1.0, 0.0, 1.0],
        [0.0, 1.0, 1.0, 1.0],
    ];

    let colors = buffers.add(ShaderBuffer::from(color_data));

    let mesh_handle = meshes.add(Cuboid::from_size(Vec3::splat(0.3)));
    // Create the custom material with the storage buffer
    let material_handle = materials.add(CustomMaterial {
        colors: colors.clone(),
    });

    commands.insert_resource(CustomMaterialHandle(material_handle.clone()));

    // Spawn cubes with the custom material
    let mut current_color_id: u32 = 0;
    for i in -6..=6 {
        for j in -3..=3 {
            commands.spawn((
                Mesh3d(mesh_handle.clone()),
                MeshMaterial3d(material_handle.clone()),
                MeshTag::new(current_color_id % 5),
                Transform::from_xyz(i as f32, j as f32, 0.0),
            ));
            current_color_id += 1;
        }
    }

    // Camera
    commands.spawn((
        Camera3d::default(),
        Transform::from_xyz(0.0, 0.0, 10.0).looking_at(Vec3::ZERO, Vec3::Y),
    ));
}

examples/shader/array_texture.rs (line 69)

fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<ArrayTextureMaterial>>,
    asset_server: Res<AssetServer>,
) {
    // Load the texture.
    let array_texture = asset_server
        .load_builder()
        .with_settings(|settings: &mut ImageLoaderSettings| {
            settings.array_layout = Some(ImageArrayLayout::RowCount {
                rows: TEXTURE_COUNT,
            });
        })
        .load("textures/array_texture.png");

    // light
    commands.spawn((
        DirectionalLight::default(),
        Transform::from_xyz(3.0, 2.0, 1.0).looking_at(Vec3::ZERO, Vec3::Y),
    ));

    // camera
    commands.spawn((
        Camera3d::default(),
        Transform::from_xyz(5.0, 5.0, 5.0).looking_at(Vec3::new(1.5, 0.0, 0.0), Vec3::Y),
    ));

    // Spawn some cubes using the array texture.
    let mesh_handle = meshes.add(Cuboid::default());
    let material_handle = materials.add(ArrayTextureMaterial { array_texture });
    for x in -5..=5 {
        commands.spawn((
            Mesh3d(mesh_handle.clone()),
            MeshMaterial3d(material_handle.clone()),
            // Pass a different mesh tag to allow selecting different layers of
            // the array texture in the shader.
            MeshTag::new(x as u32 % TEXTURE_COUNT),
            Transform::from_xyz(x as f32 + 0.5, 0.0, 0.0),
        ));
    }
}

examples/shader/automatic_instancing.rs (line 64)

fn setup(
    mut commands: Commands,
    assets: Res<AssetServer>,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<CustomMaterial>>,
) {
    // We will use this image as our external data for our material to sample from in the vertex shader
    let image = assets.load("branding/icon.png");

    // Our single mesh handle that will be instanced
    let mesh_handle = meshes.add(Cuboid::from_size(Vec3::splat(0.01)));

    // Create the custom material with a reference to our texture
    // Automatic instancing works with any Material, including the `StandardMaterial`.
    // This custom material is used to demonstrate the optional `MeshTag` feature.
    let material_handle = materials.add(CustomMaterial {
        image: image.clone(),
    });

    // We're hardcoding the image dimensions for simplicity
    let image_dims = UVec2::new(256, 256);
    let total_pixels = image_dims.x * image_dims.y;

    for index in 0..total_pixels {
        // Get x,y from index - x goes left to right, y goes top to bottom
        let x = index % image_dims.x;
        let y = index / image_dims.x;

        // Convert to centered world coordinates
        let world_x = (x as f32 - image_dims.x as f32 / 2.0) / 50.0;
        let world_y = -((y as f32 - image_dims.y as f32 / 2.0) / 50.0); // Still need negative for world space

        commands.spawn((
            // For automatic instancing to take effect you need to
            // use the same mesh handle and material handle for each instance
            Mesh3d(mesh_handle.clone()),
            MeshMaterial3d(material_handle.clone()),
            // This is an optional component that can be used to help tie external data to a mesh instance
            MeshTag::new(index),
            Transform::from_xyz(world_x, world_y, 0.0),
        ));
    }

    // Camera
    commands.spawn((
        Camera3d::default(),
        Transform::from_xyz(0.0, 0.0, 5.0).looking_at(Vec3::ZERO, Vec3::Y),
    ));
}

pub fn with_type<T>(value: u32) -> MeshTag

where T: 'static,

Creates a new MeshTag with the given value and type.

In debug mode, the type is stored on the MeshTag component and used for detecting accidental tag overwriting.

pub fn with_type_id(value: u32, _type_id: TypeId) -> MeshTag

Creates a new MeshTag with the given value and type ID.

This is the equivalent of Self::with_type, except that the type ID can be supplied dynamically.

In debug mode, the type ID is stored on the MeshTag component and used for detecting accidental tag overwriting.

pub fn type_is<T>(&self) -> bool

where T: 'static,

Returns true if the type ID is present and equal to the ID of the given type.

GpuComponentArrayBuffer uses this to emit diagnostics if the component array buffer logic overwrites a tag that might have been used for application-specific purposes or for storing other components backed by array buffers.

In debug mode, this always returns true.

pub fn type_id_is(&self, type_id: TypeId) -> bool

Available on debug-assertions enabled only.

Returns true if the type ID is present and equal to the given type ID.

This is the equivalent of Self::type_is, except that the type ID can be supplied dynamically.

In debug mode, this always returns true.

Trait Implementations

impl Clone for MeshTag

fn clone(&self) -> MeshTag

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Component for MeshTag

where MeshTag: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

A constant indicating the storage type used for this component.

type Mutability = Mutable

A marker type to assist Bevy with determining if this component is mutable, or immutable. Mutable components will have Component<Mutability = Mutable>, while immutable components will instead have Component<Mutability = Immutable>.

fn register_required_components( _requiree: ComponentId, required_components: &mut RequiredComponentsRegistrator<'_, '_>, )

Registers required components.

fn clone_behavior() -> ComponentCloneBehavior

Called when registering this component, allowing to override clone function (or disable cloning altogether) for this component.

fn relationship_accessor() -> Option<ComponentRelationshipAccessor<MeshTag>>

Returns ComponentRelationshipAccessor required for working with relationships in dynamic contexts.

fn on_add() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_add ComponentHook for this Component if one is defined.

fn on_insert() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_insert ComponentHook for this Component if one is defined.

fn on_discard() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_discard ComponentHook for this Component if one is defined.

fn on_remove() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_remove ComponentHook for this Component if one is defined.

fn on_despawn() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_despawn ComponentHook for this Component if one is defined.

fn map_entities<E>(_this: &mut Self, _mapper: &mut E)

where E: EntityMapper,

Maps the entities on this component using the given EntityMapper. This is used to remap entities in contexts like scenes and entity cloning. When deriving Component, this is populated by annotating fields containing entities with #[entities]

const HAS_SUMMARY_TICK: bool = false

Set this constant to true if the component should track a summary tick.

impl Debug for MeshTag

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

Formats the value using the given formatter.

impl Default for MeshTag

fn default() -> MeshTag

Returns the “default value” for a type.

impl Deref for MeshTag

type Target = u32

The resulting type after dereferencing.

fn deref(&self) -> &<MeshTag as Deref>::Target

Dereferences the value.

impl DerefMut for MeshTag

fn deref_mut(&mut self) -> &mut <MeshTag as Deref>::Target

Mutably dereferences the value.

impl Eq for MeshTag

impl FromArg for MeshTag

type This<'from_arg> = MeshTag

The type to convert into.

fn from_arg(arg: Arg<'_>) -> Result<<MeshTag as FromArg>::This<'_>, ArgError>

Creates an item from an argument.

impl FromReflect for MeshTag

fn from_reflect(reflect: &(dyn PartialReflect + 'static)) -> Option<MeshTag>

Constructs a concrete instance of Self from a reflected value.

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

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

impl GetOwnership for MeshTag

fn ownership() -> Ownership

Returns the ownership of Self.

impl GetTypeRegistration for MeshTag

fn get_type_registration() -> TypeRegistration

Returns the default TypeRegistration for this type.

fn register_type_dependencies(registry: &mut TypeRegistry)

Registers other types needed by this type.

impl IntoReturn for MeshTag

fn into_return<'into_return>(self) -> Return<'into_return>

where MeshTag: 'into_return,

Converts Self into a Return value.

impl PartialEq for MeshTag

fn eq(&self, other: &MeshTag) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialReflect for MeshTag

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

Returns the TypeInfo of the type represented by this value.

fn try_apply( &mut self, value: &(dyn PartialReflect + 'static), ) -> Result<(), ApplyError>

Tries to apply a reflected value to this value.

fn reflect_kind(&self) -> ReflectKind

Returns a zero-sized enumeration of “kinds” of type.

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

Returns an immutable enumeration of “kinds” of type.

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

Returns a mutable enumeration of “kinds” of type.

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

Returns an owned enumeration of “kinds” of type.

fn try_into_reflect( self: Box<MeshTag>, ) -> Result<Box<dyn Reflect>, Box<dyn PartialReflect>>

Attempts to cast this type to a boxed, fully-reflected value.

fn try_as_reflect(&self) -> Option<&(dyn Reflect + 'static)>

Attempts to cast this type to a fully-reflected value.

fn try_as_reflect_mut(&mut self) -> Option<&mut (dyn Reflect + 'static)>

Attempts to cast this type to a mutable, fully-reflected value.

fn into_partial_reflect(self: Box<MeshTag>) -> Box<dyn PartialReflect>

Casts this type to a boxed, reflected value.

fn as_partial_reflect(&self) -> &(dyn PartialReflect + 'static)

Casts this type to a reflected value.

fn as_partial_reflect_mut(&mut self) -> &mut (dyn PartialReflect + 'static)

Casts this type to a mutable, reflected value.

fn reflect_partial_eq( &self, value: &(dyn PartialReflect + 'static), ) -> Option<bool>

Returns a “partial equality” comparison result.

fn reflect_partial_cmp( &self, value: &(dyn PartialReflect + 'static), ) -> Option<Ordering>

Returns a “partial comparison” result.

fn reflect_clone(&self) -> Result<Box<dyn Reflect>, ReflectCloneError>

Attempts to clone Self using reflection.

fn apply(&mut self, value: &(dyn PartialReflect + 'static))

Applies a reflected value to this value.

fn to_dynamic(&self) -> Result<Box<dyn PartialReflect>, ReflectCloneError>

Converts this reflected value into its dynamic representation based on its kind.

fn reflect_clone_and_take<T>(&self) -> Result<T, ReflectCloneError>

where T: 'static, Self: Sized + TypePath,

For a type implementing PartialReflect, combines reflect_clone and take in a useful fashion, automatically constructing an appropriate ReflectCloneError if the downcast fails.

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 is_dynamic(&self) -> bool

Indicates whether or not this type is a dynamic type.

impl Reflect for MeshTag

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

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &(dyn Any + 'static)

Returns the value as a &dyn Any.

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Returns the value as a &mut dyn Any.

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

Casts this type to a boxed, fully-reflected value.

fn as_reflect(&self) -> &(dyn Reflect + 'static)

Casts this type to a fully-reflected value.

fn as_reflect_mut(&mut self) -> &mut (dyn Reflect + 'static)

Casts this type to a mutable, fully-reflected value.

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

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

impl Struct for MeshTag

fn field(&self, name: &str) -> Option<&(dyn PartialReflect + 'static)>

Gets a reference to the value of the field named name as a &dyn PartialReflect.

fn field_mut( &mut self, name: &str, ) -> Option<&mut (dyn PartialReflect + 'static)>

Gets a mutable reference to the value of the field named name as a &mut dyn PartialReflect.

fn field_at(&self, index: usize) -> Option<&(dyn PartialReflect + 'static)>

Gets a reference to the value of the field with index index as a &dyn PartialReflect.

fn field_at_mut( &mut self, index: usize, ) -> Option<&mut (dyn PartialReflect + 'static)>

Gets a mutable reference to the value of the field with index index as a &mut dyn PartialReflect.

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

Gets the name of the field with index index.

fn index_of_name(&self, name: &str) -> Option<usize>

Gets the index of the field with the given name.

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 to_dynamic_struct(&self) -> Result<DynamicStruct, ReflectCloneError>

Creates a new DynamicStruct from this struct.

fn get_represented_struct_info(&self) -> Option<&'static StructInfo>

Will return None if TypeInfo is not available.

impl StructuralPartialEq for MeshTag

impl TypePath for MeshTag

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 MeshTag

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.