Struct bevy::pbr::StandardMaterial

pub struct StandardMaterial {

    pub base_color: Color,
    pub base_color_texture: Option<Handle<Image>>,
    pub emissive: Color,
    pub emissive_texture: Option<Handle<Image>>,
    pub perceptual_roughness: f32,
    pub metallic: f32,
    pub metallic_roughness_texture: Option<Handle<Image>>,
    pub reflectance: f32,
    pub normal_map_texture: Option<Handle<Image>>,
    pub flip_normal_map_y: bool,
    pub occlusion_texture: Option<Handle<Image>>,
    pub double_sided: bool,
    pub cull_mode: Option<Face>,
    pub unlit: bool,
    pub fog_enabled: bool,
    pub alpha_mode: AlphaMode,
    pub depth_bias: f32,
    pub depth_map: Option<Handle<Image>>,
    pub parallax_depth_scale: f32,
    pub parallax_mapping_method: ParallaxMappingMethod,
    pub max_parallax_layer_count: f32,
}

A material with “standard” properties used in PBR lighting Standard property values with pictures here https://google.github.io/filament/Material%20Properties.pdf.

May be created directly from a Color or an Image.

Fields

base_color: Color

The color of the surface of the material before lighting.

Doubles as diffuse albedo for non-metallic, specular for metallic and a mix for everything in between. If used together with a base_color_texture, this is factored into the final base color as base_color * base_color_texture_value

Defaults to Color::WHITE.

base_color_texture: Option<Handle<Image>>

The texture component of the material’s color before lighting. The actual pre-lighting color is base_color * this_texture.

See base_color for details.

You should set base_color to Color::WHITE (the default) if you want the texture to show as-is.

Setting base_color to something else than white will tint the texture. For example, setting base_color to pure red will tint the texture red.

emissive: Color

Color the material “emits” to the camera.

This is typically used for monitor screens or LED lights. Anything that can be visible even in darkness.

The emissive color is added to what would otherwise be the material’s visible color. This means that for a light emissive value, in darkness, you will mostly see the emissive component.

The default emissive color is black, which doesn’t add anything to the material color.

Note that an emissive material won’t light up surrounding areas like a light source, it just adds a value to the color seen on screen.

emissive_texture: Option<Handle<Image>>

The emissive map, multiplies pixels with emissive to get the final “emitting” color of a surface.

This color is multiplied by emissive to get the final emitted color. Meaning that you should set emissive to Color::WHITE if you want to use the full range of color of the emissive texture.

perceptual_roughness: f32

Linear perceptual roughness, clamped to [0.089, 1.0] in the shader.

Defaults to 0.5.

Low values result in a “glossy” material with specular highlights, while values close to 1 result in rough materials.

If used together with a roughness/metallic texture, this is factored into the final base color as roughness * roughness_texture_value.

0.089 is the minimum floating point value that won’t be rounded down to 0 in the calculations used.

metallic: f32

How “metallic” the material appears, within [0.0, 1.0].

This should be set to 0.0 for dielectric materials or 1.0 for metallic materials. For a hybrid surface such as corroded metal, you may need to use in-between values.

Defaults to 0.00, for dielectric.

If used together with a roughness/metallic texture, this is factored into the final base color as metallic * metallic_texture_value.

metallic_roughness_texture: Option<Handle<Image>>

Metallic and roughness maps, stored as a single texture.

The blue channel contains metallic values, and the green channel contains the roughness values. Other channels are unused.

Those values are multiplied by the scalar ones of the material, see metallic and perceptual_roughness for details.

Note that with the default values of metallic and perceptual_roughness, setting this texture has no effect. If you want to exclusively use the metallic_roughness_texture values for your material, make sure to set metallic and perceptual_roughness to 1.0.

reflectance: f32

Specular intensity for non-metals on a linear scale of [0.0, 1.0].

Use the value as a way to control the intensity of the specular highlight of the material, i.e. how reflective is the material, rather than the physical property “reflectance.”

Set to 0.0, no specular highlight is visible, the highlight is strongest when reflectance is set to 1.0.

Defaults to 0.5 which is mapped to 4% reflectance in the shader.

normal_map_texture: Option<Handle<Image>>

Used to fake the lighting of bumps and dents on a material.

A typical usage would be faking cobblestones on a flat plane mesh in 3D.

Notes

Normal mapping with StandardMaterial and the core bevy PBR shaders requires:

• A normal map texture
• Vertex UVs
• Vertex tangents
• Vertex normals

Tangents do not have to be stored in your model, they can be generated using the Mesh::generate_tangents method. If your material has a normal map, but still renders as a flat surface, make sure your meshes have their tangents set.

flip_normal_map_y: bool

Normal map textures authored for DirectX have their y-component flipped. Set this to flip it to right-handed conventions.

occlusion_texture: Option<Handle<Image>>

Specifies the level of exposure to ambient light.

This is usually generated and stored automatically (“baked”) by 3D-modelling software.

Typically, steep concave parts of a model (such as the armpit of a shirt) are darker, because they have little exposure to light. An occlusion map specifies those parts of the model that light doesn’t reach well.

The material will be less lit in places where this texture is dark. This is similar to ambient occlusion, but built into the model.

double_sided: bool

Support two-sided lighting by automatically flipping the normals for “back” faces within the PBR lighting shader.

Defaults to false. This does not automatically configure backface culling, which can be done via cull_mode.

cull_mode: Option<Face>

Whether to cull the “front”, “back” or neither side of a mesh. If set to None, the two sides of the mesh are visible.

Defaults to Some(Face::Back). In bevy, the order of declaration of a triangle’s vertices in Mesh defines the triangle’s front face.

When a triangle is in a viewport, if its vertices appear counter-clockwise from the viewport’s perspective, then the viewport is seeing the triangle’s front face. Conversely, if the vertices appear clockwise, you are seeing the back face.

In short, in bevy, front faces winds counter-clockwise.

Your 3D editing software should manage all of that.

unlit: bool

Whether to apply only the base color to this material.

Normals, occlusion textures, roughness, metallic, reflectance, emissive, shadows, alpha mode and ambient light are ignored if this is set to true.

fog_enabled: bool

Whether to enable fog for this material.

alpha_mode: AlphaMode

How to apply the alpha channel of the base_color_texture.

See AlphaMode for details. Defaults to AlphaMode::Opaque.

depth_bias: f32

Adjust rendered depth.

A material with a positive depth bias will render closer to the camera while negative values cause the material to render behind other objects. This is independent of the viewport.

depth_bias affects render ordering and depth write operations using the wgpu::DepthBiasState::Constant field.

depth_map: Option<Handle<Image>>

The depth map used for parallax mapping.

It is a greyscale image where white represents bottom and black the top. If this field is set, bevy will apply parallax mapping. Parallax mapping, unlike simple normal maps, will move the texture coordinate according to the current perspective, giving actual depth to the texture.

The visual result is similar to a displacement map, but does not require additional geometry.

Use the parallax_depth_scale field to control the depth of the parallax.

Limitations

• It will look weird on bent/non-planar surfaces.
• The depth of the pixel does not reflect its visual position, resulting in artifacts for depth-dependent features such as fog or SSAO.
• For the same reason, the the geometry silhouette will always be the one of the actual geometry, not the parallaxed version, resulting in awkward looks on intersecting parallaxed surfaces.

Performance

Parallax mapping requires multiple texture lookups, proportional to max_parallax_layer_count, which might be costly.

Use the parallax_mapping_method and max_parallax_layer_count fields to tweak the shader, trading graphical quality for performance.

To improve performance, set your depth_map’s Image::sampler_descriptor filter mode to FilterMode::Nearest, as this paper indicates, it improves performance a bit.

To reduce artifacts, avoid steep changes in depth, blurring the depth map helps with this.

Larger depth maps haves a disproportionate performance impact.

parallax_depth_scale: f32

How deep the offset introduced by the depth map should be.

Default is 0.1, anything over that value may look distorted. Lower values lessen the effect.

The depth is relative to texture size. This means that if your texture occupies a surface of 1 world unit, and parallax_depth_scale is 0.1, then the in-world depth will be of 0.1 world units. If the texture stretches for 10 world units, then the final depth will be of 1 world unit.

parallax_mapping_method: ParallaxMappingMethod

Which parallax mapping method to use.

We recommend that all objects use the same ParallaxMappingMethod, to avoid duplicating and running two shaders.

max_parallax_layer_count: f32

In how many layers to split the depth maps for parallax mapping.

If you are seeing jaggy edges, increase this value. However, this incurs a performance cost.

Dependent on the situation, switching to ParallaxMappingMethod::Relief and keeping this value low might have better performance than increasing the layer count while using ParallaxMappingMethod::Occlusion.

Default is 16.0.

Trait Implementations

impl AsBindGroup for StandardMaterial

type Data = StandardMaterialKey

Data that will be stored alongside the “prepared” bind group.

fn as_bind_group( &self, layout: &BindGroupLayout, render_device: &RenderDevice, images: &RenderAssets<Image>, fallback_image: &FallbackImage ) -> Result<PreparedBindGroup<<StandardMaterial as AsBindGroup>::Data>, AsBindGroupError>

Creates a bind group for self matching the layout defined in AsBindGroup::bind_group_layout.

fn bind_group_layout(render_device: &RenderDevice) -> BindGroupLayout

Creates the bind group layout matching all bind groups returned by AsBindGroup::as_bind_group

impl AsBindGroupShaderType<StandardMaterialUniform> for StandardMaterial

fn as_bind_group_shader_type( &self, images: &RenderAssets<Image> ) -> StandardMaterialUniform

Return the T ShaderType for self. When used in AsBindGroup derives, it is safe to assume that all images in self exist.

impl Clone for StandardMaterial

fn clone(&self) -> StandardMaterial

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for StandardMaterial

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

Formats the value using the given formatter.

impl Default for StandardMaterial

fn default() -> StandardMaterial

Returns the “default value” for a type.

impl From<&StandardMaterial> for StandardMaterialKey

fn from(material: &StandardMaterial) -> StandardMaterialKey

Converts to this type from the input type.

impl From<Color> for StandardMaterial

fn from(color: Color) -> StandardMaterial

Converts to this type from the input type.

impl From<Handle<Image>> for StandardMaterial

fn from(texture: Handle<Image>) -> StandardMaterial

Converts to this type from the input type.

impl FromReflect for StandardMaterialwhere Color: FromReflect, Option<Handle<Image>>: FromReflect, f32: FromReflect, bool: FromReflect, AlphaMode: FromReflect, ParallaxMappingMethod: FromReflect, Option<Face>: Any + Send + Sync,

fn from_reflect(reflect: &(dyn Reflect + 'static)) -> Option<StandardMaterial>

Constructs a concrete instance of Self from a reflected value.

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

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

impl GetTypeRegistration for StandardMaterialwhere Color: FromReflect, Option<Handle<Image>>: FromReflect, f32: FromReflect, bool: FromReflect, AlphaMode: FromReflect, ParallaxMappingMethod: FromReflect, Option<Face>: Any + Send + Sync,

fn get_type_registration() -> TypeRegistration

impl Material for StandardMaterial

fn specialize( _pipeline: &MaterialPipeline<StandardMaterial>, descriptor: &mut RenderPipelineDescriptor, _layout: &Hashed<InnerMeshVertexBufferLayout, FixedState>, key: MaterialPipelineKey<StandardMaterial> ) -> Result<(), SpecializedMeshPipelineError>

Customizes the default RenderPipelineDescriptor for a specific entity using the entity’s MaterialPipelineKey and MeshVertexBufferLayout as input.

fn prepass_fragment_shader() -> ShaderRef

Returns this material’s prepass fragment shader. If ShaderRef::Default is returned, the default prepass fragment shader will be used.

fn fragment_shader() -> ShaderRef

Returns this material’s fragment shader. If ShaderRef::Default is returned, the default mesh fragment shader will be used.

fn alpha_mode(&self) -> AlphaMode

Returns this material’s AlphaMode. Defaults to AlphaMode::Opaque.

fn depth_bias(&self) -> f32

Add a bias to the view depth of the mesh which can be used to force a specific render order for meshes with similar depth, to avoid z-fighting. The bias is in depth-texture units so large values may be needed to overcome small depth differences.

fn vertex_shader() -> ShaderRef

Returns this material’s vertex shader. If ShaderRef::Default is returned, the default mesh vertex shader will be used.

fn prepass_vertex_shader() -> ShaderRef

Returns this material’s prepass vertex shader. If ShaderRef::Default is returned, the default prepass vertex shader will be used.

impl Reflect for StandardMaterialwhere Color: FromReflect, Option<Handle<Image>>: FromReflect, f32: FromReflect, bool: FromReflect, AlphaMode: FromReflect, ParallaxMappingMethod: FromReflect, Option<Face>: Any + Send + Sync,

fn type_name(&self) -> &str

Returns the type name of the underlying type.

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

Returns the TypeInfo of the type represented by this value.

fn into_any(self: Box<StandardMaterial, Global>) -> Box<dyn Any, Global>

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<StandardMaterial, Global>) -> Box<dyn Reflect, Global>

Casts this type to a boxed reflected value.

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

Casts this type to a reflected value.

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

Casts this type to a mutable reflected value.

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

Clones the value as a Reflect trait object.

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

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

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

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<StandardMaterial, Global>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

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

Returns a “partial equality” comparison result.

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

Debug formatter for the value.

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

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

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 Struct for StandardMaterialwhere Color: FromReflect, Option<Handle<Image>>: FromReflect, f32: FromReflect, bool: FromReflect, AlphaMode: FromReflect, ParallaxMappingMethod: FromReflect, Option<Face>: Any + Send + Sync,

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

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 + 'static)>

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 + 'static)>

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 + 'static)>

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 TypePath for StandardMaterialwhere Color: FromReflect, Option<Handle<Image>>: FromReflect, f32: FromReflect, bool: FromReflect, AlphaMode: FromReflect, ParallaxMappingMethod: FromReflect, Option<Face>: 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 moudle the type is in, or None if it is anonymous.

impl TypeUuid for StandardMaterial

const TYPE_UUID: Uuid = bevy_reflect::Uuid::from_bytes([116, 148, 136, 139, 192, 130, 69, 123, 170, 207, 81, 114, 40, 204, 12, 34])

impl Typed for StandardMaterialwhere Color: FromReflect, Option<Handle<Image>>: FromReflect, f32: FromReflect, bool: FromReflect, AlphaMode: FromReflect, ParallaxMappingMethod: FromReflect, Option<Face>: Any + Send + Sync,

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.