Trait Material2d

Source

pub trait Material2d:
    Sized
    + AsBindGroup
    + Asset
    + Clone {
    // Provided methods
    fn vertex_shader() -> ShaderRef { ... }
    fn fragment_shader() -> ShaderRef { ... }
    fn depth_bias(&self) -> f32 { ... }
    fn alpha_mode(&self) -> AlphaMode2d { ... }
    fn specialize(
        descriptor: &mut RenderPipelineDescriptor,
        layout: &MeshVertexBufferLayoutRef,
        key: Material2dKey<Self>,
    ) -> Result<(), SpecializedMeshPipelineError> { ... }
}

Expand description

Materials are used alongside Material2dPlugin, Mesh2d, and MeshMaterial2d to spawn entities that are rendered with a specific Material2d type. They serve as an easy to use high level way to render Mesh2d entities with custom shader logic.

Materials must implement AsBindGroup to define how data will be transferred to the GPU and bound in shaders. AsBindGroup can be derived, which makes generating bindings straightforward. See the AsBindGroup docs for details.

§Example

Here is a simple Material2d implementation. The AsBindGroup derive has many features. To see what else is available, check out the AsBindGroup documentation.

#[derive(AsBindGroup, Debug, Clone, Asset, TypePath)]
pub struct CustomMaterial {
    // Uniform bindings must implement `ShaderType`, which will be used to convert the value to
    // its shader-compatible equivalent. Most core math types already implement `ShaderType`.
    #[uniform(0)]
    color: LinearRgba,
    // Images can be bound as textures in shaders. If the Image's sampler is also needed, just
    // add the sampler attribute with a different binding index.
    #[texture(1)]
    #[sampler(2)]
    color_texture: Handle<Image>,
}

// All functions on `Material2d` have default impls. You only need to implement the
// functions that are relevant for your material.
impl Material2d for CustomMaterial {
    fn fragment_shader() -> ShaderRef {
        "shaders/custom_material.wgsl".into()
    }
}

// Spawn an entity with a mesh using `CustomMaterial`.
fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<CustomMaterial>>,
    asset_server: Res<AssetServer>,
) {
    commands.spawn((
        Mesh2d(meshes.add(Circle::new(50.0))),
        MeshMaterial2d(materials.add(CustomMaterial {
            color: RED.into(),
            color_texture: asset_server.load("some_image.png"),
        })),
    ));
}

In WGSL shaders, the material’s binding would look like this:

struct CustomMaterial {
    color: vec4<f32>,
}

@group(2) @binding(0) var<uniform> material: CustomMaterial;
@group(2) @binding(1) var color_texture: texture_2d<f32>;
@group(2) @binding(2) var color_sampler: sampler;