Struct Material 

#[non_exhaustive]
pub struct Material {

    pub base_colour: [f32; 3],
    pub ambient: f32,
    pub diffuse: f32,
    pub specular: f32,
    pub shininess: f32,
    pub metallic: f32,
    pub roughness: f32,
    pub texture_id: Option<TextureId>,
    pub normal_map_id: Option<TextureId>,
    pub ao_map_id: Option<TextureId>,
    pub metallic_roughness_texture_id: Option<TextureId>,
    pub emissive: [f32; 3],
    pub emissive_texture_id: Option<TextureId>,
    pub alpha_mode: AlphaMode,
    pub shading_model: ShadingModel,
    pub param_vis: Option<ParamVis>,
    pub backface_policy: BackfacePolicy,
    pub uv_offset: [f32; 2],
    pub uv_scale: [f32; 2],
    pub ao_range: [f32; 2],
    pub metallic_range: [f32; 2],
    pub roughness_range: [f32; 2],
}

Per-object material properties for Blinn-Phong and PBR shading.

Materials carry all shading parameters that were previously global in LightingSettings. Each SceneRenderItem now has its own Material, enabling per-object visual distinction.

This struct is #[non_exhaustive]: construct via Material::default, Material::from_colour, or spread syntax (..Default::default()). This allows new fields to be added later without breaking downstream code.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

base_colour: [f32; 3]

Base diffuse colour [r, g, b] in linear 0..1 range. Default [0.7, 0.7, 0.7].

ambient: f32

Ambient light coefficient. Default 0.15.

diffuse: f32

Diffuse light coefficient. Default 0.75.

specular: f32

Specular highlight coefficient. Default 0.4.

shininess: f32

Specular shininess exponent. Default 32.0.

metallic: f32

Metallic factor for PBR Cook-Torrance shading. 0=dielectric, 1=metal. Default 0.0.

roughness: f32

Roughness factor for PBR microfacet distribution. 0=mirror, 1=fully rough. Default 0.5.

texture_id: Option<TextureId>

Optional albedo texture identifier. None = no texture applied. Default None.

normal_map_id: Option<TextureId>

Optional normal map texture identifier. None = no normal mapping. Default None.

The normal map must be in tangent-space with XY encoded as RG (0..1 -> -1..+1). Requires UVs and tangents on the mesh for correct TBN construction.

ao_map_id: Option<TextureId>

Optional ambient occlusion map texture identifier. None = no AO map. Default None.

The AO map R channel encodes cavity factor (0=fully occluded, 1=fully lit). Applied multiplicatively to ambient and diffuse terms.

metallic_roughness_texture_id: Option<TextureId>

Optional combined metallic-roughness texture (ORM layout). Default None.

Matches the glTF metallicRoughnessTexture: G channel encodes roughness, B channel encodes metallic. Each channel is multiplied by the corresponding scalar factor (roughness, metallic). Only sampled when the material’s shading_model is ShadingModel::Pbr.

emissive: [f32; 3]

Self-illumination colour added after lighting. Default [0.0, 0.0, 0.0].

Matches glTF emissiveFactor. Applied to both Blinn-Phong and PBR paths. When emissive_texture_id is set, this value is multiplied by the texture sample.

emissive_texture_id: Option<TextureId>

Optional emissive texture identifier. Default None.

Matches glTF emissiveTexture. Sampled and multiplied by emissive.

alpha_mode: AlphaMode

Alpha handling mode. Default AlphaMode::Opaque.

Mask(cutoff) discards fragments below the cutoff using the alpha channel. Blend routes the mesh through the OIT transparent pass.

shading_model: ShadingModel

Which lit shading model evaluates this surface. Default ShadingModel::Phong.

Phong uses Blinn-Phong; Pbr uses Cook-Torrance GGX driven by metallic and roughness; Matcap(id) replaces the lit path with a matcap texture lookup. The unlit per-item bypass on ItemSettings is checked independently and takes precedence over any value here.

param_vis: Option<ParamVis>

UV parameterization visualization. When set, replaces albedo/lighting with a procedural pattern in UV space : useful for inspecting parameterization quality.

Requires UV coordinates on the mesh. Default None (standard shading).

backface_policy: BackfacePolicy

Back-face rendering policy. Default BackfacePolicy::Cull (back faces hidden).

Use BackfacePolicy::Identical for single-sided geometry like planes and open surfaces. Use BackfacePolicy::DifferentColour to highlight back faces in a distinct colour : helpful for diagnosing mesh orientation errors.

uv_offset: [f32; 2]

Per-material UV offset applied to all texture samples (albedo, normal, AO, metallic-roughness, emissive). Default [0.0, 0.0].

Sampled as uv = mesh_uv * uv_scale + uv_offset in the fragment shader. Lets one mesh be shared between multiple atlas-region materials without duplicating vertex buffers : an asset pack with a single tree atlas can pick the trunk or leaves region per material instance.

uv_scale: [f32; 2]

Per-material UV scale. Default [1.0, 1.0].

See uv_offset for the full sampling formula.

ao_range: [f32; 2]

Min/max range applied to the AO map’s R sample. Identity [0.0, 1.0] passes the sample through unchanged. Skipped when ao_map_id is None.

The remap is mix(min, max, raw_sample). Useful when a packed mask map authors AO in a reduced range (e.g. [0.4, 1.0]) and the renderer needs to normalise the sample before it drives lighting.

metallic_range: [f32; 2]

Min/max range applied to the metallic sample (B channel of the metallic-roughness texture in the glTF/ORM convention). Identity [0.0, 1.0]. Skipped when metallic_roughness_texture_id is None.

Applied to the texture sample before the scalar metallic factor: final = clamp(mix(min, max, raw.b) * metallic, 0.0, 1.0).

roughness_range: [f32; 2]

Min/max range applied to the roughness sample (G channel of the metallic-roughness texture). Identity [0.0, 1.0]. Skipped when metallic_roughness_texture_id is None.

Applied to the texture sample before the scalar roughness factor: final = max(mix(min, max, raw.g) * roughness, 0.04).

Implementations

impl Material

pub fn is_two_sided(&self) -> bool

Returns true if the backface policy makes back faces visible.

pub fn backface_needs_per_object(&self) -> bool

Returns true if back faces need the per-object draw path.

Cull and Identical render correctly through the instanced path: Cull uses back-face culling and Identical disables culling but shades back faces with the geometric normal, neither of which needs per-item state the instanced shader does not carry. The styled policies (DifferentColour, Tint, Pattern) flip the normal and read a per-item back-face colour, so they stay on the per-object path.

pub fn is_blend(&self) -> bool

Returns true if this material uses alpha blending and should go through the OIT pass.

pub fn from_colour(colour: [f32; 3]) -> Self

Construct from a plain colour, all other parameters at their defaults.

pub fn pbr(base_colour: [f32; 3], metallic: f32, roughness: f32) -> Self

Construct a Cook-Torrance PBR material.

• metallic: 0.0 = dielectric, 1.0 = full metal
• roughness: 0.0 = mirror, 1.0 = fully rough

All other parameters take their defaults. Enable post-processing (PostProcessSettings::enabled = true) for correct HDR tone mapping.

pub fn is_pbr(&self) -> bool

Returns true when the material’s shading model is Cook-Torrance PBR.

pub fn is_flat(&self) -> bool

Returns true when the material’s shading model is flat / faceted.

pub fn flat(base_colour: [f32; 3]) -> Self

Construct a flat (faceted) material with the given base colour. The per-vertex normal is replaced at the fragment stage by a geometric normal recovered from screen-space derivatives, so polygon edges remain visible on otherwise smooth meshes. Everything else takes material defaults.

pub fn matcap_id(&self) -> Option<MatcapId>

Returns the matcap id when the material uses a matcap shading model.

pub fn solid(colour: [f32; 3]) -> Self

Alias for Material::from_colour.

Returns a material with the given base colour and all other fields at defaults. “solid” is a more familiar name in some graphics contexts; both names are kept so existing from_colour call sites do not need updating.

pub fn textured(texture_id: TextureId) -> Self

Returns a material with only texture_id set; all other fields take defaults.

Useful when the mesh already carries a UV layout and the only requirement is to apply a texture. Base colour, lighting model, and all other fields stay at their default values.

pub fn pbr_with_ao( base_colour: [f32; 3], metallic: f32, roughness: f32, ao_map: Option<TextureId>, ) -> Self

PBR constructor that also sets a baked ambient-occlusion texture.

• base_colour: RGB albedo in linear 0..1
• metallic: 0.0 = dielectric, 1.0 = full metal
• roughness: 0.0 = mirror, 1.0 = fully rough
• ao_map: baked AO texture id, or None to disable AO

Sets shading_model = ShadingModel::Pbr. All other fields take defaults. Use Material::pbr when no AO map is needed.

Trait Implementations

impl Clone for Material

fn clone(&self) -> Material

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Material

impl Debug for Material

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

Formats the value using the given formatter.

impl Default for Material

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Material

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Material

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Material

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Material