Notes on migrating from WGSL to rust-gpu shaders

Preface

You probably ended up here through googling one of the weird error messages mentioned below. I also tried googling them with limited success, so I decided to post this to save time to anyone in the same situation.

I develop a small game on top of the project structure from Learn WGPU guide. I found WGSL shaders tedious to write, though, since text editor support is non-existent, and it's hard to find examples and precise documentation. Once I learned about rust-gpu approach to writing shaders in plain Rust code, I instantly decided to try it out and to migrate my existing WGSL shaders. Below goes several obstacles I faced and learnings I took away.

rust-gpu is in active development, so most things here might change in future versions. For reference, here are the versions I'm using at the moment:

• rust edition 2021
• toolchain nightly-2022-01-13
• spirv-std 0.4.0-alpha.12

Implicit locations

In WGSL, you explicitly specify locations for position, texture coordinates etc. This is how input parameters in my WGSL shader for displaying textured models looked like:

struct VertexInput {
    [[location(0)]] position: vec3<f32>;
    [[location(1)]] uv: vec2<f32>;
    [[location(2)]] normal: vec3<f32>;
    [[location(3)]] tangent: vec3<f32>;
    [[location(4)]] bitangent: vec3<f32>;
};

struct VertexOutput {
    [[builtin(position)]] position: vec4<f32>;
    [[location(0)]] uv: vec2<f32>;
    [[location(1)]] tangent_position: vec3<f32>;
    [[location(2)]] tangent_view_position: vec3<f32>;
};

...

[[stage(vertex)]]
fn main(model: VertexInput) -> VertexOutput {
    ...
}

It took me time to figure out how to represent a similar set of input/output parameters in rust-gpu. It turns out the order of arguments in the shader function maps to the location index. It is more evident with input parameters, though. Output parameters are all &mut arguments; as far as I understand, their locations are resolved in order of occurrence except for the ones marked explicitly to built-in meanings (like #[spirv(position, invariant)] in the code below).

#[spirv(vertex)]
pub fn main_vs(
    position: Vec3, // implicit input Location 0
    uv: Vec2,       // implicit input Location 1
    normal: Vec3,   // implicit input Location 2 etc.
    tangent: Vec3,
    bitangent: Vec3,
    ...
    #[spirv(position, invariant)] out_position: &mut Vec4, // builtin position
    out_uv: &mut Vec2,                      // implicit output Location 0
    out_tangent_position: &mut Vec3,        // implicit output Location 1
    out_tangent_view_position: &mut Vec3    // implicit output Location 2
    )

From indexes to Glam methods

In the WGSL shader, all vector arguments had built-in type vec3<f32>, and you could access elements by index. Naively, I copied the code into the rust-gpu shader, using glam::Vec3 as an input type.

use spirv_std::glam::Vec3;

#[spirv(vertex)]
pub fn main_vs(
    position: Vec3,
    ...
) {
    let x = position[0];
}

This code causes a confusing compiler error:

error: Using pointers with OpPhi requires capability VariablePointers or VariablePointersStorageBuffer
           %184 = OpPhi %_ptr_Function_float %181 %172 %182 %173 %183 %174
    |
    = note: module `/Users/bardt/Projects/rust/asteroids/target/spirv-builder/spirv-unknown-vulkan1.2/release/deps/model.spv.dir/module`

The remedy is to be careful while copy-pasting the code between shaders and consider the new data structures used. In Glam, you access elements via named properties:

use spirv_std::glam::Vec3;

#[spirv(vertex)]
pub fn main_vs(
    position: Vec3,
    ...
) {
    let x = position.x; // use property instead
}

Matrix parameters

One thing I couldn't make work in WGSL and hoped to get in rust-gpu is passing matrix parameters. I hoped this to work:

#[spirv(vertex)]
pub fn main_vs(
    position: Vec3,
    uv: Vec2,
    normal: Vec3,
    tangent: Vec3,
    bitangent: Vec3,
    model_matrix: Mat4, // matrix parameter
    ...
) { 
    ...
}

Unfortunately, magic didn't happen. Instead, I got a very confusing error. I don't fully understand why the location is 6 while I expected it to be 5. Now I know that this roughly translates to "there is something wrong with your arguments".

error: Entry-point has conflicting input location assignment at location 6, component 0
    OpEntryPoint Vertex %2 "main_vs" %position %uv %normal %tangent %bitangent %model_matrix ...

I had to switch back to passing each matrix column as a separate vector and then combining them in the shader body. The same applies to passing arguments between vertex and fragment shader.

use spirv_std::glam::mat4;

#[spirv(vertex)]
pub fn main_vs(
    position: Vec3,
    uv: Vec2,
    normal: Vec3,
    tangent: Vec3,
    bitangent: Vec3,
    model_matrix_0: Vec4,
    model_matrix_1: Vec4,
    model_matrix_2: Vec4,
    model_matrix_3: Vec4,
    ...
) {
    let model_matrix = mat4(
        model_matrix_0,
        model_matrix_1,
        model_matrix_2,
        model_matrix_3,
    );
    ...
}

for loops

Another weird thing I noticed is for loops are not working. The shader compiles fine and passes validation, but pixels are not drawn on the screen, so I assume the code doesn't reach the final line.

for i in 0..lights_number {
    // do stuff
}

*output = result_color;

After refactoring to a while loop, everything works just fine.

let mut i = 0_usize;    
while i < lights_number {
    // do stuff
}

min/max on ints

One more surprise: the min and max methods do not work on integers while working fine on floats.

let lights_number: usize = lights.size.min(MAX_LIGHTS);

The error message gives a slight hint on the roots of the problem but doesn't help much in solving it:

error: u8 without OpCapability Int8
     --> ~/.rustup/toolchains/nightly-2022-01-13-aarch64-apple-darwin/lib/rustlib/src/rust/library/core/src/cmp.rs:850:5
      |
  850 |     fn partial_cmp(&self, other: &Ordering) -> Option<Ordering> {
      |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      |
      = note: Stack:
              core::cmp::min_by::<usize, <usize as core::cmp::Ord>::cmp>
              <usize as core::cmp::Ord>::min
              model::main_fs
              main_fs

I decided not to spend too much time on finding the root causes (here is a related issue), and rewrote that comparison by hand.

fn min_usize(a: usize, b: usize) -> usize {
    if a <= b {
        a
    } else {
        b
    }
}

let lights_number: usize = min_usize(lights.size, MAX_LIGHTS);

Conclusion

rust-gpu concept and vision has the potential to flip the game in writing testable, maintainable, reusable shader code. Still, it is in alpha, has a lot of minor issues and inconveniences, and you should seriously evaluate if you want to spend time on those in a project with a deadline and requirements for performance and stability. However, all of this is not the case for my pet project game, so I keep living on the edge and look forward to a bright future.