You've learned how to sample textures, and you've learned how to filter them to keep them sharp or smooth. Now we encounter a new problem: what happens when a mesh is bigger than its texture?

If you map a 1-meter texture onto a 10-meter wall, do you stretch it? Do you tile it like wallpaper? What happens at the edges?

These behaviors are controlled by Texture Wrapping Modes (also known as Address Modes). In this article, you'll master:

• The Address Mode Enum: Understanding Repeat, MirrorRepeat, ClampToEdge, and ClampToBorder.

• Sampler Configuration: How to change these settings in Bevy without reloading textures.

• UV Math: How to manipulate coordinates in WGSL to create scrolling, rotating, and scaling effects.

• Seamless Tiling: Techniques to make repeated textures look natural.

Understanding UV Coordinates and Wrapping

To understand wrapping, we have to look at the math of the Sampler.

When your Fragment Shader calls textureSample(texture, sampler, uv), the GPU looks at the UV coordinates.

• Standard UVs are between 0.0 and 1.0. (0,0) is usually the top-left (or bottom-left, depending on API), and (1,1) is the opposite corner.

• Out-of-Bounds UVs are anything less than 0.0 or greater than 1.0.

The Sampler's Job

The texture image is a finite grid of colored pixels (texels). It has no concept of "infinity." If you ask for the pixel at 1.5, the image says "I don't have that."

The Sampler is the translator. It takes your request for 1.5, applies a specific Addressing Rule, and translates it into a valid coordinate within the [0, 1] range before fetching the color.

If you don't define this rule, the behavior is undefined (though usually defaults to clamping). In Bevy, we define these rules explicitly to get the artistic control we need.

The Four Primary Wrapping Modes

There are four standard modes available in WebGPU (and thus Bevy). Let's look at how they handle a UV coordinate of 1.5 (50% past the edge).

1. Repeat Mode (Repeat)

This is the standard "tiling" mode. It ignores the integer part of the coordinate and keeps only the fractional part.

• Logic: Final UV = fract(Input UV)

• Result: 1.5 becomes 0.5. 2.5 becomes 0.5.

• Visual: The image repeats infinitely.

• Use Case: Floors, brick walls, grass, or any surface that needs to cover a large area with a small texture.

|   Texture   |   Texture   |   Texture   |
(0.0)-----(1.0)(0.0)-----(1.0)(0.0)-----(1.0)

2. Mirror Repeat Mode (MirrorRepeat)

Similar to Repeat, but it flips the image on every other integer step.

• Logic: Integers 0..1 are normal. 1..2 are flipped. 2..3 are normal.

• Result: Creates a seamless "ping-pong" effect.

• Use Case: Making non-seamless textures look continuous (e.g., generic noise, marble, or wood grain), though it can look like a kaleidoscope if the texture has distinct features.

|   Texture   |  erutxeT    |   Texture   |
(0.0)-----(1.0)(1.0)-----(0.0)(0.0)-----(1.0)

3. Clamp to Edge (ClampToEdge)

The sampler simply refuses to go past 0.0 or 1.0.

• Logic: Final UV = clamp(Input UV, 0.0, 1.0)

• Result: 1.5 becomes 1.0.

• Visual: The pixels at the very edge of the image are stretched infinitely in that direction.

• Use Case:

  • UI Elements: Prevents a button icon from tiling if the quad is slightly too big.

  • Skyboxes/Panoramas: Ensures the edges don't bleed into the opposite side.

  • Texture Atlases: Vital for preventing neighboring sprites from bleeding into the current one.

|   Texture   |
>>>>>>>>>>>|             |<<<<<<<<<<<<<
Stretched  (0.0)-----(1.0)  Stretched

4. Clamp to Border (ClampToBorder)

If the UV is out of bounds, return a specific "border color" instead of sampling the texture.

• Logic: if (UV < 0 || UV > 1) return BorderColor;

• Result: The texture appears once, surrounded by the border color.

• Limit: In Bevy (and WebGPU), the border color is not fully customizable in the high-level API due to hardware constraints. It typically defaults to Transparent Black (0,0,0,0).

• Use Case: Decals that shouldn't repeat, or debugging to see exactly where your UVs are going out of bounds.

Technical Deep Dive

Configuring Samplers in Bevy

In Bevy, the wrapping mode is part of the ImageSampler. By default, Bevy imports textures with ClampToEdge (or sometimes Repeat depending on the file type/loader settings), but explicit configuration is always safer.

You configure this using the ImageSamplerDescriptor struct. You can specify the mode for each axis independently:

• U (Horizontal): address_mode_u

• V (Vertical): address_mode_v

• W (Depth): address_mode_w (Only used for 3D textures, like volume data)

Here is how you configure a sampler in a Bevy system:

use bevy::image::{ImageAddressMode, ImageSampler, ImageSamplerDescriptor};

fn configure_tiling_texture(
    mut images: ResMut<Assets<Image>>,
    my_texture_handle: Res<MyTextureHandle>,
) {
    if let Some(image) = images.get_mut(&my_texture_handle.0) {
        image.sampler = ImageSampler::Descriptor(ImageSamplerDescriptor {
            // Repeat horizontally
            address_mode_u: ImageAddressMode::Repeat,
            // Clamp vertically (great for side-scrolling backgrounds)
            address_mode_v: ImageAddressMode::ClampToEdge,
            // Standard filtering settings
            mag_filter: bevy::image::ImageFilterMode::Linear,
            min_filter: bevy::image::ImageFilterMode::Linear,
            ..default()
        });
    }
}

Note: Modifying the sampler on an existing image asset triggers an update on the GPU automatically. You don't need to re-upload the texture data.

UV Manipulation in WGSL

While the Sampler handles the rules for out-of-bounds UVs, you often need to push the UVs out of bounds intentionally to create effects. This is done inside the Fragment Shader.

1. Tiling (Scaling)

To repeat a texture, you multiply the UV coordinates.

• Math: uv * tiling_factor

• Why: If UV goes from 0 to 1, multiplying by 4.0 makes it go from 0 to 4. The Sampler then wraps this 4 times.

let tiling = vec2<f32>(4.0, 4.0); // Repeat 4x4 times
let tiled_uv = in.uv * tiling;
let color = textureSample(my_texture, my_sampler, tiled_uv);

2. Scrolling (Offset)

To animate a texture (like a conveyor belt or flowing water), you add values to the UVs over time.

// 'time' is a uniform passed from Rust
let scroll_speed = vec2<f32>(0.5, 0.0); 
let scrolled_uv = in.uv + (scroll_speed * time);
let color = textureSample(my_texture, my_sampler, scrolled_uv);

3. Rotation

Rotating UVs is slightly trickier because you need to rotate around a specific pivot point (usually the center, 0.5, 0.5).

fn rotate_uv(uv: vec2<f32>, rotation: f32) -> vec2<f32> {
    let pivot = vec2<f32>(0.5, 0.5);
    let s = sin(rotation);
    let c = cos(rotation);
    
    // 1. Move UV so pivot is at (0,0)
    let uv_centered = uv - pivot;
    
    // 2. Rotate
    let rotated = vec2<f32>(
        uv_centered.x * c - uv_centered.y * s,
        uv_centered.x * s + uv_centered.y * c
    );
    
    // 3. Move back
    return rotated + pivot;
}

Common Pitfalls

1. Non-Seamless Textures: If you use Repeat on a photograph or a texture with distinct edges, you will see hard lines where the tiles meet. MirrorRepeat is a quick hack to hide this, but the best solution is to author textures that are specifically "tileable" (left edge matches right edge).

2. Texture Bleeding (Atlas): If you use a Texture Atlas (spritesheet), you usually want ClampToEdge. If you use Repeat, your character's head might start displaying their feet from the frame below!

3. UI Stretching: A common bug in UI rendering is setting ClampToEdge on a 9-patch image but getting the UVs wrong, resulting in the edge pixels stretching all the way across the button.

Advanced Techniques & Considerations

Before we jump into the demo, let's cover a few advanced topics that separate basic texture usage from professional shader work.

1. The Art of Seamless Textures

Using Repeat mode reveals the truth about your texture: is it seamless?

A seamless texture is one where the left edge perfectly matches the right edge, and the top matches the bottom. If they don't match, you get visible "seams" - hard lines that ruin the illusion of a continuous surface.

If you don't have a seamless texture, you have two options:

1. The "Lazy" Fix: Switch to MirrorRepeat. By flipping the texture, the edges always meet identical pixels. It eliminates hard lines but can create strange "Rorschach test" patterns.

2. The "Pro" Fix: Edit the texture. In tools like Photoshop or GIMP, you "offset" the image by 50% horizontally and vertically so the edges move to the center. You then paint over the visible seams in the center. When you offset it back, the edges are now perfect.

2. Polar Coordinates

One of the coolest uses of wrapping modes is converting Cartesian coordinates (x, y) to Polar coordinates (angle, radius). This allows you to wrap a rectangular texture into a circle or a spiral.

fn cartesian_to_polar(uv: vec2<f32>) -> vec2<f32> {
    // 1. Center the UVs from [0,1] to [-0.5, 0.5]
    let centered = uv - 0.5;
    
    // 2. Calculate Angle and Radius
    let radius = length(centered) * 2.0; // Scale so edge is at 1.0
    let angle = atan2(centered.y, centered.x);
    
    // 3. Normalize Angle from [-PI, PI] to [0, 1]
    let normalized_angle = (angle / (2.0 * 3.14159)) + 0.5;
    
    return vec2<f32>(normalized_angle, radius);
}

If you use Repeat mode with this function:

• The texture wraps around the center point endlessly.

• The "seam" where 0 and 1 meet becomes invisible (if the texture is seamless horizontally).

3. Hardware Reality: The "Border Color" Limit

You might wonder: "Can I set the border color to Hot Pink for debugging?"

In older graphics APIs (OpenGL), yes. In modern WebGPU (and thus Bevy's abstraction), no. Hardware support for arbitrary border colors is inconsistent across platforms (especially mobile).

In Bevy 0.16, ClampToBorder typically defaults to Transparent Black (0, 0, 0, 0). If you need a specific colored border for a gameplay mechanic (e.g., a red warning zone), you usually have to implement that logic manually in the shader code, as we will do in our demo.

4. Performance

Does Repeat cost more than Clamp?

• Generally, no. Texture wrapping is handled by dedicated hardware units on the GPU. The cost difference is negligible.

• Cache Locality: The only minor performance hit comes from "Dependent Texture Reads." If your UV math gets incredibly complex (randomly jumping from UV 0.1 to 900.5), the GPU's texture cache becomes ineffective because it can't predict which pixels to load next. For standard tiling and scrolling, this is never an issue.

Complete Example

We are going to build a Wrapping Mode Playground. This interactive demo lets you cycle through different wrapping modes in real-time while animating UVs (scrolling, rotating, and scaling). It perfectly illustrates how the sampler behaves when UVs go beyond the standard 0.0 to 1.0 range.

Our Goal

1. Interactive Sampler: Change the ImageAddressMode of a texture dynamically using keyboard input.

2. UV Animation: Implement tiling, scrolling, and rotation in WGSL to force UVs out of bounds.

3. Visual Debugging: Create a shader that can highlight exactly where UVs cross the texture boundaries.

The Shader (assets/shaders/d04_03_wrapping_demo.wgsl)

This shader accepts a set of uniforms to transform the UV coordinates. It includes a helper function rotate_uv to handle rotation around the center. It also includes a debug feature: when enabled, it mixes the texture color with a raw UV visualization so you can see the coordinate grid.

#import bevy_pbr::mesh_functions
#import bevy_pbr::view_transformations::position_world_to_clip

struct WrappingMaterial {
    tiling: vec2<f32>,
    offset: vec2<f32>,
    scroll_speed: vec2<f32>,
    time: f32,
    rotation: f32,
    blend_factor: f32,
    _padding: f32,
}

@group(2) @binding(0)
var texture: texture_2d<f32>;

@group(2) @binding(1)
var texture_sampler: sampler;

@group(2) @binding(2)
var<uniform> material: WrappingMaterial;

struct VertexInput {
    @builtin(instance_index) instance_index: u32,
    @location(0) position: vec3<f32>,
    @location(1) normal: vec3<f32>,
    @location(2) uv: vec2<f32>,
}

struct VertexOutput {
    @builtin(position) clip_position: vec4<f32>,
    @location(0) world_position: vec3<f32>,
    @location(1) world_normal: vec3<f32>,
    @location(2) uv: vec2<f32>,
}

@vertex
fn vertex(in: VertexInput) -> VertexOutput {
    var out: VertexOutput;

    let model = mesh_functions::get_world_from_local(in.instance_index);
    let world_position = mesh_functions::mesh_position_local_to_world(
        model,
        vec4<f32>(in.position, 1.0)
    );

    out.clip_position = position_world_to_clip(world_position.xyz);
    out.world_position = world_position.xyz;
    out.world_normal = mesh_functions::mesh_normal_local_to_world(
        in.normal,
        in.instance_index
    );
    out.uv = in.uv;

    return out;
}

// Rotate UV coordinates around center (0.5, 0.5)
fn rotate_uv(uv: vec2<f32>, angle: f32) -> vec2<f32> {
    let center = vec2<f32>(0.5, 0.5);
    let uv_centered = uv - center;

    let cos_a = cos(angle);
    let sin_a = sin(angle);

    let rotated = vec2<f32>(
        uv_centered.x * cos_a - uv_centered.y * sin_a,
        uv_centered.x * sin_a + uv_centered.y * cos_a
    );

    return rotated + center;
}

// Visualize UV coordinates as color (Red = U, Green = V)
fn uv_debug_color(uv: vec2<f32>) -> vec3<f32> {
    return vec3<f32>(fract(uv.x), fract(uv.y), 0.0);
}

// Check if UV is out of bounds
fn is_out_of_bounds(uv: vec2<f32>) -> bool {
    return uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0;
}

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    // 1. Start with base UV
    var uv = in.uv;

    // 2. Apply transformations
    uv = rotate_uv(uv, material.rotation);
    uv = uv + material.offset;
    uv = uv + material.scroll_speed * material.time;
    uv = uv * material.tiling;

    // 3. Sample texture
    // The wrapping mode (Repeat, Clamp, etc.) is handled here by the sampler
    var texture_color = textureSample(texture, texture_sampler, uv);

    // 4. Optional: Debug Visualization
    // Mix the texture with the UV grid based on blend_factor
    let debug_color = vec4<f32>(uv_debug_color(uv), 1.0);
    let color = mix(texture_color, debug_color, material.blend_factor);

    // Highlight out-of-bounds regions in Red when in Debug mode
    // This helps visualize where the border actually is.
    if (material.blend_factor > 0.5 && is_out_of_bounds(uv)) {
        return vec4<f32>(color.rgb + vec3<f32>(0.3, 0.0, 0.0), color.a);
    }

    return color;
}

The Rust Material (src/materials/d04_03_wrapping_demo.rs)

This material struct holds the texture handle and the uniform data. We use the AsBindGroup derive macro to automatically generate the binding layout for Bevy. Note that we define a separate WrappingMaterialUniforms struct that implements ShaderType to ensure our data is strictly aligned for the GPU.

use bevy::prelude::*;
use bevy::render::render_resource::{AsBindGroup, ShaderRef};

mod uniforms {
    #![allow(dead_code)]

    use bevy::prelude::*;
    use bevy::render::render_resource::ShaderType;

    #[derive(ShaderType, Debug, Clone, Copy)]
    pub struct WrappingMaterial {
        pub tiling: Vec2,
        pub offset: Vec2,
        pub scroll_speed: Vec2,
        pub time: f32,
        pub rotation: f32,
        pub blend_factor: f32, // 0.0 = texture only, 1.0 = UV debug
        pub _padding: f32,
    }

    impl Default for WrappingMaterial {
        fn default() -> Self {
            Self {
                tiling: Vec2::ONE,
                offset: Vec2::ZERO,
                scroll_speed: Vec2::ZERO,
                time: 0.0,
                rotation: 0.0,
                blend_factor: 0.0,
                _padding: 0.0,
            }
        }
    }
}

pub use uniforms::WrappingMaterial as WrappingMaterialUniforms;

#[derive(Asset, TypePath, AsBindGroup, Debug, Clone)]
pub struct WrappingMaterial {
    #[texture(0)]
    #[sampler(1)]
    pub texture: Handle<Image>,

    #[uniform(2)]
    pub uniforms: WrappingMaterialUniforms,
}

impl Material for WrappingMaterial {
    fn vertex_shader() -> ShaderRef {
        "shaders/d04_03_wrapping_demo.wgsl".into()
    }

    fn fragment_shader() -> ShaderRef {
        "shaders/d04_03_wrapping_demo.wgsl".into()
    }
}

Don't forget to add it to src/materials/mod.rs:

pub mod d04_03_wrapping_demo;

The Demo Module (src/demos/d04_03_wrapping_demo.rs)

This module handles the logic. It spawns a procedurally generated checkerboard texture (easier to see wrapping seams than a photo). The handle_input system listens for key presses and modifies the Image asset's sampler field directly. This updates the GPU resource without needing to reload the texture.

use crate::materials::d04_03_wrapping_demo::{WrappingMaterial, WrappingMaterialUniforms};
use bevy::image::{ImageAddressMode, ImageFilterMode, ImageSampler, ImageSamplerDescriptor};
use bevy::prelude::*;
use bevy::render::render_asset::RenderAssetUsages;
use bevy::render::render_resource::{Extent3d, TextureDimension, TextureFormat};
use std::f32::consts::PI;

#[derive(Resource)]
struct DemoState {
    current_mode: WrapMode,
    scrolling_enabled: bool,
    rotation_enabled: bool,
    debug_mode: bool,
}

#[derive(Debug, Clone, Copy, PartialEq)]
enum WrapMode {
    Repeat,
    ClampToEdge,
    MirrorRepeat,
    ClampToBorder,
}

impl WrapMode {
    fn next(&self) -> Self {
        match self {
            WrapMode::Repeat => WrapMode::ClampToEdge,
            WrapMode::ClampToEdge => WrapMode::MirrorRepeat,
            WrapMode::MirrorRepeat => WrapMode::ClampToBorder,
            WrapMode::ClampToBorder => WrapMode::Repeat,
        }
    }

    fn to_address_mode(&self) -> ImageAddressMode {
        match self {
            WrapMode::Repeat => ImageAddressMode::Repeat,
            WrapMode::ClampToEdge => ImageAddressMode::ClampToEdge,
            WrapMode::MirrorRepeat => ImageAddressMode::MirrorRepeat,
            WrapMode::ClampToBorder => ImageAddressMode::ClampToBorder,
        }
    }

    fn name(&self) -> &str {
        match self {
            WrapMode::Repeat => "Repeat",
            WrapMode::ClampToEdge => "Clamp to Edge",
            WrapMode::MirrorRepeat => "Mirror Repeat",
            WrapMode::ClampToBorder => "Clamp to Border",
        }
    }
}

pub fn run() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(MaterialPlugin::<WrappingMaterial>::default())
        .insert_resource(DemoState {
            current_mode: WrapMode::Repeat,
            scrolling_enabled: true,
            rotation_enabled: false,
            debug_mode: false,
        })
        .add_systems(Startup, setup)
        .add_systems(Update, (handle_input, update_materials, update_ui))
        .run();
}

fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<WrappingMaterial>>,
    mut images: ResMut<Assets<Image>>,
) {
    let texture_handle = create_checkerboard_texture(&mut images);

    let material_handle = materials.add(WrappingMaterial {
        texture: texture_handle,
        uniforms: WrappingMaterialUniforms {
            tiling: Vec2::new(3.0, 3.0),
            scroll_speed: Vec2::new(0.2, 0.1),
            ..Default::default()
        },
    });

    commands.spawn((
        Mesh3d(meshes.add(Plane3d::default().mesh().size(10.0, 10.0))),
        MeshMaterial3d(material_handle),
        Transform::from_rotation(Quat::from_rotation_x(PI / 2.0)),
    ));

    commands.spawn((
        DirectionalLight {
            illuminance: 10_000.0,
            shadows_enabled: false,
            ..default()
        },
        Transform::from_rotation(Quat::from_euler(EulerRot::XYZ, -PI / 4.0, PI / 4.0, 0.0)),
    ));

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

    commands.spawn((
        Text::new(""),
        Node {
            position_type: PositionType::Absolute,
            top: Val::Px(10.0),
            left: Val::Px(10.0),
            padding: UiRect::all(Val::Px(10.0)),
            ..default()
        },
        TextColor(Color::WHITE),
        BackgroundColor(Color::srgba(0.0, 0.0, 0.0, 0.8)),
    ));
}

fn create_checkerboard_texture(images: &mut ResMut<Assets<Image>>) -> Handle<Image> {
    let size = 64;
    let mut data = vec![0u8; (size * size * 4) as usize];

    for y in 0..size {
        for x in 0..size {
            let checker = ((x / 8) + (y / 8)) % 2;
            let base_idx = ((y * size + x) * 4) as usize;
            let val = if checker == 0 { 255 } else { 50 };
            data[base_idx] = val;
            data[base_idx + 1] = val;
            data[base_idx + 2] = val;
            data[base_idx + 3] = 255;
        }
    }

    let mut image = Image::new_fill(
        Extent3d {
            width: size,
            height: size,
            depth_or_array_layers: 1,
        },
        TextureDimension::D2,
        &data,
        TextureFormat::Rgba8UnormSrgb,
        RenderAssetUsages::default(),
    );

    image.sampler = ImageSampler::Descriptor(ImageSamplerDescriptor {
        address_mode_u: ImageAddressMode::Repeat,
        address_mode_v: ImageAddressMode::Repeat,
        mag_filter: ImageFilterMode::Nearest,
        min_filter: ImageFilterMode::Nearest,
        ..Default::default()
    });

    images.add(image)
}

fn handle_input(
    keyboard: Res<ButtonInput<KeyCode>>,
    mut state: ResMut<DemoState>,
    mut images: ResMut<Assets<Image>>,
    mut materials: ResMut<Assets<WrappingMaterial>>,
) {
    if keyboard.just_pressed(KeyCode::Space) {
        state.current_mode = state.current_mode.next();
        println!("Switching to mode: {:?}", state.current_mode);

        // LOGIC FIX:
        // When using Clamp, we want to center the texture on the quad to see the edges.
        // Math: UV range [0, 1].
        // Offset -0.25 -> [-0.25, 0.75].
        // Scale 2.0 -> [-0.5, 1.5].
        // Result: Texture (0-1) is centered, surrounded by out-of-bounds UVs.

        let (new_tiling, new_offset, enable_scroll) = match state.current_mode {
            WrapMode::ClampToEdge | WrapMode::ClampToBorder => {
                (Vec2::splat(2.0), Vec2::splat(-0.25), false)
            }
            _ => (Vec2::splat(3.0), Vec2::ZERO, true),
        };

        state.scrolling_enabled = enable_scroll;
        state.rotation_enabled = enable_scroll; // Also disable rotation for clarity

        // Apply settings to all materials
        for (_, mat) in materials.iter_mut() {
            mat.uniforms.tiling = new_tiling;
            mat.uniforms.offset = new_offset;
        }

        // Apply sampler settings
        for (_, material) in materials.iter() {
            if let Some(image) = images.get_mut(&material.texture) {
                let mode = state.current_mode.to_address_mode();
                image.sampler = ImageSampler::Descriptor(ImageSamplerDescriptor {
                    address_mode_u: mode,
                    address_mode_v: mode,
                    mag_filter: ImageFilterMode::Nearest,
                    min_filter: ImageFilterMode::Nearest,
                    ..Default::default()
                });
            }
        }
    }

    if keyboard.just_pressed(KeyCode::KeyS) {
        state.scrolling_enabled = !state.scrolling_enabled;
    }
    if keyboard.just_pressed(KeyCode::KeyR) {
        state.rotation_enabled = !state.rotation_enabled;
    }
    if keyboard.just_pressed(KeyCode::KeyD) {
        state.debug_mode = !state.debug_mode;
    }
}

fn update_materials(
    time: Res<Time>,
    state: Res<DemoState>,
    keyboard: Res<ButtonInput<KeyCode>>,
    mut materials: ResMut<Assets<WrappingMaterial>>,
) {
    for (_, material) in materials.iter_mut() {
        material.uniforms.time = time.elapsed_secs();

        material.uniforms.rotation = if state.rotation_enabled {
            time.elapsed_secs() * 0.3
        } else {
            0.0
        };

        material.uniforms.scroll_speed = if state.scrolling_enabled {
            Vec2::new(0.2, 0.1)
        } else {
            Vec2::ZERO
        };

        material.uniforms.blend_factor = if state.debug_mode { 0.5 } else { 0.0 };

        if keyboard.pressed(KeyCode::Equal) {
            material.uniforms.tiling *= 1.02;
        }
        if keyboard.pressed(KeyCode::Minus) {
            material.uniforms.tiling *= 0.98;
            material.uniforms.tiling = material.uniforms.tiling.max(Vec2::splat(0.1));
        }
    }
}

fn update_ui(state: Res<DemoState>, mut query: Query<&mut Text>) {
    for mut text in &mut query {
        **text = format!(
            "TEXTURE WRAPPING MODES\n\
             [Space] Mode: {}\n\
             [S] Scroll: {}\n\
             [R] Rotate: {}\n\
             [D] Debug UV: {}\n\
             [+/-] Zoom Tiling",
            state.current_mode.name(),
            if state.scrolling_enabled { "ON" } else { "OFF" },
            if state.rotation_enabled { "ON" } else { "OFF" },
            if state.debug_mode { "ON" } else { "OFF" },
        );
    }
}

Don't forget to add it to src/demos/mod.rs:

pub mod d04_03_wrapping_demo;

And register it in src/main.rs:

Demo {
    number: "4.3",
    title: "Texture Wrapping Modes",
    run: demos::d04_03_wrapping_demo::run,
},

Running the Demo

This demo allows you to see exactly how each wrapping mode behaves when the UV coordinates exceed the 0-1 range.

Controls

What You're Seeing

1. Repeat: The checkerboard pattern continues infinitely.

2. ClampToEdge: The edge pixels (black or white squares) are stretched infinitely outwards.

3. MirrorRepeat: The pattern reverses at every boundary, creating a seamless (though kaleidoscopic) look.

4. ClampToBorder: The texture disappears outside the center, replaced by the border color (transparent black).

   • Note: Press D in this mode to see the red debug overlay, which proves that the UVs are indeed out of bounds!

Key Takeaways

1. Samplers Control Edges: The texture image ends at 1.0. The Sampler decides what happens after that.

2. Explicit Configuration: Always configure your ImageSamplerDescriptor explicitly for the effect you want (e.g., Clamp for UI, Repeat for floors).

3. UVs are Flexible: You can multiply (tile), add (scroll), and rotate UVs in the shader to create dynamic effects without changing the mesh geometry.

4. Mirroring Hides Seams: MirrorRepeat is a useful tool for procedurally texturing surfaces with non-seamless noise textures.

What's Next?

We've mastered single textures - sampling, filtering, and wrapping. But most realistic materials aren't made of just one image. A brick wall has color, but it also has bumpiness (normal maps), shininess (roughness maps), and ambient shadows (AO maps).

In the next article, we will combine multiple textures into a single shader to create a complete PBR Material.

Next up: 4.4 - Multi-Texture Materials

Quick Reference

Wrapping Modes Cheat Sheet

Bevy Configuration

// Standard Repeating Sampler
ImageSampler::Descriptor(ImageSamplerDescriptor {
    address_mode_u: ImageAddressMode::Repeat,
    address_mode_v: ImageAddressMode::Repeat,
    // ... filtering settings
    ..default()
})

You've learned how to sample textures in shaders using UV coordinates. Now comes a critical question: how exactly does the GPU calculate the color between pixels?

When you render a 3D wall, it's rare that one pixel on your screen aligns perfectly with one "pixel" (texel) on the texture image. The texture might be stretched across a huge wall, or shrunk onto a tiny object in the distance.

This is where texture filtering comes in. The choices you make here determine whether your game looks like a crisp retro arcade game, a blurry N64 title, or a modern high-end render.

In this article, you'll understand:

• Texels vs. Pixels: The fundamental disconnect between image data and screen space.

• Filtering Modes: The difference between Nearest, Linear, and Anisotropic filtering.

• Mipmapping: How pre-calculating smaller versions of textures solves shimmering and aliasing.

• The Sampler Resource: How to configure these settings in Bevy and WGSL.

• Performance Trade-offs: Why "better" filtering isn't always free.

The Texture Sampling Problem

To understand filtering, we must distinguish between two types of "pixels":

1. Pixels: The physical dots of light on your monitor.

2. Texels (Texture Elements): The color data points stored in your texture image.

When the GPU runs your fragment shader, it has to assign a color to a screen pixel. It calculates a UV coordinate (e.g., 0.501, 0.501) and asks the texture for data.

There is almost never a 1:1 relationship.

• Magnification: The texture is small, but the object is close. One texel covers many screen pixels. The GPU needs to fill the space between texels.

• Minification: The texture is large, but the object is far away. One screen pixel covers many texels. The GPU needs to summarize multiple data points into one color.

• Anisotropy: The surface is angled (like a floor). One screen pixel covers a trapezoid shape of texels - long in one direction, short in the other.

The Sampler is the GPU component that answers these questions based on the rules you provide.

Point Filtering (Nearest Neighbor)

The simplest rule is: "Just give me the single texel closest to my UV coordinate."

How It Works

Imagine a grid of colors. If your UV coordinate falls at (1.1, 1.1), the GPU rounds down to (1, 1) and returns that exact color. It ignores the fact that you are slightly closer to 1.2.

When To Use It

In Bevy, this is called ImageFilterMode::Nearest.

• ✓ Pixel Art: Essential for keeping sprites crisp.

• ✓ Minecraft-style Voxel Games: Preserves the blocky aesthetic.

• ✓ Data Textures: If your texture stores non-color data (like object IDs), you never want to blend values (e.g., blending ID 1 and ID 5 to get ID 3 is wrong).

Visual Result

Up close, the texture looks blocky. Each texel appears as a distinct square.

Linear Filtering (Bilinear)

The standard rule for 3D graphics is: "Look at the four closest texels and blend them together."

How It Works

If your UV coordinate is (1.5, 1.5), the GPU grabs the texels at (1,1), (2,1), (1,2), and (2,2). It then performs a weighted average (Linear Interpolation, or "Lerp") based on how close the coordinate is to each center.

When To Use It

In Bevy, this is ImageFilterMode::Linear.

• ✓ Realistic 3D: Almost everything in a standard game (skin, rocks, metal) uses this.

• ✓ UI Elements: Ensures smooth edges on text and icons.

Visual Result

Up close, the texture looks smooth and blurry. You can't distinguish individual texels.

Mipmapping: Solving the Distance Problem

Linear filtering works great when the texture is close (magnification). It fails miserably when the texture is far away (minification).

Imagine a high-resolution brick wall texture (1024x1024) rendered on an object that is only 10 pixels wide on screen. Each screen pixel effectively covers 100 texels. The GPU can't sample all 100 texels for every pixel - that would be incredibly slow. Instead, it just samples 4 random ones (linear filtering).

As the camera moves, the "4 random pixels" picked will change drastically, causing the surface to sparkle, shimmer, and produce jagged patterns called Moiré patterns.

The Solution: Mipmaps

Mipmaps (from the Latin multum in parvo, "much in little") are a sequence of progressively smaller versions of the main image.

• Level 0: Original (1024x1024)

• Level 1: 512x512

• Level 2: 256x256

• ...

• Level N: 1x1

When rendering, the GPU calculates how "dense" the UVs are.

• If the object is close, it reads from Level 0.

• If the object is far, it reads from Level 3 or 4.

This effectively pre-blends the distant pixels, eliminating shimmering and improving performance (because the GPU reads smaller chunks of memory).

Trilinear Filtering

When an object moves from a distance requiring Mip Level 1 to a distance requiring Mip Level 2, you might see a visible "pop" or line where the sharpness changes.

Trilinear Filtering solves this by blending between the mip levels. It samples Level 1 (bilinear) and Level 2 (bilinear), then blends those two results together.

In Bevy, you control this with the mipmap_filter field in the sampler descriptor.

Anisotropic Filtering

Standard Linear/Trilinear filtering assumes the "footprint" of a pixel is a square. But for a floor stretching into the distance, a screen pixel corresponds to a long, thin trapezoid of texels.

If you use standard filtering on a floor, it will look excessively blurry in the distance because the GPU is sampling a square region that includes data "from the sides" that shouldn't be there, while missing data "from the back" that should be included.

Anisotropic Filtering takes multiple samples along the angle of the surface to recover detail on oblique angles. Bevy exposes this via anisotropy_clamp (typically set to 16 for high quality).

Configuring Samplers in Bevy

In Bevy, the texture data and the "rules for reading it" (the Sampler) are bundled together in the Image asset. By default, Bevy sets up images with Linear filtering and Repeat address mode, which is good for general 3D use.

To change this, you modify the sampler field of the Image asset using an ImageSamplerDescriptor.

The ImageSamplerDescriptor Struct

This struct is your control panel for texture quality.

use bevy::image::{ImageSampler, ImageSamplerDescriptor, ImageFilterMode};

// 1. Pixel Art / Retro Style
// Sharp pixels, no blending
let pixel_art_sampler = ImageSampler::Descriptor(ImageSamplerDescriptor {
    mag_filter: ImageFilterMode::Nearest, // When close (magnified)
    min_filter: ImageFilterMode::Nearest, // When far (minified)
    mipmap_filter: ImageFilterMode::Nearest, // Sharp transitions between mips
    ..default()
});

// 2. Standard 3D (Trilinear)
// Smooth blending everywhere
let standard_sampler = ImageSampler::Descriptor(ImageSamplerDescriptor {
    mag_filter: ImageFilterMode::Linear,
    min_filter: ImageFilterMode::Linear,
    mipmap_filter: ImageFilterMode::Linear, // Smooth transitions between mips
    ..default()
});

// 3. High Quality Ground (Anisotropic)
// Crisp details at oblique angles
let ground_sampler = ImageSampler::Descriptor(ImageSamplerDescriptor {
    // Anisotropy is an integer (usually 1, 2, 4, 8, or 16)
    anisotropy_clamp: 16, 
    
    // We still use Linear filtering for the base colors
    mag_filter: ImageFilterMode::Linear,
    min_filter: ImageFilterMode::Linear,
    mipmap_filter: ImageFilterMode::Linear,
    ..default()
});

Applying Samplers in Systems

Since textures are assets, you typically modify them in a system after they have loaded, or configure them via ImageLoaderSettings if you are loading them manually.

For the purpose of our custom shaders, here is how you might configure a texture in a startup system:

fn configure_textures(
    mut images: ResMut<Assets<Image>>,
    my_texture_handle: Res<MyTextureHandle>, // Assuming you stored the handle
) {
    if let Some(image) = images.get_mut(&my_texture_handle.0) {
        image.sampler = ImageSampler::Descriptor(ImageSamplerDescriptor {
            mag_filter: ImageFilterMode::Nearest,
            min_filter: ImageFilterMode::Nearest,
            mipmap_filter: ImageFilterMode::Nearest,
            ..default()
        });
    }
}

Note: If you change a sampler on an existing image, Bevy automatically updates the GPU resource for you.

Performance vs. Quality

You might be tempted to just set anisotropy_clamp: 16 and Linear on everything. Why not?

The Cost of Filtering

Every time your shader calls textureSample(), the GPU performs memory lookups.

1. Nearest (Point): 1 memory fetch. The GPU grabs exactly one texel. This is the fastest possible operation.

2. Bilinear: 4 memory fetches. The GPU grabs the four surrounding texels and blends them.

3. Trilinear: 8 memory fetches. The GPU grabs 4 texels from Mip Level X and 4 from Mip Level X+1.

4. Anisotropic (16x): Up to 128 memory fetches (in theory, though hardware is highly optimized). It takes many samples along the viewing angle.

Hardware Reality

Modern GPUs (even on mobile phones) are incredibly optimized for Bilinear and Trilinear filtering. The hardware has dedicated circuits ("Texture Units") to do this math for free. You will rarely see a frame rate drop going from Bilinear to Trilinear.

However, Anisotropic filtering hits memory bandwidth. Because it fetches so much data per pixel, using 16x Anisotropic on every surface can slow down games on lower-end hardware or mobile devices.

Recommended Settings

Common Pitfall: Filtering at the Edge

Understanding filtering explains one of the most annoying bugs in graphics programming: Texture Bleeding.

Imagine you have a texture atlas (a sprite sheet) where multiple images are packed next to each other. You want to display just one sprite. You calculate your UVs perfectly. But on screen, you see a faint line of color from the neighboring sprite at the edge of your character.

Why does this happen?

It's Linear filtering's fault.

When the GPU renders a pixel at the very edge of your sprite (e.g., UV 0.25), Linear filtering asks for the "neighboring" texels to blend with.

• If your UV is 0.25, the filter might look at 0.249 and 0.251.

• If 0.251 falls inside the next sprite in the atlas, the GPU happily blends that color in.

The Fixes:

1. Padding: Add empty (transparent) space between sprites in your atlas.

2. Point Filtering: Switch to Nearest filtering. Since it doesn't blend, it never looks at the neighbor.

3. Address Modes: If it's a single texture (not an atlas), setting AddressMode::ClampToEdge ensures that when the filter hits the edge (1.0), it doesn't try to wrap around to 0.0 to find a blending partner.

Advanced: Manual Mip Control

Usually, you want the GPU to calculate mip levels automatically. But sometimes, you need to take control.

1. Fine-Tuning Sharpness (LOD Bias)

Sometimes, the GPU plays it too safe. To prevent aliasing, it might switch to a lower-resolution mipmap too early, causing a texture to look blurry when viewed at an angle.

You can force the GPU to "upscale" slightly - using a higher-resolution mip level than it thinks it needs - by applying a LOD Bias.

// WGSL
// textureSampleBias(texture, sampler, uv, bias)

// A negative bias forces a sharper (higher res) mip level.
// -1.0 means "use one mip level higher than calculated"
let crisp_color = textureSampleBias(my_texture, my_sampler, in.uv, -1.0);

• Negative Bias (-0.5 to -1.0): Makes textures sharper/crisper. Great for detailed ground textures, but can introduce shimmering (aliasing) if pushed too far.

• Positive Bias (+1.0): Makes textures softer. Useful for reducing noise on very high-frequency patterns.

2. Reading Textures in the Vertex Shader

In 4.1, we mentioned that textureSample() is forbidden in Vertex Shaders. Now you know why.

textureSample() relies on derivatives (calculating how UVs change between neighboring pixels) to pick the right mip level.

• Fragment Shader: Runs on pixels in groups (quads), so it knows about neighbors.

• Vertex Shader: Runs on individual vertices. It has no idea how far away the camera is or how dense the pixels are.

Therefore, the GPU cannot calculate the mip level automatically. If you want to read a texture in a vertex shader (e.g., a heightmap for terrain displacement), you must specify the level explicitly:

@vertex
fn vertex(in: VertexInput) -> VertexOutput {
    // ... setup ...
    
    // Explicitly read from Mip Level 0 (Full resolution)
    // Note: We typically use a dedicated sampler for this, or a shared one.
    let height = textureSampleLevel(height_map, my_sampler, in.uv, 0.0).r;
    
    // Displace vertex
    let new_pos = in.position + vec3(0.0, height * 10.0, 0.0);
    
    // ... output ...
}

Complete Example: The Filtering Comparator

We are going to build a tool that lets you toggle between different filtering modes in real-time. To make this comparison valid, we need a special texture: one that has high-frequency details (prone to aliasing) and a complete chain of Mipmaps.

Since we are generating the texture procedurally, we will also write a helper to generate the mipmaps on the CPU. This ensures that Trilinear and Anisotropic filtering have data to work with.

Our Goal

1. Procedural Texture: Generate a "torture test" pattern (checkerboards and concentric circles) with full mipmaps.

2. Custom Shader: A shader that can either sample the texture normally or visualize the calculated Mip Level.

3. Comparator UI: A system to hot-swap the Sampler configuration on the fly.

The Shader (assets/shaders/d04_02_filtering_comparison.wgsl)

This shader handles the sampling. Note the "Mip Level Visualization" mode (Mode 5), which uses the dpdx and dpdy derivatives to calculate exactly which mip level the GPU would select for a given pixel.

#import bevy_pbr::mesh_functions
#import bevy_pbr::view_transformations::position_world_to_clip

struct FilteringMaterial {
    display_mode: u32,
    base_color: vec4<f32>,
}

@group(2) @binding(0)
var<uniform> material: FilteringMaterial;

@group(2) @binding(1)
var base_texture: texture_2d<f32>;

@group(2) @binding(2)
var base_sampler: sampler;

struct VertexInput {
    @builtin(instance_index) instance_index: u32,
    @location(0) position: vec3<f32>,
    @location(1) normal: vec3<f32>,
    @location(2) uv: vec2<f32>,
}

struct VertexOutput {
    @builtin(position) clip_position: vec4<f32>,
    @location(0) world_position: vec3<f32>,
    @location(1) world_normal: vec3<f32>,
    @location(2) uv: vec2<f32>,
}

@vertex
fn vertex(in: VertexInput) -> VertexOutput {
    var out: VertexOutput;

    let model = mesh_functions::get_world_from_local(in.instance_index);
    let world_position = mesh_functions::mesh_position_local_to_world(
        model,
        vec4<f32>(in.position, 1.0)
    );

    // Pass data to fragment shader
    out.clip_position = position_world_to_clip(world_position.xyz);
    out.world_position = world_position.xyz;
    out.world_normal = mesh_functions::mesh_normal_local_to_world(in.normal, in.instance_index);
    out.uv = in.uv;

    return out;
}

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    var final_color: vec4<f32>;

    // MODE 5: Mip Level Visualization
    if (material.display_mode == 5u) {
        // Get texture dimensions to calculate accurate derivatives
        let dims = vec2<f32>(textureDimensions(base_texture));

        // Calculate the rate of change of UVs relative to texture size
        let dx = dpdx(in.uv * dims);
        let dy = dpdy(in.uv * dims);

        // The max length of the derivative vector determines the mip level
        let delta_max_sq = max(dot(dx, dx), dot(dy, dy));
        let mip_level = 0.5 * log2(delta_max_sq);

        // Color code based on level: Red (0) -> Yellow -> Green -> Blue (High)
        let colors = array<vec3<f32>, 6>(
            vec3(1.0, 0.0, 0.0), // Level 0: Red
            vec3(1.0, 0.5, 0.0), // Level 1: Orange
            vec3(1.0, 1.0, 0.0), // Level 2: Yellow
            vec3(0.0, 1.0, 0.0), // Level 3: Green
            vec3(0.0, 1.0, 1.0), // Level 4: Cyan
            vec3(0.0, 0.0, 1.0)  // Level 5+: Blue
        );

        let idx = u32(clamp(mip_level, 0.0, 5.0));
        final_color = vec4<f32>(colors[idx], 1.0);
    }
    // STANDARD MODES (0-4)
    else {
        final_color = textureSample(base_texture, base_sampler, in.uv) * material.base_color;
    }

    // Apply simple directional lighting
    let N = normalize(in.world_normal);
    let L = normalize(vec3<f32>(1.0, 1.0, 0.5));
    let diffuse = max(dot(N, L), 0.0);
    let ambient = 0.2;

    return vec4<f32>(final_color.rgb * (diffuse + ambient), final_color.a);
}

The Rust Material (src/materials/d04_02_filtering_comparison.rs)

This file includes a helper function create_test_texture.

Why is this function so long?
When you load an image from disk (like a PNG), Bevy usually generates mipmaps for you. Since we are creating a texture procedurally (pixel by pixel), we must generate the mipmaps ourselves. We do this by repeatedly downscaling the image (averaging 4 pixels into 1) until we reach a 1x1 size.

Without this step, "Trilinear" filtering would look exactly like "Bilinear" because there would be no lower-resolution levels to blend with!

use bevy::prelude::*;
use bevy::render::render_asset::RenderAssetUsages;
use bevy::render::render_resource::{
    AsBindGroup, Extent3d, ShaderRef, TextureDimension, TextureFormat,
};

#[derive(Asset, TypePath, AsBindGroup, Debug, Clone)]
pub struct FilteringMaterial {
    #[uniform(0)]
    pub display_mode: u32,
    #[uniform(0)]
    pub base_color: LinearRgba,

    #[texture(1)]
    #[sampler(2)]
    pub texture: Handle<Image>,
}

impl Material for FilteringMaterial {
    fn fragment_shader() -> ShaderRef {
        "shaders/d04_02_filtering_comparison.wgsl".into()
    }
}

/// Generates a high-frequency test pattern with full mipmaps.
/// This ensures Trilinear and Anisotropic filtering work correctly.
pub fn create_test_texture(size: u32) -> Image {
    // 1. Generate Base Level (Level 0)
    let mut pixels = Vec::with_capacity((size * size * 4) as usize);
    for y in 0..size {
        for x in 0..size {
            let (r, g, b) = generate_pattern_pixel(x, y, size);
            pixels.extend_from_slice(&[r, g, b, 255]);
        }
    }

    // 2. Setup Image
    let mut image = Image::new(
        Extent3d {
            width: size,
            height: size,
            depth_or_array_layers: 1,
        },
        TextureDimension::D2,
        pixels,
        TextureFormat::Rgba8Unorm,
        RenderAssetUsages::default(),
    );

    // 3. Manually Generate Mipmaps (Box Filter)
    let mut current_width = size;
    let mut current_height = size;

    // FIX: Clone the inner Vec<u8> (data is Option<Vec<u8>> in Bevy 0.15+)
    let mut current_data = image.data.clone().expect("Image created without data");

    let mip_levels = (size as f32).log2().floor() as u32 + 1;
    image.texture_descriptor.mip_level_count = mip_levels;

    for _level in 1..mip_levels {
        let next_width = current_width / 2;
        let next_height = current_height / 2;
        let mut next_data = Vec::with_capacity((next_width * next_height * 4) as usize);

        for y in 0..next_height {
            for x in 0..next_width {
                // Average the 4 pixels from the previous level
                let src_x = x * 2;
                let src_y = y * 2;

                let p1 = get_pixel(&current_data, current_width, src_x, src_y);
                let p2 = get_pixel(&current_data, current_width, src_x + 1, src_y);
                let p3 = get_pixel(&current_data, current_width, src_x, src_y + 1);
                let p4 = get_pixel(&current_data, current_width, src_x + 1, src_y + 1);

                next_data
                    .push(((p1[0] as u32 + p2[0] as u32 + p3[0] as u32 + p4[0] as u32) / 4) as u8);
                next_data
                    .push(((p1[1] as u32 + p2[1] as u32 + p3[1] as u32 + p4[1] as u32) / 4) as u8);
                next_data
                    .push(((p1[2] as u32 + p2[2] as u32 + p3[2] as u32 + p4[2] as u32) / 4) as u8);
                next_data.push(255);
            }
        }

        // FIX: Unwrap image.data to append the new mip level
        if let Some(data) = &mut image.data {
            data.extend_from_slice(&next_data);
        }

        // Prepare for next iteration
        current_data = next_data;
        current_width = next_width;
        current_height = next_height;
    }

    image
}

fn get_pixel(data: &[u8], width: u32, x: u32, y: u32) -> [u8; 4] {
    let idx = ((y * width + x) * 4) as usize;
    [data[idx], data[idx + 1], data[idx + 2], data[idx + 3]]
}

fn generate_pattern_pixel(x: u32, y: u32, size: u32) -> (u8, u8, u8) {
    let fx = x as f32;
    let fy = y as f32;

    // High frequency checkerboard (1x1)
    let ultra_fine = (x + y) % 2 == 0;
    // Larger checkerboard (8x8)
    let fine_checker = ((x / 8) + (y / 8)) % 2 == 0;
    // Concentric circles
    let center = size as f32 / 2.0;
    let dist = ((fx - center).powi(2) + (fy - center).powi(2)).sqrt();
    let circles = (dist / 4.0) as u32 % 2 == 0;

    let mut val = 40; // Base dark gray
    if ultra_fine {
        val += 40;
    }
    if fine_checker {
        val += 60;
    }
    if circles {
        val += 80;
    }

    // Color tinting
    let r = val;
    let g = if circles { val } else { val / 2 };
    let b = if fine_checker { val } else { val / 3 };

    (r, g, b)
}

Don't forget to register it in src/materials/mod.rs:

pub mod d04_02_filtering_comparison;

The Demo Module (src/demos/d04_02_filtering_comparison.rs)

This system sets up the scene and handles the user input. When you press keys 1-4, we generate a new ImageSamplerDescriptor and assign it to the image. Bevy handles updating the GPU resource automatically.

We also implement a simple Spherical Orbit Camera so you can easily inspect the ground plane from different angles.

use crate::materials::d04_02_filtering_comparison::{FilteringMaterial, create_test_texture};
use bevy::image::{ImageAddressMode, ImageFilterMode, ImageSampler, ImageSamplerDescriptor};
use bevy::pbr::MeshMaterial3d;
use bevy::prelude::*;
use std::f32::consts::PI;

#[derive(Component)]
struct Rotator;

#[derive(Component)]
struct OrbitCamera {
    radius: f32,
    pitch: f32,
    yaw: f32,
    focus: Vec3,
}

impl Default for OrbitCamera {
    fn default() -> Self {
        Self {
            radius: 15.0,
            pitch: 0.5,
            yaw: 0.0,
            focus: Vec3::ZERO,
        }
    }
}

#[derive(Resource)]
struct DemoState {
    texture_handle: Handle<Image>,
    current_mode: usize,
    auto_rotate_obj: bool,
}

pub fn run() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(MaterialPlugin::<FilteringMaterial>::default())
        .add_systems(Startup, setup)
        .add_systems(
            Update,
            (handle_input, rotate_objects, update_camera, update_ui),
        )
        .run();
}

fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<FilteringMaterial>>,
    mut images: ResMut<Assets<Image>>,
) {
    // 1. Create and add texture
    let mut image = create_test_texture(512);
    // Start with Nearest (Point) filtering
    image.sampler = ImageSampler::Descriptor(ImageSamplerDescriptor {
        mag_filter: ImageFilterMode::Nearest,
        min_filter: ImageFilterMode::Nearest,
        mipmap_filter: ImageFilterMode::Nearest,
        address_mode_u: ImageAddressMode::Repeat,
        address_mode_v: ImageAddressMode::Repeat,
        ..default()
    });

    let texture_handle = images.add(image);

    // 2. Create Material
    let material = materials.add(FilteringMaterial {
        display_mode: 0,
        base_color: LinearRgba::WHITE,
        texture: texture_handle.clone(),
    });

    // 3. Spawn Scene
    // Large ground plane (shows Anisotropy best)
    commands.spawn((
        Mesh3d(meshes.add(Plane3d::default().mesh().size(50.0, 50.0))),
        MeshMaterial3d(material.clone()),
        Transform::from_xyz(0.0, 0.0, 0.0),
        Rotator,
    ));

    // Light
    commands.spawn((
        DirectionalLight {
            illuminance: 10_000.0,
            ..default()
        },
        Transform::from_rotation(Quat::from_euler(EulerRot::XYZ, -1.0, 0.5, 0.0)),
    ));

    // Camera
    commands.spawn((
        Camera3d::default(),
        OrbitCamera::default(),
        Transform::default(), // Will be set by update_camera system
    ));

    // UI
    commands.spawn((
        Text::new(""),
        Node {
            position_type: PositionType::Absolute,
            top: Val::Px(12.0),
            left: Val::Px(12.0),
            ..default()
        },
    ));

    // Init State
    commands.insert_resource(DemoState {
        texture_handle,
        current_mode: 1,        // Start at mode 1
        auto_rotate_obj: false, // Default to manual control so you can inspect
    });
}

fn handle_input(
    keyboard: Res<ButtonInput<KeyCode>>,
    mut state: ResMut<DemoState>,
    mut images: ResMut<Assets<Image>>,
    mut materials: ResMut<Assets<FilteringMaterial>>,
    mat_query: Query<&MeshMaterial3d<FilteringMaterial>>,
) {
    let mut changed = false;

    // Mode Switching
    if keyboard.just_pressed(KeyCode::Digit1) {
        state.current_mode = 1;
        changed = true;
    }
    if keyboard.just_pressed(KeyCode::Digit2) {
        state.current_mode = 2;
        changed = true;
    }
    if keyboard.just_pressed(KeyCode::Digit3) {
        state.current_mode = 3;
        changed = true;
    }
    if keyboard.just_pressed(KeyCode::Digit4) {
        state.current_mode = 4;
        changed = true;
    }
    if keyboard.just_pressed(KeyCode::Digit5) {
        state.current_mode = 5;
        changed = true;
    }

    if keyboard.just_pressed(KeyCode::Space) {
        state.auto_rotate_obj = !state.auto_rotate_obj;
    }

    if changed {
        // Update Uniforms (For Mode 5 visualization)
        for handle in &mat_query {
            if let Some(mat) = materials.get_mut(handle) {
                mat.display_mode = if state.current_mode == 5 { 5 } else { 0 };
            }
        }

        // Update Sampler (For Modes 1-4)
        if let Some(image) = images.get_mut(&state.texture_handle) {
            let desc = match state.current_mode {
                1 => ImageSamplerDescriptor {
                    // Nearest
                    mag_filter: ImageFilterMode::Nearest,
                    min_filter: ImageFilterMode::Nearest,
                    mipmap_filter: ImageFilterMode::Nearest,
                    ..default()
                },
                2 => ImageSamplerDescriptor {
                    // Bilinear
                    mag_filter: ImageFilterMode::Linear,
                    min_filter: ImageFilterMode::Linear,
                    mipmap_filter: ImageFilterMode::Nearest,
                    ..default()
                },
                3 => ImageSamplerDescriptor {
                    // Trilinear
                    mag_filter: ImageFilterMode::Linear,
                    min_filter: ImageFilterMode::Linear,
                    mipmap_filter: ImageFilterMode::Linear,
                    ..default()
                },
                4 => ImageSamplerDescriptor {
                    // Anisotropic
                    mag_filter: ImageFilterMode::Linear,
                    min_filter: ImageFilterMode::Linear,
                    mipmap_filter: ImageFilterMode::Linear,
                    anisotropy_clamp: 16,
                    ..default()
                },
                _ => return,
            };

            let mut full_desc = desc;
            full_desc.address_mode_u = ImageAddressMode::Repeat;
            full_desc.address_mode_v = ImageAddressMode::Repeat;
            image.sampler = ImageSampler::Descriptor(full_desc);
        }
    }
}

fn update_camera(
    time: Res<Time>,
    keyboard: Res<ButtonInput<KeyCode>>,
    mut query: Query<(&mut Transform, &mut OrbitCamera)>,
) {
    let dt = time.delta_secs();

    for (mut transform, mut orbit) in &mut query {
        // Manual Orbit Controls
        if keyboard.pressed(KeyCode::ArrowLeft) {
            orbit.yaw += 2.0 * dt;
        }
        if keyboard.pressed(KeyCode::ArrowRight) {
            orbit.yaw -= 2.0 * dt;
        }
        if keyboard.pressed(KeyCode::ArrowUp) {
            orbit.pitch += 1.0 * dt;
        }
        if keyboard.pressed(KeyCode::ArrowDown) {
            orbit.pitch -= 1.0 * dt;
        }

        // Zoom
        if keyboard.pressed(KeyCode::KeyW) {
            orbit.radius -= 10.0 * dt;
        }
        if keyboard.pressed(KeyCode::KeyS) {
            orbit.radius += 10.0 * dt;
        }

        // Clamp
        orbit.pitch = orbit.pitch.clamp(0.05, PI / 2.0 - 0.05); // Don't go below ground or flip over
        orbit.radius = orbit.radius.clamp(2.0, 50.0);

        // Spherical to Cartesian conversion
        // x = r * cos(pitch) * sin(yaw)
        // y = r * sin(pitch)
        // z = r * cos(pitch) * cos(yaw)
        // Note: In Bevy Y is up. So we map Pitch to Y-height and Yaw to XZ plane.
        let r_xz = orbit.radius * orbit.pitch.cos();
        let x = r_xz * orbit.yaw.sin();
        let y = orbit.radius * orbit.pitch.sin();
        let z = r_xz * orbit.yaw.cos();

        transform.translation = orbit.focus + Vec3::new(x, y, z);
        transform.look_at(orbit.focus, Vec3::Y);
    }
}

fn rotate_objects(
    time: Res<Time>,
    state: Res<DemoState>,
    mut query: Query<&mut Transform, With<Rotator>>,
) {
    if state.auto_rotate_obj {
        for mut transform in &mut query {
            transform.rotate_y(time.delta_secs() * 0.1);
        }
    }
}

fn update_ui(state: Res<DemoState>, mut query: Query<&mut Text>) {
    let mode_text = match state.current_mode {
        1 => "1: Point (Nearest) - Pixelated, shimmer in distance",
        2 => "2: Bilinear - Smooth close, sharp mip transitions",
        3 => "3: Trilinear - Smooth everywhere, blurry at angles",
        4 => "4: Anisotropic 16x - Sharp at angles",
        5 => "5: Mip Level Viz - Red(0) to Blue(5)",
        _ => "",
    };

    let rotate_status = if state.auto_rotate_obj { "On" } else { "Off" };

    for mut text in &mut query {
        **text = format!(
            "CONTROLS:\n\
            [1-4] Set Filtering Mode\n\
            [5]   Visualize Mip Levels\n\
            [Arrows] Orbit Camera\n\
            [W/S] Zoom In/Out\n\
            [Space] Rotate Floor: {}\n\
            \n\
            Current: {}",
            rotate_status, mode_text
        );
    }
}

Don't forget to add it to src/demos/mod.rs:

pub mod d04_02_filtering_comparison;

And register it in src/main.rs:

Demo {
    number: "4.2",
    title: "Texture Filtering and Mipmapping",
    run: demos::d04_02_filtering_comparison::run,
},

Running the Demo

When you run the demo, look specifically at the Ground Plane receding into the distance.

Controls

What You're Seeing

This demo proves why Mipmaps and Filtering are essential. Without them (Mode 1), the game looks broken and noisy. With basic filtering (Mode 3), it looks stable but blurry. With Anisotropic filtering (Mode 4), you get the quality of high-res textures with the stability of mipmaps.

Key Takeaways

1. Mipmaps are Mandatory: Always generate mipmaps for 3D textures. Without them, you get aliasing (noise) or have to rely on expensive supersampling.

2. Trilinear is the Standard: For most objects, Linear min/mag/mipmap filters are the correct choice.

3. Anisotropy for Ground: Use anisotropy_clamp: 16 for floors and terrain. It costs a bit more performance but massively improves visual clarity.

4. Sampler Objects: In Bevy/WGSL, the sampler is a distinct resource that tells the GPU how to read the texture data. You can swap samplers without reloading the texture.

What's Next?

We've covered how to sample a single texture. But real materials use multiple textures combined together, and they often need to tile or clamp at the edges.

In the next article, we will master Texture Coordinates (UVs) and Address Modes to create complex, scrolling, and tiling materials.

Next up: 4.3 - Texture Wrapping Modes

Quick Reference

1. Filtering Modes Cheat Sheet

2. Understanding Mipmaps

• What: A chain of progressively smaller versions of a texture (50%, 25%, 12.5%...).

• Why: Prevents "shimmering" and aliasing when textures are far away.

• Cost: Increases memory usage by ~33%.

• Rule: Always enable for 3D objects. Disable only for 2D pixel art or non-color data textures.

3. Performance Hierarchy

From cheapest to most expensive (in terms of memory bandwidth):

1. Nearest: 1 Fetch (Fastest)

2. Bilinear: 4 Fetches

3. Trilinear: 8 Fetches

4. Anisotropic (16x): Up to 128 Fetches (Heavy on bandwidth, use selectively)

4. Bevy Configuration

The "Standard 3D" Sampler (Trilinear):

ImageSampler::Descriptor(ImageSamplerDescriptor {
    mag_filter: ImageFilterMode::Linear,    // Smooth up close
    min_filter: ImageFilterMode::Linear,    // Smooth far away
    mipmap_filter: ImageFilterMode::Linear, // Smooth transitions between distances
    ..default()
})

The "High Quality Ground" Sampler (Anisotropic):

ImageSampler::Descriptor(ImageSamplerDescriptor {
    mag_filter: ImageFilterMode::Linear,
    min_filter: ImageFilterMode::Linear,
    mipmap_filter: ImageFilterMode::Linear,
    anisotropy_clamp: 16, // Range: 1 (Off) to 16 (Max)
    ..default()
})

The "Pixel Art" Sampler:

ImageSampler::Descriptor(ImageSamplerDescriptor {
    mag_filter: ImageFilterMode::Nearest,
    min_filter: ImageFilterMode::Nearest,
    mipmap_filter: ImageFilterMode::Nearest,
    ..default()
})

Up until now, we've been generating colors procedurally - calculating them with math equations directly in our shaders. But most real-world 3D graphics rely on textures: images that wrap around 3D geometry to provide color, detail, and visual richness. A character's skin, the rough bark of a tree, or the rust on a metal barrel - these are all typically defined by textures.

Textures are fundamental to modern graphics. They allow us to decouple surface detail from geometric complexity. Instead of modeling every pore on a face or every brick in a wall, we simply "paint" them onto a simpler shape.

While the concept seems straightforward - "just paste an image onto a model" - there is surprising depth here. How do 2D flat images map seamlessly onto complex 3D curves? What happens when a texture is viewed from a sharp angle or from miles away? How does the GPU interpret colors between pixels?

By the end of this article, you'll understand:

• Texture vs. Sampler: Why GPUs separate the image data from the instructions on how to read it.

• UV Coordinates: The coordinate system that bridges 3D geometry and 2D images.

• The textureSample() Function: How to retrieve color data in a fragment shader.

• Texture Filtering: How to control the look of your textures (pixelated retro vs. smooth modern).

• Address Modes: What happens at the edge of a texture (repeat, clamp, mirror).

• Bevy Integration: How to load images and bind them to your custom materials.

Understanding Textures in WGSL

Before we write any code, we need to shift our mental model. To a CPU, an image might just be a file on a disk. To a GPU, a Texture and a Sampler are two distinct, specialized resources.

What Is a Texture?

A texture is a structured grid of data stored in high-speed GPU memory. While we usually use them for color images, they are just data containers.

• 1D Texture: A single row of pixels. Useful for gradients or lookup curves.

[R G B A | R G B A | R G B A | ...]

• 2D Texture: A grid of pixels (width × height). This is the standard "image" format.

[row 0: R G B A | R G B A | ...]
[row 1: R G B A | R G B A | ...]
[row 2: R G B A | R G B A | ...]

• 3D Texture: A volume of pixels (width × height × depth). Used for fog, smoke simulations, or MRI data.

[layer 0][layer 1][layer 2]...

• Cube Texture: A collection of 6 faces forming a cube. Used for skyboxes and reflections.

[+X face][-X face][+Y][-Y][+Z][-Z]

In this article, we will focus exclusively on 2D Textures.

Texture Formats

Textures can be stored in various formats to balance precision against memory usage. When you define a texture in WGSL, the type you choose generally corresponds to the return value, not necessarily the storage format on disk.

Common formats you'll encounter:

1. Rgba8Unorm (Standard): 4 channels (Red, Green, Blue, Alpha). Each channel is 8 bits (0-255). Shader View: The GPU automatically converts the 0-255 integer range to a 0.0 to 1.0 floating-point range when you sample it.

2. R16Float / R32Float: Single channel floating point. Usage: Heightmaps, physics data, or non-color information.

3. Rg8Unorm: Two channels. Usage: Often used for Normal maps (storing X and Y direction), allowing the Z component to be reconstructed mathematically.

Declaring Textures in WGSL

In WGSL, we declare a texture as a global variable. Note the specific type syntax:

// A standard 2D texture that returns floating point values (0.0 - 1.0)
@group(2) @binding(0)
var my_texture: texture_2d<f32>;

• texture_2d: Specifies the dimensionality.

• <f32>: Specifies the return type. Even if the image on disk is 8-bit integers (PNG), the shader reads them as normalized floats. You can also use <i32> for integer textures or <u32> for unsigned integer textures, but these are for specialized use cases (like grid data), not standard images.

The Sampler: The "How"

Here is the most important concept to grasp: A texture does not know how to be read.

A texture is just a blob of data. If you ask for the color at coordinate (0.5, 0.5), the texture has the data, but it doesn't know:

• Should I blend nearby pixels smoothly?

• Should I just return the exact nearest pixel (pixel art style)?

• What if you ask for coordinate (1.5, 0.5) - should I wrap around to the start or stop at the edge?

These instructions are provided by a Sampler.

By separating the Texture (data) from the Sampler (logic), modern graphics APIs allow you to reuse the same image in different ways. You could sample a noise texture smoothly for clouds, and then sample the exact same texture with "nearest neighbor" filtering for a glitch effect, without reloading the image.

Declaring Samplers in WGSL

Samplers are declared as their own resource type:

// A sampler configuration
@group(2) @binding(1)
var my_sampler: sampler;

There is also a specialized type called sampler_comparison used for shadow mapping, but for standard materials, sampler is what you need.

Pairing Textures and Samplers in Bevy

Because they are separate resources, you need to define both in your Rust material struct. Bevy's AsBindGroup macro handles the boilerplate of binding them to the specific slots.

#[derive(Asset, TypePath, AsBindGroup, Clone)]
pub struct MyMaterial {
    // 1. The Texture Data
    // We bind it to group 2, binding 0
    #[texture(0)] 
    // 2. The Sampler Configuration
    // We bind it to group 2, binding 1
    #[sampler(1)] 
    pub color_image: Handle<Image>,
}

Notice a convenience here: In Rust, we use a single Handle<Image>. The Image asset in Bevy bundles the pixel data and the sampler configuration together for convenience. However, AsBindGroup splits them apart behind the scenes so the shader receives them as two distinct variables:

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

UV Coordinates: The Bridge to 3D

To paint a 2D image onto a 3D object, we need a translation map. We can't say "put this pixel on that vertex" because vertices move, rotate, and scale. Instead, we use a normalized coordinate system called UV Coordinates.

What Are UV Coordinates?

UVs act as anchors. They map a specific point on the 3D mesh surface to a specific point on the 2D texture.

• U (Horizontal): Corresponds to the X-axis of the image (0.0 is Left, 1.0 is Right).

• V (Vertical): Corresponds to the Y-axis of the image (0.0 is Top, 1.0 is Bottom).

Note: While the coordinate system mathematically goes from 0.0 to 1.0, different engines and modeling software treat the vertical origin differently. In WGPU (and thus Bevy), (0, 0) is the top-left corner of the texture data.

Think of it like gift wrapping. The wrapping paper (texture) is flat. You wrap it around a box (mesh). The UV coordinates tell the engine exactly which part of the paper touches each corner of the box.

UVs in the Graphics Pipeline

UVs differ from textures in one major way: UVs are vertex data. They live on the mesh, not in the material.

1. Vertex Input: Each vertex in your mesh has a position (x, y, z) and a UV coordinate (u, v).

2. Interpolation: This is the magic step. The vertex shader passes the UVs to the rasterizer. When the GPU draws a triangle, it automatically interpolates the UVs between the three vertices for every single pixel inside that triangle.

3. Fragment Input: By the time the code reaches your fragment shader, the uv variable represents the precise coordinate for that specific pixel on the screen.

Passing UVs in WGSL

To use UVs, we must explicitly pass them from the Vertex Shader to the Fragment Shader.

struct VertexInput {
    @location(0) position: vec3<f32>,
    @location(1) normal: vec3<f32>,
    @location(2) uv: vec2<f32>, // Input from Mesh
}

struct VertexOutput {
    @builtin(position) clip_position: vec4<f32>,
    // We create a location to pass UVs to the fragment stage
    @location(0) uv: vec2<f32>, 
}

@vertex
fn vertex(in: VertexInput) -> VertexOutput {
    var out: VertexOutput;
    // ... calculate clip_position ...
    
    // Pass the UVs through unchanged
    out.uv = in.uv;
    return out;
}

The textureSample() Function

Now that we have the Texture (data), the Sampler (rules), and the UVs (coordinates), we can finally retrieve a color.

Basic Usage

The primary function for this is textureSample().

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    // Syntax: textureSample(texture_variable, sampler_variable, coordinates)
    let color = textureSample(my_texture, my_sampler, in.uv);
    
    return color;
}

Return Type: textureSample always returns a vec4<f32>.

• Even if your texture is a JPEG with no transparency, the alpha channel (.a) will be set to 1.0.

• Even if your texture is black and white, you get a vec4 (usually with R=G=B).

Constraint: Fragment Shader Only

There is a critical rule you must remember: textureSample() can only be used in the Fragment Shader.

If you try to use it in a Vertex Shader, your code will fail to compile.

Why? To avoid "shimmering" or "aliasing" on distant objects, GPUs use Mipmaps (smaller versions of the texture). The GPU decides which mipmap level to use based on how fast the UV coordinates are changing from pixel to pixel (derivatives).

• In the Fragment Shader, the GPU knows about neighboring pixels and can calculate this.

• In the Vertex Shader, vertices are processed in isolation. The GPU has no concept of "neighbors" or "screen density," so it cannot automatically choose a mipmap level.

Note: If you absolutely must read a texture in the vertex shader - e.g., for a heightmap displacement - you must use textureSampleLevel(), which forces you to manually specify the mipmap level, usually 0.0.

Swizzling and Channels

Often, you don't need the full RGBA color. You can use standard vector swizzling to get what you need:

let raw_sample = textureSample(my_texture, my_sampler, in.uv);

// Just the Red channel (useful for grayscale masks)
let roughness = raw_sample.r; 

// Just the RGB color (dropping alpha)
let base_color = raw_sample.rgb;

// Reordering channels (Swap Red and Blue)
let bgr_color = raw_sample.bgr;

Texture Filtering: The "Zoom" Problem

Textures are made of discrete pixels (texels). Screens are made of discrete pixels. Rarely do they align perfectly 1:1.

When a texture is displayed larger than its original size (Magnification) or smaller than its original size (Minification), the GPU has to make a decision about how to fill the gaps.

This behavior is controlled by the Filter Mode setting on the Sampler.

1. Nearest Neighbor (Nearest)

This is the simplest method. The GPU simply picks the single texel closest to the UV coordinate.

• Look: Blocky, pixelated.

• Best For: Pixel art games, Minecraft-style aesthetics, or debugging.

• Performance: Extremely fast.

2. Linear Interpolation (Linear)

The GPU takes the 4 closest texels surrounding the UV coordinate and blends them together based on distance (bilinear interpolation).

• Look: Smooth, slightly blurry at close range.

• Best For: Realistic textures, photos, most standard 3D objects.

• Performance: Standard (hardware optimized).

Mipmaps and Minification

When a texture is far away (minification), sampling just one pixel causes "noise" or "shimmering" because you might hit a bright pixel on one frame and a dark pixel on the next, even if the camera moves slightly.

To solve this, we use Mipmaps: a chain of progressively smaller versions of the image (100%, 50%, 25%...).

• mipmap_filter: Nearest: Switches abruptly between detail levels. You can see a visible "line" where the quality drops.

• mipmap_filter: Linear: Blends between the two nearest mipmap levels (Trilinear filtering). This is the gold standard for smooth rendering.

Address Modes: The "Edge" Problem

UV coordinates are typically 0.0 to 1.0. But what happens if we pass 2.5 or -0.1? The Address Mode (or Wrap Mode) determines this behavior.

1. Repeat

The texture tiles infinitely. 1.1 behaves exactly like 0.1.

Use Case: Brick walls, grass, tile floors.

2. ClampToEdge

Any value greater than 1.0 reads the last pixel on the edge. Any value less than 0.0 reads the first pixel.

Use Case: UI elements, skyboxes (to prevent seams), or any object that shouldn't tile.

3. MirrorRepeat

The texture tiles, but flips direction every time (0-1, then 1-0, then 0-1).

Use Case: Creating seamless patterns from non-seamless images, or weird psychedelic effects.

Bevy Integration

In Bevy, textures are loaded as Image assets. The Image struct holds both the pixel data and the sampler configuration.

Configuring Samplers in Rust

By default, Bevy loads images with Repeat address mode and Linear filtering. If you want "pixel perfect" rendering or clamping, you need to modify the image asset.

use bevy::image::{ImageSampler, ImageSamplerDescriptor, ImageFilterMode, ImageAddressMode};

fn configure_texture(
    mut images: ResMut<Assets<Image>>,
    my_handle: Res<TextureHandle>, // Assuming you stored the handle
) {
    if let Some(image) = images.get_mut(&my_handle) {
        image.sampler = ImageSampler::Descriptor(ImageSamplerDescriptor {
            // "Pixel Art" settings:
            mag_filter: ImageFilterMode::Nearest, // Sharp pixels when close
            min_filter: ImageFilterMode::Linear,  // Smooth when far away
            
            // Tiling settings:
            address_mode_u: ImageAddressMode::Repeat,
            address_mode_v: ImageAddressMode::Repeat,
            
            ..default()
        });
    }
}

Anisotropic Filtering

There is one more advanced sampler setting: Anisotropy.

When you look at a floor texture at a sharp, grazing angle, standard linear filtering makes it look blurry because the "footprint" of the pixel is long and thin, but linear filtering assumes a square.

Anisotropic Filtering solves this by taking multiple samples along the slope.

image.sampler = ImageSampler::Descriptor(ImageSamplerDescriptor {
    // 16x Anisotropy (High Quality)
    anisotropy_clamp: Some(16), 
    ..default()
});

This is significantly more expensive but essential for ground planes and roads in first-person games.

Complete Example: Textured Quad with Custom UVs

We are going to build a demo that demystifies UVs. Instead of using a standard cube, we will manually build a Quad mesh so we can define the UVs ourselves. We will then manipulate these UVs in the shader to scroll, zoom, and tile a texture.

Our Goal

1. Load an external texture (or generate one).

2. Display it on a custom mesh.

3. Use uniforms to control Tiling (Zoom) and Offset (Pan) in real-time.

The Shader (assets/shaders/d04_01_textured_quad.wgsl)

#import bevy_pbr::mesh_functions
#import bevy_pbr::view_transformations::position_world_to_clip

struct TexturedMaterial {
    base_color: vec4<f32>,
    uv_scale: vec2<f32>,
    uv_offset: vec2<f32>,
}

@group(2) @binding(0)
var<uniform> material: TexturedMaterial;

@group(2) @binding(1)
var base_texture: texture_2d<f32>;

@group(2) @binding(2)
var base_sampler: sampler;

struct VertexInput {
    @builtin(instance_index) instance_index: u32,
    @location(0) position: vec3<f32>,
    @location(2) uv: vec2<f32>,
}

struct VertexOutput {
    @builtin(position) clip_position: vec4<f32>,
    @location(0) uv: vec2<f32>,
}

@vertex
fn vertex(in: VertexInput) -> VertexOutput {
    var out: VertexOutput;

    let world_from_local = mesh_functions::get_world_from_local(in.instance_index);
    let world_position = mesh_functions::mesh_position_local_to_world(
        world_from_local,
        vec4<f32>(in.position, 1.0)
    );
    out.clip_position = position_world_to_clip(world_position.xyz);

    // UV Manipulation
    // 1. Scale (Tiling)
    var transformed_uv = in.uv * material.uv_scale;

    // 2. Offset (Panning)
    transformed_uv = transformed_uv + material.uv_offset;

    out.uv = transformed_uv;

    return out;
}

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    let texture_color = textureSample(base_texture, base_sampler, in.uv);
    return texture_color * material.base_color;
}

The Rust Material (src/materials/d04_01_textured_quad.rs)

use bevy::prelude::*;
use bevy::render::render_resource::{AsBindGroup, ShaderRef};

#[derive(Asset, TypePath, AsBindGroup, Debug, Clone)]
pub struct TexturedMaterial {
    #[uniform(0)]
    pub base_color: LinearRgba,
    #[uniform(0)]
    pub uv_scale: Vec2,
    #[uniform(0)]
    pub uv_offset: Vec2,

    #[texture(1)]
    #[sampler(2)]
    pub base_texture: Handle<Image>,
}

impl Default for TexturedMaterial {
    fn default() -> Self {
        Self {
            base_color: LinearRgba::WHITE,
            uv_scale: Vec2::ONE,
            uv_offset: Vec2::ZERO,
            base_texture: Handle::default(),
        }
    }
}

impl Material for TexturedMaterial {
    fn vertex_shader() -> ShaderRef {
        "shaders/d04_01_textured_quad.wgsl".into()
    }

    fn fragment_shader() -> ShaderRef {
        "shaders/d04_01_textured_quad.wgsl".into()
    }
}

Don't forget to register it in src/materials/mod.rs:

pub mod d04_01_textured_quad;

The Demo Module (src/demos/d04_01_textured_quad.rs)

We'll procedurally generate a "Checkerboard" texture so you don't need to download any assets to run this demo. We also configure its sampler to use Repeat mode so we can scroll it infinitely.

use bevy::image::{ImageAddressMode, ImageFilterMode, ImageSampler, ImageSamplerDescriptor};
use bevy::prelude::*;
use bevy::render::render_asset::RenderAssetUsages;
use bevy::render::render_resource::{Extent3d, TextureDimension, TextureFormat};

use crate::materials::d04_01_textured_quad::TexturedMaterial;

pub fn run() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(MaterialPlugin::<TexturedMaterial>::default())
        .add_systems(Startup, setup)
        .add_systems(
            Update,
            (handle_input, rotate_quads, update_ui, sync_loaded_icon),
        )
        .run();
}

#[derive(Component)]
struct Rotator;

#[derive(Resource)]
struct DemoState {
    procedural_handle: Handle<Image>,
    icon_handle: Handle<Image>,

    // Settings
    filter_mode: ImageFilterMode,
    address_mode: ImageAddressMode,

    // Rotation
    auto_rotate: bool,
    manual_rotation: f32,

    // State tracking
    icon_configured: bool,
}

fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<TexturedMaterial>>,
    mut images: ResMut<Assets<Image>>,
    asset_server: Res<AssetServer>,
) {
    // 1. Initial Sampler Settings
    let initial_descriptor = ImageSamplerDescriptor {
        mag_filter: ImageFilterMode::Nearest,
        min_filter: ImageFilterMode::Nearest,
        address_mode_u: ImageAddressMode::Repeat,
        address_mode_v: ImageAddressMode::Repeat,
        ..default()
    };

    // 2. Create Procedural "UV Test" Texture
    // We create a colored gradient so address modes are obvious.
    // Red = X axis, Green = Y axis.
    let size = 256;
    let mut data = Vec::with_capacity((size * size * 4) as usize);
    for y in 0..size {
        for x in 0..size {
            let r = x as u8; // 0 to 255 horizontally
            let g = y as u8; // 0 to 255 vertically
            // Blue checkerboard overlay for detail
            let b = if ((x / 16) + (y / 16)) % 2 == 0 {
                255
            } else {
                0
            };

            data.extend_from_slice(&[r, g, b, 255]);
        }
    }

    let mut proc_image = Image::new(
        Extent3d {
            width: size,
            height: size,
            depth_or_array_layers: 1,
        },
        TextureDimension::D2,
        data,
        TextureFormat::Rgba8Unorm,
        RenderAssetUsages::default(),
    );
    // Apply initial sampler
    proc_image.sampler = ImageSampler::Descriptor(initial_descriptor.clone());
    let proc_handle = images.add(proc_image);

    // 3. Load Icon (Async)
    let icon_handle = asset_server.load("textures/bevy_icon.png");

    // 4. Save State
    commands.insert_resource(DemoState {
        procedural_handle: proc_handle.clone(),
        icon_handle: icon_handle.clone(),
        filter_mode: ImageFilterMode::Nearest,
        address_mode: ImageAddressMode::Repeat,
        auto_rotate: true,
        manual_rotation: 0.0,
        icon_configured: false,
    });

    // 5. Scene Setup
    let quad_handle = meshes.add(Plane3d::default().mesh().size(3.0, 3.0));

    // Left Quad: Procedural
    commands.spawn((
        Mesh3d(quad_handle.clone()),
        MeshMaterial3d(materials.add(TexturedMaterial {
            base_texture: proc_handle,
            ..default()
        })),
        Transform::from_xyz(-2.0, 0.0, 0.0),
        Rotator,
    ));

    // Right Quad: Loaded Icon
    commands.spawn((
        Mesh3d(quad_handle),
        MeshMaterial3d(materials.add(TexturedMaterial {
            base_texture: icon_handle,
            ..default()
        })),
        Transform::from_xyz(2.0, 0.0, 0.0),
        Rotator,
    ));

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

    // UI
    commands.spawn((
        Text::new(""), // Updated in update_ui
        Node {
            position_type: PositionType::Absolute,
            top: Val::Px(12.0),
            left: Val::Px(12.0),
            ..default()
        },
    ));
}

fn handle_input(
    time: Res<Time>,
    keyboard: Res<ButtonInput<KeyCode>>,
    mut materials: ResMut<Assets<TexturedMaterial>>,
    mut images: ResMut<Assets<Image>>,
    mut state: ResMut<DemoState>,
) {
    let dt = time.delta_secs();

    // 1. UV Manipulation
    for (_, mat) in materials.iter_mut() {
        if keyboard.pressed(KeyCode::ArrowLeft) {
            mat.uv_offset.x -= dt;
        }
        if keyboard.pressed(KeyCode::ArrowRight) {
            mat.uv_offset.x += dt;
        }
        if keyboard.pressed(KeyCode::ArrowUp) {
            mat.uv_offset.y -= dt;
        }
        if keyboard.pressed(KeyCode::ArrowDown) {
            mat.uv_offset.y += dt;
        }

        if keyboard.pressed(KeyCode::KeyW) {
            mat.uv_scale += dt;
        }
        if keyboard.pressed(KeyCode::KeyS) {
            mat.uv_scale = (mat.uv_scale - dt).max(Vec2::splat(0.1));
        }
    }

    // 2. Rotation Controls
    if keyboard.just_pressed(KeyCode::KeyR) {
        state.auto_rotate = !state.auto_rotate;
    }
    if !state.auto_rotate {
        if keyboard.pressed(KeyCode::KeyA) {
            state.manual_rotation -= dt;
        }
        if keyboard.pressed(KeyCode::KeyD) {
            state.manual_rotation += dt;
        }
    }

    // 3. Sampler Switching
    let mut update_samplers = false;

    if keyboard.just_pressed(KeyCode::Digit1) {
        state.filter_mode = match state.filter_mode {
            ImageFilterMode::Nearest => ImageFilterMode::Linear,
            _ => ImageFilterMode::Nearest,
        };
        update_samplers = true;
    }

    if keyboard.just_pressed(KeyCode::Digit2) {
        state.address_mode = match state.address_mode {
            ImageAddressMode::Repeat => ImageAddressMode::MirrorRepeat,
            ImageAddressMode::MirrorRepeat => ImageAddressMode::ClampToEdge,
            ImageAddressMode::ClampToEdge => ImageAddressMode::Repeat,
            _ => ImageAddressMode::Repeat,
        };
        update_samplers = true;
    }

    if update_samplers {
        update_all_images(&mut images, &mut state);
    }
}

// Helper to apply current settings to all valid images
fn update_all_images(images: &mut Assets<Image>, state: &mut DemoState) {
    let descriptor = ImageSamplerDescriptor {
        mag_filter: state.filter_mode,
        min_filter: state.filter_mode,
        address_mode_u: state.address_mode,
        address_mode_v: state.address_mode,
        ..default()
    };

    // Update procedural
    if let Some(image) = images.get_mut(&state.procedural_handle) {
        image.sampler = ImageSampler::Descriptor(descriptor.clone());
    }

    // Update loaded icon (if loaded)
    if let Some(image) = images.get_mut(&state.icon_handle) {
        image.sampler = ImageSampler::Descriptor(descriptor);
        state.icon_configured = true;
    }
}

// Automatically configures the icon once it finishes loading
fn sync_loaded_icon(mut images: ResMut<Assets<Image>>, mut state: ResMut<DemoState>) {
    // If the icon is loaded but hasn't been configured yet
    if !state.icon_configured && images.contains(&state.icon_handle) {
        update_all_images(&mut images, &mut state);
    }
}

fn rotate_quads(
    time: Res<Time>,
    mut state: ResMut<DemoState>,
    mut query: Query<&mut Transform, With<Rotator>>,
) {
    if state.auto_rotate {
        state.manual_rotation += time.delta_secs() * 0.2;
    }

    for mut transform in &mut query {
        transform.rotation =
            Quat::from_rotation_y(state.manual_rotation) * Quat::from_rotation_x(0.5);
    }
}

fn update_ui(state: Res<DemoState>, mut query: Query<&mut Text>) {
    let filter_text = match state.filter_mode {
        ImageFilterMode::Nearest => "Nearest (Pixelated)",
        _ => "Linear (Smooth)",
    };
    let address_text = match state.address_mode {
        ImageAddressMode::Repeat => "Repeat (Tile)",
        ImageAddressMode::MirrorRepeat => "MirrorRepeat (Flip)",
        _ => "ClampToEdge (Stretch)",
    };
    let rotate_text = if state.auto_rotate {
        "Auto"
    } else {
        "Manual (A/D)"
    };

    for mut text in &mut query {
        **text = format!(
            "CONTROLS:\n\
            [Arrows] Pan UVs\n\
            [W/S]    Zoom UVs\n\
            [1]      Filter: {}\n\
            [2]      Address: {}\n\
            [R]      Rotation: {}",
            filter_text, address_text, rotate_text
        );
    }
}

Don't forget to add it to src/demos/mod.rs:

pub mod d04_01_textured_quad;

And register it in src/main.rs:

Demo {
    number: "4.1",
    title: "Texture Sampling Basics",
    run: demos::d04_01_textured_quad::run,
},

Running the Demo

When you run this demo, you will see a large checkerboard spinning slowly in the void.

Controls

What You're Seeing

1. Sampler Power: Even though our procedural texture is tiny (256x256), it looks sharp because of mag_filter: Nearest. If we changed it to Linear, the edges of the checks would be blurry.

2. Addressing: As you scroll with the arrow keys, notice how the pattern repeats seamlessly. This is the ImageAddressMode::Repeat setting doing the heavy lifting.

3. Vertex Shader Efficiency: We are doing the scrolling math in the vertex shader. Since our plane has only 4 vertices, we only run those additions/multiplications 4 times per frame! The GPU interpolates the result for the thousands of pixels in between.

Key Takeaways

1. Textures ≠ Samplers: A texture is raw data. A sampler is the set of rules for reading it. They are separate resources in WGSL (texture_2d vs sampler).

2. Fragment Only: You cannot use textureSample() in a vertex shader. You must calculate UVs in the vertex shader and pass them to the fragment shader.

3. Address Modes Matter: If you want a texture to tile, you must configure the sampler to Repeat.

4. UV Math: Tiling is multiplication (uv * 2.0). Scrolling is addition (uv + offset).

What's Next?

We've mastered the single texture. But real materials are rarely just one image. They are composites - a blend of base colors, detail maps, dirt layers, and decals.

In the next article, we will learn how to combine multiple textures, use grayscale textures as masks, and layer effects together.

Next up: 4.2 - Texture Filtering and Mipmapping

Quick Reference

WGSL Texture Declaration:

@group(1) @binding(0) var my_tex: texture_2d<f32>;
@group(1) @binding(1) var my_samp: sampler;

Sampling:

let color = textureSample(my_tex, my_samp, uv);

Common UV Math:

let tiled_uv = uv * 5.0;         // Repeat 5 times
let scrolled_uv = uv + time;     // Move diagonally
let centered_uv = uv - 0.5;      // Move origin to center

Color is one of the most powerful tools in your graphics arsenal. So far, we've worked with basic color operations - sampling textures, mixing colors, and applying simple lighting. But there's a whole world of advanced color manipulation techniques that can transform the look and feel of your renders from "functional" to "cinematic."

Think about photo editing apps or professional color grading tools in film production. These effects aren't magic - they are careful mathematical manipulations of color values. The same techniques used in Hollywood color grading suites can be implemented in real-time fragment shaders.

The difference between basic and advanced color work is like the difference between painting with a single brush and having a full artist's toolkit. Basic operations get you pixels on the screen. Advanced techniques give you creative control - the ability to establish mood, guide attention, create visual coherence, and evoke specific emotions.

By the end of this article, you'll understand:

• Color Correction Fundamentals: How to mathematically adjust brightness, contrast, saturation, and gamma.

• Color Grading with LUTs: Using 3D Lookup Tables to apply complex cinematic looks cheaply.

• Stylized Effects: Implementing posterization (quantization) for retro or comic-book aesthetics.

• Channel Manipulation: How to isolate and shift specific color channels.

• Lens Simulation: Creating chromatic aberration (color fringing) to simulate physical lens imperfections.

• Edge Detection: Using the Sobel operator to find outlines based on color differences.

• Custom Blend Modes: Implementing mathematical blends beyond standard alpha mixing (Overlay, Screen, Multiply).

• Post-Processing Preview: Building a complete "Instagram-style" filter system using a render-to-texture pipeline.

Color Correction Fundamentals

Before diving into complex effects, let's master the core color adjustments. These are the "bread and butter" functions you will use constantly, whether you are tweaking a specific material or grading an entire scene.

Understanding Color Spaces

Most of our shader math happens in RGB space, but understanding how to navigate other representations makes specific tasks much easier.

1. RGB (Red, Green, Blue):

   • Hardware Native: This is how monitors display light.

   • Additive: 100% Red + 100% Green = Yellow.

   • Good for: Technical operations, texture storage, and lighting math.

   • Bad for: "Make this 10% brighter" or "Shift the hue slightly."

2. HSV (Hue, Saturation, Value):

   • Perceptual: Modeled after how humans describe color.

   • Cylindrical: Hue is an angle (0-360°), Saturation is a radius, Value is height.

   • Good for: "Make this color more vivid" (Saturation) or "Change this red to blue" (Hue).

   • Bad for: Lighting calculations.

We will often convert RGB to HSV, modify it, and convert back to RGB.

Brightness Adjustment

The simplest correction is adding or subtracting light.

fn adjust_brightness(color: vec3<f32>, amount: f32) -> vec3<f32> {
    // amount: -1.0 (black) to 1.0 (white)
    return color + amount;
}

Key Insight: This is a linear offset. It shifts the entire histogram. While simple, it can wash out blacks (if positive) or crush whites (if negative).

Safety First: Color operations can easily push values below 0.0 or above 1.0. In a StandardMaterial pipeline, values > 1.0 create "bloom" (glow). If that isn't intended, always clamp your final result.

fn adjust_brightness_safe(color: vec3<f32>, amount: f32) -> vec3<f32> {
    return clamp(color + amount, vec3<f32>(0.0), vec3<f32>(1.0));
}

Contrast Adjustment

Contrast defines the separation between light and dark values. High contrast makes darks darker and lights lighter. Low contrast makes everything gray.

fn adjust_contrast(color: vec3<f32>, contrast: f32) -> vec3<f32> {
    // contrast = 1.0: Neutral
    // contrast > 1.0: High Contrast
    // contrast < 1.0: Low Contrast

    // We scale the color relative to "Middle Gray" (0.5)
    let midpoint = vec3<f32>(0.5);

    return (color - midpoint) * contrast + midpoint;
}

Visualizing the Math:
Imagine a color value of 0.6 (slightly bright).

• Subtract 0.5 → 0.1

• Multiply by 2.0 (High Contrast) → 0.2

• Add 0.5 → 0.7
  The value moved from 0.6 to 0.7 (brighter).

Imagine a color value of 0.4 (slightly dark).

• Subtract 0.5 → -0.1

• Multiply by 2.0 → -0.2

• Add 0.5 → 0.3
  The value moved from 0.4 to 0.3 (darker).

Saturation Adjustment

Saturation controls the intensity of the color. To adjust it, we interpolate between the original color and a grayscale version of itself.

fn adjust_saturation(color: vec3<f32>, saturation: f32) -> vec3<f32> {
    // 0.0 = Grayscale
    // 1.0 = Neutral
    // >1.0 = Vivid

    // 1. Calculate Luminance (Perceived Brightness)
    // We use the Rec. 709 luma coefficients (modern standard for sRGB)
    // Green contributes most to brightness, Blue contributes least.
    let luminance = dot(color, vec3<f32>(0.2126, 0.7152, 0.0722));
    let grayscale = vec3<f32>(luminance);

    // 2. Mix between gray and color
    return mix(grayscale, color, saturation);
}

Note on Coefficients: You might see 0.299, 0.587, 0.114 in older tutorials. Those are for SDTV (Rec. 601). Since Bevy and modern computing use sRGB/Rec. 709, 0.2126, 0.7152, 0.0722 is more mathematically accurate, though the visual difference is subtle.

Gamma Adjustment (Midtones)

Gamma allows you to brighten or darken the image without crushing the blacks or blowing out the whites. It specifically targets the midtones.

fn adjust_gamma(color: vec3<f32>, gamma: f32) -> vec3<f32> {
    // gamma = 1.0: Neutral
    // gamma > 1.0: Brightens midtones
    // gamma < 1.0: Darkens midtones (NOTE: This convention varies!)

    // Bevy note: Standard sRGB decoding uses a power of 2.2.
    // For artistic control, we often simply use power.
    return pow(color, vec3<f32>(1.0 / gamma));
}

Combined Pipeline

Order of operations matters. A standard color grading pipeline usually applies operations in this order to mimic how film is processed:

fn color_correct(
    color: vec3<f32>,
    brightness: f32,
    contrast: f32,
    saturation: f32,
    gamma: f32,
) -> vec3<f32> {
    var result = color;

    // 1. Apply Gamma/Midtones first (shaping the curve)
    result = adjust_gamma(result, gamma);

    // 2. Apply Brightness (offsetting the curve)
    result = result + brightness;

    // 3. Apply Contrast (expanding the curve around center)
    // Doing this after brightness allows you to contrast-stretch the brightened image
    let midpoint = vec3<f32>(0.5);
    result = (result - midpoint) * contrast + midpoint;

    // 4. Apply Saturation (final polish)
    let luminance = dot(result, vec3<f32>(0.2126, 0.7152, 0.0722));
    result = mix(vec3<f32>(luminance), result, saturation);

    return clamp(result, vec3<f32>(0.0), vec3<f32>(1.0));
}

Color Grading with Lookup Tables (LUTs)

While mathematical formulas are great for basic adjustments, creating a complex, artistic "film look" (like the famous "Teal and Orange" blockbuster style) purely with math is incredibly difficult.

Enter the Lookup Table (LUT). A LUT is essentially a translation dictionary for color.

What is a LUT?

Imagine a function f(color) -> new_color. A LUT pre-calculates this function for every possible color (or a representative sample of them) and stores the result in a table.

• Input: The original pixel color (Red, Green, Blue).

• Lookup: The shader uses the Input RGB values as coordinates to look up a position in the table.

• Output: The color found at that position.

This allows artists to use tools like Photoshop or DaVinci Resolve to grade a screenshot, export that grade as a .cube or texture file, and have the game engine replicate that exact look in real-time.

The 3D Texture approach

In modern graphics, we typically use 3D LUTs.
Think of a 3D LUT as a cube of colors:

• X-axis represents Red (0.0 to 1.0).

• Y-axis represents Green (0.0 to 1.0).

• Z-axis represents Blue (0.0 to 1.0).

To use a LUT, we simply take our pixel's color and use it as the (u, v, w) texture coordinates to sample this 3D texture.

Applying a 3D LUT in WGSL

The WGSL implementation is surprisingly simple because the hardware does the heavy lifting (interpolation) for us.

@group(2) @binding(1) var lut_texture: texture_3d<f32>;
@group(2) @binding(2) var lut_sampler: sampler;

fn apply_lut(original_color: vec3<f32>, strength: f32) -> vec3<f32> {
    // 1. Clamp input to valid texture coordinate range [0.0, 1.0]
    // If we don't clamp, bright values might wrap around or sample invalid data.
    let lut_coords = clamp(original_color, vec3<f32>(0.0), vec3<f32>(1.0));

    // 2. Sample the 3D texture
    // The GPU automatically interpolates between the stored colors
    // if our specific color falls between the grid points.
    let graded_color = textureSample(lut_texture, lut_sampler, lut_coords).rgb;

    // 3. Mix based on strength (Intensity slider)
    return mix(original_color, graded_color, strength);
}

Generating a LUT in Rust

While you normally load LUTs from assets, generating one programmatically is a great way to understand the data structure. Here is how to create a "Identity LUT" (one that maps every color to itself) in Bevy. You can then modify the math inside the loop to bake complex effects into the texture.

use bevy::prelude::*;
use bevy::render::render_asset::RenderAssetUsages;
use bevy::render::render_resource::{Extent3d, TextureDimension, TextureFormat};

fn generate_identity_lut(size: u32) -> Image {
    // Standard sizes: 16, 32, or 64. 
    // 32 is a good balance of quality vs memory (32x32x32 pixels).
    let mut data = Vec::with_capacity((size * size * size * 4) as usize);

    for z in 0..size {
        for y in 0..size {
            for x in 0..size {
                // Normalize coordinates to 0.0 - 1.0 range
                let r = x as f32 / (size - 1) as f32;
                let g = y as f32 / (size - 1) as f32;
                let b = z as f32 / (size - 1) as f32;

                // Store the color. For an identity LUT, the Color IS the Coordinate.
                // To make a "Sepia" LUT, you would do math on r,g,b here before storing.
                data.push((r * 255.0) as u8);
                data.push((g * 255.0) as u8);
                data.push((b * 255.0) as u8);
                data.push(255); // Alpha
            }
        }
    }

    Image::new(
        Extent3d {
            width: size,
            height: size,
            depth_or_array_layers: size, // Depth is the Blue axis
        },
        TextureDimension::D3,
        data,
        TextureFormat::Rgba8Unorm, // Standard 8-bit color
        RenderAssetUsages::default(),
    )
}

Stylized Effects: Posterization & Quantization

Sometimes you don't want realism - you want a style. Posterization (or color quantization) reduces the continuous spectrum of colors into discrete "bands" or steps. This mimics the look of old EGA graphics, comic books, or silk-screen posters.

Basic Posterization

The math relies on floor() to snap values to the nearest "step."

fn posterize(color: vec3<f32>, steps: f32) -> vec3<f32> {
    // steps: Number of color bands (e.g., 4.0, 8.0, 16.0)

    // 1. Scale up (0.0 - 1.0 becomes 0.0 - 4.0)
    // 2. Floor (0.0, 1.0, 2.0, 3.0, 4.0)
    // 3. Scale down (0.0, 0.25, 0.50, 0.75, 1.0)
    return floor(color * steps) / steps;
}

Dithered Posterization

The problem with simple posterization is "banding" - large, flat areas of single color that look artificial. Dithering adds noise before quantization to break up these edges, creating the illusion of more colors through pixel patterns.

// A pseudo-random hash function for noise
fn hash(uv: vec2<f32>) -> f32 {
    return fract(sin(dot(uv, vec2<f32>(12.9898, 78.233))) * 43758.5453);
}

fn posterize_dithered(
    color: vec3<f32>, 
    steps: f32, 
    uv: vec2<f32>,
    dither_strength: f32
) -> vec3<f32> {
    // Generate noise between -0.5 and 0.5
    let noise = (hash(uv) - 0.5) * dither_strength;

    // Add noise BEFORE quantization
    let noisy_color = color + noise;

    return floor(noisy_color * steps) / steps;
}

Chromatic Aberration

Chromatic Aberration is an optical defect where a lens fails to focus all colors to the same convergence point. It manifests as red and blue color fringes along high-contrast edges, especially near the corners of the image.

In games, we add it intentionally to make the camera feel "physical" and imperfect, adding realism or unease.

The Technique

Instead of sampling the texture once at uv, we sample it three times - once for each color channel - with slightly different coordinates.

fn chromatic_aberration(
    base_texture: texture_2d<f32>,
    base_sampler: sampler,
    uv: vec2<f32>,
    strength: f32
) -> vec3<f32> {
    // 1. Calculate direction from center
    let center = vec2<f32>(0.5);
    let dist_vector = uv - center;

    // 2. Calculate distortion amount
    // Aberration is usually stronger at the edges (squared distance)
    let dist_sq = dot(dist_vector, dist_vector);
    let offset = dist_vector * dist_sq * strength;

    // 3. Sample channels separately
    // Red channel shifts OUTWARD
    let r = textureSample(base_texture, base_sampler, uv + offset).r;

    // Green channel stays centered (or shifts slightly)
    let g = textureSample(base_texture, base_sampler, uv).g;

    // Blue channel shifts INWARD
    let b = textureSample(base_texture, base_sampler, uv - offset).b;

    return vec3<f32>(r, g, b);
}

Edge Detection with Sobel

Edge detection is fundamental for outline shaders (toon shading) and image analysis. We use the Sobel Operator, which looks at a pixel's neighbors to determine if there is a sudden change in brightness.

The Sobel operator uses two "kernels" (grids) to measure the gradient (change) in the X and Y directions.

Sobel Implementation

fn get_luminance(color: vec3<f32>) -> f32 {
    return dot(color, vec3<f32>(0.2126, 0.7152, 0.0722));
}

fn sobel_edge_detection(
    tex: texture_2d<f32>,
    samp: sampler,
    uv: vec2<f32>,
    resolution: vec2<f32> // Screen dimensions in pixels
) -> f32 {
    let step = 1.0 / resolution; // Size of one pixel in UV space

    // Sample the 8 neighbors + center
    // We only need luminance for simple edge detection
    let tl = get_luminance(textureSample(tex, samp, uv + vec2<f32>(-step.x, -step.y)).rgb);
    let t  = get_luminance(textureSample(tex, samp, uv + vec2<f32>( 0.0,    -step.y)).rgb);
    let tr = get_luminance(textureSample(tex, samp, uv + vec2<f32>( step.x, -step.y)).rgb);

    let l  = get_luminance(textureSample(tex, samp, uv + vec2<f32>(-step.x,  0.0)).rgb);
    let r  = get_luminance(textureSample(tex, samp, uv + vec2<f32>( step.x,  0.0)).rgb);

    let bl = get_luminance(textureSample(tex, samp, uv + vec2<f32>(-step.x,  step.y)).rgb);
    let b  = get_luminance(textureSample(tex, samp, uv + vec2<f32>( 0.0,     step.y)).rgb);
    let br = get_luminance(textureSample(tex, samp, uv + vec2<f32>( step.x,  step.y)).rgb);

    // Sobel Kernels
    // Horizontal (Gx)     Vertical (Gy)
    // -1  0  1           -1 -2 -1
    // -2  0  2            0  0  0
    // -1  0  1            1  2  1

    let gx = (tr + 2.0 * r + br) - (tl + 2.0 * l + bl);
    let gy = (bl + 2.0 * b + br) - (tl + 2.0 * t + tr);

    // Magnitude of the gradient vector
    // High value = Strong Edge
    return sqrt(gx * gx + gy * gy);
}

If the return value is close to 0.0, the area is flat. If it is > 0.5, there is a sharp edge.

Custom Blend Modes

Finally, let's look at how to blend a filter color with the original image. Standard alpha blending mix(a, b, alpha) is boring. Photoshop-style blend modes offer more artistic control.

These functions take a base color (the image) and a blend color (the filter tint).

// MULTIPLY: Darkens the image. Good for shadows or vignetting.
// Formula: A * B
fn blend_multiply(base: vec3<f32>, blend: vec3<f32>) -> vec3<f32> {
    return base * blend;
}

// SCREEN: Lightens the image. Good for glows.
// Formula: 1 - (1-A) * (1-B)
fn blend_screen(base: vec3<f32>, blend: vec3<f32>) -> vec3<f32> {
    return vec3<f32>(1.0) - (vec3<f32>(1.0) - base) * (vec3<f32>(1.0) - blend);
}

// OVERLAY: Increases contrast. Combines Multiply (for darks) and Screen (for lights).
fn blend_overlay(base: vec3<f32>, blend: vec3<f32>) -> vec3<f32> {
    // If base is dark (< 0.5), multiply. If bright, screen.
    let is_bright = step(vec3<f32>(0.5), base);

    let dark_mix = 2.0 * base * blend;
    let bright_mix = 1.0 - 2.0 * (1.0 - base) * (1.0 - blend);

    return mix(dark_mix, bright_mix, is_bright);
}

Complete Example: Instagram-Style Filter System

To demonstrate these techniques, we will build a comprehensive "Photo Filter" application. This will include everything we discussed: manual color correction (brightness/contrast/saturation), artistic presets, chromatic aberration, posterization, and edge detection.

Important Architecture Note:
To apply these effects to the entire scene at once, we need a technique called Render-to-Texture (RTT).

1. We create a special Image asset manually in Rust (our "film roll").

2. We tell our Main Camera (Layer 0) to render into that image instead of to the screen.

3. We spawn a second "Post-Processing Camera" (Layer 1).

4. We place a large flat rectangle in front of this second camera.

5. We apply our custom shader to this rectangle, using the Image from step 1 as a texture.

This is a simplified version of how professional post-processing pipelines work!

The Shader (assets/shaders/d03_08_photo_filter.wgsl)

This shader integrates every concept from this article into a single, unified pipeline. We use linear math for the Chromatic Aberration to ensure the effect is clearly visible.

#import bevy_pbr::forward_io::VertexOutput

struct PhotoFilterMaterial {
    // 1. Manual Color Correction
    brightness: f32,
    contrast: f32,
    saturation: f32,

    // 2. Artistic Presets
    filter_mode: u32,     // 0=None, 1=Vintage, 2=Noir
    filter_strength: f32, // Mix amount (0.0 to 1.0)

    // 3. Advanced Effects
    aberration_strength: f32, // Offset amount
    posterize_steps: f32,     // 0.0 = disabled
    edge_show: u32,           // 0 = Off, 1 = On

    _padding: f32,            // Alignment padding
}

@group(2) @binding(0) var<uniform> material: PhotoFilterMaterial;
@group(2) @binding(1) var base_texture: texture_2d<f32>;
@group(2) @binding(2) var base_sampler: sampler;

// --- Helper Math ---
fn get_luminance(color: vec3<f32>) -> f32 {
    // Rec. 709 coefficients
    return dot(color, vec3<f32>(0.2126, 0.7152, 0.0722));
}

fn adjust_contrast(color: vec3<f32>, contrast: f32) -> vec3<f32> {
    return (color - 0.5) * contrast + 0.5;
}

fn adjust_saturation(color: vec3<f32>, saturation: f32) -> vec3<f32> {
    let grey = vec3<f32>(get_luminance(color));
    return mix(grey, color, saturation);
}

// --- Effects ---

fn chromatic_aberration(uv: vec2<f32>, strength: f32) -> vec3<f32> {
    let center = vec2<f32>(0.5);

    // Linear falloff: Effect increases linearly towards edges
    // This makes the effect strong and clearly visible
    let offset = (uv - center) * strength;

    let r = textureSample(base_texture, base_sampler, uv - offset).r;
    let g = textureSample(base_texture, base_sampler, uv).g; // Green is anchor
    let b = textureSample(base_texture, base_sampler, uv + offset).b;

    return vec3<f32>(r, g, b);
}

fn posterize(color: vec3<f32>, steps: f32) -> vec3<f32> {
    return floor(color * steps) / steps;
}

fn sobel_edge_detection(uv: vec2<f32>) -> f32 {
    let dims = vec2<f32>(textureDimensions(base_texture));
    let step = 1.0 / dims;

    // Simplified Sobel (Horizontal + Vertical)
    let t = get_luminance(textureSample(base_texture, base_sampler, uv + vec2<f32>(0.0, -step.y)).rgb);
    let b = get_luminance(textureSample(base_texture, base_sampler, uv + vec2<f32>(0.0, step.y)).rgb);
    let l = get_luminance(textureSample(base_texture, base_sampler, uv + vec2<f32>(-step.x, 0.0)).rgb);
    let r = get_luminance(textureSample(base_texture, base_sampler, uv + vec2<f32>(step.x, 0.0)).rgb);

    let gy = t - b;
    let gx = l - r;

    return sqrt(gx*gx + gy*gy);
}

// --- Filter Presets ---
fn filter_vintage(color: vec3<f32>) -> vec3<f32> {
    var c = color;
    c = adjust_contrast(c, 1.2);
    c = adjust_saturation(c, 0.6);
    c *= vec3<f32>(1.1, 1.0, 0.8); // Sepia tint
    return c;
}

fn filter_noir(color: vec3<f32>) -> vec3<f32> {
    let lum = get_luminance(color);
    var c = vec3<f32>(lum);
    c = adjust_contrast(c, 1.5); // High contrast B&W
    return c;
}

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    // 1. Chromatic Aberration (modifies UV sampling)
    var color = vec3<f32>(0.0);
    if material.aberration_strength > 0.0 {
        color = chromatic_aberration(in.uv, material.aberration_strength);
    } else {
        color = textureSample(base_texture, base_sampler, in.uv).rgb;
    }

    // 2. Manual Color Correction
    color = color + material.brightness;
    color = adjust_contrast(color, material.contrast);
    color = adjust_saturation(color, material.saturation);

    // 3. Filter Presets
    if material.filter_mode > 0u {
        var filtered = color;
        switch material.filter_mode {
            case 1u: { filtered = filter_vintage(color); }
            case 2u: { filtered = filter_noir(color); }
            default: { filtered = color; }
        }
        color = mix(color, filtered, material.filter_strength);
    }

    // 4. Posterization (Stylized)
    if material.posterize_steps > 0.0 {
        color = posterize(color, material.posterize_steps);
    }

    // 5. Edge Detection Overlay
    if material.edge_show > 0u {
        let edge = sobel_edge_detection(in.uv);
        // Green edges overlaid on top
        color = mix(color, vec3<f32>(0.0, 1.0, 0.0), edge * 5.0);
    }

    return vec4<f32>(color, 1.0);
}

The Rust Material (src/materials/d03_08_photo_filter.rs)

We map our Rust struct to the WGSL layout.

use bevy::prelude::*;
use bevy::render::render_resource::{AsBindGroup, ShaderRef};

#[derive(Asset, TypePath, AsBindGroup, Debug, Clone)]
pub struct PhotoFilterMaterial {
    // Manual Correction
    #[uniform(0)]
    pub brightness: f32,
    #[uniform(0)]
    pub contrast: f32,
    #[uniform(0)]
    pub saturation: f32,

    // Artistic Presets
    #[uniform(0)]
    pub filter_mode: u32,
    #[uniform(0)]
    pub filter_strength: f32,

    // Advanced Effects
    #[uniform(0)]
    pub aberration_strength: f32,
    #[uniform(0)]
    pub posterize_steps: f32,
    #[uniform(0)]
    pub edge_show: u32,
    #[uniform(0)]
    pub _padding: f32,

    // The Render Target
    #[texture(1)]
    #[sampler(2)]
    pub base_texture: Handle<Image>,
}

impl Default for PhotoFilterMaterial {
    fn default() -> Self {
        Self {
            brightness: 0.0,
            contrast: 1.0,
            saturation: 1.0,
            filter_mode: 0,
            filter_strength: 1.0,
            aberration_strength: 0.0,
            posterize_steps: 0.0,
            edge_show: 0,
            _padding: 0.0,
            base_texture: Handle::default(),
        }
    }
}

impl Material for PhotoFilterMaterial {
    fn fragment_shader() -> ShaderRef {
        "shaders/d03_08_photo_filter.wgsl".into()
    }
}

Don't forget to add it to src/materials/mod.rs:

pub mod d03_08_photo_filter;

The Demo Module (src/demos/d03_08_photo_filter.rs)

We've added an OrbitCamera system so you can rotate around the scene using the Left/Right Arrow keys. We also use an Orthographic Projection for the Post-Processing camera to ensure our filter quad fills the window perfectly.

use crate::materials::d03_08_photo_filter::PhotoFilterMaterial;
use bevy::prelude::*;
use bevy::render::camera::{RenderTarget, ScalingMode};
use bevy::render::render_resource::{Extent3d, TextureDimension, TextureFormat, TextureUsages};
use bevy::render::view::RenderLayers;

pub fn run() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(MaterialPlugin::<PhotoFilterMaterial>::default())
        .add_systems(Startup, setup)
        .add_systems(
            Update,
            (rotate_objects, orbit_camera, handle_input, update_ui),
        )
        .run();
}

#[derive(Resource)]
struct FilterState {
    material_handle: Handle<PhotoFilterMaterial>,
}

#[derive(Component)]
struct Rotator;

#[derive(Component)]
struct OrbitCamera {
    radius: f32,
    angle: f32,
}

fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<PhotoFilterMaterial>>,
    mut standard_materials: ResMut<Assets<StandardMaterial>>,
    mut images: ResMut<Assets<Image>>,
) {
    // 1. Setup Render Target (High Res for quality)
    let size = Extent3d {
        width: 1920,
        height: 1080,
        ..default()
    };

    let mut image = Image {
        texture_descriptor: bevy::render::render_resource::TextureDescriptor {
            label: Some("render_target"),
            size,
            dimension: TextureDimension::D2,
            format: TextureFormat::Rgba8UnormSrgb,
            mip_level_count: 1,
            sample_count: 1,
            usage: TextureUsages::TEXTURE_BINDING
                | TextureUsages::COPY_DST
                | TextureUsages::RENDER_ATTACHMENT,
            view_formats: &[],
        },
        ..default()
    };
    image.resize(size);
    let image_handle = images.add(image);

    // 2. Scene Camera (Renders to the Image, Layer 0)
    // We attach our OrbitCamera component here
    commands.spawn((
        Camera3d::default(),
        Camera {
            target: RenderTarget::Image(image_handle.clone().into()),
            ..default()
        },
        Transform::from_xyz(0.0, 1.5, 3.5).looking_at(Vec3::ZERO, Vec3::Y),
        RenderLayers::layer(0),
        OrbitCamera {
            radius: 3.5,
            angle: 0.0,
        },
    ));

    // 3. Post-Process Camera (Renders to Screen, Layer 1)
    // We use Orthographic to make filling the screen easy.
    commands.spawn((
        Camera3d::default(),
        Projection::Orthographic(OrthographicProjection {
            scaling_mode: ScalingMode::FixedVertical {
                viewport_height: 1.0,
            },
            ..OrthographicProjection::default_3d()
        }),
        Camera {
            order: 1, // Run after scene camera
            ..default()
        },
        Transform::from_xyz(0.0, 0.0, 5.0).looking_at(Vec3::ZERO, Vec3::Y),
        RenderLayers::layer(1),
    ));

    // 4. The Screen Quad (Layer 1)
    // Height 1.0 matches Camera height. Width 16/9 matches render target aspect.
    let filter_mat = materials.add(PhotoFilterMaterial {
        base_texture: image_handle,
        ..default()
    });

    commands.spawn((
        Mesh3d(meshes.add(Rectangle::new(1.0, 1.0))),
        MeshMaterial3d(filter_mat.clone()),
        Transform::from_scale(Vec3::new(16.0 / 9.0, 1.0, 1.0)),
        RenderLayers::layer(1),
    ));

    commands.insert_resource(FilterState {
        material_handle: filter_mat,
    });

    // 5. The Scene Content (Layer 0)
    commands.spawn((
        Mesh3d(meshes.add(Cuboid::default())),
        MeshMaterial3d(standard_materials.add(Color::srgb(1.0, 0.1, 0.1))),
        Transform::from_xyz(-1.2, 0.0, 0.0),
        Rotator,
        RenderLayers::layer(0),
    ));

    commands.spawn((
        Mesh3d(meshes.add(Sphere::default())),
        MeshMaterial3d(standard_materials.add(Color::srgb(0.1, 1.0, 0.1))),
        Transform::from_xyz(1.2, 0.0, 0.0),
        Rotator,
        RenderLayers::layer(0),
    ));

    commands.spawn((
        PointLight {
            intensity: 2_000_000.0,
            ..default()
        },
        Transform::from_xyz(2.0, 5.0, 3.0),
        RenderLayers::layer(0),
    ));

    // UI
    commands.spawn((
        Text::new(""), // Updated by system
        Node {
            position_type: PositionType::Absolute,
            top: Val::Px(12.0),
            left: Val::Px(12.0),
            ..default()
        },
    ));
}

fn rotate_objects(time: Res<Time>, mut query: Query<&mut Transform, With<Rotator>>) {
    for mut t in &mut query {
        t.rotate_y(time.delta_secs());
        t.rotate_x(time.delta_secs() * 0.5);
    }
}

fn orbit_camera(
    time: Res<Time>,
    keyboard: Res<ButtonInput<KeyCode>>,
    mut query: Query<(&mut Transform, &mut OrbitCamera)>,
) {
    let speed = 2.0;
    for (mut transform, mut orbit) in &mut query {
        if keyboard.pressed(KeyCode::ArrowLeft) {
            orbit.angle -= speed * time.delta_secs();
        }
        if keyboard.pressed(KeyCode::ArrowRight) {
            orbit.angle += speed * time.delta_secs();
        }

        let x = orbit.radius * orbit.angle.sin();
        let z = orbit.radius * orbit.angle.cos();

        transform.translation = Vec3::new(x, 1.5, z);
        transform.look_at(Vec3::new(0.0, 0.0, 0.0), Vec3::Y);
    }
}

fn handle_input(
    keyboard: Res<ButtonInput<KeyCode>>,
    state: Res<FilterState>,
    mut materials: ResMut<Assets<PhotoFilterMaterial>>,
    time: Res<Time>,
) {
    let dt = time.delta_secs() / 2.0;

    if let Some(mat) = materials.get_mut(&state.material_handle) {
        // Presets
        if keyboard.just_pressed(KeyCode::Digit1) {
            mat.filter_mode = 0;
        }
        if keyboard.just_pressed(KeyCode::Digit2) {
            mat.filter_mode = 1;
        }
        if keyboard.just_pressed(KeyCode::Digit3) {
            mat.filter_mode = 2;
        }

        // Manual Color Corrections
        if keyboard.pressed(KeyCode::KeyQ) {
            mat.brightness -= dt;
        }
        if keyboard.pressed(KeyCode::KeyW) {
            mat.brightness += dt;
        }

        if keyboard.pressed(KeyCode::KeyA) {
            mat.contrast -= dt;
        }
        if keyboard.pressed(KeyCode::KeyS) {
            mat.contrast += dt;
        }

        if keyboard.pressed(KeyCode::KeyZ) {
            mat.saturation -= dt;
        }
        if keyboard.pressed(KeyCode::KeyX) {
            mat.saturation += dt;
        }

        // Toggles
        if keyboard.just_pressed(KeyCode::KeyC) {
            // 0.10 (10%) shift is a massive glitch effect!
            mat.aberration_strength = if mat.aberration_strength > 0.0 {
                0.0
            } else {
                0.10
            };
        }
        if keyboard.just_pressed(KeyCode::KeyP) {
            mat.posterize_steps = if mat.posterize_steps > 0.0 { 0.0 } else { 8.0 };
        }
        if keyboard.just_pressed(KeyCode::KeyE) {
            mat.edge_show = if mat.edge_show > 0 { 0 } else { 1 };
        }

        // Reset
        if keyboard.just_pressed(KeyCode::KeyR) {
            mat.brightness = 0.0;
            mat.contrast = 1.0;
            mat.saturation = 1.0;
        }
    }
}

fn update_ui(
    state: Res<FilterState>,
    materials: Res<Assets<PhotoFilterMaterial>>,
    mut text_q: Query<&mut Text>,
) {
    if let Some(mat) = materials.get(&state.material_handle) {
        for mut text in &mut text_q {
            let mode = match mat.filter_mode {
                0 => "None",
                1 => "Vintage",
                _ => "Noir",
            };
            **text = format!(
                "CONTROLS:\n\
                [Left/Right] Orbit Camera\n\
                [1-3] Preset: {}\n\
                [Q/W] Brightness: {:.2}\n\
                [A/S] Contrast:   {:.2}\n\
                [Z/X] Saturation: {:.2}\n\
                [C] Aberration:   {}\n\
                [P] Posterize:    {}\n\
                [E] Edge Detect:  {}\n\
                [R] Reset",
                mode,
                mat.brightness,
                mat.contrast,
                mat.saturation,
                if mat.aberration_strength > 0.0 {
                    "ON"
                } else {
                    "OFF"
                },
                if mat.posterize_steps > 0.0 {
                    "ON"
                } else {
                    "OFF"
                },
                if mat.edge_show > 0 { "ON" } else { "OFF" }
            );
        }
    }
}

Don't forget to add it to src/demos/mod.rs:

pub mod d03_08_photo_filter;

And register it in src/main.rs:

Demo {
    number: "3.8",
    title: "Advanced Color Techniques",
    run: demos::d03_08_photo_filter::run,
},

Running the Demo

When you run this demo, you essentially have a mini-Photoshop running in real-time. The Orthographic camera setup ensures the filter fills your window perfectly.

Controls

What You're Seeing

1. Orbit Controls: Use the arrows to fly around. This makes the Edge Detection effect much more obvious, as you can see the green outlines reacting dynamically to the changing silhouette of the cube and sphere.

2. Full Pipeline: All adjustments happen sequentially in the shader. You can, for example, turn on "Vintage" mode, then manually boost the Contrast using A, and then add Chromatic Aberration with C for a very stylized "broken camera" look.

3. Render Target: Notice the quality of the image. Because we set the render target to 1920x1080, the edges are crisp, even if your actual window is smaller (downsampled) or larger (upsampled).

Key Takeaways

1. Color Space Mastery: Knowing when to use RGB vs. Luminance vs. HSV is half the battle.

2. Order Matters: Applying contrast before saturation yields different results than saturation before contrast. A standard pipeline is Gamma → Exposure → Contrast → Saturation.

3. Render-To-Texture: To apply effects to the whole screen (like Chromatic Aberration), you need to capture the scene into a texture first.

4. Sampling Tricks: Many cool effects (Aberration, Blur, Edge Detection) come from simply sampling the texture multiple times at slightly different coordinates.

5. Artistic Control: Shaders aren't just for realism. Tools like Posterization and LUTs allow you to define a unique visual identity for your game.

What's Next?

We've mastered color. Now it's time to master surface detail. In the next article, we will explore how to make flat surfaces look bumpy, cracked, and detailed without adding a single polygon.

Next up: 4.1 - Texture Sampling Basics

Quick Reference

Chromatic Aberration (Linear):

let offset = (uv - 0.5) * strength;
let red    = textureSample(tex, s, uv - offset).r;
let blue   = textureSample(tex, s, uv + offset).b;

Luminance (Rec. 709):

let lum = dot(color, vec3<f32>(0.2126, 0.7152, 0.0722));

Sobel Edge Logic:

// Sample neighbors, calculate gradient magnitude
let gx = (top_right + 2*right + bot_right) - (top_left + 2*left + bot_left);
let gy = (bot_left + 2*bot + bot_right) - (top_left + 2*top + top_right);
let edge = sqrt(gx*gx + gy*gy);

So far in this series, every fragment we've processed has been drawn to the screen. We've colored them, textured them, and lit them - but we've always drawn them. What if you don't want to draw certain fragments at all? What if you want holes, cutouts, or complex silhouettes without adding extra geometry?

This is where the discard statement comes in - one of the most powerful and distinctive tools in a fragment shader. With a single keyword, you can make a fragment disappear as if it never existed. No color written, no depth written, nothing. It is the fragment shader equivalent of an invisibility cloak.

However, transparency isn't just about deleting pixels. There is also alpha blending - where fragments partially show through to what's behind them. These two approaches - discard and blending - solve different problems and come with very different trade-offs in the deferred or forward rendering pipelines.

In this article, you will learn:

• The Discard Statement: How to immediately terminate a pixel's processing.

• Alpha Testing: Creating hard cutouts for foliage, fences, and grates.

• Discard vs. Blending: Why discard gives you correct depth sorting for free, while blending creates sorting headaches.

• Performance: Why "doing nothing" (discarding) can sometimes be slower than drawing.

• Bevy's Alpha Modes: How to configure StandardMaterial or custom materials for different types of transparency.

Concept: Forward vs. Deferred Rendering

To understand why transparency is tricky, we need to understand the two main ways game engines render scenes.

1. Forward Rendering: The classic approach. The GPU draws each object one by one and calculates lighting immediately.

   • Pros: Handles transparency (blending) well.

   • Cons: Gets very slow if you have hundreds of dynamic lights.

2. Deferred Rendering: The modern approach for high-fidelity games. The GPU first renders the geometry data (Position, Normal, Color) of every pixel to a buffer (the "G-Buffer"), and calculates lighting for the entire screen at the end.

   • Pros: Can handle thousands of lights efficiently.

   • Cons: Hates transparency. Because the G-Buffer only stores data for the single closest object per pixel, it can't store "multiple transparent layers" (like glass in front of a car).

Why this matters: When you use discard, the fragment remains "opaque" - it's either there or it isn't. This works perfectly in both pipelines.
When you use alpha blending, the engine usually has to break out of the Deferred pipeline and draw that specific object using Forward rendering at the very end. This is why "cutout" shaders (discard) are often much faster than "transparent" shaders (blend).

Understanding Fragment Discard

Let's start with the simplest and most dramatic tool: the discard statement.

What discard Does

The discard statement immediately terminates the execution of the fragment shader. The fragment is not written to any output - not the color buffer, not the depth buffer, nothing. The GPU simply stops working on that specific pixel for that specific triangle.

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    // Calculate if we should discard based on arbitrary logic
    let should_hide = in.uv.y > 0.5;

    if should_hide {
        discard;  // STOP. Do not pass Go. Do not write pixel.
    }

    // This code only runs if we didn't discard
    return vec4<f32>(1.0, 0.0, 0.0, 1.0);
}

Critical properties of discard:

1. Immediate Termination: Code written after the discard statement inside that branch does not execute.

2. No Depth Write: This is the most important feature. If a fragment is discarded, it does not update the depth buffer. Objects behind this fragment will be rendered normally, as if this geometry wasn't there.

3. Binary Visibility: A fragment is either there (100% opacity) or it isn't (0% opacity). There is no "50% visible" with discard.

Visual Comparison

Basic Example: The Checkerboard

The simplest procedural use case is a checkerboard. We don't need a texture for this; we can calculate it using UVs.

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    // Create a 10x10 grid pattern
    let tiles = floor(in.uv * 10.0);

    // Check if the sum of x and y indices is even or odd
    let checker = tiles.x + tiles.y;

    // modulo 2.0 to alternate
    if (checker % 2.0) > 0.5 {
        discard;
    }

    // Render the remaining squares as red
    return vec4<f32>(1.0, 0.0, 0.0, 1.0);
}

This creates a lattice where half the squares are completely transparent - you can see through them to the world behind - and half are solid red.

Performance: When to Discard

It is important to understand that discard is not like a return. It aborts the thread.

Optimization Tip: If you know you are going to discard a pixel, do it as early as possible.

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    // 1. Check discard condition FIRST
    if in.uv.y < 0.1 {
        discard;
    }

    // 2. Perform expensive lighting/math AFTER
    // This code won't run for the bottom 10% of the UVs, saving GPU power.
    let lighting = calculate_complex_pbr_lighting(in);

    return vec4<f32>(lighting, 1.0);
}

Discard and Depth Testing

One of the key features of discard is how it interacts with the depth buffer.

Normally, when a fragment shader runs, the GPU might update the Depth Buffer to say "there is an object here at distance Z." If we discard, that update never happens. This means we don't need to worry about the "draw order" of our triangles.

This makes discard the perfect tool for foliage, chain-link fences, and grates.

Alpha Testing with Conditional Discard

The most common use of discard is Alpha Testing (also called "Cutout" transparency). This technique uses a texture's alpha channel to decide which pixels to keep and which to delete.

The Classic Alpha Test Pattern

Imagine you have a texture of a chain-link fence. The metal parts have an alpha of 1.0 (opaque), and the gaps have an alpha of 0.0 (transparent).

// Define bindings for Group 2 (Material Data)
@group(2) @binding(0) var base_texture: texture_2d<f32>;
@group(2) @binding(1) var base_sampler: sampler;

struct AlphaCutoffMaterial {
    cutoff_threshold: f32, // Usually 0.5
}

@group(2) @binding(2) var<uniform> material: AlphaCutoffMaterial;

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    // 1. Sample the texture
    let color = textureSample(base_texture, base_sampler, in.uv);

    // 2. Alpha Test: Compare texture alpha against our threshold
    if color.a < material.cutoff_threshold {
        discard;
    }

    // 3. Render the pixel (opaque)
    return color;
}

How it works:

1. We sample the texture at the current UV.

2. We check if the alpha value is too low (e.g., < 0.5).

3. If it is, we discard. If not, we draw the pixel at full opacity.

Choosing the Right Threshold

The cutoff threshold determines how "strict" the discard is.

• 0.5: The standard default. Balanced.

• 0.1: "Generous." Keeps almost everything, even faint wisps. Good for preserving details but might leave "dirty" edges.

• 0.9: "Strict." Only keeps the most solid parts. Good for shrinking an object visually.

Alpha Channel Gradient:   0.0 ... 0.3 ... 0.5 ... 0.7 ... 1.0

Threshold 0.5 keeps:                      [------ KEEP -----]
Threshold 0.9 keeps:                                  [KEEP ]

The Problem: Binary Edges

With standard Alpha Testing, there are only two states: visible or invisible. There is no partial transparency. This creates "jagged" or aliased edges, especially when the camera is close.

To fix this cheaply without enabling expensive Alpha Blending, we can use Dithering.

Advanced: Dithered Alpha Testing

Dithering uses a noise pattern to randomly discard pixels near the edge threshold. This fakes transparency by mixing opaque and discarded pixels in a checkerboard-like pattern.

// Helper: 4x4 Bayer Matrix for ordered dithering
fn bayer_dither(position: vec2<f32>) -> f32 {
    let x = u32(position.x) % 4u;
    let y = u32(position.y) % 4u;

    // Hardcoded Bayer matrix normalized to 0.0-1.0
    // This creates a balanced noise pattern
    let index = y * 4u + x;
    var bayer = array<f32, 16>(
        0.0/16.0, 8.0/16.0, 2.0/16.0, 10.0/16.0,
        12.0/16.0, 4.0/16.0, 14.0/16.0, 6.0/16.0,
        3.0/16.0, 11.0/16.0, 1.0/16.0, 9.0/16.0,
        15.0/16.0, 7.0/16.0, 13.0/16.0, 5.0/16.0
    );

    return bayer[index];
}

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    let color = textureSample(base_texture, base_sampler, in.uv);

    // Get a dither value based on SCREEN position (in.position)
    // -0.5 to +0.5 range centered around 0
    let dither_noise = bayer_dither(in.position.xy) - 0.5;

    // Modulate the threshold slightly per pixel
    // "0.1" controls how wide the "fuzzy" edge is
    let noisy_threshold = material.cutoff_threshold + (dither_noise * 0.1);

    if color.a < noisy_threshold {
        discard;
    }

    return color;
}

This effectively "softens" the hard edge. From a distance, the dithered pixels blend together in your eye, making the edge look smooth.

Creating Cutout Effects

Alpha testing is the standard technique for specific types of objects in games.

Leaves and Foliage

Leaves are almost always rendered as simple quads (rectangles) with a texture.

A tree might have 10,000 leaves. Sorting them back-to-front for Alpha Blending would crush the CPU. With discard, the Z-buffer handles the sorting automatically.

Fences and Grates

Chain-link fences are just flat planes with a repeating texture.

discard creates sharp, metallic edges. Semi-transparent blending would make the metal look like ghost-fence.

Procedural Holes

You don't always need a texture. You can punch holes mathematically using discard.

// Example: Swiss Cheese Shader
@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    // Create a repeating grid
    let grid_uv = fract(in.uv * 10.0);

    // Calculate distance from center of the grid cell
    let dist = length(grid_uv - vec2<f32>(0.5));

    // If inside the circle radius, discard
    if dist < 0.4 {
        discard;
    }

    return vec4<f32>(1.0, 1.0, 0.0, 1.0); // Yellow cheese
}

Discard vs. Alpha Blending Trade-offs

Now we reach the critical question: when should you use Alpha Testing (discard) versus standard Alpha Blending?

In Bevy, you choose between these behaviors using the AlphaMode setting on your material, but understanding what happens under the hood is vital for performance and visual quality.

Alpha Blending Recap

Before comparing, let's remember what Alpha Blending is. instead of "deleting" the pixel, the GPU mixes it with the color that is already on the screen behind it.

// Alpha Blending (No discard)
@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    let color = textureSample(base_texture, base_sampler, in.uv);

    // Return color with alpha.
    // The GPU hardware handles the mixing automatically.
    return color; 
}

Equation: FinalColor = (SourceColor * Alpha) + (DestinationColor * (1.0 - Alpha))

Comparison Table

The Sorting Problem

The single biggest downside of Alpha Blending is that draw order matters.

If you draw a red glass pane in front of a blue glass pane:

• Correct (Back-to-Front): Draw Blue, then Draw Red on top. Result: Purple.

• Incorrect (Front-to-Back): Draw Red. Because it is transparent, it doesn't write to the depth buffer. Then Draw Blue. Since nothing wrote to the depth buffer, Blue draws on top of Red. Result: Blue looks like it is in front of Red.

How Bevy handles this:
Bevy's renderer automatically calculates the distance from the camera to every object with AlphaMode::Blend and sorts them every frame.

• Limitation 1: It sorts objects, not triangles. If a large complex mesh intersects itself, it will glitch.

• Limitation 2: It costs CPU time to sort thousands of objects every frame.

Why discard wins here:
Because discard allows the opaque pixels to write to the depth buffer, order does not matter. You can draw a forest of 10,000 trees in any order, and the depth buffer ensures the trees behind are correctly hidden by the trees in front.

Performance Considerations

When choosing a transparency mode, it helps to view them in a hierarchy of cost.

1. Opaque (AlphaMode::Opaque) - The Speed King

This is the fastest mode. Modern GPUs use "Early-Z" optimization: before running your pixel shader, they check the depth buffer. If a wall is in front of the pixel, the GPU skips the shader entirely.

Verdict: Use this whenever possible.

2. Discard / Alpha Mask (AlphaMode::Mask) - The Optimization Breaker

You might think: "Discarding pixels means I don't write them, so it should be faster than Opaque!"
Not always!

To know if a pixel should be discarded, the GPU must run the fragment shader. This forces the GPU to disable Early-Z optimization for that object. It calculates every single pixel, even the ones hidden behind other objects, just to check if they need to be deleted.

Verdict: Slower than Opaque, but much faster than Blending.

3. Alpha Blending (AlphaMode::Blend) - The Bandwidth Eater

This is the most expensive mode.

• CPU Cost: Bevy must calculate distances and sort every object every frame.

• GPU Cost: For every transparent layer (e.g., looking through smoke), the GPU must read the current color from memory, do math, and write it back. This "Read-Modify-Write" loop eats up Memory Bandwidth, which is often the bottleneck on mobile devices and integrated graphics.

Verdict: Use sparingly.

Summary Rule of Thumb

• If it's solid, use AlphaMode::Opaque.

  • If it has holes but hard edges (leaves, fences), use AlphaMode::Mask.

  • Only use AlphaMode::Blend if you absolutely need partial transparency (glass, water).

Bevy's Alpha Mode Configuration

In Bevy, you control this behavior directly on your material struct. Whether you use StandardMaterial or a custom Material, the API is the same.

use bevy::prelude::*;

impl Material for MyCustomMaterial {
    fn fragment_shader() -> ShaderRef {
        "shaders/my_shader.wgsl".into()
    }

    // This function tells Bevy's pipeline how to handle your shader
    fn alpha_mode(&self) -> AlphaMode {
        // Option A: Opaque (Default)
        // Fastest. Writes Depth. Ignores alpha channel.
        AlphaMode::Opaque

        // Option B: Alpha Mask / Testing
        // Writes Depth. Enables `discard` behavior in the generic shader.
        // The f32 value is the cutoff threshold (usually 0.5).
        AlphaMode::Mask(0.5)

        // Option C: Alpha Blending
        // No Depth Write. CPU Sorting enabled. Smooth edges.
        AlphaMode::Blend

        // Option D: Additive (Good for glowing particles/fire)
        AlphaMode::Add
    }
}

Note: If you are writing a completely custom fragment shader (like we are in the next section), setting AlphaMode::Mask in Rust does not automatically add the discard keyword to your WGSL code. You must write the if (alpha < threshold) { discard; } logic yourself!

The AlphaMode in Rust primarily tells the render pipeline:

1. Whether to enable Depth Writes.

2. Whether to enable the CPU Sorter.

3. Which Blend State (Mix, Add, Multiply) to configure on the GPU.

Complete Example: The Teleportation Chamber

We will build a sci-fi teleportation scene that demonstrates both uses of transparency in a single project. This approach highlights exactly when to use one technique over the other.

1. Safety Grates (Alpha Mask): We will create a perforated metal floor and wall. Since metal is solid (it's either there or it isn't), we use Alpha Testing. We will also disable backface culling so we can see the grates from both sides.

2. The Hero (Blend + Discard): We will create a holographic character. Since holograms are made of light, they are semi-transparent (Alpha Blending). However, when the character teleports, they will "dematerialize" using a noise-based Discard effect.

This example relies entirely on procedural math (sine waves and hash functions), so no texture assets are required.

1. The Grate Material (Alpha Testing)

This material generates a "Perforated Metal" look. We use AlphaMode::Mask because we want the edges of the holes to be razor-sharp.

The Shader (assets/shaders/d03_07_simple_grate.wgsl)

In the fragment shader, we divide the UV space into a grid. Inside each cell, we calculate the distance from the center. If that distance is smaller than our hole_radius, we discard the pixel.

To make it look 3D, we add a fake "bevel" highlight around the rim of the hole using smoothstep. This makes the flat geometry feel like a thick metal plate.

#import bevy_pbr::forward_io::VertexOutput

struct GrateMaterial {
    color: vec4<f32>,
    bar_width: f32, // Controls hole size (0.0 to 0.5)
    _padding: vec3<f32>,
}

@group(2) @binding(0) var<uniform> material: GrateMaterial;

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    // 1. Create a repeating grid
    // We offset by 0.5 so the center of the UV cell is (0,0)
    let grid_uv = fract(in.uv * 20.0) - 0.5;

    // 2. Calculate distance from the center of the cell
    let dist = length(grid_uv);

    // 3. Alpha Test (The Hole)
    // If we are inside the circle radius defined by bar_width, discard.
    // This creates "Swiss Cheese" perforated metal.
    if dist < material.bar_width {
        discard;
    }

    // 4. Fake "Bevel" Lighting
    // We make the pixels right next to the hole brighter.
    // This simulates light catching the rim of the drilled hole,
    // making the flat plane look like it has thickness.
    let bevel = smoothstep(material.bar_width, material.bar_width + 0.1, dist);

    // Mix a dark shadow color with the material color based on the bevel
    let final_color = mix(material.color.rgb * 0.5, material.color.rgb, bevel);

    return vec4<f32>(final_color, material.color.a);
}

The Rust Code (src/materials/d03_07_simple_grate.rs)

In the Rust material, we do two important things:

1. We set AlphaMode::Mask(0.5) to enable the cutouts.

2. We override the specialize method to disable cull_mode. This tells the GPU to draw the triangles even if they are facing away from the camera, allowing us to see the back of the wall through the front of the wall.

use bevy::pbr::{MaterialPipeline, MaterialPipelineKey};
use bevy::prelude::*;
use bevy::render::mesh::MeshVertexBufferLayoutRef;
use bevy::render::render_resource::{
    AsBindGroup, RenderPipelineDescriptor, ShaderRef, SpecializedMeshPipelineError,
};

#[derive(Asset, TypePath, AsBindGroup, Debug, Clone)]
pub struct GrateMaterial {
    #[uniform(0)]
    pub color: LinearRgba,
    #[uniform(0)]
    pub hole_radius: f32, // Renamed for clarity (was bar_width)
    #[uniform(0)]
    pub _padding: Vec3,
}

impl Default for GrateMaterial {
    fn default() -> Self {
        Self {
            color: LinearRgba::new(0.6, 0.6, 0.7, 1.0), // Steel Blue-Grey
            hole_radius: 0.35,                          // Nice perforation size
            _padding: Vec3::ZERO,
        }
    }
}

impl Material for GrateMaterial {
    fn fragment_shader() -> ShaderRef {
        "shaders/d03_07_simple_grate.wgsl".into()
    }

    fn alpha_mode(&self) -> AlphaMode {
        AlphaMode::Mask(0.5)
    }

    // ENABLE DOUBLE-SIDED RENDERING
    fn specialize(
        _pipeline: &MaterialPipeline<Self>,
        descriptor: &mut RenderPipelineDescriptor,
        _layout: &MeshVertexBufferLayoutRef,
        _key: MaterialPipelineKey<Self>,
    ) -> Result<(), SpecializedMeshPipelineError> {
        // None = Draw both front and back faces
        descriptor.primitive.cull_mode = None;
        Ok(())
    }
}

Don't forget to add it to src/materials/mod.rs:

pub mod d03_07_simple_grate;

2. The Teleport Material (Blend + Discard)

This material renders the "Hero". It combines three distinct effects:

1. Hologram Scanlines: A sine wave moving vertically to simulate projection interference.

2. Rim Lighting: A Fresnel calculation to make the edges of the model glow, enhancing the 3D volume.

3. Teleport Dissolve: A noise-based discard effect that eats away the geometry.

The Shader (assets/shaders/d03_07_teleport_body.wgsl)

Note that we calculate the Fresnel effect using the dot product between the view vector (camera direction) and the normal vector. This adds that classic sci-fi "edge glow."

The dissolve effect happens before the lighting. If the noise value is below our threshold, we discard immediately. If the pixel survives, we then apply the holographic blending.

#import bevy_pbr::forward_io::VertexOutput
#import bevy_pbr::mesh_view_bindings::view

struct TeleportMaterial {
    color: vec4<f32>,
    dissolve_amount: f32,
    time: f32,
    _padding: vec2<f32>,
}

@group(2) @binding(0) var<uniform> material: TeleportMaterial;

fn hash(p: vec2<f32>) -> f32 {
    let n = dot(p, vec2<f32>(12.9898, 78.233));
    return fract(sin(n) * 43758.5453);
}

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    // 1. Dissolve (Discard)
    let noise = hash(in.uv * 50.0 + material.time);
    if noise < material.dissolve_amount {
        discard;
    }

    // 2. Hologram Scanlines
    let scanline = sin(in.world_position.y * 50.0 - material.time * 5.0);
    let scan_strength = 0.7 + 0.3 * scanline;

    // 3. Fresnel Rim Light (3D effect)
    let view_dir = normalize(view.world_position.xyz - in.world_position.xyz);
    let normal = normalize(in.world_normal);
    let fresnel = 1.0 - max(dot(view_dir, normal), 0.0);
    let rim_glow = pow(fresnel, 3.0) * 2.0;

    // 4. Combine
    let final_alpha = material.color.a * scan_strength + rim_glow;
    let final_color = material.color.rgb + vec3<f32>(rim_glow);

    return vec4<f32>(final_color, final_alpha);
}

The Rust Code (src/materials/d03_07_teleport_body.rs)

We use AlphaMode::Blend. Even though we use discard inside the shader, we need Blending enabled to make the hologram look like semi-transparent light.

use bevy::prelude::*;
use bevy::render::render_resource::{AsBindGroup, ShaderRef};

#[derive(Asset, TypePath, AsBindGroup, Debug, Clone)]
pub struct TeleportMaterial {
    #[uniform(0)]
    pub color: LinearRgba,
    #[uniform(0)]
    pub dissolve_amount: f32,
    #[uniform(0)]
    pub time: f32,
    #[uniform(0)]
    pub _padding: Vec2,
}

impl Default for TeleportMaterial {
    fn default() -> Self {
        Self {
            color: LinearRgba::new(0.0, 1.0, 1.0, 0.3), // Cyan, low opacity
            dissolve_amount: 0.0,
            time: 0.0,
            _padding: Vec2::ZERO,
        }
    }
}

impl Material for TeleportMaterial {
    fn fragment_shader() -> ShaderRef {
        "shaders/d03_07_teleport_body.wgsl".into()
    }

    fn alpha_mode(&self) -> AlphaMode {
        AlphaMode::Blend
    }
}

Don't forget to add it to src/materials/mod.rs:

pub mod d03_07_teleport_body;

3. The Demo Scene (src/demos/d03_07_teleport_demo.rs)

This demo sets up the chamber, spawns the hero, and handles the logic. We add an Orbit Camera so you can rotate around the scene and inspect the transparency sorting from all angles.

When you press Space, we animate the dissolve_amount uniform. The hero dissolves, moves to a new random location while invisible, and then re-materializes.

use crate::materials::d03_07_simple_grate::GrateMaterial;
use crate::materials::d03_07_teleport_body::TeleportMaterial;
use bevy::prelude::*;

pub fn run() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(MaterialPlugin::<GrateMaterial>::default())
        .add_plugins(MaterialPlugin::<TeleportMaterial>::default())
        .add_systems(Startup, setup)
        .add_systems(
            Update,
            (
                handle_teleport_input,
                animate_teleport,
                update_time,
                orbit_camera,
            ),
        )
        .run();
}

#[derive(Component)]
struct Hero;

#[derive(Component)]
struct OrbitCamera {
    radius: f32,
    angle: f32,
}

#[derive(Component)]
struct TeleportState {
    target_pos: Vec3,
    is_teleporting: bool,
    dissolve_progress: f32,
}

fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut grate_materials: ResMut<Assets<GrateMaterial>>,
    mut teleport_materials: ResMut<Assets<TeleportMaterial>>,
) {
    // Camera
    commands.spawn((
        Camera3d::default(),
        Transform::from_xyz(0.0, 5.0, 12.0).looking_at(Vec3::ZERO, Vec3::Y),
        OrbitCamera {
            radius: 12.0,
            angle: 0.0,
        },
    ));

    // Light
    commands.spawn((
        PointLight {
            intensity: 2_000_000.0,
            range: 20.0,
            ..default()
        },
        Transform::from_xyz(0.0, 10.0, 0.0),
    ));

    // 1. The Chamber (Perforated Metal)
    let wall_mesh = meshes.add(Rectangle::new(8.0, 4.0));
    let grate_mat = grate_materials.add(GrateMaterial::default());

    // Back Wall
    commands.spawn((
        Mesh3d(wall_mesh.clone()),
        MeshMaterial3d(grate_mat.clone()),
        Transform::from_xyz(0.0, 2.0, -4.0),
    ));
    // Front Wall
    commands.spawn((
        Mesh3d(wall_mesh),
        MeshMaterial3d(grate_mat),
        Transform::from_xyz(0.0, 2.0, 4.0),
    ));

    // 2. The Hero (Hologram)
    commands.spawn((
        Mesh3d(meshes.add(Capsule3d::default())),
        MeshMaterial3d(teleport_materials.add(TeleportMaterial::default())),
        Transform::from_xyz(0.0, 1.0, 0.0),
        Hero,
        TeleportState {
            target_pos: Vec3::ZERO,
            is_teleporting: false,
            dissolve_progress: 0.0,
        },
    ));

    // UI
    commands.spawn((
        Text::new(
            "CONTROLS:\n\
             [Space] Teleport Hero\n\
             [Left/Right] Orbit Camera",
        ),
        Node {
            position_type: PositionType::Absolute,
            top: Val::Px(12.0),
            left: Val::Px(12.0),
            ..default()
        },
    ));
}

fn update_time(time: Res<Time>, mut materials: ResMut<Assets<TeleportMaterial>>) {
    for (_, mat) in materials.iter_mut() {
        mat.time = time.elapsed_secs();
    }
}

fn orbit_camera(
    time: Res<Time>,
    keyboard: Res<ButtonInput<KeyCode>>,
    mut query: Query<(&mut Transform, &mut OrbitCamera)>,
) {
    let speed = 2.0;
    for (mut transform, mut orbit) in query.iter_mut() {
        if keyboard.pressed(KeyCode::ArrowLeft) {
            orbit.angle -= speed * time.delta_secs();
        }
        if keyboard.pressed(KeyCode::ArrowRight) {
            orbit.angle += speed * time.delta_secs();
        }

        let x = orbit.radius * orbit.angle.sin();
        let z = orbit.radius * orbit.angle.cos();

        transform.translation = Vec3::new(x, 5.0, z);
        transform.look_at(Vec3::new(0.0, 1.0, 0.0), Vec3::Y);
    }
}

fn handle_teleport_input(
    keyboard: Res<ButtonInput<KeyCode>>,
    mut query: Query<&mut TeleportState, With<Hero>>,
) {
    if keyboard.just_pressed(KeyCode::Space) {
        for mut state in query.iter_mut() {
            if !state.is_teleporting {
                state.is_teleporting = true;
                state.dissolve_progress = 0.0;
                let x = (rand::random::<f32>() - 0.5) * 6.0;
                state.target_pos = Vec3::new(x, 1.0, 0.0);
            }
        }
    }
}

fn animate_teleport(
    time: Res<Time>,
    mut materials: ResMut<Assets<TeleportMaterial>>,
    mut query: Query<(
        &mut Transform,
        &mut TeleportState,
        &MeshMaterial3d<TeleportMaterial>,
    )>,
) {
    for (mut transform, mut state, handle) in query.iter_mut() {
        if state.is_teleporting {
            state.dissolve_progress += time.delta_secs() * 2.0;

            if let Some(material) = materials.get_mut(handle) {
                if state.dissolve_progress < 1.0 {
                    // Dissolve
                    material.dissolve_amount = state.dissolve_progress;
                } else {
                    // Move & Reappear
                    if state.dissolve_progress < 1.1 {
                        transform.translation = state.target_pos;
                    }
                    material.dissolve_amount = 2.0 - state.dissolve_progress;
                }
            }

            if state.dissolve_progress >= 2.0 {
                state.is_teleporting = false;
                if let Some(material) = materials.get_mut(handle) {
                    material.dissolve_amount = 0.0;
                }
            }
        }
    }
}

Don't forget to add it to src/demos/mod.rs:

pub mod d03_07_teleport_demo;

And register it in src/main.rs:

Demo {
    number: "3.7",
    title: "Fragment Discard and Transparency",
    run: demos::d03_07_teleport_demo::run,
},

Running the Demo

Controls

What You're Seeing

1. The Grate (Alpha Mask): Notice the sharp, pixel-perfect edges of the holes. As you orbit the camera, look through the holes of the front wall to see the back wall. Because we use discard, the depth buffer works perfectly, and the sorting is correct.

2. The Hologram (Alpha Blend): The hero looks like a volume of light. Notice the scanlines and the rim glow.

3. The Teleport (Discard): When you press Space, the hero doesn't fade out evenly; they "burn away" into static. This demonstrates that you can use discard inside a blended material to create interesting erosion effects.

Key Takeaways

1. Discard is distinct from Alpha: Transparency (alpha < 1.0) blends colors. Discard deletes pixels.

2. Use Masks for Structure: For objects like fences, grates, or foliage, use AlphaMode::Mask (Discard). It's sharp, performant, and handles depth correctly.

3. Use Blend for Light: For objects that represent glass, ghosts, or energy, use AlphaMode::Blend.

4. Combine them for Effects: You can use discard inside a Blended shader to create dissolve, burn, or teleportation effects.

5. Disable Culling for Thin Objects: If you have a single-plane object (like a grate or leaf) that should be visible from both sides, remember to disable backface culling in the specialize method.

What's Next?

We've mastered how to draw pixels, how to move them, and how to delete them. Now it's time to look at the final stage of the pipeline: effects that happen after the scene is drawn.

Next up: 3.8 - Advanced Color Techniques

Quick Reference

Transparency Comparison

Choosing the right AlphaMode is the most important optimization you can make for transparent objects.

Performance Heuristics

• The Early-Z Penalty: Using discard in a shader usually disables the GPU's ability to skip hidden pixels (Early-Z). The shader must run for every pixel to decide if it should be deleted.

• The Overdraw Penalty: Alpha Blending requires reading and writing to the same pixel memory multiple times. Too many layers of smoke or glass will bottleneck your GPU's memory bandwidth.

• The Sorting Penalty: Bevy must sort all Blended objects on the CPU every frame. Avoid thousands of transparent objects.

Common Math for Effects

• Circular Hole: if length(uv - center) < radius { discard; }

• Grid: if step(width, sin(uv * scale)) < 0.5 { discard; }

• Dissolve: if noise(uv) < threshold { discard; }

• Rim Light: 1.0 - dot(view_dir, normal)

So far in this series, we've worked with mathematical functions like sine waves, smooth gradients, and geometric patterns. These are powerful, but they all share a common limitation: they are too perfect. Nature isn't perfectly regular - clouds don't form in neat circles, marble doesn't have uniform veins, and terrain doesn't follow mathematical curves. To create convincing organic materials, we need controlled chaos.

This is the world of Procedural Noise.

Unlike standard random number generators that produce "static," noise functions produce smooth, rolling hills of random values. This distinction is the foundation of almost every organic effect in computer graphics.

In this article, you will learn:

• Random vs. Noise: Why rand() creates TV static, but Noise creates landscapes.

• The Hash Function: How to generate deterministic pseudo-randomness from coordinates.

• Value vs. Gradient Noise: The evolution from blocky pixels to smooth Perlin-style noise.

• Fractal Brownian Motion (FBM): Layering noise to create complex detail like coastlines or clouds.

• Domain Warping: Using noise to distort other noise for liquid, gooey effects.

• Calculated vs. Texture Noise: When to compute it on the fly and when to load a texture.

Random vs. Noise: Understanding the Difference

Before writing code, we must distinguish between "randomness" and "noise."

Pure Randomness (White Noise)

A standard random function (like rand()) returns unrelated values. There is no correlation between an input of 0.1 and 0.2.

In graphics, this looks like "TV static" or snow. It is useful for dissolving pixels or sparkling glitter, but it doesn't look like a physical object.

Coherent Noise

Noise functions are coherent. This means that if you input two numbers that are close to each other, the return values will also be close to each other.

Visual Comparison

If we visualize these values as a 2D grayscale image, the difference is obvious:

The Four Properties of Good Noise

To be useful in a shader, our noise function needs four specific traits:

1. Deterministic: The same input coordinate (x, y) must always produce the exact same output value. This ensures the terrain doesn't flicker when we move the camera.

2. Continuous: The transition between values must be smooth (no sharp edges).

3. Apparent Randomness: While it follows a pattern, it shouldn't look like a repeating pattern to the human eye.

4. Controllable: We need to be able to scale the frequency (how wide the features are) and amplitude (how strong the features are).

Hash Functions: The Foundation

To generate noise, we first need a source of randomness. But in a shader, we don't have a rand() function that remembers previous states. Shaders run in parallel on thousands of pixels simultaneously; they can't share state.

Instead, we use a Hash Function.

A hash function takes an input (like a coordinate) and mangles it mathematically to produce a seemingly random number.

1. The Sine-Fract Hash

The most common "quick and dirty" hash used in shader tutorials relies on the chaotic nature of the sine wave at high amplitudes.

fn hash_2d(p: vec2<f32>) -> f32 {
    // 1. Dot Product: Squash the 2D vector into a single float
    // The "magic numbers" (127.1, 311.7) are arbitrary primes chosen to avoid patterns.
    let n = dot(p, vec2<f32>(127.1, 311.7));

    // 2. Sine Chaos: Apply sine and multiply by a huge number.
    // 43758.5453 is chosen because it scrambles the bits effectively.
    // 3. Fract: Keep only the decimal part.
    return fract(sin(n) * 43758.5453123);
}

How it works:

1. Dot Product: We mix x and y together. If we just added them (x+y), the pattern would be diagonal lines. Using different weights breaks that symmetry.

2. Sine: sin(n) gives a wave from -1 to 1.

3. Amplitude: Multiplying by 43758.54 creates a wave that oscillates wildly.

4. Fract: By taking the fractional part, we get a value between 0.0 and 1.0. Because the wave is oscillating so fast, moving just 0.0001 units in space results in a completely different decimal value.

Production Note: This sine-based hash is perfect for learning and small scenes, but it has limits. Because floating-point precision drops as numbers get larger, this function starts to show artifacts (patterns or solid blocks) at very large coordinates (e.g., p > 100,000.0). For infinite procedural worlds, developers use better hash functions (like PCG Hash) which are stable everywhere.

2. 3D Hash Function

If we are working in 3D space (like for a volumetric cloud shader), we simply add a third "magic number" to the dot product.

fn hash_3d(p: vec3<f32>) -> f32 {
    let n = dot(p, vec3<f32>(127.1, 311.7, 74.7));
    return fract(sin(n) * 43758.5453123);
}

Visualizing the Output

If we output this hash directly to the screen:

let noise = hash_2d(in.uv * 100.0);
return vec4<f32>(vec3<f32>(noise), 1.0);

We get "White Noise" - pure, unconnected static.

This is our raw material. To make it organic, we need to interpolate it.

Value Noise: Interpolating Random Values

The simplest form of procedural noise is Value Noise.

The concept is straightforward: imagine an infinite grid (like graph paper).

1. At every intersection (integer coordinate), we generate a random value using our Hash function.

2. For any point between the intersections, we smoothly blend the values of the four nearest corners.

The Concept

To find the value at point P:

1. Identify the 4 corners.

2. Hash them to get the random values (0.3, 0.9, 0.8, 0.2).

3. Blend based on how close P is to each corner.

Implementation

Here is the complete WGSL function for 2D Value Noise.

fn value_noise_2d(p: vec2<f32>) -> f32 {
    // 1. Grid Identification
    // floor(p) gives us the integer coordinate of the bottom-left corner.
    let i = floor(p);
    // fract(p) gives us the position within the grid square (0.0 to 1.0).
    let f = fract(p);

    // 2. Hash the 4 Corners
    // We add specific offsets to 'i' to get the 4 neighbor coordinates.
    let v00 = hash_2d(i + vec2<f32>(0.0, 0.0)); // Bottom-Left
    let v10 = hash_2d(i + vec2<f32>(1.0, 0.0)); // Bottom-Right
    let v01 = hash_2d(i + vec2<f32>(0.0, 1.0)); // Top-Left
    let v11 = hash_2d(i + vec2<f32>(1.0, 1.0)); // Top-Right

    // 3. Smooth Interpolation Curve
    // If we just used 'f' directly, we'd get linear mixing (pointy mountains).
    // We use a "Smoothstep" curve (Hermite interpolation) to round off the edges.
    // Formula: 3x^2 - 2x^3
    let u = f * f * (3.0 - 2.0 * f);

    // 4. Bilinear Interpolation (Mixing)
    // First, mix the bottom two corners horizontally
    let mix_bottom = mix(v00, v10, u.x);
    // Next, mix the top two corners horizontally
    let mix_top    = mix(v01, v11, u.x);
    // Finally, mix those two results vertically
    return mix(mix_bottom, mix_top, u.y);
}

Why the "Smooth" Step Matters

In step 3, we modified our interpolation factor f to create u. Why not just use f?

• Linear Mix (f): Creates sharp, diamond-shaped artifacts. The gradient changes abruptly at grid lines. It looks like a low-poly terrain.

• Smooth Mix (u): Creates an "S-curve." It starts slow, speeds up in the middle, and slows down at the end. This ensures the slope of the noise is zero at the grid boundaries, making the transition to the next grid cell invisible.

Characteristics of Value Noise

• Pros: Very cheap to calculate. Easy to understand.

• Cons: It tends to look "blocky" or "square-ish" because the random values are aligned to a strict grid. Even with smoothing, your eye can often detect the underlying squares.

To fix the "blockiness," we need something smarter: Gradient Noise.

Gradient Noise: Perlin-Style Smoothness

To solve the blocky look of Value Noise, Ken Perlin invented Gradient Noise (often called Perlin Noise).

The Key Difference

In Value Noise, we assigned a random height (0.0 to 1.0) to each grid corner.
In Gradient Noise, we assign a random slope (direction vector) to each grid corner.

Instead of simply interpolating the height, we calculate the height based on where the slope "points."

• If the slope at a corner points towards our pixel, the value increases.

• If it points away, the value decreases.

This results in a structure that naturally rises and falls like waves, hiding the underlying grid structure much better than Value Noise.

Implementation

Implementing Gradient Noise is slightly more complex. We need a helper function to turn our hash into a random unit vector.

// Helper: Turn a grid coordinate into a random unit vector
fn random_gradient_2d(cell: vec2<f32>) -> vec2<f32> {
    // 1. Get a random angle (0 to 2PI)
    let random = hash_2d(cell);
    let angle = random * 6.283185307; // 2 * PI

    // 2. Convert angle to a vector (x, y)
    return vec2<f32>(cos(angle), sin(angle));
}

fn gradient_noise_2d(p: vec2<f32>) -> f32 {
    // 1. Grid Identification (Same as Value Noise)
    let i = floor(p);
    let f = fract(p);

    // 2. Get smooth interpolation weights (The S-Curve)
    let u = f * f * (3.0 - 2.0 * f);

    // 3. Calculate the 4 corners
    // For each corner, we do two things:
    //   a. Get the random gradient vector (g)
    //   b. Get the distance vector from corner to pixel (d)
    //   c. Dot product (g . d) determines the value contribution

    // Bottom-Left
    let g00 = random_gradient_2d(i + vec2<f32>(0.0, 0.0));
    let d00 = f - vec2<f32>(0.0, 0.0);
    let v00 = dot(g00, d00);

    // Bottom-Right
    let g10 = random_gradient_2d(i + vec2<f32>(1.0, 0.0));
    let d10 = f - vec2<f32>(1.0, 0.0);
    let v10 = dot(g10, d10);

    // Top-Left
    let g01 = random_gradient_2d(i + vec2<f32>(0.0, 1.0));
    let d01 = f - vec2<f32>(0.0, 1.0);
    let v01 = dot(g01, d01);

    // Top-Right
    let g11 = random_gradient_2d(i + vec2<f32>(1.0, 1.0));
    let d11 = f - vec2<f32>(1.0, 1.0);
    let v11 = dot(g11, d11);

    // 4. Bilinear Interpolation
    // Blend the dot product results
    let mix_bottom = mix(v00, v10, u.x);
    let mix_top    = mix(v01, v11, u.x);
    let result     = mix(mix_bottom, mix_top, u.y);

    // 5. Normalization
    // The result of the dot products is roughly between -0.7 and 0.7.
    // We map it to 0.0 -> 1.0 for easier use in colors.
    return result * 0.5 + 0.5;
}

3D Gradient Noise

The concept extends perfectly to 3D. Instead of a square with 4 corners, we use a cube with 8 corners. We generate 3D gradient vectors for each corner, calculate dot products, and use trilinear interpolation (mix X, then mix Y, then mix Z).

This is the standard noise used for volumetric clouds, smoke, and marble.

Pro Tip: Simplex Noise
You might hear about "Simplex Noise." It is an improvement on Perlin Noise that uses a triangular grid (triangles/tetrahedrons) instead of squares/cubes. It is faster in high dimensions and has fewer artifacts. However, the math is significantly harder to implement from scratch. For most game effects, standard Gradient Noise is perfectly sufficient and easier to debug.

Fractal Brownian Motion (FBM)

Single-layer noise is smooth, but it looks like "blobs." It lacks the gritty detail of real nature.
Real terrain has large mountains, medium boulders, small rocks, and tiny pebbles.

To mimic this, we use Fractal Brownian Motion (FBM).
FBM isn't a new type of noise; it's a technique of layering noise. We stack multiple layers (called Octaves) of noise on top of each other.

The Formula

For each new layer, we change two things:

1. Frequency: We zoom out (multiply the coordinate). Usually doubled (x2).

2. Amplitude: We reduce the strength. Usually halved (x0.5).

Implementation

fn fbm_noise(p: vec2<f32>, octaves: u32) -> f32 {
    var value = 0.0;
    var amplitude = 0.5;
    var frequency = 1.0;

    // Loop through the octaves
    for (var i = 0u; i < octaves; i++) {
        // Sample the noise
        value += amplitude * gradient_noise_2d(p * frequency);

        // Prepare for next layer
        frequency *= 2.0; // "Lacunarity": How fast frequency grows
        amplitude *= 0.5; // "Gain": How fast amplitude shrinks
    }

    return value;
}

FBM Parameters

You can tweak the "feel" of the noise by changing the multipliers:

• Lacunarity (Frequency multiplier): Controls how "busy" the detail is. Higher values (e.g., 3.0) make the detail look more scattered.

• Gain (Amplitude multiplier): Controls "roughness."

  • 0.5: Standard "cloudy" look.

  • 0.8: Very rough, noisy look (good for rocks).

  • 0.3: Very smooth, subtle detail (good for water).

Specialized FBM: Turbulence

If we take the absolute value of the noise abs(noise) before adding it, we turn the smooth valleys into sharp creases. This creates a "Ridged" look, perfect for fire, lightning, or marble veins.

// Turbulence: Sharp valleys
value += amplitude * abs(gradient_noise_2d(p * frequency));

Domain Warping

If FBM is the tool for adding detail, Domain Warping is the tool for adding "flow." It is the secret technique behind liquid, surreal, and highly organic effects.

The concept is meta: Use the output of one noise function to distort the input coordinates of another.

fn domain_warp(p: vec2<f32>) -> f32 {
    // 1. Create a vector based on noise
    let offset = vec2<f32>(
        gradient_noise_2d(p),
        gradient_noise_2d(p + 5.2) // Offset to get a different random value
    );

    // 2. Distort the original coordinate 'p' by this noisy offset
    // The multiplier (4.0) controls the strength of the warp
    let warped_p = p + offset * 4.0;

    // 3. Sample noise at the new, warped location
    return gradient_noise_2d(warped_p);
}

Visualizing the effect:
Imagine a pattern of straight stripes.

• Standard Noise: The stripes get brighter and darker, but stay straight.

• Domain Warping: The stripes bend, twist, and swirl like oil paint on water.

This technique is essential for effects like smoke, fire, marble, and psychedelic backgrounds.

Texture-Based vs. Calculated Noise

In game development, you have two ways to get noise into your shader. Knowing which to choose is a critical optimization skill.

1. Calculated Noise (What we just learned)

We compute the noise math inside the shader, on the fly, for every pixel.

• ✅ Pros: Infinite resolution. No pixels ever. You can animate it easily by adding time to the coordinates. 3D noise costs no memory.

• ❌ Cons: Expensive. Calculating FBM with 6 octaves requires dozens of math operations per pixel. Heavy use can drop your frame rate, especially on mobile GPUs.

2. Texture-Based Noise

We generate the noise offline (in Photoshop or code), save it as a seamlessly tiling PNG texture, and sample it.

• ✅ Pros: Extremely fast. It's just one memory lookup (textureSample).

• ❌ Cons: Finite resolution. If you get too close, you see pixels (unless you mix in expensive texture filtering). Repetition can be obvious.

The Hybrid "Pro" Approach

Triple-A games often combine both:

1. Use a Noise Texture for the base shape (low frequency). This is fast and covers the bulk of the work.

2. Add Calculated Noise for the tiny details (high frequency) on top.

Since the tiny details are small, you often only need 1 or 2 octaves of calculated noise to make the texture look infinite, saving massive amounts of GPU power compared to calculating the whole thing.

Recipes: Organic Patterns

Before we build the final demo, here are the "recipes" for common materials. These are just logical combinations of the functions we've built.

Wood

Wood is composed of rings (distance from a center line) distorted by noise.

// 1. Basic Ring Pattern
let dist = length(p.xy);     // Distance from center
let rings = sin(dist * 20.0); // Concentric rings

// 2. Make it Organic
// Add noise to the coordinate BEFORE calculating distance
let noise = gradient_noise_3d(p);
let dist = length(p.xy + noise * 0.5); // Distorted distance
let wood_grain = sin(dist * 20.0);

Marble

Marble is smooth rock with sharp veins. We use Turbulence (absolute value of noise) to create the veins, and use the sine function to create layers.

let noise = turbulence(p * 2.0); 
// Distortion creates the "veins" through the sine wave layers
let marble = sin(p.x * 10.0 + noise * 5.0);

Clouds

Clouds are simply FBM masked by a density threshold.

let density = fbm_noise(p, 6u);
// Smoothstep clears out the low-density "wisps" to create empty sky
let cloud = smoothstep(0.4, 0.8, density);

Complete Example: Animated Procedural Clouds

We will build a shader that renders a dynamic, wind-blown sky. It uses:

1. Gradient Noise for the base.

2. FBM to create fluffy detail.

3. Domain Warping to make the clouds drift and morph organically.

4. Time-based animation for wind.

Our Goal

A sky quad where clouds drift, morph, and interact with a "sun" light direction.

The Shader (assets/shaders/d03_06_procedural_clouds.wgsl)

Note on Imports: In a real project, you would put the noise functions in a file like assets/shaders/noise_utils.wgsl and import them using #import "shaders/noise_utils.wgsl"::hash_2d. For this tutorial, we include them in the same file to make copy-pasting easier.

#import bevy_pbr::forward_io::VertexOutput

struct CloudMaterial {
    time: f32,
    cloud_scale: f32,
    cloud_speed: f32,
    density_threshold: f32,
    octaves: u32,
    // Colors
    sky_color_a: vec4<f32>,
    sky_color_b: vec4<f32>,
    cloud_color: vec4<f32>,
}

@group(2) @binding(0)
var<uniform> material: CloudMaterial;

// --- NOISE LIBRARY START ---

fn hash_2d(p: vec2<f32>) -> f32 {
    let n = dot(p, vec2<f32>(127.1, 311.7));
    return fract(sin(n) * 43758.5453123);
}

fn noise_2d(p: vec2<f32>) -> f32 {
    let i = floor(p);
    let f = fract(p);

    // Four corners
    let a = hash_2d(i);
    let b = hash_2d(i + vec2<f32>(1.0, 0.0));
    let c = hash_2d(i + vec2<f32>(0.0, 1.0));
    let d = hash_2d(i + vec2<f32>(1.0, 1.0));

    // Smooth interpolation
    let u = f * f * (3.0 - 2.0 * f);

    // Mix
    return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);
}

// Simple FBM
fn fbm(p: vec2<f32>, octaves: u32) -> f32 {
    var value = 0.0;
    var amp = 0.5;
    var freq = 1.0;

    for(var i = 0u; i < octaves; i++) {
        value += amp * noise_2d(p * freq);
        freq *= 2.0;
        amp *= 0.5;
    }
    return value;
}

// --- NOISE LIBRARY END ---

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    // 1. Correct UVs to be centered and proportional
    let uv = in.uv * material.cloud_scale;

    // 2. Animate coordinates (Wind)
    let wind = vec2<f32>(material.time * material.cloud_speed, material.time * material.cloud_speed * 0.2);
    let p = uv + wind;

    // 3. Domain Warping
    // We use low-frequency noise to distort the input of the high-freq FBM
    let q = vec2<f32>(
        fbm(p, material.octaves),
        fbm(p + vec2<f32>(5.2, 1.3), material.octaves)
    );

    // The actual cloud density calculation
    // We warp 'p' by adding 'q'
    let density = fbm(p + q * 1.5, material.octaves);

    // 4. Shaping the Clouds
    // Use smoothstep to create defined cloud shapes vs empty sky
    let cloud_mask = smoothstep(material.density_threshold, material.density_threshold + 0.2, density);

    // 5. Coloring
    // Gradient sky background
    let sky = mix(material.sky_color_a, material.sky_color_b, in.uv.y);

    // Mix sky with cloud color
    // We add a subtle highlight based on the density derivative for fake depth
    let final_color = mix(sky, material.cloud_color, cloud_mask);

    return final_color;
}

The Rust Material (src/materials/d03_06_procedural_clouds.rs)

We map the Rust struct to the WGSL struct. Note that vec4<f32> in WGSL requires 16-byte alignment. Bevy's ShaderType derive macro handles the padding between the u32 (octaves) and the first color automatically, ensuring the data aligns correctly in the GPU buffer.

use bevy::prelude::*;
use bevy::render::render_resource::{AsBindGroup, ShaderRef};

pub mod uniforms {
    #![allow(dead_code)]
    use bevy::prelude::*;
    use bevy::render::render_resource::ShaderType;

    #[derive(ShaderType, Debug, Clone)]
    pub struct CloudMaterialUniforms {
        pub time: f32,
        pub cloud_scale: f32,
        pub cloud_speed: f32,
        pub density_threshold: f32,
        pub octaves: u32,
        pub sky_color_a: LinearRgba,
        pub sky_color_b: LinearRgba,
        pub cloud_color: LinearRgba,
    }
}

use uniforms::CloudMaterialUniforms;

#[derive(Asset, TypePath, AsBindGroup, Debug, Clone)]
pub struct CloudMaterial {
    #[uniform(0)]
    pub uniforms: CloudMaterialUniforms,
}

impl Default for CloudMaterial {
    fn default() -> Self {
        Self {
            uniforms: CloudMaterialUniforms {
                time: 0.0,
                cloud_scale: 3.5,
                cloud_speed: 0.2,
                density_threshold: 0.5,
                octaves: 4,
                sky_color_a: LinearRgba::new(0.0, 0.4, 0.8, 1.0), // Deep Blue
                sky_color_b: LinearRgba::new(0.4, 0.7, 1.0, 1.0), // Cyan
                cloud_color: LinearRgba::new(1.0, 1.0, 1.0, 1.0), // White
            },
        }
    }
}

impl Material for CloudMaterial {
    fn fragment_shader() -> ShaderRef {
        "shaders/d03_06_procedural_clouds.wgsl".into()
    }
}

Don't forget to add it to src/materials/mod.rs:

pub mod d03_06_procedural_clouds;

The Demo Module (src/demos/d03_06_procedural_clouds.rs)

This demo sets up a live environment where you can tune the noise parameters. Seeing how octaves affects detail or how density_threshold changes the cloud cover in real-time is the best way to understand the math.

use crate::materials::d03_06_procedural_clouds::CloudMaterial;
use bevy::prelude::*;

pub fn run() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(MaterialPlugin::<CloudMaterial>::default())
        .add_systems(Startup, setup)
        .add_systems(Update, (update_time, handle_input, update_ui))
        .run();
}

fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<CloudMaterial>>,
) {
    commands.spawn((Camera3d::default(), Transform::from_xyz(0.0, 0.0, 2.0)));

    commands.spawn((
        Mesh3d(meshes.add(Rectangle::new(2.0, 2.0))),
        MeshMaterial3d(materials.add(CloudMaterial::default())),
        Transform::default(),
    ));

    // UI Information
    commands.spawn((
        Text::new("Procedural Clouds Demo"),
        Node {
            position_type: PositionType::Absolute,
            top: Val::Px(12.0),
            left: Val::Px(12.0),
            ..default()
        },
        TextFont {
            font_size: 16.0,
            ..default()
        },
        TextColor(Color::WHITE),
        BackgroundColor(Color::srgba(0.0, 0.0, 0.0, 0.7)),
    ));
}

fn update_time(time: Res<Time>, mut materials: ResMut<Assets<CloudMaterial>>) {
    for (_, material) in materials.iter_mut() {
        material.uniforms.time = time.elapsed_secs();
    }
}

fn handle_input(keyboard: Res<ButtonInput<KeyCode>>, mut materials: ResMut<Assets<CloudMaterial>>) {
    for (_, material) in materials.iter_mut() {
        let u = &mut material.uniforms;

        // Density
        if keyboard.pressed(KeyCode::ArrowUp) {
            u.density_threshold = (u.density_threshold + 0.01).min(1.0);
        }
        if keyboard.pressed(KeyCode::ArrowDown) {
            u.density_threshold = (u.density_threshold - 0.01).max(0.0);
        }

        // Scale
        if keyboard.pressed(KeyCode::ArrowRight) {
            u.cloud_scale += 0.05;
        }
        if keyboard.pressed(KeyCode::ArrowLeft) {
            u.cloud_scale = (u.cloud_scale - 0.05).max(0.1);
        }

        // Octaves (Integer steps)
        if keyboard.just_pressed(KeyCode::KeyO) {
            u.octaves = u.octaves.saturating_sub(1).max(1);
        }
        if keyboard.just_pressed(KeyCode::KeyP) {
            u.octaves = (u.octaves + 1).min(8);
        }
    }
}

fn update_ui(materials: Res<Assets<CloudMaterial>>, mut text_query: Query<&mut Text>) {
    if let Some((_, mat)) = materials.iter().next() {
        let u = &mat.uniforms;
        for mut text in text_query.iter_mut() {
            **text = format!(
                "CONTROLS:\n\
                [Up/Down] Density Threshold: {:.2}\n\
                [Left/Right] Scale: {:.2}\n\
                [O/P] Octaves: {}\n\
                (Watch the detail change with Octaves!)",
                u.density_threshold, u.cloud_scale, u.octaves
            );
        }
    }
}

Don't forget to add it to src/demos/mod.rs:

pub mod d03_06_procedural_clouds;

And register it in src/main.rs:

Demo {
    number: "3.6a",
    title: "Procedural Noise - Clouds",
    run: demos::d03_06_procedural_clouds::run,
},

Running the Demo

Controls

What You're Seeing

• The Drift: The clouds move continuously because we add time to the UVs.

• The Shape: It doesn't look like a repeating texture. It looks organic because of Domain Warping.

• The Edges: The smoothstep creates soft, fluffy edges instead of hard cutouts.

• Detail Levels: Press 'O' until Octaves = 1. You will see blurry, shapeless blobs. Press 'P' up to 4 or 5, and notice how the tiny, gritty details appear on the edges. That is FBM in action.

Bonus Mini-Project: Procedural Marble

While clouds use 2D noise to manipulate UVs, solid materials like marble, wood, or stone use 3D noise based on World Position. This ensures that the texture wraps perfectly around the object without seams, stretching, or UV mapping headaches.

This technique is often called Solid Texturing. Imagine carving your object out of a solid block of wood or stone; the grain exists inside the object, not just painted on the surface.

The Shader (assets/shaders/procedural_marble.wgsl)

#import bevy_pbr::forward_io::VertexOutput

struct MarbleMaterial {
    vein_frequency: f32,
    roughness: f32,
    vein_color: vec4<f32>,
    base_color: vec4<f32>,
}

@group(2) @binding(0)
var<uniform> material: MarbleMaterial;

// --- 3D NOISE FUNCTIONS ---

fn hash_3d(p: vec3<f32>) -> f32 {
    let n = dot(p, vec3<f32>(127.1, 311.7, 74.7));
    return fract(sin(n) * 43758.5453123);
}

fn noise_3d(p: vec3<f32>) -> f32 {
    let i = floor(p);
    let f = fract(p);

    // Smooth interpolation (S-Curve)
    let u = f * f * (3.0 - 2.0 * f);

    // 8 Corners of the cube
    let a = hash_3d(i + vec3<f32>(0.0, 0.0, 0.0));
    let b = hash_3d(i + vec3<f32>(1.0, 0.0, 0.0));
    let c = hash_3d(i + vec3<f32>(0.0, 1.0, 0.0));
    let d = hash_3d(i + vec3<f32>(1.0, 1.0, 0.0));
    let e = hash_3d(i + vec3<f32>(0.0, 0.0, 1.0));
    let f_ = hash_3d(i + vec3<f32>(1.0, 0.0, 1.0)); // 'f' is reserved
    let g = hash_3d(i + vec3<f32>(0.0, 1.0, 1.0));
    let h = hash_3d(i + vec3<f32>(1.0, 1.0, 1.0));

    // Trilinear Mix
    let mix_1 = mix(mix(a, b, u.x), mix(c, d, u.x), u.y);
    let mix_2 = mix(mix(e, f_, u.x), mix(g, h, u.x), u.y);
    return mix(mix_1, mix_2, u.z);
}

// Turbulence: Sum of absolute noise values
fn turbulence(p: vec3<f32>, octaves: u32) -> f32 {
    var value = 0.0;
    var amp = 0.5;
    var freq = 1.0;

    for(var i = 0u; i < octaves; i++) {
        // abs() creates the sharp ridges for veins
        value += amp * abs(noise_3d(p * freq));
        freq *= 2.0;
        amp *= 0.5;
    }
    return value;
}

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    // Solid Texturing: Use world position.
    let p = in.world_position.xyz;

    // 1. Calculate Turbulence
    let t = turbulence(p * material.roughness, 4u);

    // 2. Domain Warping the Sine Wave
    // Standard marble formula: sin(x + turbulence)
    // The sine wave creates layers; the turbulence distorts them.
    let pattern = sin(p.x * material.vein_frequency + t * 4.0);

    // 3. Map -1.0 to 1.0 range -> 0.0 to 1.0 range
    let mask = pattern * 0.5 + 0.5;

    // 4. Sharpen the veins
    let sharp_mask = pow(mask, 4.0);

    return mix(material.vein_color, material.base_color, sharp_mask);
}

The Rust Material (src/materials/procedural_marble.rs)

use bevy::prelude::*;
use bevy::render::render_resource::{AsBindGroup, ShaderRef};

pub mod uniforms {
    #![allow(dead_code)]
    use bevy::prelude::*;
    use bevy::render::render_resource::ShaderType;

    #[derive(ShaderType, Debug, Clone)]
    pub struct MarbleMaterialUniforms {
        pub vein_frequency: f32,
        pub roughness: f32,
        pub vein_color: LinearRgba,
        pub base_color: LinearRgba,
    }
}

use uniforms::MarbleMaterialUniforms;

#[derive(Asset, TypePath, AsBindGroup, Debug, Clone)]
pub struct MarbleMaterial {
    #[uniform(0)]
    pub uniforms: MarbleMaterialUniforms,
}

impl Default for MarbleMaterial {
    fn default() -> Self {
        Self {
            uniforms: MarbleMaterialUniforms {
                vein_frequency: 10.0,
                roughness: 1.5,
                vein_color: LinearRgba::new(0.1, 0.1, 0.1, 1.0),
                base_color: LinearRgba::new(0.9, 0.9, 0.85, 1.0),
            },
        }
    }
}

impl Material for MarbleMaterial {
    fn fragment_shader() -> ShaderRef {
        "shaders/procedural_marble.wgsl".into()
    }
}

Don't forget to add it to src/materials/mod.rs:

pub mod procedural_marble;

The Demo Module (src/demos/procedural_marble.rs)

use crate::materials::procedural_marble::MarbleMaterial;
use bevy::prelude::*;

pub fn run() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(MaterialPlugin::<MarbleMaterial>::default())
        .add_systems(Startup, setup)
        .add_systems(Update, (handle_input, update_ui))
        .run();
}

#[derive(Component)]
struct Movable;

fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<MarbleMaterial>>,
) {
    commands.spawn((
        Camera3d::default(),
        Transform::from_xyz(0.0, 2.0, 4.0).looking_at(Vec3::ZERO, Vec3::Y),
    ));

    // Shared material handle ensures settings apply to both objects
    let material = materials.add(MarbleMaterial::default());

    // 1. Stationary Cube (The "Base")
    commands.spawn((
        Mesh3d(meshes.add(Cuboid::new(2.0, 2.0, 2.0))),
        MeshMaterial3d(material.clone()),
        Transform::from_xyz(-1.2, 0.0, 0.0),
    ));

    // 2. Movable Sphere (The "Rover")
    commands.spawn((
        Mesh3d(meshes.add(Sphere::new(1.2))),
        MeshMaterial3d(material),
        Transform::from_xyz(1.2, 0.0, 0.0),
        Movable,
    ));

    commands.spawn((
        Text::new("Marble Demo"),
        Node {
            position_type: PositionType::Absolute,
            top: Val::Px(12.0),
            left: Val::Px(12.0),
            ..default()
        },
    ));
}

fn handle_input(
    time: Res<Time>,
    keyboard: Res<ButtonInput<KeyCode>>,
    mut materials: ResMut<Assets<MarbleMaterial>>,
    mut query: Query<&mut Transform, With<Movable>>,
) {
    // Material Controls
    for (_, material) in materials.iter_mut() {
        let u = &mut material.uniforms;
        if keyboard.pressed(KeyCode::KeyW) {
            u.vein_frequency += 0.1;
        }
        if keyboard.pressed(KeyCode::KeyS) {
            u.vein_frequency = (u.vein_frequency - 0.1).max(0.0);
        }
    }

    // Movement Controls
    let speed = 2.0 * time.delta_secs();
    for mut transform in query.iter_mut() {
        if keyboard.pressed(KeyCode::ArrowLeft) {
            transform.translation.x -= speed;
        }
        if keyboard.pressed(KeyCode::ArrowRight) {
            transform.translation.x += speed;
        }
        if keyboard.pressed(KeyCode::ArrowUp) {
            transform.translation.z -= speed;
        }
        if keyboard.pressed(KeyCode::ArrowDown) {
            transform.translation.z += speed;
        }
    }
}

fn update_ui(materials: Res<Assets<MarbleMaterial>>, mut text_query: Query<&mut Text>) {
    if let Some((_, mat)) = materials.iter().next() {
        let u = &mat.uniforms;
        for mut text in text_query.iter_mut() {
            **text = format!(
                "CONTROLS:\n\
                [Arrow Keys] Move Sphere\n\
                [W/S] Vein Frequency: {:.1}",
                u.vein_frequency
            );
        }
    }
}

Don't forget to add it to src/demos/mod.rs:

pub mod procedural_marble;

And register it in src/main.rs:

Demo {
    number: "3.6b",
    title: "Procedural Noise - Marble",
    run: demos::d03_06_procedural_clouds::run,
},

Running the Demo

Controls

What You're Seeing

• The "Swimming" Effect: As you move the sphere, the veins don't travel with it; they slide across the surface. This visually proves that the veins exist at specific coordinates in the world (in.world_position), like a cloud that the object is passing through.

• Seamless Intersection: Move the sphere so it overlaps the cube. Notice how the veins line up perfectly at the junction. This is the superpower of solid texturing - you can jam any number of objects together, and they will look like a single carved block.

Key Takeaways

1. Noise ≠ Random: Random is static; Noise is a smooth landscape.

2. Gradient Noise: The standard for natural looks. It interpolates slopes, not just heights.

3. FBM (Fractals): Realism comes from layering noise at different frequencies (Octaves).

4. Domain Warping: Distorting the coordinate space creates liquid, swirling effects.

5. World Space Texturing: Using world_position instead of uv allows you to texture objects seamlessly in 3D, creating the effect of solid materials like stone or wood.

What's Next?

We have mastered shapes with SDFs and textures with Noise. But there is a rendering technique that lets us simply delete pixels to create complex silhouettes like foliage, fences, or grates without extra geometry.

Next up: 3.7 - Fragment Discard and Transparency

Quick Reference

Concept Map

Hash vs. Noise

• Hash: Returns a single, chaotic, unrelated number. (TV Static)

• Noise: Returns a value related to its neighbors. (Rolling Hills)

• Value Noise: Interpolates random heights at grid corners. (Blocky)

• Gradient Noise: Interpolates random slopes at grid corners. (Smooth/Natural)

FBM (Fractal Brownian Motion)

Layering noise to create detail.

• Octaves: How many layers you stack. (More = more detail, more cost).

• Lacunarity: How much the frequency increases per layer. (Usually x2).

• Gain/Persistence: How much the amplitude decreases per layer. (Usually x0.5).

Noise Modifiers

• Turbulence: abs(noise). Sharp valleys. Used for: Fire, Veins, Lightning.

• Ridged Multifractal: 1.0 - abs(noise). Inverted valleys (sharp peaks). Used for: Terrain ranges.

• Domain Warping: noise(p + noise(p)). Distorting coordinates. Used for: Liquids, Smoke, Marble.

2D vs 3D Noise usage

• 2D Noise: Use in.uv. Good for surfaces, clouds, water planes.

• 3D Noise: Use in.world_position. Good for solid objects (wood, stone) or volumetric fog.

In previous articles, we created patterns using explicit boundaries: "Is this pixel inside the square?" But there is a more powerful way to define shapes in computer graphics: "How far is this pixel from the edge?"

This is the world of Signed Distance Functions (SDFs). Instead of defining shapes as rigid masks, we define them as mathematical fields of distance. This shift unlocks capabilities that are impossible with traditional texture sprites or simple grid logic.

In this article, you will learn:

• The SDF Mindset: Why treating shapes as distance fields is superior to hard masks.

• Primitive Shapes: How to build circles, rectangles, and polygons using simple math.

• Boolean Operations: Combining shapes using min() and max() instead of if statements.

• Smooth Blending: How to melt shapes together like liquid mercury.

• Distance-Based Effects: Creating free outlines, glows, and soft shadows from a single value.

• Infinite Resolution: Why SDFs look perfectly crisp at any zoom level or rotation.

Understanding Distance Fields

Before writing code, we need to understand the fundamental concept.

What is a Distance Field?

In a standard image (like a PNG texture), every pixel stores a color.
In a distance field, every pixel stores a number: the distance to the nearest edge of a shape.

For a circle, the "field" looks like a gradient radiating from the center.

The "Signed" Part

The "Signed" in SDF is crucial. It gives us orientation:

• Negative (d < 0.0): Inside the shape.

• Zero (d = 0.0): Exactly on the surface/edge.

• Positive (d > 0.0): Outside the shape.

This sign tells us immediately not just where we are, but relationship to the shape.

// Example: A Circle SDF
// A point at the exact center has a distance of -radius.
// A point on the edge has a distance of 0.0.
let dist = length(p - center) - radius;

Visualizing the Field

Because an SDF is just a number, we can visualize it directly in the shader to debug our math.

1. The "Heatmap" View

If we output the distance directly as color, the "inside" (negative) becomes black (clamped to 0.0), and the "outside" (positive) becomes a gradient from black to white.

let dist = sdf_circle(uv, center, radius);
return vec4<f32>(vec3<f32>(dist), 1.0);

2. The "Contour" View

We can use math to draw lines at specific distance intervals, like a topographic map.

let dist = sdf_circle(uv, center, radius);
// Create repeating rings every 0.1 units
let contour = step(0.9, fract(dist * 10.0));
return vec4<f32>(vec3<f32>(contour), 1.0);

Why This Paradigm is Powerful

Why go through the trouble of calculating distances instead of just drawing a circle?

1. Infinite Resolution: SDFs are mathematical. They have no pixels. You can zoom in 1000x, and the edge will remain mathematically perfect.

2. Free Effects: Once you have the dist variable, you can create a stroke (outline) just by checking if abs(dist) < width. You can create a glow by checking dist < glow_radius.

3. Smooth Operations: You can blend shapes together smoothly by mathematically interpolating their distance values, something that is incredibly hard to do with standard geometry or textures.

Building Primitive SDFs

An SDF is just a function that takes a position (p) and returns a distance (f32).

The Coordinate System

To make the math easy, SDF functions usually assume the shape is centered at (0,0). Since our UV coordinates range from (0,0) to (1,0), we need to adjust them before passing them to the SDF.

// 1. Center the coordinates
// 0.0 to 1.0  -->  -0.5 to 0.5
let p = in.uv - 0.5;

// 2. Correct aspect ratio (if your quad isn't a square)
// p.x *= aspect_ratio;

// 3. Calculate distance
let dist = sdf_circle(p, radius);

1. The Circle

The circle is our baseline. It relies on length(), which is the Euclidean distance formula ($\sqrt{x2+y2}​$).

fn sdf_circle(p: vec2<f32>, radius: f32) -> f32 {
    return length(p) - radius;
}

How it works: We calculate the distance from the origin to our pixel. By subtracting the radius, we shift the "zero point" from the center of the circle out to its edge.

• If the pixel is at the center, distance is 0.0. Result: -radius (Deep inside).

• If the pixel is on the edge, distance is radius. Result: 0.0 (On edge).

• If the pixel is far away, distance is huge. Result: Positive (Outside).

2. The Rectangle

Rectangles introduce the concept of component-wise distance. We analyze the X distance and Y distance separately.

fn sdf_rectangle(p: vec2<f32>, half_size: vec2<f32>) -> f32 {
    // 1. Shift origin to the corner of the box
    // Inside the box, 'd' is negative. Outside, it's positive.
    let d = abs(p) - half_size;

    // 2. Calculate Outside Distance (for points outside the box)
    // If d.x or d.y is negative (we are next to an edge), clamp it to 0.
    // If both are positive (we are near a corner), length() gives precise distance to corner.
    let outside = length(max(d, vec2<f32>(0.0)));

    // 3. Calculate Inside Distance (for points inside the box)
    // We want the distance to the CLOSEST edge, which is the larger (less negative) value.
    // We clamp to 0 so this doesn't affect outside points.
    let inside = min(max(d.x, d.y), 0.0);

    return outside + inside;
}

How it works:

Imagine extending the sides of the rectangle to infinity. This creates a grid of 9 zones. The math handles each zone differently.

1. The Corners (Zones 1, 3, 7, 9):
   Here, the pixel is outside both the X range and the Y range.

   • d.x is positive, d.y is positive.

   • length(d) calculates the diagonal distance to the corner point.

2. The Edges (Zones 2, 4, 6, 8):
   Here, the pixel is aligned with the box on one axis, but outside on the other.

   • Example Zone 2: d.x is negative (aligned), d.y is positive (above).

   • max(d, 0.0) clamps the negative X to 0.0.

   • The vector becomes (0.0, d.y). The length is just d.y. This gives us a straight linear distance.

3. The Inside (Zone 5):
   Here, the pixel is inside the box.

   • d.x and d.y are both negative.

   • The outside calculation becomes length(0,0) which is 0.

   • The inside calculation picks the largest value (e.g., -0.1 is larger than -5.0). This ensures we measure distance to the closest edge.

3. The Rounded Box

Once you have a rectangle, making it rounded is incredibly simple. You don't change the math of the box; you change the definition of the "edge."

fn sdf_rounded_box(p: vec2<f32>, half_size: vec2<f32>, radius: f32) -> f32 {
    // A rounded box is just a standard box...
    let d = sdf_rectangle(p, half_size);

    // ...with the edge "inflated" by the radius.
    return d - radius;
}

How it works

In a sharp box, the value 0.0 is at the sharp walls.
By subtracting radius from the result, the value 0.0 moves outwards.

• The straight walls move out by radius.

• The corners, which previously measured distance from a single point, now measure distance radius away from that point... creating a perfect circular arc.

4. The Line Segment

Drawing a line between two arbitrary points (A and B) is essential for debug drawing, lasers, or skeletal animation.

fn sdf_line(p: vec2<f32>, a: vec2<f32>, b: vec2<f32>, thickness: f32) -> f32 {
    let pa = p - a;
    let ba = b - a;

    // Project point p onto the line 'ba'.
    // Clamp ensures we stop at the endpoints A and B.
    let h = clamp(dot(pa, ba) / dot(ba, ba), 0.0, 1.0);

    // Distance from P to the closest point on the line
    return length(pa - ba * h) - thickness;
}

How it works

This uses the Dot Product projection technique.

1. We project the pixel's position onto the infinite line passing through A and B.

2. The clamp(..., 0.0, 1.0) restricts that projection to the segment itself. If you project past B, it snaps back to B.

3. We calculate the distance to that snapped point.

5. The Cross (Union of Boxes)

Complex shapes can often be built by combining simple ones. A cross is just a horizontal box merged with a vertical box.

fn sdf_cross(p: vec2<f32>, size: f32, thick: f32) -> f32 {
    // 1. Horizontal Box
    let rect_a = sdf_box(p, vec2<f32>(size, thick));
    // 2. Vertical Box
    let rect_b = sdf_box(p, vec2<f32>(thick, size));

    // 3. Union (min)
    return min(rect_a, rect_b);
}

How it works

We calculate two separate distance fields: one for a wide, short box, and one for a tall, thin box.
By taking the min(), we effectively weld them together. Any pixel inside either box is considered inside the cross.

6. The Hexagon

Now we enter the realm of complex shapes. Instead of calculating distance to 6 different lines, we use Domain Folding.

fn sdf_hexagon(p: vec2<f32>, r: f32) -> f32 {
    // 1. Define symmetry constants (sin(60), cos(60), tan(60))
    let k = vec3<f32>(-0.866025404, 0.5, 0.577350269);

    // 2. Fold the space!
    // We reflect the coordinate system so all 6 sectors map to 1.
    var p_adj = abs(p);
    p_adj -= 2.0 * min(dot(k.xy, p_adj), 0.0) * k.xy;

    // 3. Calculate distance to the single remaining edge
    let d = length(p_adj - vec2<f32>(clamp(p_adj.x, -k.z * r, k.z * r), r)) * sign(p_adj.y - r);
    return d;
}

How it works

Imagine a kaleidoscope. A hexagon has 6 identical triangular sectors.

1. abs(p) folds the left side onto the right side. Now we have 3 sectors.

2. The dot product math reflects the top-left and top-right sectors down.

3. We have folded the entire 2D plane into a single small wedge. We only need to calculate the distance to one vertical edge in that wedge, and the math applies to all 6 sides automatically.

7. The Star

To create a star with any number of points ($N$), we usually think in terms of Polar Domain Repetition. Instead of defining the whole shape, we define one "pie slice" and repeat it.

However, a naive implementation using atan2 produces a distorted distance field - distances grow faster as you move away from the center. This ruins effects like outlines and soft shadows.

For a high-quality, sharp star, we combine the concept of repetition with Folding Geometry. We fold the space using symmetry lines defined by the star's angles (e.g., $360/5=72360/5=72\textdegree$), then measure the exact Euclidean distance to the edge of the triangle wedge.

fn sdf_star(p: vec2<f32>, r: f32, n: f32, m: f32) -> f32 {
    // 1. Define the angle of one sector (e.g. 72 degrees for N=5)
    let an = 3.141593 / n;
    let en = 3.141593 / m;

    // 2. Get the angle of the current pixel using Polar Coordinates
    let angle = atan2(p.x, p.y) + an;

    // 3. Repeat the sector (The "Pie Slice" Logic)
    // This maps the full 360 degrees to a single sector index.
    // By using 'fract', a pixel at 350° is treated exactly the same as 10°.
    let sector = floor(angle / (2.0 * an));
    let a = fract(angle / (2.0 * an)) - 0.5;

    // 4. Rotate pixel into local sector space
    // Now every pixel "thinks" it is in the top slice!
    let p_rot = vec2<f32>(cos(a * 2.0 * an), sin(a * 2.0 * an)) * length(p);

    // 5. Calculate exact distance (Folding Logic)
    // We now only need to measure distance to ONE line segment.
    // Because of step #3, this logic automatically applies to all N points.
    // ... (Exact segment math omitted for brevity) ...
}

How it works

1. Polar Coordinates: We convert the pixel's position from (x,y) to (angle, radius) using atan2.

2. Slicing the Pie: We divide the full circle ($2\pi$) by $N$ (e.g., 5). This gives us the width of one sector.

3. Modulo Arithmetic: By using fract(), we discard the specific sector number. We are left with a single triangular wedge.

4. Folding for Precision: Instead of just using the angle (which distorts distance), we rotate the pixel into that wedge and measure the real geometric distance to the star's edge.

Combining SDFs: Boolean Operations

This is where SDFs truly shine. In traditional geometry, merging two shapes requires complex mesh generation. In SDFs, it is just min() and max().

1. Union (min)

To combine two shapes into one compound shape, we simply ask: "What is the distance to the nearest edge?"

fn op_union(d1: f32, d2: f32) -> f32 {
    return min(d1, d2);
}

How it works

The min() function effectively stitches the distance fields together.

• Wherever Shape A is closer, d1 wins.

• Wherever Shape B is closer, d2 wins.

• At the junction where they intersect, d1 == d2, creating a seamless seam.

2. Intersection (max)

To find the overlap, we ask: "How far do I have to travel to be inside both shapes?"
This is the largest distance. If you are inside Shape A (-5) but outside Shape B (+2), the max is +2 (Outside). You are only "Inside" (negative) if both are negative. The logic is simple: take the maximum value.

fn op_intersection(d1: f32, d2: f32) -> f32 {
    return max(d1, d2);
}

How it works

• If you are outside both, max() returns the distance to the shape that is furthest away (because you have to cross both boundaries to get inside).

• If you are inside one but outside the other, max() returns the positive value (Outside).

• If you are inside both, max() returns the value closest to 0 (closest to the edge).

3. Subtraction

To carve Shape B out of Shape A (like using a cookie cutter), we use a clever trick involving inversion.

In an SDF, "Inside" is negative and "Outside" is positive.
If we put a minus sign in front of a distance (-d), we invert the world: Inside becomes Outside, and Outside becomes Inside.

Therefore, "Subtraction" is just the Intersection of Shape A and the Inverse of Shape B.
We want the region that is Inside A AND Outside B.

fn op_subtraction(d1: f32, d2: f32) -> f32 {
    // "Intersection of d1 and NOT d2"
    return max(d1, -d2);
}

How it works

• d1: Distance to the base shape.

• -d2: Distance to the "anti-shape".

• max(): Returns the intersection. The result is only negative (inside) if you are inside A (d1 < 0) AND inside the anti-B (-d2 < 0, which means d2 > 0, i.e., outside B).

4. Smooth Blending (The "Liquid" Effect)

The functions above create sharp corners where shapes meet. But because SDFs are continuous fields, we can blend them mathematically.

Instead of a hard min(), we use a polynomial mix to smooth out the junction.

fn op_smooth_union(d1: f32, d2: f32, k: f32) -> f32 {
    // k controls the "goo factor" or blend radius.
    // h calculates a weight from 0.0 to 1.0 based on how close d1 and d2 are.
    let h = clamp(0.5 + 0.5 * (d2 - d1) / k, 0.0, 1.0);

    // 1. mix(d2, d1, h): Linearly blends the distances (like a bevel)
    // 2. - k * h * (1.0 - h): Subtracts a bit more to create the curved "fillet"
    return mix(d2, d1, h) - k * h * (1.0 - h);
}

Visualizing Smooth Union

Imagine two drops of water touching. They don't just intersect; surface tension pulls them into a single smooth blob. op_smooth_union replicates this perfectly. It is commonly used for organic shapes, biological effects, or gooey UI elements.

Using SDFs for Anti-Aliasing

One of the greatest superpowers of SDFs is infinite resolution. Whether your shape is 10 pixels wide or 1000 pixels wide, the math is the same. However, if we simply cut the shape at 0.0, we get jagged, pixelated edges.

To fix this, we need to blur the edge slightly - but only by the width of one pixel.

1. The Hard Edge (Aliased)

Using step() acts like a binary switch.

• Distance -0.0001 → Color (Inside)

• Distance +0.0001 → Black (Outside)

let dist = sdf_circle(p, 0.5);
// Result is either 0.0 or 1.0. Nothing in between.
let alpha = step(0.0, -dist);

2. The Smooth Edge (Anti-Aliased)

We want the pixels lying exactly on the boundary to be partially transparent (gray).
To do this, we need to map the distance to opacity using smoothstep.

But how wide should the smooth transition be?

• Too narrow? Still jagged.

• Too wide? The shape looks blurry.

The answer is fwidth(dist).

3. The fwidth Magic

fwidth(dist) allows the GPU to peek at the neighbor pixels. It asks: "How much does the dist value change from this pixel to the one next to it?"
This value tells us exactly how "wide" one pixel is in terms of distance units.

let dist = sdf_circle(p, 0.5);

// Calculate the width of one pixel in distance space
let edge_width = fwidth(dist);

// Create a smooth transition exactly 2 pixels wide centered on the edge
// smoothstep(lower_bound, upper_bound, value)
let alpha = smoothstep(-edge_width, edge_width, -dist);

Why this works

If you zoom in on your shape, dist changes very slowly between pixels. fwidth becomes small. The transition stays sharp (1 pixel wide).
If you zoom out, dist changes rapidly. fwidth becomes large. The transition widens to match the pixel size.
The result: perfectly crisp edges at any zoom level.

Distance Field Effects

Since dist tells us exactly how far we are from the edge, we can map that number to colors to create effects that would be complex with textures.

1. Outlines (Borders)

To create an outline, we don't care if we are inside or outside. we only care that we are near the edge.
Mathematically, this means looking at the Absolute Value of the distance (abs(dist)).

let dist = sdf_circle(p, 0.5);

// Define border thickness
let border_width = 0.02;

// Calculate "Distance from Border"
// abs(dist) is 0 at the edge, and grows as we move away in EITHER direction.
// We effectively create a "V" shape distance field centered on the line.
let d_border = abs(dist);

// Create the mask
// We use fwidth for anti-aliasing again!
let w = fwidth(dist);
let border_mask = smoothstep(border_width + w, border_width - w, d_border);

// Apply color
let final_color = mix(fill_color, border_color, border_mask);

2. Outer Glow

A glow is just light fading over distance. We take the positive distance (outside) and map it to brightness.

// Option A: Smoothstep Glow (Contained)
// Glow starts at edge (0.0) and fades to nothing at 0.2
let glow = smoothstep(0.2, 0.0, dist);

// Option B: Exponential Glow (Natural)
// Looks more like a light source.
// The multiplier (10.0) controls tightness. Higher = tighter glow.
// We max(dist, 0.0) so we don't glow on the inside.
let glow = exp(-10.0 * max(dist, 0.0));

// Add glow to color
color += glow_color * glow;

3. Inner Shadow / Inset

To create an inner shadow (like a button pressed in), we look at the negative distance (inside).

// Invert distance so "deep inside" is positive
let inside_dist = -dist;

// Smoothstep from edge (0.0) to deep inside (0.1)
let shadow = smoothstep(0.0, 0.1, inside_dist);

// Darken the color
color *= (1.0 - shadow * 0.5);

Complete Example: Animated Shape Morphing

To demonstrate the versatility of distance fields, we will build a "shapeshifter" material. Unlike standard mesh morphing - which requires complex vertex animation - SDF morphing is as simple as blending two numbers.

Our Goal

We want to create a dynamic glyph that:

1. Morphs smoothly between 6 different primitive shapes.

2. Rendering Effects: Applies a glowing outline and a distance-based pattern.

3. Perfect Edges: Renders with infinite resolution and anti-aliasing.

The Shader (assets/shaders/d03_05_sdf_morphing.wgsl)

This shader acts as our SDF engine. It defines the mathematical formulas for all our primitive shapes - Circle, Box, Hexagon, Cross, and Star.

The fragment entry point orchestrates the effect:

1. Coordinate Setup: It centers the UVs so (0,0) is in the middle of the quad.

2. Distance Calculation: It computes the distance field for both the Start Shape and the Target Shape.

3. Morphing: It blends these two distances using mix(). We apply an ease-in-out curve to the time factor so the transition feels organic rather than robotic.

4. Rendering: Finally, it uses the blended distance value to generate the anti-aliased fill, the white outline, and the outer glow.

#import bevy_pbr::forward_io::VertexOutput

struct SdfMaterial {
    time: f32,
    morph_factor: f32,
    shape_a: u32,
    shape_b: u32,
    glow_intensity: f32,
    outline_width: f32,
    // Colors
    primary_color: vec4<f32>,
    secondary_color: vec4<f32>,
    background_color: vec4<f32>,
    glow_color: vec4<f32>,
    outline_color: vec4<f32>,
}

@group(2) @binding(0)
var<uniform> material: SdfMaterial;

// --- 1. SDF PRIMITIVE LIBRARY ---

fn sdf_circle(p: vec2<f32>, r: f32) -> f32 {
    return length(p) - r;
}

fn sdf_box(p: vec2<f32>, b: vec2<f32>) -> f32 {
    let d = abs(p) - b;
    return length(max(d, vec2<f32>(0.0))) + min(max(d.x, d.y), 0.0);
}

fn sdf_rounded_box(p: vec2<f32>, b: vec2<f32>, r: f32) -> f32 {
    // Note: This effectively inflates the box by r
    return sdf_box(p, b) - r;
}

fn sdf_hexagon(p: vec2<f32>, r: f32) -> f32 {
    let k = vec3<f32>(-0.866025404, 0.5, 0.577350269);
    var p_adj = abs(p);
    p_adj -= 2.0 * min(dot(k.xy, p_adj), 0.0) * k.xy;
    let d = length(p_adj - vec2<f32>(clamp(p_adj.x, -k.z * r, k.z * r), r)) * sign(p_adj.y - r);
    return d;
}

fn sdf_cross(p: vec2<f32>, size: f32, thick: f32) -> f32 {
    let rect_a = sdf_box(p, vec2<f32>(size, thick));
    let rect_b = sdf_box(p, vec2<f32>(thick, size));
    return min(rect_a, rect_b);
}

fn sdf_star(p: vec2<f32>, r: f32, factor: f32) -> f32 {
    let k1 = vec2<f32>(0.809016994375, -0.587785252292);
    let k2 = vec2<f32>(-k1.x, k1.y);

    var p_adj = p;
    p_adj.x = abs(p_adj.x);
    p_adj -= 2.0 * max(dot(k1, p_adj), 0.0) * k1;
    p_adj -= 2.0 * max(dot(k2, p_adj), 0.0) * k2;
    p_adj.x = abs(p_adj.x);
    p_adj.y -= r;

    let ba = factor * vec2<f32>(-k1.y, k1.x) - vec2<f32>(0.0, 1.0);
    let h = clamp(dot(p_adj, ba) / dot(ba, ba), 0.0, r);

    return length(p_adj - ba * h) * sign(p_adj.y * ba.x - p_adj.x * ba.y);
}

fn get_dist(id: u32, p: vec2<f32>) -> f32 {
    let size = 0.30;

    switch id {
        case 0u: { return sdf_circle(p, size); }
        case 1u: { return sdf_box(p, vec2<f32>(size, size)); }
        // For rounded box, subtract radius from size so visual size stays ~0.3
        case 2u: { return sdf_rounded_box(p, vec2<f32>(size - 0.1, size - 0.1), 0.1); }
        case 3u: { return sdf_hexagon(p, size); }
        case 4u: { return sdf_cross(p, size, size * 0.35); }
        case 5u: { return sdf_star(p, size + 0.1, 0.45); }
        default: { return sdf_circle(p, size); }
    }
}

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    let p = in.uv - 0.5;

    // 1. Morph Logic
    let d1 = get_dist(material.shape_a, p);
    let d2 = get_dist(material.shape_b, p);

    let t = smoothstep(0.0, 1.0, material.morph_factor);
    let dist = mix(d1, d2, t);

    // 2. Rendering Effects
    let aa = fwidth(dist);

    // Fill
    let fill_mask = 1.0 - smoothstep(-aa, aa, dist);
    let pattern_val = sin(dist * 40.0 - material.time * 3.0) * 0.5 + 0.5;
    let fill_color = mix(material.primary_color, material.secondary_color, pattern_val);

    // Outline
    let outline_mask = smoothstep(material.outline_width + aa, material.outline_width, abs(dist));

    // Outer Glow
    let glow_mask = exp(-5.0 * max(dist, 0.0)) * material.glow_intensity;
    let glow = material.glow_color * glow_mask;

    // 3. Composition
    var final_color = material.background_color.rgb;

    final_color = mix(final_color, fill_color.rgb, fill_mask);

    if (material.outline_width > 0.001) {
        final_color = mix(final_color, material.outline_color.rgb, outline_mask);
    }

    final_color += glow.rgb;

    return vec4<f32>(final_color, 1.0);
}

The Rust Material (src/materials/d03_05_sdf_morphing.rs)

This file bridges the gap between the CPU and GPU. It defines the SdfUniforms struct, which maps 1:1 to the SdfMaterial struct in our shader.

We use a submodule with #![allow(dead_code)] to encapsulate the uniforms. This is a handy pattern in Bevy shader development to suppress compiler warnings about unused fields or methods generated by the ShaderType derive macro, keeping your build output clean.

use bevy::prelude::*;
use bevy::render::render_resource::{AsBindGroup, ShaderRef};

pub mod uniforms {
    #![allow(dead_code)]
    use bevy::prelude::*;
    use bevy::render::render_resource::ShaderType;

    #[derive(ShaderType, Debug, Clone)]
    pub struct SdfUniforms {
        pub time: f32,
        pub morph_factor: f32,
        pub shape_a: u32,
        pub shape_b: u32,
        pub glow_intensity: f32,
        pub outline_width: f32,
        pub primary_color: LinearRgba,
        pub secondary_color: LinearRgba,
        pub background_color: LinearRgba,
        pub glow_color: LinearRgba,
        pub outline_color: LinearRgba,
    }
}
pub use uniforms::SdfUniforms;

#[derive(Asset, TypePath, AsBindGroup, Debug, Clone)]
pub struct SdfMorphMaterial {
    #[uniform(0)]
    pub uniforms: SdfUniforms,
}

impl Default for SdfMorphMaterial {
    fn default() -> Self {
        Self {
            uniforms: SdfUniforms {
                time: 0.0,
                morph_factor: 0.0,
                shape_a: 5, // Star
                shape_b: 0, // Circle
                glow_intensity: 0.8,
                outline_width: 0.02,
                primary_color: LinearRgba::new(0.0, 0.8, 1.0, 1.0), // Cyan
                secondary_color: LinearRgba::new(1.0, 0.0, 0.8, 1.0), // Magenta
                background_color: LinearRgba::new(0.02, 0.02, 0.05, 1.0),
                glow_color: LinearRgba::new(0.0, 0.6, 0.8, 1.0),
                outline_color: LinearRgba::WHITE,
            },
        }
    }
}

impl Material for SdfMorphMaterial {
    fn fragment_shader() -> ShaderRef {
        "shaders/d03_05_sdf_morphing.wgsl".into()
    }
}

Don't forget to add it to src/materials/mod.rs:

pub mod d03_05_sdf_morphing;

The Demo Module (src/demos/d03_05_sdf_morphing.rs)

This module sets up the interactive environment. It spawns the camera, the quad mesh, and the UI overlay.

The core logic lies in the handle_input and animate_shader systems. Instead of just playing a fixed animation, these systems read the keyboard state and directly modify the properties of the SdfMorphMaterial asset. This allows for real-time control over the morphing speed, the active shapes, and the visual effects.

use crate::materials::d03_05_sdf_morphing::SdfMorphMaterial;
use bevy::prelude::*;

pub fn run() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(MaterialPlugin::<SdfMorphMaterial>::default())
        .insert_resource(AnimationState {
            auto_morph: true,
            morph_speed: 0.5,
            manual_t: 0.0,
            ping_pong_direction: 1.0,
        })
        .add_systems(Startup, setup)
        .add_systems(Update, (handle_input, animate_shader, update_ui))
        .run();
}

#[derive(Resource)]
struct AnimationState {
    auto_morph: bool,
    morph_speed: f32,
    manual_t: f32,
    ping_pong_direction: f32,
}

fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<SdfMorphMaterial>>,
) {
    commands.spawn((
        Camera3d::default(),
        Transform::from_xyz(0.0, 0.0, 2.0).looking_at(Vec3::ZERO, Vec3::Y),
    ));

    commands.spawn((
        Mesh3d(meshes.add(Rectangle::new(2.0, 2.0))),
        MeshMaterial3d(materials.add(SdfMorphMaterial::default())),
        Transform::default(),
    ));

    commands.spawn((
        Text::new("SDF Morphing Demo"),
        Node {
            position_type: PositionType::Absolute,
            top: Val::Px(10.0),
            left: Val::Px(10.0),
            padding: UiRect::all(Val::Px(10.0)),
            ..default()
        },
        TextFont {
            font_size: 16.0,
            ..default()
        },
        TextColor(Color::WHITE),
        BackgroundColor(Color::srgba(0.0, 0.0, 0.0, 0.8)),
    ));
}

fn handle_input(
    keyboard: Res<ButtonInput<KeyCode>>,
    mut state: ResMut<AnimationState>,
    mut materials: ResMut<Assets<SdfMorphMaterial>>,
) {
    for (_, material) in materials.iter_mut() {
        let u = &mut material.uniforms;
        let shift = keyboard.pressed(KeyCode::ShiftLeft) || keyboard.pressed(KeyCode::ShiftRight);

        if keyboard.just_pressed(KeyCode::Space) {
            state.auto_morph = !state.auto_morph;
            if !state.auto_morph {
                state.manual_t = u.morph_factor;
            }
        }

        // Shape Selection
        if keyboard.just_pressed(KeyCode::Digit1) {
            if shift {
                u.shape_b = 0;
            } else {
                u.shape_a = 0;
            }
        }
        if keyboard.just_pressed(KeyCode::Digit2) {
            if shift {
                u.shape_b = 1;
            } else {
                u.shape_a = 1;
            }
        }
        if keyboard.just_pressed(KeyCode::Digit3) {
            if shift {
                u.shape_b = 2;
            } else {
                u.shape_a = 2;
            }
        }
        if keyboard.just_pressed(KeyCode::Digit4) {
            if shift {
                u.shape_b = 3;
            } else {
                u.shape_a = 3;
            }
        }
        if keyboard.just_pressed(KeyCode::Digit5) {
            if shift {
                u.shape_b = 4;
            } else {
                u.shape_a = 4;
            }
        }
        if keyboard.just_pressed(KeyCode::Digit6) {
            if shift {
                u.shape_b = 5;
            } else {
                u.shape_a = 5;
            }
        }

        // Toggles
        if keyboard.just_pressed(KeyCode::KeyG) {
            u.glow_intensity = if u.glow_intensity > 0.0 { 0.0 } else { 0.8 };
        }
        if keyboard.just_pressed(KeyCode::KeyO) {
            u.outline_width = if u.outline_width > 0.0 { 0.0 } else { 0.02 };
        }

        // Manual Morph
        if !state.auto_morph {
            let delta = 0.02;
            if keyboard.pressed(KeyCode::ArrowRight) {
                state.manual_t = (state.manual_t + delta).min(1.0);
                u.morph_factor = state.manual_t;
            }
            if keyboard.pressed(KeyCode::ArrowLeft) {
                state.manual_t = (state.manual_t - delta).max(0.0);
                u.morph_factor = state.manual_t;
            }
        }

        // Speed
        let speed_delta = 0.01;
        if keyboard.pressed(KeyCode::ArrowUp) {
            state.morph_speed = (state.morph_speed + speed_delta).min(5.0);
        }
        if keyboard.pressed(KeyCode::ArrowDown) {
            state.morph_speed = (state.morph_speed - speed_delta).max(0.0);
        }
    }
}

fn animate_shader(
    time: Res<Time>,
    mut state: ResMut<AnimationState>,
    mut materials: ResMut<Assets<SdfMorphMaterial>>,
) {
    if !state.auto_morph {
        for (_, material) in materials.iter_mut() {
            material.uniforms.time = time.elapsed_secs();
        }
        return;
    }

    let delta = time.delta_secs();

    for (_, material) in materials.iter_mut() {
        let u = &mut material.uniforms;
        u.time = time.elapsed_secs();

        u.morph_factor += delta * state.morph_speed * state.ping_pong_direction;

        if u.morph_factor >= 1.0 {
            u.morph_factor = 1.0;
            state.ping_pong_direction = -1.0;
        } else if u.morph_factor <= 0.0 {
            u.morph_factor = 0.0;
            state.ping_pong_direction = 1.0;
        }
    }
}

fn get_shape_name(id: u32) -> &'static str {
    match id {
        0 => "Circle",
        1 => "Box",
        2 => "RoundBox",
        3 => "Hexagon",
        4 => "Cross",
        5 => "Star",
        _ => "Unknown",
    }
}

fn update_ui(
    state: Res<AnimationState>,
    materials: Res<Assets<SdfMorphMaterial>>,
    mut text_query: Query<&mut Text>,
) {
    if let Some((_, mat)) = materials.iter().next() {
        let u = &mat.uniforms;
        for mut text in text_query.iter_mut() {
            **text = format!(
                "CONTROLS:\n\
                [1-6] Set Shape A\n\
                [Shift + 1-6] Set Shape B\n\
                [Space] Auto-Loop: {}\n\
                [Left/Right] Manual Morph\n\
                [Up/Down] Morph Speed\n\
                [G] Glow: {} | [O] Outline: {}\n\
                \n\
                STATUS:\n\
                Morph: {} <---> {}\n\
                Factor: {:.0}% | Speed: {:.2}",
                if state.auto_morph { "ON" } else { "MANUAL" },
                if u.glow_intensity > 0.0 { "ON" } else { "OFF" },
                if u.outline_width > 0.0 { "ON" } else { "OFF" },
                get_shape_name(u.shape_a),
                get_shape_name(u.shape_b),
                u.morph_factor * 100.0,
                state.morph_speed
            );
        }
    }
}

Don't forget to add it to src/demos/mod.rs:

pub mod d03_05_sdf_morphing;

And register it in src/main.rs:

Demo {
    number: "3.5",
    title: "SDF Morphing",
    run: demos::d03_05_sdf_morphing::run,
},

Running the Demo

Controls

What You're Seeing

• Geometric Morphing: The transitions are now mathematically perfect. The Star (6) is sharp and precise. When morphing to a Circle (1), the points retract and the edges bulge outward until it is perfectly round.

• The Outline: Notice the white outline. It is generated by abs(dist). Even when the shape is half-morphed and looks like a strange blob, the outline stays perfectly consistent and sharp.

• Ripples: The internal pattern visualizes the distance field itself. The ripples act like contour lines on a map, showing you exactly how the distance value changes from the center to the edge.

Key Takeaways

1. Think in Fields, Not Pixels: An SDF doesn't define where the shape is. It defines how far every pixel is from the edge. This shift in thinking unlocks powerful effects.

2. Infinite Resolution: Because SDFs are mathematical functions, they remain perfectly sharp at any zoom level. By using fwidth(), we can create edges that are always exactly 1 pixel soft, regardless of scale.

3. Boolean Algebra: You don't need complex mesh algorithms to combine shapes. You just need min() (Union), max() (Intersection), and max(d1, -d2) (Subtraction).

4. Free Effects: Once you have a distance field, adding an outline is just abs(dist). Adding a glow is just exp(-dist). The "hard work" of geometry gives you these effects for free.

What's Next?

We've mastered precise geometric shapes. But nature is rarely perfect. To create clouds, fire, terrain, or water, we need controlled chaos. In the next article, we will dive into Procedural Noise, learning how to generate organic textures using randomness and fractals.

Next up: 3.6 - Procedural Noise

Quick Reference

1. The SDF Sign Convention

The most important rule to remember. The sign tells you where you are.

• Negative (<0): Inside the shape.

• Zero (=0): Exactly on the edge.

• Positive (>0): Outside the shape.

2. Boolean Logic Cheat Sheet

Combine shapes by comparing their distance values.

• Union (Merge) -> min(a, b)

  • Logic: "I am closest to shape A or shape B."

• Intersection (Overlap) -> max(a, b)

  • Logic: "I am strictly inside only if I am inside both."

• Subtraction (Cut) -> max(a, -b)

  • Logic: "Intersect Shape A with the inverse of Shape B."

3. The Golden Rule of Anti-Aliasing

Never use step(0.0, dist) if you want smooth edges.
The magic formula for perfect edges at any zoom level is to smooth over the width of one pixel:

let aa = fwidth(dist);
let alpha = 1.0 - smoothstep(-aa, aa, dist);

4. Creating Effects

Once you have the distance d, you can derive effects without extra geometry:

• Outline: abs(d) creates a V-shape field centered on the edge.

• Glow: exp(-d) creates a natural light falloff.

• Inset: -d (inverted distance) lets you render effects inside the shape.

5. Domain Manipulation

Don't model complex repetition; warp the space instead.

• Mirror Symmetry: p.x = abs(p.x) folds the left side onto the right.

• Radial Symmetry: Use atan2 to convert to polar coordinates, then repeat the angle.

In the real world, colors are rarely static. The sky shifts from deep azure to pale cyan; a metal pipe has a bright highlight that fades into shadow; a sunset paints the clouds in bands of orange, pink, and purple. To replicate this in a shader, we need to master gradients.

At their core, gradients are about interpolation: the math of smoothly blending from one value to another. In previous articles, we used interpolation to move things. Now, we apply those same principles to color.

In this article, you will learn:

• The Logic of mix(): How to blend any two values - colors, positions, or numbers - using a control factor.

• Linear Gradients: Using UV coordinates to create horizontal, vertical, and diagonal color ramps.

• smoothstep() Basics: How to create buttery-smooth transitions that feel organic rather than mechanical.

• Radial and Angled Gradients: Moving beyond simple lines to create circles, cones, and sweeping angles.

• Banding and Dithering: Why gradients sometimes look "stepped" on monitors and how to fix it with noise.

• The Aurora Shader: A complete project blending noise and gradients to create a dynamic northern lights effect.

The Foundation: Linear Interpolation

Before we paint a sunset, we must understand the brush. In WGSL, that brush is the mix() function.

In mathematics, this operation is often called Linear Interpolation (or lerp). It calculates a value between a start point and an end point based on a percentage t.

Understanding mix()

The function signature is:

let result = mix(start, end, t);

Think of t as a slider or a percentage from 0.0 to 1.0.

• When t is 0.0, you get 100% of the start value.

• When t is 1.0, you get 100% of the end value.

• When t is 0.5, you get a perfect 50/50 blend.

Mathematically, the GPU performs this calculation:
result = start * (1.0 - t) + end * t

Visualizing the Slider

Interpolating Colors

Because colors in WGSL are just vectors (vec3<f32> or vec4<f32>), mix() works on them exactly the same way it works on single numbers. It blends the Red, Green, and Blue channels independently.

let red = vec3<f32>(1.0, 0.0, 0.0);
let blue = vec3<f32>(0.0, 0.0, 1.0);

// 50% Red + 50% Blue = Purple
let purple = mix(red, blue, 0.5); 
// Result: vec3<f32>(0.5, 0.0, 0.5)

A Note on Color Mud:
Standard RGB interpolation is "linear," but human eyes don't perceive color linearly. If you mix pure Red and pure Green, the mathematical midpoint is a dark, murky olive color, not the bright Yellow you might expect. For simple gradients, this is fine, but if your gradients look "muddy" in the middle, it's often because of this limitation in the RGB color space.

Linear Gradients with UV Coordinates

The most common "slider" we have in a fragment shader is the UV coordinate system. Since UVs naturally range from 0.0 to 1.0 across the mesh, they plug directly into the t parameter of mix().

Horizontal Gradient

To create a gradient from left to right, we use the U coordinate (uv.x).

#import bevy_pbr::forward_io::VertexOutput

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    let color_left = vec3<f32>(1.0, 0.0, 0.0);  // Red
    let color_right = vec3<f32>(0.0, 0.0, 1.0); // Blue

    // Use U coordinate as our slider (0.0 at left, 1.0 at right)
    let t = in.uv.x;

    let color = mix(color_left, color_right, t);

    return vec4<f32>(color, 1.0);
}

Result:

Vertical Gradient

To go from bottom to top, we use the V coordinate (uv.y).

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    let color_bottom = vec3<f32>(0.2, 0.2, 0.2); // Dark Gray
    let color_top = vec3<f32>(0.5, 0.7, 1.0);    // Sky Blue

    // Use V coordinate (0.0 at bottom, 1.0 at top)
    let t = in.uv.y;

    let color = mix(color_bottom, color_top, t);

    return vec4<f32>(color, 1.0);
}

Diagonal Gradient

A diagonal gradient requires a t value that increases as we move both right and up. We can achieve this by averaging the coordinates.

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    let color_a = vec3<f32>(1.0, 0.0, 0.0);
    let color_b = vec3<f32>(0.0, 0.0, 1.0);

    // Average U and V. 
    // Bottom-Left (0,0) -> 0.0
    // Top-Right (1,1) -> 1.0
    let t = (in.uv.x + in.uv.y) * 0.5;

    let color = mix(color_a, color_b, t);

    return vec4<f32>(color, 1.0);
}

Controlling the Range

What if you want the gradient to start 20% of the way in and finish 80% of the way across? We need to manipulate our t value before plugging it into mix.

We remap the range using simple math: (value - start) / (end - start).

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    let color_bg = vec3<f32>(0.0, 0.0, 0.0); // Black background
    let color_fg = vec3<f32>(1.0, 1.0, 0.0); // Yellow foreground

    // Define the start and end of the gradient in UV space
    let start = 0.2;
    let end = 0.8;

    // Remap uv.x to our new 0.0-1.0 range
    let t_raw = (in.uv.x - start) / (end - start);

    // Essential! Clamp the value.
    // Without clamp, mix() would extrapolate beyond colors A and B,
    // potentially creating negative colors or hyper-bright values.
    let t = clamp(t_raw, 0.0, 1.0);

    let color = mix(color_bg, color_fg, t);

    return vec4<f32>(color, 1.0);
}

Repeating Gradients

In the previous article, we used fract() to repeat patterns. We can do the same for gradients to create soft, repeating bands.

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    let color_a = vec3<f32>(0.0, 0.0, 0.0);
    let color_b = vec3<f32>(1.0, 1.0, 1.0);

    // Scale UVs by 5.0, then take the fractional part.
    // This creates a sawtooth wave: 0->1, 0->1, 0->1... five times.
    let t = fract(in.uv.x * 5.0);

    let color = mix(color_a, color_b, t);

    return vec4<f32>(color, 1.0);
}

The smoothstep() Function

Linear interpolation is useful, but it often looks mechanical or "robotic." In the real world, transitions rarely happen at a constant speed; they accelerate and decelerate. Shadows have soft edges, and lights have a "hotspot" that fades out gradually.

To achieve this organic look, we use the smoothstep() function. It is arguably the most important function in procedural shader programming after mix().

Understanding smoothstep

The function takes three arguments:

let result = smoothstep(edge0, edge1, x);

It returns a value between 0.0 and 1.0, based on where x lies relative to edge0 and edge1.

1. Below the Lower Edge: If x is less than edge0, it returns 0.0.

2. Above the Upper Edge: If x is greater than edge1, it returns 1.0.

3. In Between: If x is between the edges, it performs a smooth Hermite interpolation (an S-shaped curve). It starts slow, speeds up in the middle, and slows down at the end.

Visual Comparison

Imagine we are fading from black to white as UV.x goes from 0.0 to 1.0.

Linear (t = x): The change is constant. It looks like a stiff, perfect ramp.
0.0 ➔ 0.25 ➔ 0.5 ➔ 0.75 ➔ 1.0

Smoothstep (t = smoothstep(0.0, 1.0, x)): The change eases in and eases out. It creates more contrast in the middle and softer transitions at the ends.
0.0 ➔ 0.11 ➔ 0.5 ➔ 0.89 ➔ 1.0

Using smoothstep with mix

The real power comes when you use the result of smoothstep as the t (control) value for your mix function.

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    let color_a = vec3<f32>(0.0, 0.0, 0.0);
    let color_b = vec3<f32>(1.0, 1.0, 1.0);

    // Define the transition zone: from 30% to 70% of the screen
    let edge0 = 0.3;
    let edge1 = 0.7;

    // Calculate the curve
    let t = smoothstep(edge0, edge1, in.uv.x);

    // Blend colors using the curved t
    let color = mix(color_a, color_b, t);

    return vec4<f32>(color, 1.0);
}

What happens here:

• Left 30%: Pure color_a (Black).

• Right 30%: Pure color_b (White).

• Middle 40%: A smooth, contrast-rich transition from Black to White.

Useful Patterns

1. Inverting the Control

Often you want 1.0 at the start and 0.0 at the end (like a light fading out). You can do this in two ways:

• The Math Way: Generate a normal 0-to-1 curve, then subtract it from 1.0.

let t = 1.0 - smoothstep(0.0, 1.0, x);

• The Shorthand Way: Simply swap the edges.

let t = smoothstep(1.0, 0.0, x);

Both lines of code do exactly the same thing. Use whichever one makes more sense to you!

2. Hard Edges

If edge0 and edge1 are very close together, the smooth transition tightens until it looks like a hard line. This is how we do anti-aliasing!

// A sharp, but slightly anti-aliased line at 0.5
let line = smoothstep(0.49, 0.51, in.uv.x);

Radial Gradients

Now that we understand interpolation and smoothing, let's leave the grid behind. Radial gradients emanate from a center point, creating circles, glows, and vignettes.

The Math: Distance

The engine of a radial gradient is the distance() function (or length()). We measure how far the current pixel (UV) is from a center point.

let center = vec2<f32>(0.5, 0.5);
let dist = distance(in.uv, center); // or length(in.uv - center)

In the center, dist is 0.0. At the edges of a square (0.5 units away), dist is 0.5. In the corners, dist is roughly 0.707 (the square root of 0.5² + 0.5²).

Basic Radial Gradient

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    let center = vec2<f32>(0.5, 0.5);

    // Calculate distance
    let dist = distance(in.uv, center);

    // 1. Simple Linear Falloff
    // We want the center to be White (1.0) and the edge to be Black (0.0).
    // Since dist goes 0->0.5, we multiply by 2.0 to map it to 0->1 range.
    // Then we invert it (1.0 - val) to make the center bright.
    let brightness = 1.0 - (dist * 2.0);

    let color = vec3<f32>(brightness); // Grayscale result

    return vec4<f32>(color, 1.0);
}

Result: A cone-like gradient. It looks sharp and pointy in the center, like a pyramid viewed from above.

Soft Glow with smoothstep

The linear version usually looks too "pointy." To make it look like a glowing sphere or a spotlight, we use smoothstep.

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    let center = vec2<f32>(0.5, 0.5);
    let dist = distance(in.uv, center);

    // Create a glow that starts fading immediately (0.0) 
    // and vanishes completely at radius 0.5.
    // Note: We flip the edges! smoothstep(0.5, 0.0, dist)
    // This is a shorthand for: 1.0 - smoothstep(0.0, 0.5, dist)
    let glow = smoothstep(0.5, 0.0, dist);

    let color_center = vec3<f32>(1.0, 0.8, 0.2); // Warm Orange
    let color_edge = vec3<f32>(0.1, 0.0, 0.0);   // Dark Red

    let color = mix(color_edge, color_center, glow);

    return vec4<f32>(color, 1.0);
}

Why flip the smoothstep arguments? smoothstep(0.5, 0.0, dist) is a valid trick.

• If dist is 0.0 (center), it returns 1.0.

• If dist is 0.5 (edge), it returns 0.0.
  It saves us from writing 1.0 - ... and often easier to read: "Map 0.5 to 0, and 0.0 to 1".

Off-Center Gradient

You aren't stuck in the middle. By changing the center variable, you can move the "light source."

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    // Move center to top-right
    let center = vec2<f32>(0.8, 0.8);
    let dist = distance(in.uv, center);

    // Tighter glow radius (0.4)
    let glow = smoothstep(0.4, 0.0, dist);

    return vec4<f32>(vec3<f32>(glow), 1.0);
}

Animating the Gradient

Since mix and smoothstep are just math, we can animate the parameters over time.

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    // Animate the center point in a circle
    let center = vec2<f32>(
        0.5 + cos(material.time) * 0.3,
        0.5 + sin(material.time) * 0.3
    );

    let dist = distance(in.uv, center);

    // Pulsate the radius
    let radius = 0.3 + sin(material.time * 5.0) * 0.05;

    let glow = smoothstep(radius, 0.0, dist);

    return vec4<f32>(vec3<f32>(glow), 1.0);
}

Multi-Stop Gradients

So far, we've only mixed two colors. But what if you want a sunset that goes Blue ➔ Pink ➔ Orange? mix() only takes two inputs, so we need to chain them together using logic.

The "if/else" Approach

The simplest way to handle three colors is to split your UV space in half.

• If we are on the left side (0.0 to 0.5), mix Color A and Color B.

• If we are on the right side (0.5 to 1.0), mix Color B and Color C.

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    let color_a = vec3<f32>(0.0, 0.0, 1.0); // Blue
    let color_b = vec3<f32>(1.0, 0.0, 1.0); // Pink
    let color_c = vec3<f32>(1.0, 0.5, 0.0); // Orange

    let t = in.uv.y; // Vertical gradient

    var color: vec3<f32>;

    // We split the screen at 0.5
    if (t < 0.5) {
        // We are in the bottom half.
        // We need to remap t from [0.0, 0.5] to [0.0, 1.0] 
        // so the mix works correctly.
        // formula: t / max_value
        let local_t = t / 0.5; 
        color = mix(color_a, color_b, local_t);
    } else {
        // We are in the top half.
        // Remap t from [0.5, 1.0] to [0.0, 1.0]
        // formula: (t - start) / (end - start)
        let local_t = (t - 0.5) / 0.5;
        color = mix(color_b, color_c, local_t);
    }

    return vec4<f32>(color, 1.0);
}

Alternative: The select() Function

WGSL provides a built-in function called select(false_value, true_value, condition) that picks a value without using an if statement. This is often preferred in shader programming because it is concise and avoids "branching" (splitting the code path), which can sometimes optimize better on GPUs.

We could rewrite the logic above like this:

// Calculate both possibilities
let mix_1 = mix(color_a, color_b, t / 0.5);
let mix_2 = mix(color_b, color_c, (t - 0.5) / 0.5);

// Pick the correct one based on the boolean condition
let color = select(mix_2, mix_1, t < 0.5);

The smoothstep Blending Approach

For a softer, more organic look without hard math logic, you can calculate a "weight" for each color band using smoothstep and add them together.

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    let t = in.uv.x;

    // Define colors
    let deep_blue = vec3<f32>(0.1, 0.1, 0.4);
    let purple    = vec3<f32>(0.5, 0.0, 0.5);
    let gold      = vec3<f32>(1.0, 0.8, 0.0);

    // Start with the base color
    var final_color = deep_blue;

    // As we pass 0.3, fade in Purple
    let t_purple = smoothstep(0.3, 0.5, t);
    final_color = mix(final_color, purple, t_purple);

    // As we pass 0.6, fade in Gold
    let t_gold = smoothstep(0.6, 0.8, t);
    final_color = mix(final_color, gold, t_gold);

    return vec4<f32>(final_color, 1.0);
}

This approach essentially layers the gradients on top of each other. It's much cleaner to read and easier to tweak.

Angled Gradients with Vector Math

We can make horizontal, vertical, and radial gradients... but what about a gradient at a 45-degree angle? Or 30 degrees?

To do this, we need a tiny bit of vector math: the Dot Product.

The Logic: Projection

Imagine a line pointing in the direction you want your gradient to go. To color a specific pixel, we need to know: "How far along this line is this pixel?"

The dot(A, B) function answers exactly this question. It "projects" vector A onto vector B.

1. Direction: We define a direction vector (e.g., pointing 45 degrees up-right).

2. Position: We take the pixel's UV position relative to the center.

3. Projection: dot(position, direction) gives us a single number representing how far along that direction the pixel lies.

Implementation

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    // 1. Define the angle (in radians)
    // 45 degrees = PI / 4
    let angle = 0.785; 

    // Convert angle to a direction vector (x=cos, y=sin)
    let dir = vec2<f32>(cos(angle), sin(angle));

    // 2. Center the UVs (so 0,0 is in the middle of the mesh)
    let centered_uv = in.uv - 0.5;

    // 3. Project the position onto the direction
    // This returns a value roughly between -0.7 and 0.7
    let projection = dot(centered_uv, dir);

    // 4. Remap to 0.0 - 1.0 range for mixing
    // We add 0.5 to re-center it, and scale it slightly to fit
    let t = clamp(projection + 0.5, 0.0, 1.0);

    // 5. Mix!
    let color = mix(
        vec3<f32>(1.0, 0.0, 0.0), // Red
        vec3<f32>(0.0, 0.0, 1.0), // Blue
        t
    );

    return vec4<f32>(color, 1.0);
}

Why is this powerful?

Because angle is just a number, you can pass it in as a uniform or animate it using material.time. This allows you to create spinning gradients like radar sweeps or rotating lights with zero extra effort.

Dithering Techniques

You might notice that your beautiful smooth gradients sometimes look like a series of ugly bands or steps, especially in dark areas. This is called Color Banding.

Why Banding Happens

Banding occurs because monitors have limited precision. A standard monitor uses 8 bits per color channel, meaning it can only display 256 shades of Red, Green, or Blue.

If you stretch a gradient from Black to Dark Blue (0.0 to 0.1) across 1000 pixels, you only have about 25 shades available to cover that distance. Each shade will span roughly 40 pixels, creating visible "steps."

The Solution: Dithering

Dithering is a trick from the days of print media. By adding controlled noise to the image, we break up the hard edges between bands. Our eyes blend the noise together, creating the illusion of a smoother gradient.

1. Simple Random Dithering

The easiest method is to add a tiny amount of random noise to each pixel.

We first need a "pseudo-random" number generator. Since shaders are deterministic, we use a mathematical function that looks random.

// A standard "hash" function for shaders.
// It takes a 2D coordinate and returns a pseudo-random value between 0.0 and 1.0.
fn hash(p: vec2<f32>) -> f32 {
    let p3 = fract(vec3<f32>(p.x, p.y, p.x) * 0.1031);
    let dot_product = dot(p3, vec3<f32>(p3.y, p3.z, p3.x) + 33.33);
    return fract((p3.x + p3.y) * dot_product);
}

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    // Create a smooth gradient susceptible to banding
    let t = in.uv.x;
    let color = mix(
        vec3<f32>(0.0, 0.0, 0.05), // Very dark blue
        vec3<f32>(0.0, 0.0, 0.2),  // Slightly lighter blue
        t
    );

    // Calculate Noise
    // We multiply UV by a large number so the noise is per-pixel, not stretched
    let random_val = hash(in.uv * 1000.0);

    // Scale the noise.
    // 1.0 / 255.0 represents the smallest possible color step on a monitor.
    // We subtract 0.5 so the noise averages out to 0.
    let dither_strength = 1.0 / 255.0;
    let dither = (random_val - 0.5) * dither_strength;

    // Add the noise to the color
    return vec4<f32>(color + dither, 1.0);
}

2. Ordered (Bayer) Dithering

Random noise can sometimes look like "film grain" or static. Ordered Dithering uses a specific grid pattern (a Bayer Matrix) to offset pixels in a checkerboard-like fashion. This looks much cleaner and more stable.

// Returns a value from a 4x4 Bayer Matrix
fn bayer_dither(position: vec4<f32>) -> f32 {
    let x = u32(position.x) % 4u;
    let y = u32(position.y) % 4u;
    let index = y * 4u + x;

    // The 4x4 Bayer Matrix pattern
    var matrix = array<f32, 16>(
         0.0,  8.0,  2.0, 10.0,
        12.0,  4.0, 14.0,  6.0,
         3.0, 11.0,  1.0,  9.0,
        15.0,  7.0, 13.0,  5.0
    );

    return matrix[index] / 16.0;
}

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    let t = in.uv.x;
    let color = mix(vec3<f32>(0.0), vec3<f32>(0.1), t);

    // Use screen-space coordinates (in.clip_position) for the dither pattern
    // so the pattern stays crisp even if the object moves.
    let bayer_val = bayer_dither(in.clip_position);

    let dither_strength = 1.0 / 255.0;
    let dither = (bayer_val - 0.5) * dither_strength;

    return vec4<f32>(color + dither, 1.0);
}

Metallic and Iridescent Effects

Gradients aren't just for 2D patterns. In 3D rendering, gradients are fundamental to creating the look of complex materials like metal or oil.

The Fresnel Gradient

Metallic and shiny surfaces look different depending on the angle you view them from. Surfaces facing away from you (the edges of a sphere) tend to be more reflective than surfaces facing directly at you. This is called the Fresnel Effect.

We can calculate this "grazing angle" using the dot product between the surface Normal and the View Direction.

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    // 1. Get standard vectors
    let normal = normalize(in.world_normal);
    // Calculate direction from camera to pixel
    // (Assuming we pass camera_position as a uniform, or derive it)
    let view_dir = normalize(in.world_position - camera_position); 
    // Note: In real code, View Dir is usually (Camera - Position) to point towards camera.
    // Let's fix that direction:
    let to_camera = normalize(camera_position - in.world_position);

    // 2. Calculate alignment
    // dot() is 1.0 if looking straight at surface, 0.0 if looking at edge.
    let alignment = max(0.0, dot(normal, to_camera));

    // 3. Invert it to get the "Edge Factor"
    // 0.0 at center, 1.0 at edge.
    let fresnel = 1.0 - alignment;

    // 4. Sharpen the gradient
    // Raising to a power (typically 3.0 to 5.0) creates that distinct "rim light" look
    let rim_light = pow(fresnel, 3.0);

    // 5. Mix colors based on viewing angle
    let center_color = vec3<f32>(0.0, 0.0, 0.5); // Dark Blue
    let edge_color = vec3<f32>(0.0, 1.0, 1.0);   // Bright Cyan

    let color = mix(center_color, edge_color, rim_light);

    return vec4<f32>(color, 1.0);
}

Iridescence (Holographic Effects)

By mapping that Fresnel gradient to a spectrum of colors instead of just two, we can simulate iridescent materials like bubbles, oil slicks, or holographic stickers.

fn rainbow_gradient(t: f32) -> vec3<f32> {
    // A cosine-based palette technique (Procedural Color Palette)
    // It cycles R, G, and B waves at different offsets.
    let a = vec3<f32>(0.5, 0.5, 0.5);
    let b = vec3<f32>(0.5, 0.5, 0.5);
    let c = vec3<f32>(1.0, 1.0, 1.0);
    let d = vec3<f32>(0.0, 0.33, 0.67);

    return a + b * cos(6.28318 * (c * t + d));
}

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    let normal = normalize(in.world_normal);
    let to_camera = normalize(camera_position - in.world_position);
    let fresnel = 1.0 - max(0.0, dot(normal, to_camera));

    // Use the fresnel factor to sample a rainbow
    let color = rainbow_gradient(fresnel);

    return vec4<f32>(color, 1.0);
}

This creates a surface that shifts color wildly as you move the camera around it.

Complete Example: Aurora Borealis Shader

To bring everything we've learned together, we will build a shader for one of nature's most beautiful gradients: the Aurora Borealis.

Unlike the simple gradients we've made so far, an aurora is dynamic. It moves, shimmers, and folds. To achieve this look without using textures, we need to combine gradients with noise and coordinate distortion.

Our Goal

We want to create a "curtain" of light that hangs in the sky.

1. Shape: It should look like vertical rays or folds.

2. Color: It should transition from green at the bottom (oxygen) to purple at the top (nitrogen).

3. Movement: The curtain should wave slowly, while the internal rays shimmer quickly.

The Shader (assets/shaders/d03_04_aurora.wgsl)

This shader relies on a technique called Domain Distortion. Instead of drawing noise directly on the standard grid, we first "bend" the coordinate system into a curve. When we draw vertical lines on this bent grid, they appear to wind back and forth like a curtain.

The fragment shader creates the effect in five distinct steps:

1. Curtain Shape: We offset the Y coordinate based on a sine wave of the X coordinate. This creates the winding path.

2. Ray Generation: We generate noise using a coordinate system that is heavily stretched on the Y-axis. This turns what would be "blobs" of noise into long vertical streaks.

3. Vertical Masking: We use smoothstep to fade the aurora out at the bottom and top, ensuring it blends naturally into the sky.

4. Color Gradient: We map the Y (altitude) coordinate to a color gradient, blending from the base color to the top color.

5. Composition: We multiply the color, the rays, and the mask together to get the final glowing result.

#import bevy_pbr::forward_io::VertexOutput
#import bevy_pbr::mesh_view_bindings::globals
#import bevy_pbr::mesh_functions::{get_world_from_local, mesh_position_local_to_world}
#import bevy_pbr::view_transformations::position_world_to_clip

struct AuroraMaterial {
    base_color: vec4<f32>,
    top_color: vec4<f32>,
    speed: f32,
    curtain_waviness: f32,
    ray_density: f32,
}

@group(2) @binding(0)
var<uniform> material: AuroraMaterial;

struct Vertex {
    @builtin(instance_index) instance_index: u32,
    @location(0) position: vec3<f32>,
    @location(1) normal: vec3<f32>,
    @location(2) uv: vec2<f32>,
};

@vertex
fn vertex(vertex: Vertex) -> VertexOutput {
    var out: VertexOutput;

    // Standard Bevy vertex transformation
    let model = get_world_from_local(vertex.instance_index);
    let world_position = mesh_position_local_to_world(model, vec4<f32>(vertex.position, 1.0));

    out.world_position = world_position;
    out.world_normal = vertex.normal;
    out.uv = vertex.uv;
    out.position = position_world_to_clip(world_position.xyz);

    return out;
}

// A simple pseudo-random hash function
fn hash(p: vec2<f32>) -> f32 {
    let p3 = fract(vec3<f32>(p.x, p.y, p.x) * 0.1031);
    let dot_product = dot(p3, vec3<f32>(p3.y, p3.z, p3.x) + 33.33);
    return fract((p3.x + p3.y) * dot_product);
}

// Value Noise: Smoothly interpolated random values
fn noise(p: vec2<f32>) -> f32 {
    let i = floor(p);
    let f = fract(p);
    let u = f * f * (3.0 - 2.0 * f); // smoothstep curve

    let a = hash(i);
    let b = hash(i + vec2<f32>(1.0, 0.0));
    let c = hash(i + vec2<f32>(0.0, 1.0));
    let d = hash(i + vec2<f32>(1.0, 1.0));

    return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);
}

// Fractal Brownian Motion: Layering noise for detail
fn fbm(p: vec2<f32>) -> f32 {
    var value = 0.0;
    var amp = 0.5;
    var freq = 1.0;
    var p_iter = p;

    // 3 layers of noise
    for (var i = 0; i < 3; i++) {
        value += noise(p_iter) * amp;
        p_iter *= 2.0;
        amp *= 0.5;
    }
    return value;
}

@fragment
fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
    let time = globals.time * material.speed;

    // 1. CREATE THE CURTAIN SHAPE
    // We distort the UV.x coordinate with large sine waves to make the
    // whole curtain wind back and forth like a snake.
    let curtain_curve = sin(in.uv.x * 2.0 - time * 0.5) * 0.2
                      + sin(in.uv.x * 5.0 + time * 0.2) * 0.1;

    // We define "height" as the distance from this winding curve.
    // This bends our coordinate system.
    let curve_uv = vec2<f32>(in.uv.x, in.uv.y - curtain_curve * material.curtain_waviness);

    // 2. GENERATE VERTICAL RAYS
    // We stretch the noise heavily on the Y axis (multiplying X by density, Y by 1.0)
    // This creates long vertical streaks instead of round blobs.
    let ray_uv = vec2<f32>(
        curve_uv.x * material.ray_density + time * 0.1,
        curve_uv.y
    );
    let rays = fbm(ray_uv);

    // 3. VERTICAL FADE (The "Mask")
    // Auroras fade out at the bottom and top.
    // We use smoothstep on the Y coordinate to create a soft band.
    let bottom_fade = smoothstep(0.0, 0.2, in.uv.y);
    let top_fade = 1.0 - smoothstep(0.6, 1.0, in.uv.y);
    let alpha_mask = bottom_fade * top_fade;

    // 4. COLOR GRADIENT (Altitude)
    // Map color based on height (Y).
    // Green at the bottom (0.0), Purple/Red at the top (1.0).
    let gradient_t = smoothstep(0.2, 0.8, in.uv.y);
    let aurora_color = mix(material.base_color.rgb, material.top_color.rgb, gradient_t);

    // 5. COMBINE
    // Multiply color by the rays and the alpha mask.
    // We boost the brightness (rays * 2.0) to make it glow.
    let final_color = aurora_color * rays * 2.0;
    let final_alpha = rays * alpha_mask;

    return vec4<f32>(final_color, final_alpha);
}

The Rust Material (src/materials/d03_04_aurora.rs)

This struct maps our shader uniforms to Rust types. Note the alpha_mode implementation: setting this to AlphaMode::Blend is crucial. Without it, our shader would render as an opaque block, blacking out anything behind it. By enabling blending, we tell the pipeline to mix our output color with the background based on the alpha value we calculated in the shader, creating the ethereal, transparent look of light.

use bevy::prelude::*;
use bevy::render::render_resource::{AsBindGroup, ShaderRef};

#[derive(Asset, TypePath, AsBindGroup, Debug, Clone)]
pub struct AuroraMaterial {
    #[uniform(0)]
    pub base_color: LinearRgba,
    #[uniform(0)]
    pub top_color: LinearRgba,
    #[uniform(0)]
    pub speed: f32,
    #[uniform(0)]
    pub curtain_waviness: f32,
    #[uniform(0)]
    pub ray_density: f32,
}

impl Default for AuroraMaterial {
    fn default() -> Self {
        Self {
            base_color: LinearRgba::new(0.0, 1.0, 0.5, 1.0), // Bright Green
            top_color: LinearRgba::new(0.5, 0.0, 1.0, 1.0),  // Purple
            speed: 0.5,
            curtain_waviness: 0.5,
            ray_density: 10.0,
        }
    }
}

impl Material for AuroraMaterial {
    fn vertex_shader() -> ShaderRef {
        "shaders/d03_04_aurora.wgsl".into()
    }

    fn fragment_shader() -> ShaderRef {
        "shaders/d03_04_aurora.wgsl".into()
    }

    // Essential for the "transparent" look of light in the sky
    fn alpha_mode(&self) -> AlphaMode {
        AlphaMode::Blend
    }
}

Don't forget to add it to src/materials/mod.rs:

pub mod d03_04_aurora;

The Demo Module (src/demos/d03_04_aurora.rs)

To properly showcase the effect, we need more than just a quad in empty space. This demo constructs a scene with a sense of scale:

1. The Aurora: A large quad placed high in the distance, tilted slightly toward the camera.

2. The Ruins: We generate a ring of large, rectangular stone monoliths in the foreground. These silhouettes create a "Stonehenge-like" frame for the sky, adding parallax and contrast.

3. The Lighting: We use a very dim AmbientLight so the stones are visible as silhouettes, preserving the ominous night-time atmosphere.

use crate::materials::d03_04_aurora::AuroraMaterial;
use bevy::prelude::*;
use std::f32::consts::TAU;

pub fn run() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(MaterialPlugin::<AuroraMaterial>::default())
        .add_systems(Startup, setup)
        .add_systems(Update, (update_ui, handle_input))
        .run();
}

fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<AuroraMaterial>>,
    mut standard_materials: ResMut<Assets<StandardMaterial>>,
) {
    // 1. The Aurora Curtain (Background)
    commands.spawn((
        Mesh3d(meshes.add(Rectangle::new(40.0, 20.0))), // Made bigger to fill sky
        MeshMaterial3d(materials.add(AuroraMaterial::default())),
        // Pushed back and tilted
        Transform::from_xyz(0.0, 5.0, -15.0).with_rotation(Quat::from_rotation_x(-0.2)),
    ));

    // 2. The Ground (Foreground)
    commands.spawn((
        Mesh3d(meshes.add(Plane3d::default().mesh().size(50.0, 50.0))),
        MeshMaterial3d(standard_materials.add(StandardMaterial {
            base_color: Color::srgb(0.01, 0.01, 0.02), // Very dark blue-black
            perceptual_roughness: 1.0,
            ..default()
        })),
        Transform::from_xyz(0.0, -2.0, 0.0),
    ));

    // 3. Stonehenge Ring (Silhouettes)
    // We use Cuboids instead of Cylinders for a blockier, ancient stone look
    let stone_mesh = meshes.add(Cuboid::new(1.5, 5.0, 1.0));
    let stone_mat = standard_materials.add(StandardMaterial {
        base_color: Color::srgb(0.02, 0.02, 0.02), // Almost black
        perceptual_roughness: 1.0, // Rough stone
        ..default()
    });

    let radius = 10.0;
    let stone_count = 12;

    for i in 0..stone_count {
        let angle = (i as f32 / stone_count as f32) * TAU;
        let x = angle.cos() * radius;
        let z = angle.sin() * radius;

        commands.spawn((
            Mesh3d(stone_mesh.clone()),
            MeshMaterial3d(stone_mat.clone()),
            Transform::from_xyz(x, 0.5, z)
                // Rotate the stone to face the center of the circle
                .looking_at(Vec3::ZERO, Vec3::Y),
        ));
    }

    // 4. Lighting (Subtle)
    commands.insert_resource(AmbientLight {
        color: Color::srgb(0.05, 0.05, 0.1),
        brightness: 100.0,
        ..default()
    });

    // 5. Camera
    commands.spawn((
        Camera3d::default(),
        // Center of the circle, looking up at the sky through the stones
        Transform::from_xyz(0.0, 0.0, 6.0).looking_at(Vec3::new(0.0, 4.0, -10.0), Vec3::Y),
    ));

    // 6. UI
    commands.spawn((
        Text::new(
            "[Q/A] Speed | [W/S] Ray Density | [E/D] Waviness\n\
             \n\
             Speed: 1.00\n\
             Ray Density: 12.00\n\
             Waviness: 1.00",
        ),
        Node {
            position_type: PositionType::Absolute,
            top: Val::Px(10.0),
            left: Val::Px(10.0),
            padding: UiRect::all(Val::Px(10.0)),
            ..default()
        },
        TextFont {
            font_size: 16.0,
            ..default()
        },
        TextColor(Color::WHITE),
        BackgroundColor(Color::srgba(0.0, 0.0, 0.0, 0.7)),
    ));
}

fn handle_input(
    keyboard: Res<ButtonInput<KeyCode>>,
    mut materials: ResMut<Assets<AuroraMaterial>>,
    time: Res<Time>,
) {
    let delta = time.delta_secs();

    for (_, material) in materials.iter_mut() {
        // Speed Control
        if keyboard.pressed(KeyCode::KeyQ) { material.speed += delta; }
        if keyboard.pressed(KeyCode::KeyA) { material.speed -= delta; }

        // Ray Density (The "Streaks")
        if keyboard.pressed(KeyCode::KeyW) { material.ray_density += delta * 5.0; }
        if keyboard.pressed(KeyCode::KeyS) { material.ray_density -= delta * 5.0; }

        // Curtain Waviness (The "Snake" shape)
        if keyboard.pressed(KeyCode::KeyE) { material.curtain_waviness += delta; }
        if keyboard.pressed(KeyCode::KeyD) { material.curtain_waviness -= delta; }
    }
}

fn update_ui(
    materials: Res<Assets<AuroraMaterial>>,
    mut text_query: Query<&mut Text>,
) {
    if let Some((_, material)) = materials.iter().next() {
        for mut text in text_query.iter_mut() {
            **text = format!(
                "[Q/A] Speed | [W/S] Ray Density | [E/D] Waviness\n\
                 \n\
                 Speed: {:.2}\n\
                 Ray Density: {:.2}\n\
                 Waviness: {:.2}",
                material.speed,
                material.ray_density,
                material.curtain_waviness
            );
        }
    }
}

Don't forget to add it to src/demos/mod.rs:

pub mod d03_04_aurora;

And register it in src/main.rs:

Demo {
    number: "3.4",
    title: "Gradients & Aurora",
    run: demos::d03_04_aurora::run,
},

Running the Demo

When you run the demo, you should see a glowing, shimmering curtain of light with distinct vertical streaks. The bottom should be a vibrant green fading into a deep purple at the top.

Controls

What You're Seeing

• The Curtain Shape: Notice how the entire wall of light moves back and forth. This is the curtain_curve in the shader effectively moving the y coordinate based on the x position.

• The Rays: The vertical lines are created by the fbm noise. Because we multiply the x coordinate by ray_density (e.g., 10.0) but leave y alone, the noise stretches vertically.

• The Gradient: The color shift from Green to Purple is purely a function of the Y-axis (altitude), interpolated with smoothstep.

Key Takeaways

1. mix() is your best friend: Almost every smooth transition in graphics - whether it's color, position, or opacity - is built on linear interpolation.

2. smoothstep() adds the polish: Replacing linear transitions with S-curves makes procedural effects look organic and high-quality.

3. Math is Logic: You can build complex logic using simple math functions. A radial gradient is just distance(); an angled gradient is just dot().

4. Coordinates are Malleable: As seen in the Aurora, you don't have to accept UV coordinates as they are. You can bend, twist, and stretch them to create complex shapes from simple noise.

5. Dithering matters: When working with subtle dark gradients, always keep banding in mind. A little bit of noise goes a long way.

What's Next?

We've mastered patterns and gradients, but so far everything has been mathematically generated. What if we want to use actual images - photos of bricks, wood, or metal? In the next phase, we unlock the power of Textures, learning how to load images into Bevy and sample them in our shaders.

Next up: 3.5 - Distance Functions

Quick Reference

Linear Interpolation (Lerp)

let result = mix(start, end, t); // t is 0.0 to 1.0

Smooth Transitions

// Returns 0.0 if x < 0.2, 1.0 if x > 0.8, smooth curve in between
let t = smoothstep(0.2, 0.8, x);

Radial Gradient

let dist = distance(uv, center);
let glow = 1.0 - smoothstep(0.0, radius, dist);

Angled Gradient

let dir = vec2<f32>(cos(angle), sin(angle));
let t = dot(uv - 0.5, dir) + 0.5;

Procedural Dithering

let noise = fract(sin(dot(uv, vec2(12.9898, 78.233))) * 43758.5453);
let dithered_color = color + (noise - 0.5) / 255.0;

In the last article, we learned how to give a surface a solid color or a smooth gradient. But the real world is full of intricate details - bricks, tiles, fabrics, and complex designs. How do we create these without relying on pre-made image files? The answer lies in procedural patterns, and the canvas for these patterns is the UV coordinate system.

UV coordinates are a 2D blueprint stretched over your 3D model's surface. They provide a precise address for every point, allowing us to generate patterns mathematically, directly on the GPU. This approach is incredibly powerful because these patterns are not static pixels; they are pure math, making them infinitely scalable, easily animated, and remarkably efficient.

Understanding how to manipulate UVs is a foundational skill in shader programming. These techniques are used everywhere:

• Creating tiling patterns for floors, walls, and architectural details.

• Generating masks to control where effects appear.

• Building complex procedural textures like wood grain or marble from scratch.

• Driving animations and visual effects across a surface.

• Creating debug visualizations to understand how data flows across your mesh.

By the end of this article, you will have mastered the art and science of UV-based patterns. You'll learn:

• How to visualize and use UV coordinates, the 2D blueprint for your 3D model's surface.

• To craft fundamental patterns like stripes, checkerboards, and circles using a handful of powerful WGSL functions like fract() and step().

• How to manipulate UV space itself - scaling, rotating, and moving your patterns for precise control.

• Techniques for layering and blending simple patterns to create complex and unique designs.

• How to solve the common problem of pattern stretching on non-square shapes using aspect ratio correction.

• To build a complete, interactive procedural pattern generator that combines all these concepts.

Understanding UV Coordinates

Before we can generate patterns, we must understand the canvas we're painting on. In the world of shaders, that canvas is defined by UV coordinates.

What Are UV Coordinates?

Imagine you have a 3D model, like a character or a piece of furniture. To give it a detailed surface, artists need a way to map a flat, 2D image (a texture) onto its complex 3D shape. UV mapping is the process of "unwrapping" the 3D model into a flat, 2D plane, much like unwrapping a gift or creating a flat map of the spherical Earth.

The 2D coordinate system of this unwrapped map is called UV space.

• The letters U and V are used instead of X and Y simply to distinguish them from 3D world coordinates.

• U typically represents the horizontal axis.

• V typically represents the vertical axis.

This unwrapped map provides a 2D "address" for every single point on the 3D model's surface.

Key Properties:

• Normalized Range: UV coordinates almost always exist within a [0.0, 1.0] square. The bottom-left corner is (0.0, 0.0) and the top-right is (1.0, 1.0).

• Topology, Not Size: A tiny polygon and a huge polygon can occupy the same area in UV space. The coordinates describe the mapping, not the real-world size.

• Defined Per-Vertex: In a 3D mesh, each vertex is assigned a UV coordinate. The GPU then automatically interpolates these coordinates across the face of the triangle, giving every fragment a unique, smoothly varying UV value.

How UVs Flow from Bevy to WGSL

When you create a standard mesh in Bevy (like Plane3d or a loaded model), it usually comes with UV coordinates already defined.

1. In Rust: The list of [f32; 2] UV coordinates is inserted as a vertex attribute on the Mesh. Bevy's default meshes use Mesh::ATTRIBUTE_UV_0.

2. In the Vertex Shader: We declare an input that matches this attribute's location. For standard meshes, the UVs are at @location(2). We then pass this value to an output struct.

3. In the Fragment Shader: The GPU's rasterizer interpolates the UVs from the triangle's vertices. Our fragment shader receives this interpolated value as an input, ready to be used.