Document example 02

Author: Matthieu Pizenberg

example_01_triangle/src/main.rs

@@ -13,11 +13,11 @@
 //!    - the fragment shader
 //!    - the primitive type (triangle list)
 //! 6. Define our command encoder:
-//!    6.1. Start by defining our render pass:
+//!    1. Start by defining our render pass:
 //!       - Link to the texture output
 //!       - Link to the pipeline
 //!       - Draw the primitive (provide vertices indices)
-//!    6.2. Add a command to copy the texture output to the output buffer
+//!    2. Add a command to copy the texture output to the output buffer
 //! 7. Submit our commands to the device queue
 //! 8. (async) Transfer the output buffer into an image we can save to disk
 

example_02_buffer/src/main.rs

@@ -1,3 +1,29 @@
+//! This example aims at showing vertex buffer usage in a minimal wgpu setup.
+//! 
+//! The corner coordinates of the triangle are provided via a vertex buffer
+//! and the vertex indices in the face are provided as an index buffer.
+//! The steps of this minimal program are the following.
+//!
+//! 1. (async) Initialize the connection with the GPU device
+//! 2. Initialize a wgpu Texture object that will serve as a write target for our pipeline
+//! 3. Initialize a wgpu Buffer where the Texture output will be transferred to
+//! 4. **(new)** Create and initialize a vertex buffer containing the triangle coordinates
+//! 5. **(new)** Create and initialize an index buffer containing the vertex indices in the face
+//! 6. Load the shader module, containing both the vertex and fragment shaders
+//! 7. Define our render pipeline, including:
+//!    - the vertex shader: **(new)** include our vertex buffer layout
+//!    - the fragment shader
+//!    - the primitive type (triangle list)
+//! 8. Define our command encoder:
+//!    1. Start by defining our render pass:
+//!       - Link to the texture output
+//!       - Link to the pipeline
+//!       - **(new)** Provide vertex buffer and index buffer
+//!       - Draw the primitive
+//!    2. Add a command to copy the texture output to the output buffer
+//! 9. Submit our commands to the device queue
+//! 10. (async) Transfer the output buffer into an image we can save to disk
+
 use wgpu::util::DeviceExt; // Utility trait to create and initialize buffers with device.create_buffer_init()
 
 fn main() {
@@ -6,35 +32,41 @@ fn main() {
 }
 
 async fn run() {
-    // Initializing WebGPU
+    // (1) Initializing WebGPU
     println!("Initializing WebGPU ...");
     let (device, queue) = init_wgpu_device().await.unwrap();
 
-    // Initialize the output texture
+    // (2) Initialize the output texture
     let texture = init_output_texture(&device, 256);
     let texture_view = texture.create_view(&Default::default());
 
-    // Create and initialize the vertex buffer for the triangle vertices
+    // (3) Initialize a buffer for the texture output
+    let output_buffer_desc = create_texture_buffer_descriptor(&texture);
+    let output_buffer = device.create_buffer(&output_buffer_desc);
+
+    // (4) Create and initialize the vertex buffer for the triangle vertices
     // (needs the DeviceExt trait)
     let vertex_buffer = device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
         label: Some("Vertex Buffer"),
         contents: bytemuck::cast_slice(VERTICES),
         usage: wgpu::BufferUsages::VERTEX,
     });
 
-    // Create and initialize the index buffer for the indices of the triangle face
+    // (5) Create and initialize the index buffer for the indices of the triangle face
     // (needs the DeviceExt trait)
     let index_buffer = device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
         label: Some("Index Buffer"),
         contents: bytemuck::cast_slice(INDICES),
         usage: wgpu::BufferUsages::INDEX,
     });
 
-    // Define our pipeline
+    // (6) Load the shader module, containing both the vertex and fragment shaders
     let shader_module = device.create_shader_module(wgpu::ShaderModuleDescriptor {
         label: Some("triangle_shader"),
         source: wgpu::ShaderSource::Wgsl(include_str!("triangle.wgsl").into()),
     });
+
+    // (7) Define our pipeline
     let pipeline = build_simple_pipeline(
         &device,
         &shader_module,
@@ -45,7 +77,7 @@ async fn run() {
     // Initialize a command encoder
     let mut encoder = device.create_command_encoder(&Default::default());
 
-    // Draw our pipeline (add render pass to the command encoder)
+    // (8.1) Draw our pipeline (add render pass to the command encoder)
     // This needs to be inside {...} or a function so that the &pipeline lifetime works.
     draw_pipeline(
         &mut encoder,
@@ -56,18 +88,14 @@ async fn run() {
         INDICES.len() as u32,
     );
 
-    // Initialize a buffer for the texture output
-    let output_buffer_desc = create_texture_buffer_descriptor(&texture);
-    let output_buffer = device.create_buffer(&output_buffer_desc);
-
-    // Copy the texture output into a buffer
+    // (8.2) Copy the texture output into a buffer
     copy_texture_to_buffer(&mut encoder, &texture, &output_buffer);
 
-    // Finalize the command encoder and send it to the queue
+    // (9) Finalize the command encoder and send it to the queue
     println!("Submitting commands to the queue ...");
     queue.submit(Some(encoder.finish()));
 
-    // Transfer the texture output buffer into an image buffer
+    // (10) Transfer the texture output buffer into an image buffer
     println!("Saving the GPU output into an image ...");
     let img = to_image(&device, &output_buffer, texture.width(), texture.height()).await;
 
@@ -80,7 +108,7 @@ async fn run() {
     println!("Terminating the program ...")
 }
 
-/// Initializing WebGPU
+/// (1) Initializing WebGPU
 async fn init_wgpu_device() -> Result<(wgpu::Device, wgpu::Queue), wgpu::RequestDeviceError> {
     // Start an "Instance", which is the context for all things wgpu.
     let instance = wgpu::Instance::new(wgpu::InstanceDescriptor {
@@ -104,7 +132,7 @@ async fn init_wgpu_device() -> Result<(wgpu::Device, wgpu::Queue), wgpu::Request
     adapter.request_device(&Default::default(), None).await
 }
 
-/// Initialize the output texture
+/// (2) Initialize the output texture
 fn init_output_texture(device: &wgpu::Device, texture_size: u32) -> wgpu::Texture {
     let texture_desc = wgpu::TextureDescriptor {
         label: Some("output_texture"),
@@ -128,6 +156,19 @@ fn init_output_texture(device: &wgpu::Device, texture_size: u32) -> wgpu::Textur
     device.create_texture(&texture_desc)
 }
 
+/// (3) Create a buffer descriptor of the correct size for the texture
+fn create_texture_buffer_descriptor(texture: &wgpu::Texture) -> wgpu::BufferDescriptor {
+    let texel_size = texture.format().block_copy_size(None).unwrap();
+    wgpu::BufferDescriptor {
+        size: (texel_size * texture.width() * texture.height()).into(),
+        usage: wgpu::BufferUsages::COPY_DST
+            // this tells wpgu that we want to read this buffer from the cpu
+            | wgpu::BufferUsages::MAP_READ,
+        label: None,
+        mapped_at_creation: false,
+    }
+}
+
 /// Each corner of the triangle is a Vertex with the following properties
 /// Bytemuck is used to enable easy casting to a &[u8].
 #[repr(C)]
@@ -179,7 +220,7 @@ impl Vertex {
     }
 }
 
-/// Define our simple render pipeline
+/// (7) Define our simple render pipeline
 fn build_simple_pipeline(
     device: &wgpu::Device,
     shader_module: &wgpu::ShaderModule,
@@ -230,7 +271,7 @@ fn build_simple_pipeline(
     })
 }
 
-/// Draw our pipeline (add render pass to the command encoder).
+/// (8.1) Draw our pipeline (add render pass to the command encoder).
 fn draw_pipeline(
     encoder: &mut wgpu::CommandEncoder,
     pipeline: &wgpu::RenderPipeline,
@@ -268,20 +309,7 @@ fn draw_pipeline(
     render_pass.draw_indexed(0..num_indices, 0, 0..1);
 }
 
-/// Create a buffer descriptor of the correct size for the texture
-fn create_texture_buffer_descriptor(texture: &wgpu::Texture) -> wgpu::BufferDescriptor {
-    let texel_size = texture.format().block_copy_size(None).unwrap();
-    wgpu::BufferDescriptor {
-        size: (texel_size * texture.width() * texture.height()).into(),
-        usage: wgpu::BufferUsages::COPY_DST
-            // this tells wpgu that we want to read this buffer from the cpu
-            | wgpu::BufferUsages::MAP_READ,
-        label: None,
-        mapped_at_creation: false,
-    }
-}
-
-/// Copy the texture output into a buffer
+/// (8.2) Copy the texture output into a buffer
 fn copy_texture_to_buffer(
     encoder: &mut wgpu::CommandEncoder,
     texture: &wgpu::Texture,
@@ -310,7 +338,7 @@ fn copy_texture_to_buffer(
     );
 }
 
-/// Copy the texture output buffer into an image buffer
+/// (10) Copy the texture output buffer into an image buffer
 async fn to_image(
     device: &wgpu::Device,
     texture_buffer: &wgpu::Buffer,