Struct DecalItem 

#[non_exhaustive]
pub struct DecalItem {

    pub transform: [[f32; 4]; 4],
    pub texture_id: TextureId,
    pub blend_mode: DecalBlendMode,
    pub alpha: f32,
    pub normal_texture_id: Option<TextureId>,
    pub normal_blend_strength: f32,
    pub sort_key: i32,
    pub roughness: f32,
    pub roughness_texture_id: Option<TextureId>,
    pub metallic: f32,
    pub metallic_texture_id: Option<TextureId>,
    pub uv_offset: [f32; 2],
    pub uv_scale: [f32; 2],
    pub emissive: f32,
    pub emissive_texture_id: Option<TextureId>,
    pub edge_fade: f32,
    pub projection: DecalProjection,
    pub settings: ItemSettings,
}

A screen-space decal projected onto whatever surface lies inside its volume.

The decal’s projection volume is the unit box [-0.5, 0.5]^3 in local space. transform maps local space to world space: scale the local box to set the decal’s world-space size, rotate to orient the projection direction, and translate to position it.

The decal texture is sampled using local XY as UVs. The Z axis of the local box is the projection direction (front face = +Z in local space).

texture_id must be a value returned by [DeviceResources::upload_texture].

Normal map (D2)

Set normal_texture_id to a tangent-space normal map (same UV space as texture_id). The renderer approximates the receiver surface normal from depth derivatives, applies the decal normal map in that tangent frame, and uses the blended normal to modulate the shading. Set normal_blend_strength between 0.0 (no effect) and 1.0 (full decal normal).

Sorting (D3)

When multiple decals overlap, sort_key controls the composite order. Lower keys render first (underneath); higher keys render on top. Decals with equal keys render in insertion order.

Roughness / metallic (D3)

roughness and metallic add a view-angle specular approximation on top of the decal colour. Because decals run post-opaque without access to scene light data, the highlight uses the view direction as a retroreflection proxy: low roughness produces a tight glossy highlight at near-normal incidence; high metallic tints the highlight by the albedo colour. This approximation is sufficient for wet-surface and scuff effects; it is not physically accurate PBR.

UV animation (D4)

uv_offset and uv_scale shift and scale the final UV before texture sampling. For sprite-sheet and scroll animations, use LiveDecal with a DecalAnimation: the scene updates uv_offset / uv_scale from the animation each frame.

Emissive (D6)

emissive adds a self-illumination contribution on top of whatever the blend mode produces. The emissive colour is sampled from emissive_texture_id when set, or taken from the albedo colour otherwise. The contribution is always additive regardless of blend mode, so emissive = 0.0 (default) has no visible effect. Values above 1.0 are meaningful in HDR: they bloom under tone-mapping when post_process.enabled = true.

Soft edges (D7)

edge_fade fades the decal alpha to zero near the boundary of its projection box, hiding the rectangular cutoff. Range [0.0, 0.5]; 0.0 (default) = hard edge, 0.5 = fade covers the full half-extent. A value around 0.15-0.25 suits most decals.

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.

transform: [[f32; 4]; 4]

Model matrix: local [-0.5, 0.5]^3 -> world space.

texture_id: TextureId

Texture handle from resources.upload_texture().

blend_mode: DecalBlendMode

How the decal colour blends with the receiver. Default: Replace.

alpha: f32

Overall opacity multiplier applied on top of the texture alpha. Default: 1.0.

normal_texture_id: Option<TextureId>

Optional tangent-space normal map texture ID (D2). Default: None.

normal_blend_strength: f32

How strongly the decal normal map overrides the receiver normal. Range [0, 1]. Default: 1.0.

sort_key: i32

Draw order key. Lower = rendered first (underneath). Default: 0.

roughness: f32

Surface roughness in [0, 1]. 0 = mirror-smooth, 1 = fully matte. Default: 1.0.

roughness_texture_id: Option<TextureId>

Optional per-texel roughness map (single-channel, R component used). Default: None.

metallic: f32

Metallic factor in [0, 1]. 0 = dielectric, 1 = metal. Default: 0.0.

metallic_texture_id: Option<TextureId>

Optional per-texel metallic map (single-channel, R component used). Default: None.

uv_offset: [f32; 2]

UV offset applied before texture sampling. Modified by DecalAnimation. Default: [0, 0].

uv_scale: [f32; 2]

UV scale applied before texture sampling. Modified by DecalAnimation. Default: [1, 1].

emissive: f32

Emissive intensity multiplier. 0.0 = no emission. Default: 0.0.

emissive_texture_id: Option<TextureId>

Optional emissive texture. When None, the albedo colour is used as the emissive colour.

edge_fade: f32

Fraction of each local half-extent over which the alpha fades to zero at the box boundary. Range [0.0, 0.5]. Default: 0.0 (hard edge).

projection: DecalProjection

How the decal texture is projected onto the receiver surface. Default: Planar.

TriPlanar samples the texture from three axes and blends by the surface normal, avoiding UV stretching on corners. It costs three texture samples per pixel instead of one; use it only when the decal spans a non-planar or multi-face surface.

settings: ItemSettings

Visibility and opacity overrides. hidden skips the decal entirely; opacity multiplies the final alpha. unlit and wireframe are accepted but have no effect on decals. Set pick_id to make the decal pickable: pick() ray-tests the projection box and returns this id. When selected is set, an outline ring is traced around the decal’s footprint on the receiver surface. Default: all no-op, decal not pickable.

Trait Implementations

impl Clone for DecalItem

fn clone(&self) -> DecalItem

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Default for DecalItem

fn default() -> Self

Returns the “default value” for a type.