Precompiled shaders macro

CHANGELOG.md

@@ -109,14 +109,30 @@ Difference for SPIR-V passthrough:
 -     },
 - ))
 + device.create_shader_module_passthrough(wgpu::ShaderModuleDescriptorPassthrough {
-+     entry_point: "main".into(),
 +     label: None,
-+     spirv: Some(spirv_code),
++     spirv: Some(wgpu::SpirvPassthroughDescriptor {
++         code: spirv_code
++     }),
 +     ..Default::default()
 })
 ```
 This allows using precompiled shaders without manually checking which backend's code to pass, for example if you have shaders precompiled for both DXIL and SPIR-V.
 
+This comes along with an optional wgpu feature, `precompiled`, which provides a macro for precompiling shaders. For example, the following code is used in a test to precompile the `vs_main` entry point of `shader.wgsl` for all shader backends, excluding DXIL.
+```rust
+ctx
+    .device
+    .create_shader_module_passthrough(wgpu::include_precompiled_wgsl!(
+        // Shader source file
+        "shader.wgsl",
+        // Shader entry point
+        "vs_main",
+        // Target formats: a space separated list of backends, for example "all" or "hlsl glsl spirv"
+        all
+    ))
+```
+You can also precompile SPIR-V and GLSL, and you can precompile raw shader code (code that lives in the rust file) using `precompile_wgsl` instead of `include_precompiled_wgsl`, and the analogous functions for GLSL.
+
 #### Buffer mapping apis no longer have lifetimes
 
 `Buffer::get_mapped_range()`, `Buffer::get_mapped_range_mut()`, and `Queue::write_buffer_with()` now return guard objects without any lifetimes. This

Cargo.toml

@@ -24,7 +24,9 @@ members = [
     "wgpu-macros",
     "wgpu-types",
     "wgpu",
+    "wgpu-precompile-macro",
     "xtask",
+    "wgpu-shaders",
 ]
 exclude = []
 default-members = [
@@ -47,6 +49,7 @@ default-members = [
     "wgpu-macros",
     "wgpu-types",
     "wgpu",
+    "wgpu-precompile-macro",
     "xtask",
 ]
 
@@ -80,6 +83,7 @@ wgpu = { version = "26.0.0", path = "./wgpu", default-features = false, features
 wgpu-core = { version = "26.0.0", path = "./wgpu-core" }
 wgpu-hal = { version = "26.0.0", path = "./wgpu-hal" }
 wgpu-macros = { version = "26.0.0", path = "./wgpu-macros" }
+wgpu-precompile-macro = { version = "26.0.0", path = "./wgpu-precompile-macro" }
 wgpu-test = { version = "26.0.0", path = "./tests" }
 wgpu-types = { version = "26.0.0", path = "./wgpu-types", default-features = false }
 
@@ -166,6 +170,7 @@ pollster = "0.4"
 portable-atomic = "1.8"
 portable-atomic-util = "0.2.4"
 pp-rs = "0.2.1"
+proc-macro2 = "1.0.101"
 profiling = { version = "1.0.1", default-features = false }
 quote = "1.0.38"
 raw-window-handle = { version = "0.6.2", default-features = false }

examples/README.md

@@ -33,6 +33,7 @@ These examples use a common framework to handle wgpu init, window creation, and
 #### Graphics
 
 - `hello_triangle` - Provides an example of a bare-bones wgpu workflow using the Winit crate that simply renders a red triangle on a green background.
+- `precompiled_shader` - Essentially `hello_triangle` except that the shaders are compiled at compile-time instead of runtime
 - `uniform_values` - Demonstrates the basics of enabling shaders and the GPU, in general, to access app state through uniform variables. `uniform_values` also serves as an example of rudimentary app building as the app stores state and takes window-captured keyboard events. The app displays the Mandelbrot Set in grayscale (similar to `storage_texture`) but allows the user to navigate and explore it using their arrow keys and scroll wheel.
 - `cube` - Introduces the user to slightly more advanced models. The example creates a set of triangles to form a cube on the CPU and then uses a vertex and index buffer to send the generated model to the GPU for usage in rendering. It also uses a texture generated on the CPU to shade the sides of the cube and a uniform variable to apply a transformation matrix to the cube in the shader.
 - `bunnymark` - Demonstrates many things, but chief among them is performing numerous draw calls with different bind groups in one render pass. The example also uses textures for the icon and uniform buffers to transfer both global and per-particle states.

examples/features/Cargo.toml

@@ -56,7 +56,7 @@ wgpu-test.workspace = true
 
 [target.'cfg(not(target_arch = "wasm32"))'.dependencies]
 env_logger.workspace = true
-wgpu.workspace = true
+wgpu = { workspace = true, features = ["precompile-macro"] }
 
 [target.'cfg(target_arch = "wasm32")'.dependencies]
 console_error_panic_hook.workspace = true
@@ -67,6 +67,7 @@ wasm-bindgen-futures.workspace = true
 wgpu = { path = "../../wgpu", default-features = false, features = [
     "wgsl",
     "std",
+    "precompile-macro",
 ] }
 # We need these features in the framework examples and tests
 web-sys = { workspace = true, features = [

examples/features/src/lib.rs

@@ -17,6 +17,7 @@ pub mod mesh_shader;
 pub mod mipmap;
 pub mod msaa_line;
 pub mod multiple_render_targets;
+pub mod precompiled_shader;
 pub mod ray_cube_compute;
 pub mod ray_cube_fragment;
 pub mod ray_cube_normals;
@@ -52,6 +53,7 @@ fn all_tests() -> Vec<wgpu_test::GpuTestInitializer> {
         mipmap::TEST_QUERY,
         msaa_line::TEST,
         multiple_render_targets::TEST,
+        precompiled_shader::TEST,
         ray_cube_compute::TEST,
         ray_cube_fragment::TEST,
         ray_cube_normals::TEST,

examples/features/src/main.rs

@@ -62,6 +62,12 @@ const EXAMPLES: &[ExampleDesc] = &[
         webgl: false,
         webgpu: true,
     },
+    ExampleDesc {
+        name: "mesh_shader",
+        function: wgpu_examples::mesh_shader::main,
+        webgl: false,
+        webgpu: false,
+    },
     ExampleDesc {
         name: "mipmap",
         function: wgpu_examples::mipmap::main,
@@ -80,6 +86,12 @@ const EXAMPLES: &[ExampleDesc] = &[
         webgl: false,
         webgpu: true,
     },
+    ExampleDesc {
+        name: "precompiled_shader",
+        function: wgpu_examples::precompiled_shader::main,
+        webgl: true,
+        webgpu: true,
+    },
     ExampleDesc {
         name: "render_to_texture",
         function: wgpu_examples::render_to_texture::main,
@@ -182,12 +194,6 @@ const EXAMPLES: &[ExampleDesc] = &[
         webgl: false,  // No Ray-tracing extensions
         webgpu: false, // No Ray-tracing extensions (yet)
     },
-    ExampleDesc {
-        name: "mesh_shader",
-        function: wgpu_examples::mesh_shader::main,
-        webgl: false,
-        webgpu: false,
-    },
 ];
 
 fn get_example_name() -> Option<String> {

examples/features/src/mesh_shader/mod.rs

@@ -21,9 +21,10 @@ fn compile_glsl(device: &wgpu::Device, shader_stage: &'static str) -> wgpu::Shad
     assert!(output.status.success());
     unsafe {
         device.create_shader_module_passthrough(wgpu::ShaderModuleDescriptorPassthrough {
-            entry_point: "main".into(),
             label: None,
-            spirv: Some(wgpu::util::make_spirv_raw(&output.stdout)),
+            spirv: Some(wgpu::SpirvPassthroughDescriptor {
+                code: wgpu::util::make_spirv_raw(&output.stdout),
+            }),
             ..Default::default()
         })
     }
@@ -52,10 +53,12 @@ fn compile_hlsl(device: &wgpu::Device, entry: &str, stage_str: &str) -> wgpu::Sh
     std::fs::remove_file(out_path).unwrap();
     unsafe {
         device.create_shader_module_passthrough(wgpu::ShaderModuleDescriptorPassthrough {
-            entry_point: entry.to_owned(),
             label: None,
             num_workgroups: (1, 1, 1),
-            dxil: Some(std::borrow::Cow::Owned(file)),
+            dxil: Some(wgpu::DxilPassthroughDescriptor {
+                entry_point: entry.to_owned(),
+                code: std::borrow::Cow::Owned(file),
+            }),
             ..Default::default()
         })
     }
@@ -178,3 +181,22 @@ impl crate::framework::Example for Example {
 pub fn main() {
     crate::framework::run::<Example>("mesh_shader");
 }
+
+#[cfg(test)]
+#[wgpu_test::gpu_test]
+pub static TEST: crate::framework::ExampleTestParams = crate::framework::ExampleTestParams {
+    name: "mesh_shader",
+    image_path: "/examples/features/src/mesh_shader/screenshot.png",
+    width: 1024,
+    height: 768,
+    optional_features: wgpu::Features::default(),
+    base_test_parameters: wgpu_test::TestParameters::default()
+        .test_features_limits()
+        .features(
+            wgpu::Features::EXPERIMENTAL_MESH_SHADER
+                | wgpu::Features::EXPERIMENTAL_PASSTHROUGH_SHADERS,
+        )
+        .limits(wgpu::Limits::default().using_recommended_minimum_mesh_shader_values()),
+    comparisons: &[wgpu_test::ComparisonType::Mean(0.02)],
+    _phantom: std::marker::PhantomData::<Example>,
+};

examples/features/src/precompiled_shader/mod.rs

@@ -0,0 +1,117 @@
+use crate::framework;
+
+pub struct Example {
+    pipeline: wgpu::RenderPipeline,
+}
+impl framework::Example for Example {
+    fn init(
+        config: &wgpu::SurfaceConfiguration,
+        _adapter: &wgpu::Adapter,
+        device: &wgpu::Device,
+        _queue: &wgpu::Queue,
+    ) -> Self {
+        let vs_shader = unsafe {
+            device.create_shader_module_passthrough(wgpu::include_precompiled_wgsl!(
+                "src/hello_triangle/shader.wgsl",
+                "vs_main",
+                all
+            ))
+        };
+        let fs_shader = unsafe {
+            device.create_shader_module_passthrough(wgpu::include_precompiled_wgsl!(
+                "src/hello_triangle/shader.wgsl",
+                "fs_main",
+                all
+            ))
+        };
+
+        let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
+            label: None,
+            bind_group_layouts: &[],
+            push_constant_ranges: &[],
+        });
+        let pipeline = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
+            label: None,
+            layout: Some(&pipeline_layout),
+            vertex: wgpu::VertexState {
+                module: &vs_shader,
+                entry_point: Some("vs_main"),
+                buffers: &[],
+                compilation_options: Default::default(),
+            },
+            fragment: Some(wgpu::FragmentState {
+                module: &fs_shader,
+                entry_point: Some("fs_main"),
+                compilation_options: Default::default(),
+                targets: &[Some(config.format.into())],
+            }),
+            primitive: wgpu::PrimitiveState::default(),
+            depth_stencil: None,
+            multisample: wgpu::MultisampleState::default(),
+            multiview: None,
+            cache: None,
+        });
+        Self { pipeline }
+    }
+    fn render(&mut self, view: &wgpu::TextureView, device: &wgpu::Device, queue: &wgpu::Queue) {
+        let mut encoder =
+            device.create_command_encoder(&wgpu::CommandEncoderDescriptor { label: None });
+        {
+            let mut rpass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
+                label: None,
+                color_attachments: &[Some(wgpu::RenderPassColorAttachment {
+                    view,
+                    depth_slice: None,
+                    resolve_target: None,
+                    ops: wgpu::Operations {
+                        load: wgpu::LoadOp::Clear(wgpu::Color::GREEN),
+                        store: wgpu::StoreOp::Store,
+                    },
+                })],
+                depth_stencil_attachment: None,
+                timestamp_writes: None,
+                occlusion_query_set: None,
+            });
+            rpass.set_pipeline(&self.pipeline);
+            rpass.draw(0..3, 0..1);
+        }
+
+        queue.submit(Some(encoder.finish()));
+    }
+    fn update(&mut self, _event: winit::event::WindowEvent) {}
+    fn resize(
+        &mut self,
+        _config: &wgpu::SurfaceConfiguration,
+        _device: &wgpu::Device,
+        _queue: &wgpu::Queue,
+    ) {
+    }
+    fn required_downlevel_capabilities() -> wgpu::DownlevelCapabilities {
+        wgpu::DownlevelCapabilities::default()
+    }
+    fn required_features() -> wgpu::Features {
+        wgpu::Features::EXPERIMENTAL_PASSTHROUGH_SHADERS
+    }
+    fn required_limits() -> wgpu::Limits {
+        wgpu::Limits::defaults()
+    }
+}
+
+pub fn main() {
+    crate::framework::run::<Example>("precompiled_shader");
+}
+
+#[cfg(test)]
+#[wgpu_test::gpu_test]
+pub static TEST: crate::framework::ExampleTestParams = crate::framework::ExampleTestParams {
+    name: "precompiled_shader",
+    image_path: "/examples/features/src/mesh_shader/screenshot.png",
+    width: 1024,
+    height: 768,
+    optional_features: wgpu::Features::default(),
+    base_test_parameters: wgpu_test::TestParameters::default()
+        .test_features_limits()
+        .features(wgpu::Features::EXPERIMENTAL_PASSTHROUGH_SHADERS),
+    comparisons: &[wgpu_test::ComparisonType::Mean(0.02)],
+    _phantom: std::marker::PhantomData::<Example>,
+};