Learn Wgpu

https://sotrh.github.io/learn-wgpu
Admin
Learn Wgpu is a comprehensive tutorial guiding developers through wgpu, a Rust implementation of the...
Tokens:90,219
Snippets:763
Trust Score:8.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Odd-Even Sort - Initial Data Example

Source: https://sotrh.github.io/learn-wgpu/compute/sorting

Illustrates the initial state of an array before applying the Odd-Even Sort algorithm.

```plaintext
[3, 7, 1, 5, 0, 4, 2, 6]

```

--------------------------------

### Setup wgpu Device and Queue

Source: https://sotrh.github.io/learn-wgpu/compute/introduction

This code initializes a wgpu instance, requests an adapter, and then obtains a device and queue for GPU communication. It's a foundational step for using compute shaders.

```rust
    let instance = wgpu::Instance::new(&Default::default());
    let adapter = instance.request_adapter(&Default::default()).await.unwrap();
    let (device, queue) = adapter.request_device(&Default::default()).await.unwrap();

```

--------------------------------

### Create WGPU Surface Configuration

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial5-textures

Defines the configuration for the WGPU surface, including format, dimensions, and present mode. This is a standard setup for WGPU applications.

```rust
let config = wgpu::SurfaceConfiguration {
    usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
    format: surface_format,
    width: size.width,
    height: size.height,
    present_mode: surface_caps.present_modes[0],
    alpha_mode: surface_caps.alpha_modes[0],
    view_formats: vec![],
    desired_maximum_frame_latency: 2,
};

```

--------------------------------

### Web-Specific WASM Setup

Source: https://sotrh.github.io/learn-wgpu/showcase/pong

Handles web-specific configurations for WASM builds, including appending the canvas to the document and requesting fullscreen.

```rust
#[cfg(target_arch = "wasm32")]
{
    use winit::platform::web::WindowExtWebSys;
    web_sys::window()
        .and_then(|win| win.document())
        .and_then(|doc| {
            let dst = doc.get_element_by_id("wasm-example")?;
            let canvas = web_sys::Element::from(window.canvas()?);
            dst.append_child(&canvas).ok()?;

            // Request fullscreen, if denied, continue as normal
            match canvas.request_fullscreen() {
                Ok(_) => {},
                Err(_) => ()
            }

            Some(())
        })
        .expect("Couldn't append canvas to document body.");
}

```

--------------------------------

### Instance Creation with Rotation

Source: https://sotrh.github.io/learn-wgpu/intermediate/tutorial10-lighting

Sets up instance data, including a specific rotation for one instance to demonstrate lighting issues. This code snippet is part of the setup for rendering multiple instances.

```rust
const NUM_INSTANCES_PER_ROW: u32 = 1;

// In the loop, we create the instances in
let rotation = cgmath::Quaternion::from_axis_angle((0.0, 1.0, 0.0).into(), cgmath::Deg(180.0));
```

--------------------------------

### WGSL Odd-Even Sort Shader Setup

Source: https://sotrh.github.io/learn-wgpu/compute/sorting

Sets up the storage buffer and compute shader entry point for odd-even sorting. The `read_write` storage buffer allows in-place modification of the data array. Only `global_invocation_id` is needed for indexing.

```wgsl
@group(0)
@binding(0)
var<storage, read_write> data: array<u32>;

@compute
@workgroup_size(64, 1, 1)
fn odd_even_sort(
    @builtin(global_invocation_id)
    gid: vec3<u32>,
) {
    // ...
}

```

--------------------------------

### Mipmapper Compute Pipeline Setup

Source: https://sotrh.github.io/learn-wgpu/showcase/mipmaps

Sets up the necessary bind group layout, pipeline layout, and compute pipeline for mipmap generation using a WGSL shader. Ensure the texture format is Rgba8Unorm and compatible with storage textures.

```rust
impl Mipmapper {
    pub fn new(device: &wgpu::Device) -> Self {
        let storage_texture_layout =
            device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
                label: Some("Mipmapper::texture_layout"),
                entries: &[
                    wgpu::BindGroupLayoutEntry {
                        binding: 0,
                        visibility: wgpu::ShaderStages::COMPUTE,
                        ty: wgpu::BindingType::StorageTexture {
                            access: wgpu::StorageTextureAccess::ReadOnly,
                            format: wgpu::TextureFormat::Rgba8Unorm,
                            view_dimension: wgpu::TextureViewDimension::D2,
                        },
                        count: None,
                    },
                    wgpu::BindGroupLayoutEntry {
                        binding: 1,
                        visibility: wgpu::ShaderStages::COMPUTE,
                        ty: wgpu::BindingType::StorageTexture {
                            access: wgpu::StorageTextureAccess::WriteOnly,
                            format: wgpu::TextureFormat::Rgba8Unorm,
                            view_dimension: wgpu::TextureViewDimension::D2,
                        },
                        count: None,
                    },
                ],
            });

        let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
            label: None,
            bind_group_layouts: &[Some(&storage_texture_layout)],
            immediate_size: 0,
        });
        let compute_module = device.create_shader_module(wgpu::include_wgsl!("mipmap.wgsl"));
        let compute_mipmap = device.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
            label: Some("Mipmapper"),
            layout: Some(&pipeline_layout),
            module: &compute_module,
            entry_point: Some("compute_mipmap"),
            compilation_options: Default::default(),
            cache: None,
        });
    }

    // ...
}

```

--------------------------------

### Draw Instanced Model in wgpu

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial9-models

Example of how to use the `draw_model_instanced` method within a render pass. Ensure the instance buffer and render pipeline are set before drawing.

```rust
render_pass.set_vertex_buffer(1, self.instance_buffer.slice(..));
render_pass.set_pipeline(&self.render_pipeline);
render_pass.draw_model_instanced(&self.obj_model, 0..self.instances.len() as u32, &self.camera_bind_group);

```

--------------------------------

### Get Current Texture from Surface

Source: https://sotrh.github.io/learn-wgpu/news/pre-0.12

Demonstrates how to retrieve the current texture from the wgpu surface, handling various states like success, suboptimal, and outdated configurations.

```rust
let output = match self.surface.get_current_texture() {
            wgpu::CurrentSurfaceTexture::Success(surface_texture) => surface_texture,
            wgpu::CurrentSurfaceTexture::Suboptimal(surface_texture) => {
                self.surface.configure(&self.device, &self.config);
                surface_texture
            }
            wgpu::CurrentSurfaceTexture::Timeout
            | wgpu::CurrentSurfaceTexture::Occluded
            | wgpu::CurrentSurfaceTexture::Validation => {
                // Skip this frame
                return Ok(());
            }
            wgpu::CurrentSurfaceTexture::Outdated => {
                self.surface.configure(&self.device, &self.config);
                return Ok(());
            }
            wgpu::CurrentSurfaceTexture::Lost => {
                // You could recreate the devices and all resources
                // created with it here, but we'll just bail
                anyhow::bail!("Lost device");
            }
        };
let view = output
    .texture
    .create_view(&wgpu::TextureViewDescriptor::default());

```

--------------------------------

### Defining Vertices Without Indexing

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial4-buffer

This example shows how to define vertices for a pentagon where some vertices are repeated. This approach leads to redundant data and increased memory usage.

```rust
const VERTICES: &[Vertex] = &[
    Vertex { position: [-0.0868241, 0.49240386, 0.0], color: [0.5, 0.0, 0.5] }, // A
    Vertex { position: [-0.49513406, 0.06958647, 0.0], color: [0.5, 0.0, 0.5] }, // B
    Vertex { position: [0.44147372, 0.2347359, 0.0], color: [0.5, 0.0, 0.5] }, // E

    Vertex { position: [-0.49513406, 0.06958647, 0.0], color: [0.5, 0.0, 0.5] }, // B
    Vertex { position: [-0.21918549, -0.44939706, 0.0], color: [0.5, 0.0, 0.5] }, // C
    Vertex { position: [0.44147372, 0.2347359, 0.0], color: [0.5, 0.0, 0.5] }, // E

    Vertex { position: [-0.21918549, -0.44939706, 0.0], color: [0.5, 0.0, 0.5] }, // C
    Vertex { position: [0.35966998, -0.3473291, 0.0], color: [0.5, 0.0, 0.5] }, // D
    Vertex { position: [0.44147372, 0.2347359, 0.0], color: [0.5, 0.0, 0.5] }, // E
];

```

--------------------------------

### Defining Vertices and Indices for a Pentagon

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial4-buffer

This example demonstrates the optimized approach using an index buffer. Unique vertices are stored once, and an index buffer references these vertices to form triangles, significantly reducing data duplication.

```rust
// lib.rs
const VERTICES: &[Vertex] = &[
    Vertex { position: [-0.0868241, 0.49240386, 0.0], color: [0.5, 0.0, 0.5] }, // A
    Vertex { position: [-0.49513406, 0.06958647, 0.0], color: [0.5, 0.0, 0.5] }, // B
    Vertex { position: [-0.21918549, -0.44939706, 0.0], color: [0.5, 0.0, 0.5] }, // C
    Vertex { position: [0.35966998, -0.3473291, 0.0], color: [0.5, 0.0, 0.5] }, // D
    Vertex { position: [0.44147372, 0.2347359, 0.0], color: [0.5, 0.0, 0.5] }, // E
];

const INDICES: &[u16] = &[
    0, 1, 4,
    1, 2, 4,
    2, 3, 4,
];

```

--------------------------------

### Compile Shaders and Create Render Pipeline

Source: https://sotrh.github.io/learn-wgpu/showcase/windowless

Compiles vertex and fragment shaders using shaderc and creates a wgpu RenderPipeline. Ensure shaderc is installed and shaders are in the correct path.

```rust
let vs_src = include_str!("shader.vert");
let fs_src = include_str!("shader.frag");
let mut compiler = shaderc::Compiler::new().unwrap();
let vs_spirv = compiler
    .compile_into_spirv(
        vs_src,
        shaderc::ShaderKind::Vertex,
        "shader.vert",
        "main",
        None,
    )
    .unwrap();
let fs_spirv = compiler
    .compile_into_spirv(
        fs_src,
        shaderc::ShaderKind::Fragment,
        "shader.frag",
        "main",
        None,
    )
    .unwrap();
let vs_data = wgpu::util::make_spirv(vs_spirv.as_binary_u8());
let fs_data = wgpu::util::make_spirv(fs_spirv.as_binary_u8());
let vs_module = device.create_shader_module(wgpu::ShaderModuleDescriptor {
    label: Some("Vertex Shader"),
    source: vs_data,
    flags: wgpu::ShaderFlags::default(),
});
let fs_module = device.create_shader_module(wgpu::ShaderModuleDescriptor {
    label: Some("Fragment Shader"),
    source: fs_data,
    flags: wgpu::ShaderFlags::default(),
});

let render_pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
    label: Some("Render Pipeline Layout"),
    bind_group_layouts: &[],
    immediate_size: 0,
});

let render_pipeline = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
    label: Some("Render Pipeline"),
    layout: Some(&render_pipeline_layout),
    vertex: wgpu::VertexState {
        module: &vs_module,
        entry_point: Some("main"),
        buffers: &[],
    },
    fragment: Some(wgpu::FragmentState {
        module: &fs_module,
        entry_point: Some("main"),
        targets: &[Some(wgpu::ColorTargetState {
            format: texture_desc.format,
            alpha_blend: wgpu::BlendState::REPLACE,
            color_blend: wgpu::BlendState::REPLACE,
            write_mask: wgpu::ColorWrites::ALL,
        })],
    }),
    primitive: wgpu::PrimitiveState {
        topology: wgpu::PrimitiveTopology::TriangleList,
        strip_index_format: None,
        front_face: wgpu::FrontFace::Ccw,
        cull_mode: Some(wgpu::Face::Back),
        // Setting this to anything other than Fill requires Features::NON_FILL_POLYGON_MODE
        polygon_mode: wgpu::PolygonMode::Fill,
    },
    depth_stencil: None,
    multisample: wgpu::MultisampleState {
        count: 1,
        mask: !0,
        alpha_to_coverage_enabled: false,
    },
});

```

--------------------------------

### Begin Render Pass and Clear Screen

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial2-surface

Starts a render pass using the command encoder and configures the color attachment to clear the screen with a specific color. The render pass is enclosed in a block to ensure its mutable borrow of the encoder is released before the encoder is finished.

```rust
{
        let _render_pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
            label: Some("Render Pass"),
            color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                view: &view,
                resolve_target: None,
                depth_slice: None,
                ops: wgpu::Operations {
                    load: wgpu::LoadOp::Clear(wgpu::Color {
                        r: 0.1,
                        g: 0.2,
                        b: 0.3,
                        a: 1.0,
                    }),
                    store: wgpu::StoreOp::Store,
                },
            })],
            depth_stencil_attachment: None,
            occlusion_query_set: None,
            timestamp_writes: None,
            multiview_mask: None,
        });
    }

```

--------------------------------

### Create wgpu Surface and Request Adapter

Source: https://sotrh.github.io/learn-wgpu/news/pre-0.12

Demonstrates the updated method for creating a wgpu Surface and requesting an Adapter, replacing the previous Instance usage. Ensure to unwrap the result of adapter request.

```rust
let surface = wgpu::Surface::create(window);
let adapter = wgpu::Adapter::request(&wgpu::RequestAdapterOptions {
    ..Default::default()
}).unwrap(); // needs to be unwrapped
```

--------------------------------

### Getting Supported Present Modes

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial2-surface

Retrieves a list of supported present modes for the surface from the adapter's capabilities.

```rust
let modes = &surface_caps.present_modes;
```

--------------------------------

### Initialize Wgpu Instance and Surface

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial2-surface

Initializes the wgpu Instance and creates a surface from the provided window. This is the first step in setting up wgpu rendering.

```rust
let instance = wgpu::Instance::new(wgpu::InstanceDescriptor {
            #[cfg(not(target_arch = "wasm32"))]
            backends: wgpu::Backends::PRIMARY,
            #[cfg(target_arch = "wasm32")]
            backends: wgpu::Backends::GL,
            flags: Default::default(),
            memory_budget_thresholds: Default::default(),
            backend_options: Default::default(),
            display: None,
        });

        let surface = instance.create_surface(window.clone()).unwrap();
```

--------------------------------

### Odd-Even Sort - Even Pass Example

Source: https://sotrh.github.io/learn-wgpu/compute/sorting

Shows the pairs considered and the state of the array after the even pass of the Odd-Even Sort.

```plaintext
[[3, 1], [7, 0], [2, 4]]
[1, 3, 0, 7, 2, 4]

```

--------------------------------

### Create and Configure Window for Pong

Source: https://sotrh.github.io/learn-wgpu/showcase/pong

Sets up the event loop, primary monitor, and creates a window with fullscreen capabilities. Includes fallback resolution for WASM builds.

```rust
let event_loop = EventLoop::new();
let monitor = event_loop.primary_monitor().unwrap();
let video_mode = monitor.video_modes().next();
let size = video_mode.clone().map_or(PhysicalSize::new(800, 600), |vm| vm.size());
let window = WindowBuilder::new()
    .with_visible(false)
    .with_title("Pong")
    .with_fullscreen(video_mode.map(|vm| Fullscreen::Exclusive(vm)))
    .build(&event_loop)
    .unwrap();

// WASM builds don't have access to monitor information, so
// we should specify a fallback resolution
if window.fullscreen().is_none() {
    window.set_inner_size(PhysicalSize::new(512, 512));
}

```

--------------------------------

### Odd-Even Sort - Odd Pass Example

Source: https://sotrh.github.io/learn-wgpu/compute/sorting

Shows the pairs considered and the state of the array after the odd pass of the Odd-Even Sort.

```plaintext
[[7, 1], [5, 0], [4, 2]]
[3, 1, 7, 0, 5, 2, 4]

```

--------------------------------

### Getting the HDR Texture Format

Source: https://sotrh.github.io/learn-wgpu/intermediate/tutorial13-hdr

Returns the wgpu::TextureFormat of the HDR texture. This can be used to ensure compatibility with other rendering operations.

```rust
/// The format of the HDR texture
    pub fn format(&self) -> wgpu::TextureFormat {
        self.format
    }
```

--------------------------------

### Create Instance with Display Handle

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial2-surface

Demonstrates creating a wgpu Instance with a specific display handle, useful for certain platform-specific configurations.

```rust
let instance = Instance::new(InstanceDescriptor::new_with_display_handle(Box::new(event_loop.owned_display_handle())));
```

--------------------------------

### Begin Render Pass and Draw

Source: https://sotrh.github.io/learn-wgpu/showcase/windowless

Sets up a wgpu RenderPass with a color attachment and clears it. It then sets the render pipeline and issues a draw call for a triangle.

```rust
{
    let render_pass_desc = wgpu::RenderPassDescriptor {
        label: Some("Render Pass"),
        color_attachments: &[ 
            wgpu::RenderPassColorAttachment {
                view: &texture_view,
                resolve_target: None,
                ops: wgpu::Operations {
                    load: wgpu::LoadOp::Clear(wgpu::Color {
                        r: 0.1,
                        g: 0.2,
                        b: 0.3,
                        a: 1.0,
                    }),
                    store: wgpu::StoreOp::Store,
                },
            }
        ],
        depth_stencil_attachment: None,
    };
    let mut render_pass = encoder.begin_render_pass(&render_pass_desc);

    render_pass.set_pipeline(&render_pipeline);
    render_pass.draw(0..3, 0..1);
}

```

--------------------------------

### Create Input and Output Buffers in WebGPU

Source: https://sotrh.github.io/learn-wgpu/compute/introduction

Sets up an input buffer with initial data and an output buffer of the same size. Both buffers are configured for storage usage, allowing them to be accessed by shaders.

```rust
    let input_buffer = device.create_buffer_init(&BufferInitDescriptor {
        label: Some("input"),
        contents: bytemuck::cast_slice(&input_data),
        usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::STORAGE,
    });

    let output_buffer = device.create_buffer(&wgpu::BufferDescriptor {
        label: Some("output"),
        size: input_buffer.size(),
        usage: wgpu::BufferUsages::COPY_SRC | wgpu::BufferUsages::STORAGE,
        mapped_at_creation: false,
    });

```

--------------------------------

### Generate Instance Data

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial9-models

Generates a vector of `Instance` structs, calculating their positions and rotations. This example adjusts spacing for a grid of instances.

```rust
const SPACE_BETWEEN: f32 = 3.0;
let instances = (0..NUM_INSTANCES_PER_ROW).flat_map(|z| {
    (0..NUM_INSTANCES_PER_ROW).map(move |x| {
        let x = SPACE_BETWEEN * (x as f32 - NUM_INSTANCES_PER_ROW as f32 / 2.0);
        let z = SPACE_BETWEEN * (z as f32 - NUM_INSTANCES_PER_ROW as f32 / 2.0);

        let position = cgmath::Vector3 { x, y: 0.0, z };

        let rotation = if position.is_zero() {
            cgmath::Quaternion::from_axis_angle(cgmath::Vector3::unit_z(), cgmath::Deg(0.0))
        } else {
            cgmath::Quaternion::from_axis_angle(position.normalize(), cgmath::Deg(45.0))
        };

        Instance {
            position, rotation,
        }
    })
}).collect::<Vec<_>>();
```

--------------------------------

### Odd-Even Sort - Worst Case Example

Source: https://sotrh.github.io/learn-wgpu/compute/sorting

Illustrates the sorting process for a reverse-sorted array, showing the maximum number of passes required.

```plaintext
[7, 6, 5, 4, 3, 2, 1, 0]

```

```plaintext
[7, 5, 6, 3, 4, 1, 2, 0] // odd
[5, 7, 3, 6, 1, 4, 0, 2] // even
[5, 3, 7, 1, 6, 0, 4, 2] // odd
[3, 5, 1, 7, 0, 6, 2, 4] // even
[3, 1, 5, 0, 7, 2, 6, 4] // odd
[1, 3, 0, 5, 2, 7, 4, 6] // even
[1, 0, 3, 2, 5, 4, 7, 6] // odd
[0, 1, 2, 3, 4, 5, 6, 7] // even

```

--------------------------------

### Initialize Camera and Projection in State::new

Source: https://sotrh.github.io/learn-wgpu/intermediate/tutorial12-camera

Update the `State::new` function to initialize the `camera`, `projection`, and `camera_controller`. Ensure `camera_uniform.update_view_proj` is called with the new camera and projection.

```rust
impl State {
    async fn new(window: Arc<Window>) -> anyhow::Result<State> {
        // ...

        // UPDATED!
        let camera = camera::Camera::new((0.0, 5.0, 10.0), cgmath::Deg(-90.0), cgmath::Deg(-20.0));
        let projection = camera::Projection::new(config.width, config.height, cgmath::Deg(45.0), 0.1, 100.0);
        let camera_controller = camera::CameraController::new(4.0, 0.4);

        // ...

        camera_uniform.update_view_proj(&camera, &projection); // UPDATED!

        // ...

        Self {
            // ...
            camera,
            projection, // NEW!
            camera_controller,
            // ...
            mouse_pressed: false, // NEW!
        }
    }
}

```

--------------------------------

### Initialize Render Pipeline in State::new

Source: https://sotrh.github.io/learn-wgpu/intermediate/tutorial10-lighting

Demonstrates how to use the `create_render_pipeline` function within the `State::new` method to initialize the render pipeline.

```rust
let render_pipeline = {
    let shader = wgpu::ShaderModuleDescriptor {
        label: Some("Normal Shader"),
        source: wgpu::ShaderSource::Wgsl(include_str!("shader.wgsl").into()),
    };
    create_render_pipeline(
        &device,
        &render_pipeline_layout,
        config.format,
        Some(texture::Texture::DEPTH_FORMAT),
        &[model::ModelVertex::desc(), InstanceRaw::desc()],
        shader,
    )
};

```

--------------------------------

### WGSL Odd-Even Sort - Get Pair Index

Source: https://sotrh.github.io/learn-wgpu/compute/sorting

Retrieves the index of the pair the current thread will process. This is a fundamental step for parallelizing the comparison.

```wgsl
    let num_items = arrayLength(&data);
    let pair_index = gid.x;

```

--------------------------------

### Handle Keyboard Input in WGPU

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial2-surface

Implement the `handle_key` function to process keyboard events. This example shows how to exit the application when the Escape key is pressed.

```rust
impl State {
    fn handle_key(&self, event_loop: &ActiveEventLoop, code: KeyCode, is_pressed: bool) {
        match (code, is_pressed) {
            (KeyCode::Escape, true) => event_loop.exit(),
            _ => {}
        }
    }
}
```

--------------------------------

### Configuring the wgpu Surface

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial2-surface

Sets up the surface configuration, including format, dimensions, and present mode, based on adapter capabilities.

```rust
        let surface_caps = surface.get_capabilities(&adapter);
        // Shader code in this tutorial assumes an sRGB surface texture. Using a different
        // one will result in all the colors coming out darker. If you want to support non
        // sRGB surfaces, you'll need to account for that when drawing to the frame.
        let surface_format = surface_caps.formats.iter()
            .find(|f| f.is_srgb())
            .copied()
            .unwrap_or(surface_caps.formats[0]);
        let config = wgpu::SurfaceConfiguration {
            usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
            format: surface_format,
            width: size.width,
            height: size.height,
            present_mode: surface_caps.present_modes[0],
            alpha_mode: surface_caps.alpha_modes[0],
            view_formats: vec![],
            desired_maximum_frame_latency: 2,
        };


```

--------------------------------

### Create Compute Pipeline

Source: https://sotrh.github.io/learn-wgpu/compute/introduction

This snippet demonstrates how to create a compute pipeline using a shader module. Default values are used for most settings, with explicit configuration for the label and shader module. WGPU can infer the bind group layout and entry point if not explicitly provided.

```rust
    let shader = device.create_shader_module(wgpu::include_wgsl!("introduction.wgsl"));

    let pipeline = device.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
        label: Some("Introduction Compute Pipeline"),
        layout: None,
        module: &shader,
        entry_point: None,
        compilation_options: Default::default(),
        cache: Default::default(),
    });


```

--------------------------------

### Requesting a wgpu Device and Queue

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial2-surface

Creates a wgpu device and queue from an adapter. It includes logic to use WebGL2 defaults for WASM targets.

```rust
        let (device, queue) = adapter
            .request_device(&wgpu::DeviceDescriptor {
                label: None,
                required_features: wgpu::Features::empty(),
                experimental_features: wgpu::ExperimentalFeatures::disabled(),
                // WebGL doesn't support all of wgpu's features, so if
                // we're building for the web we'll have to disable some.
                required_limits: if cfg!(target_arch = "wasm32") {
                    wgpu::Limits::downlevel_webgl2_defaults()
                } else {
                    wgpu::Limits::default()
                },
                memory_hints: Default::default(),
                trace: wgpu::Trace::Off,
            })
            .await?;
```

--------------------------------

### Handle Window Resizing with Surface Reconfiguration

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial2-surface

The `resize` method reconfigures the WGPU surface when the window size changes. It updates the configuration with the new dimensions and sets the `is_surface_configured` flag to true.

```rust
// impl State
pub fn resize(&mut self, width: u32, height: u32) {
    if width > 0 && height > 0 {
        self.config.width = width;
        self.config.height = height;
        self.surface.configure(&self.device, &self.config);
        self.is_surface_configured = true;
    }
}

```

--------------------------------

### WASM Entry Point Function

Source: https://sotrh.github.io/learn-wgpu/showcase/pong

Defines the entry point for the WebAssembly module, marked with `#[wasm_bindgen(start)]`. This function is executed when the WASM module is loaded by JavaScript.

```rust
#[cfg(target_arch="wasm32")]
use wasm_bindgen::prelude::*;

#[cfg_attr(target_arch="wasm32", wasm_bindgen(start))]
pub fn start() {
    // Snipped...
}

```

--------------------------------

### Request Wgpu Adapter

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial2-surface

Requests a wgpu adapter compatible with the created surface, specifying power preferences. This adapter will be used to create the device and queue.

```rust
let adapter = instance
            .request_adapter(&wgpu::RequestAdapterOptions {
                power_preference: wgpu::PowerPreference::default(),
                compatible_surface: Some(&surface),
                force_fallback_adapter: false,
            })
            .await?;
```

--------------------------------

### Creating Vertex and Index Buffers in wgpu

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial4-buffer

This snippet shows how to create both the vertex buffer and the new index buffer using `device.create_buffer_init`. It also updates the count to use the number of indices.

```rust
let vertex_buffer = device.create_buffer_init(
    &wgpu::util::BufferInitDescriptor {
        label: Some("Vertex Buffer"),
        contents: bytemuck::cast_slice(VERTICES),
        usage: wgpu::BufferUsages::VERTEX,
    }
);
// NEW!
let index_buffer = device.create_buffer_init(
    &wgpu::util::BufferInitDescriptor {
        label: Some("Index Buffer"),
        contents: bytemuck::cast_slice(INDICES),
        usage: wgpu::BufferUsages::INDEX,
    }
);
let num_indices = INDICES.len() as u32;

```

--------------------------------

### Return State with Vertex Buffer in Rust

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial4-buffer

Returns the initialized `State` struct, including the newly created `vertex_buffer`. This completes the setup for using the vertex buffer in rendering.

```rust
Ok(Self {
    surface,
    device,
    queue,
    config,
    is_surface_configured: false,
    window,
    render_pipeline,
    vertex_buffer,
})
```

--------------------------------

### Get Current Surface Texture for Drawing

Source: https://sotrh.github.io/learn-wgpu/news/pre-0.12

Obtain the current texture from the surface to draw on. Handles suboptimal or outdated textures by reconfiguring the surface. Returns an error if the device is lost.

```rust
let output = match self.surface.get_current_texture() {
            wgpu::CurrentSurfaceTexture::Success(surface_texture) => surface_texture,
            wgpu::CurrentSurfaceTexture::Suboptimal(surface_texture) => {
                self.surface.configure(&self.device, &self.config);
                surface_texture
            }
            wgpu::CurrentSurfaceTexture::Timeout
            | wgpu::CurrentSurfaceTexture::Occluded
            | wgpu::CurrentSurfaceTexture::Validation => {
                // Skip this frame
                return Ok(());
            }
            wgpu::CurrentSurfaceTexture::Outdated => {
                self.surface.configure(&self.device, &self.config);
                return Ok(());
            }
            wgpu::CurrentSurfaceTexture::Lost => {
                // You could recreate the devices and all resources
                // created with it here, but we'll just bail
                anyhow::bail!("Lost device");
            }
        };
let view = output
    .texture
    .create_view(&wgpu::TextureViewDescriptor::default());
```

--------------------------------

### Create and Initialize Camera Buffer

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial6-uniforms

Initializes a wgpu uniform buffer with camera data. This buffer is marked with UNIFORM and COPY_DST usages, allowing it to be updated from the CPU and read by shaders.

```rust
// in new() after creating `camera`

let mut camera_uniform = CameraUniform::new();
camera_uniform.update_view_proj(&camera);

let camera_buffer = device.create_buffer_init(
    &wgpu::util::BufferInitDescriptor {
        label: Some("Camera Buffer"),
        contents: bytemuck::cast_slice(&[camera_uniform]),
        usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
    }
);

```

--------------------------------

### Create and Initialize Light Uniform Buffer in Rust

Source: https://sotrh.github.io/learn-wgpu/intermediate/tutorial10-lighting

Initializes a Wgpu uniform buffer with light data. This buffer is marked with COPY_DST to allow for future updates to the light's properties.

```rust
let light_uniform = LightUniform {
    position: [2.0, 2.0, 2.0],
    _padding: 0,
    color: [1.0, 1.0, 1.0],
    _padding2: 0,
};

 // We'll want to update our lights position, so we use COPY_DST
let light_buffer = device.create_buffer_init(
    &wgpu::util::BufferInitDescriptor {
        label: Some("Light VB"),
        contents: bytemuck::cast_slice(&[light_uniform]),
        usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
    }
);

```

--------------------------------

### WGSL Struct Definition for Light

Source: https://sotrh.github.io/learn-wgpu/showcase/alignment

Defines a 'Light' struct with position and color, each as a vec3<f32>. This example illustrates a common struct layout that requires understanding WGSL's alignment rules.

```wgsl
struct Light {
    position: vec3<f32>,
    color: vec3<f32>,
}

```

--------------------------------

### Load Image Data and Get Dimensions

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial5-textures

Load image bytes from a file using 'include_bytes!' and decode them using the 'image' crate. Convert the image to RGBA8 format and extract its dimensions for texture creation.

```rust
let diffuse_bytes = include_bytes!("happy-tree.png");
let diffuse_image = image::load_from_memory(diffuse_bytes).unwrap();
let diffuse_rgba = diffuse_image.to_rgba8();

use image::GenericImageView;
let dimensions = diffuse_image.dimensions();

```

--------------------------------

### Initialize Update Method in WGPU

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial2-surface

Define the `update` method for the game state. Currently, it's empty as there are no game logic updates to perform yet.

```rust
fn update(&mut self) {
    // remove `todo!()`
}
```

--------------------------------

### Run Function for wgpu Application

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial1-window

Initializes logging, creates an event loop, and runs the application. Includes conditional logic for web assembly targets.

```rust
pub fn run() -> anyhow::Result<()> {
    #[cfg(not(target_arch = "wasm32"))] {
        env_logger::init();
    }
    #[cfg(target_arch = "wasm32")] {
        console_log::init_with_level(log::Level::Info).unwrap_throw();
    }

    let event_loop = EventLoop::with_user_event().build()?;
    #[cfg(not(target_arch = "wasm32"))] {
        let mut app = App::new();
        event_loop.run_app(&mut app)?;
    }
    #[cfg(target_arch = "wasm32")] {
        let app = App::new(&event_loop);
        event_loop.spawn_app(app);
    }

    Ok(())
}

```

--------------------------------

### Create Shader Module using include_wgsl!

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial3-pipeline

Use the include_wgsl! macro as a shortcut to create a shader module descriptor.

```rust
let shader = device.create_shader_module(wgpu::include_wgsl!("shader.wgsl"));

```

--------------------------------

### Enumerate and Filter Wgpu Adapters

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial2-surface

Enumerates all available wgpu adapters and filters them to find one that supports the given surface. This is an alternative to `request_adapter` when more control is needed.

```rust
let adapter = instance
    .enumerate_adapters(wgpu::Backends::all())
    .await
    .into_iter()
    .filter(|adapter| {
        // Check if this adapter supports our surface
        adapter.is_surface_supported(&surface)
    })
    .next()
    .unwrap()
```

--------------------------------

### Configure wgpu Surface

Source: https://sotrh.github.io/learn-wgpu/news/pre-0.12

Use this code to configure the wgpu surface with desired properties like usage, format, dimensions, and present mode. Ensure the format is supported by the surface.

```rust
let config = wgpu::SurfaceConfiguration {
    usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
    format: surface.get_supported_formats(&adapter)[0],
    width: size.width,
    height: size.height,
    present_mode: wgpu::PresentMode::Fifo,
};
surface.configure(&device, &config);
```

--------------------------------

### Rust Compilation Error for Misaligned Struct

Source: https://sotrh.github.io/learn-wgpu/showcase/alignment

Shows the specific Rust compiler error encountered when trying to transmute a struct with implicit padding bytes, like the 'LightUniform' example, to a type without padding. This error indicates a size mismatch.

```rust
error[E0512]: cannot transmute between types of different sizes, or dependently-sized types
   --> code/intermediate/tutorial10-lighting/src/main.rs:246:8
    |
246 | struct LightUniform {
    |        ^^^^^^^^^^^^
    |
    = note: source type: `LightUniform` (256 bits)
    = note: target type: `_::{closure#0}::TypeWithoutPadding` (192 bits)


```

--------------------------------

### Setup Render Pipeline with Stencil Buffer

Source: https://sotrh.github.io/learn-wgpu/showcase/stencil

Configures a wgpu render pipeline with specific stencil buffer operations for drawing hidden objects. Ensure the depth_stencil format is correctly set and the stencil compare function is set to 'Equal' to only draw when the stencil reference matches the buffer.

```rust
let hidden_pipeline = framework::RenderPipelineBuilder::new()
    .layout(&model_pipeline_layout)
    .vertex_shader(model_shader.clone())
    .fragment_shader(model_shader.clone())
    .cull_mode(Some(wgpu::Face::Back))
    .color_state(wgpu::ColorTargetState {
        format: display.config.format,
        blend: None,
        write_mask: wgpu::ColorWrites::ALL,
    })
    .depth_stencil(wgpu::DepthStencilState {
        format: depth_stencil.format(),
        depth_write_enabled: Some(true),
        depth_compare: Some(wgpu::CompareFunction::Less),
        stencil: wgpu::StencilState {
            // Read all bits
            read_mask: 0xFF,
            write_mask: 0xFF,
            front: wgpu::StencilFaceState {
                // Only draw when stencil reference == what's in the buffer
                compare: wgpu::CompareFunction::Equal,
                depth_fail_op: wgpu::StencilOperation::Keep,
                ..Default::default()
            },
            back: wgpu::StencilFaceState::IGNORE,
        },
        bias: wgpu::DepthBiasState::default(),
    })
    .vertex_buffer_desc(ModelVertex::desc())
    .vertex_buffer_desc(InstanceVertex::DESC)
    .build(&display.device)?;
```

--------------------------------

### Import Camera Module

Source: https://sotrh.github.io/learn-wgpu/intermediate/tutorial12-camera

Add the camera module to your project's main file. Ensure this is done before using any camera-related functionalities.

```rust
mod model;
mod texture;
mod camera; // NEW!

```

--------------------------------

### Request Adapter and Device

Source: https://sotrh.github.io/learn-wgpu/showcase/windowless

Obtain a wgpu adapter and device for GPU operations without needing a compatible surface. This is useful for compute-only tasks.

```rust
let adapter = instance
    .request_adapter(&wgpu::RequestAdapterOptions {
        power_preference: wgpu::PowerPreference::default(),
        compatible_surface: None,
    })
    .await
    .unwrap();
let (device, queue) = adapter
    .request_device(&Default::default(), None)
    .await
    .unwrap();
```

--------------------------------

### Initialize State with Surface Configuration

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial2-surface

This snippet shows the initialization of the State struct, including the surface, device, queue, and configuration. The `is_surface_configured` flag is set to false initially.

```rust
    async fn new(window: Arc<Window>) -> anyhow::Result<State> {
        // ...

        Ok(Self {
            surface,
            device,
            queue,
            config,
            is_surface_configured: false,
            window,
        })
    }

```

--------------------------------

### CameraController Initialization

Source: https://sotrh.github.io/learn-wgpu/intermediate/tutorial12-camera

Constructor for CameraController, setting initial movement amounts to zero and applying provided speed and sensitivity.

```rust
impl CameraController {
    pub fn new(speed: f32, sensitivity: f32) -> Self {
        Self {
            amount_left: 0.0,
            amount_right: 0.0,
            amount_forward: 0.0,
            amount_backward: 0.0,
            amount_up: 0.0,
            amount_down: 0.0,
            rotate_horizontal: 0.0,
            rotate_vertical: 0.0,
            scroll: 0.0,
            speed,
            sensitivity,
        }
    }

```

--------------------------------

### Initialize Vertex Buffer in Rust

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial4-buffer

Initializes a vertex buffer using `device.create_buffer_init`. Requires importing `wgpu::util::DeviceExt`. The `bytemuck::cast_slice` function is used to convert vertex data to `&[u8]`.

```rust
let vertex_buffer = device.create_buffer_init(
    &wgpu::util::BufferInitDescriptor {
        label: Some("Vertex Buffer"),
        contents: bytemuck::cast_slice(VERTICES),
        usage: wgpu::BufferUsages::VERTEX,
    }
);
```

--------------------------------

### Create Mipmap Generation Pipeline

Source: https://sotrh.github.io/learn-wgpu/showcase/mipmaps

Initializes the necessary components for mipmap generation, including the render pipeline and a linear sampler. Requires a `wgpu::Device`.

```rust
impl Mipmapper {
    pub fn new(device: &wgpu::Device) -> Self {
        let blit_shader = wgpu::include_wgsl!("blit.wgsl");
        let blit_format = wgpu::TextureFormat::Rgba8Unorm;
        let blit_mipmap = RenderPipelineBuilder::new()
            .vertex_shader(blit_shader.clone())
            .fragment_shader(blit_shader.clone())
            .cull_mode(Some(wgpu::Face::Back))
            .color_solid(blit_format)
            .build(device)
            .unwrap();
        let blit_sampler = device.create_sampler(&wgpu::SamplerDescriptor {
            min_filter: wgpu::FilterMode::Linear,
            mag_filter: wgpu::FilterMode::Linear,
            ..Default::default()
        });

        // ...
    }
}
```

--------------------------------

### Initialize Material with Normal Texture

Source: https://sotrh.github.io/learn-wgpu/intermediate/tutorial11-normals

Implement the `Material::new` function to accept and store the normal texture, and create the corresponding bind group entries.

```rust
impl Material {
    pub fn new(
        device: &wgpu::Device,
        name: &str,
        diffuse_texture: texture::Texture,
        normal_texture: texture::Texture, // NEW!
        layout: &wgpu::BindGroupLayout,
    ) -> Self {
        let bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
            layout,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: wgpu::BindingResource::TextureView(&diffuse_texture.view),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: wgpu::BindingResource::Sampler(&diffuse_texture.sampler),
                },
                // NEW!
                wgpu::BindGroupEntry {
                    binding: 2,
                    resource: wgpu::BindingResource::TextureView(&normal_texture.view),
                },
                wgpu::BindGroupEntry {
                    binding: 3,
                    resource: wgpu::BindingResource::Sampler(&normal_texture.sampler),
                },
            ],
            label: Some(name),
        });

        Self {
            name: String::from(name),
            diffuse_texture,
            normal_texture, // NEW!
            bind_group,
        }
    }
}
```

--------------------------------

### Create Skybox Render Pipeline

Source: https://sotrh.github.io/learn-wgpu/intermediate/tutorial13-hdr

Sets up the render pipeline for the skybox, including the pipeline layout that incorporates camera and environment bind group layouts, and the shader module. Ensure the shader file 'sky.wgsl' exists.

```rust
let sky_pipeline = {
    let layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
        label: Some("Sky Pipeline Layout"),
        bind_group_layouts: &[Some(&camera_bind_group_layout), Some(&environment_layout)],
        immediate_size: 0,
    });
    let shader = wgpu::include_wgsl!("sky.wgsl");
    create_render_pipeline(
        &device,
        &layout,
        hdr.format(),
        Some(texture::Texture::DEPTH_FORMAT),
        &[],
        wgpu::PrimitiveTopology::TriangleList,
        shader,
    )
};
```

--------------------------------

### Resize wgpu Surface Configuration

Source: https://sotrh.github.io/learn-wgpu/news/pre-0.12

Update the surface configuration with new width and height values when the window is resized. This ensures rendering matches the current window dimensions. Call this only when width and height are greater than 0.

```rust
if width > 0 && height > 0 {
    self.is_surface_configured = true;
    self.config.width = width;
    self.config.height = height;
    self.surface.configure(&self.device, &self.config);
}
```

--------------------------------

### Load Texture and Create Mipmapped Texture Descriptor

Source: https://sotrh.github.io/learn-wgpu/showcase/mipmaps

Loads an image using the 'image' crate and computes the number of mip levels. It then creates a WGPU texture with the appropriate mip level count and usage flags for texture binding, copying destination, and copying source.

```rust
let diffuse_img = image::open(res_dir.join("textures/cobble-diffuse.png"))?.to_rgba8();

let mip_level_count = diffuse_img.width().min(diffuse_img.height()).ilog2() + 1;

let diffuse_blit_texture = display.device.create_texture(&wgpu::TextureDescriptor {
    label: Some("textures/cobble-diffuse.png"),
    size: wgpu::Extent3d {
        width: diffuse_img.width(),
        height: diffuse_img.height(),
        depth_or_array_layers: 1,
    },
    mip_level_count, 
    sample_count: 1,
    dimension: wgpu::TextureDimension::D2,
    format: wgpu::TextureFormat::Rgba8UnormSrgb,
    usage: wgpu::TextureUsages::TEXTURE_BINDING
        | wgpu::TextureUsages::COPY_DST
        | wgpu::TextureUsages::COPY_SRC,
    view_formats: &[],
});
```

--------------------------------

### Create Command Encoder

Source: https://sotrh.github.io/learn-wgpu/showcase/windowless

Initializes a wgpu CommandEncoder to record drawing commands.

```rust
let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
    label: None,
});

```

--------------------------------

### Create Render Pipeline Descriptor

Source: https://sotrh.github.io/learn-wgpu/beginner/tutorial3-pipeline

Configure the render pipeline with shader modules, entry points, vertex buffers, and fragment targets.

```rust
let render_pipeline = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
    label: Some("Render Pipeline"),
    layout: Some(&render_pipeline_layout),
    vertex: wgpu::VertexState {
        module: &shader,
        entry_point: Some("vs_main"), // 1.
        buffers: &[], // 2.
        compilation_options: wgpu::PipelineCompilationOptions::default(),
    },
    fragment: Some(wgpu::FragmentState { // 3.
        module: &shader,
        entry_point: Some("fs_main"),
        targets: &[Some(wgpu::ColorTargetState { // 4.
            format: config.format,
            blend: Some(wgpu::BlendState::REPLACE),
            write_mask: wgpu::ColorWrites::ALL,
        })],
        compilation_options: wgpu::PipelineCompilationOptions::default(),
    }),
    // continued ...

```
Tokens:
Raw