Multiple Attributes 🟢¶

With webgpu.hpp

Resulting code: step033-next

Vanilla webgpu.h

Resulting code: step033-vanilla-next

Vertices can contain more than just a position attribute. A typical example is to add a color attribute to each vertex. This will also show us how the rasterizer automatically interpolate vertex attributes across triangles.

Shader¶

Vertex input struct¶

You may have guessed that we can simply add a second argument to the vertex shader entry point vs_main, with a different @location WGSL attribute:

// We could do this, but there might be a lot of attributes
@vertex
fn vs_main(
    @location(0) in_position: vec2f,
    @location(1) in_color: vec3f
) -> /* ... */ {
    // [...]
}

This works, but when the number of input attribute grows, we will prefer to instead take a single argument whose type is a custom struct labeled with locations:

/**
 * A structure with fields labeled with vertex attribute locations can be used
 * as input to the entry point of a shader.
 */
struct VertexInput {
    @location(0) position: vec2f,
    @location(1) color: vec3f,
};

Our vertex shader thus only receive one single argument, whose type is VertexInput:

fn vs_main(in: VertexInput) -> /* ... */ {
    {{Vertex shader body}}
}

const char* shaderSource = R"(
{{Shader source}}
)";

{{Shader prelude}}

@vertex
{{Vertex shader}}

@fragment
{{Fragment shader}}

{{Define VertexInput struct}}

Forwarding vertex attribute to fragments¶

😐 But I don’t need the color in the vertex shader, I want it in the fragment shader. Couldn’t I write fn fs_main(@location(1) color: vec3f)?

Nope. Vertex attributes are only provided to the vertex shader. However, the fragment shader can receive whatever the vertex shader returns! This is where the structure-based approach becomes handy.

First of all, we once again change the signature of vs_main to return a custom struct (instead of @builtin(position) vec4f):

fn vs_main(in: VertexInput) -> VertexOutput {
    //                         ^^^^^^^^^^^^ We return a custom struct
    {{Vertex shader body}}
}

What do we put in this struct? We of course need the mandatory @builtin(position) attribute required by the rasterizer to know where on screen to draw the geometry. We also add a custom vertex shader output, which we name color and associate to a location index (e.g., 0).

/**
 * A structure with fields labeled with builtins and locations can also be used
 * as *output* of the vertex shader, which is also the input of the fragment
 * shader.
 */
struct VertexOutput {
    @builtin(position) position: vec4f,
    // The location here does not refer to a vertex attribute, it just means
    // that this field must be handled by the rasterizer.
    // (It can also refer to another field of another struct that would be used
    // as input to the fragment shader.)
    @location(0) color: vec3f,
};

{{Define VertexOutput struct}}

Now we can change the arguments of the fragment shader entry point fs_main. Like for the vertex shader, we can directly label arguments:

// We can directly label arguments:
fn fs_main(@location(0) color: vec3f) -> @location(0) vec4f {
    //     ^^^^^^^^^^^^^^^^^^^^^^^^^ A new argument, with a location WGSL attribute
    {{Fragment shader body}}
}

Or, we can use a custom struct whose fields are labeled… like the VertexOutput itself! It could be a different one, as long as we stay consistent regarding @location indices.

// Or we can use a custom struct whose fields are labeled
fn fs_main(in: VertexOutput) -> @location(0) vec4f {
    //     ^^^^^^^^^^^^^^^^ Use for instance the same struct as what the vertex outputs
    {{Fragment shader body}}
}

All there remains now is to connect the dots and return from the vertex shader the color needed by the fragment shader:

@vertex
fn vs_main(in: VertexInput) -> VertexOutput {
    var out: VertexOutput; // create the output struct
    out.position = vec4f(in.position, 0.0, 1.0); // same as what we used to directly return
    out.color = in.color; // forward the color attribute to the fragment shader
    return out;
}

@fragment
fn fs_main(in: VertexOutput) -> @location(0) vec4f {
    return vec4f(in.color, 1.0); // use the interpolated color coming from the vertex shader
}

// In vs_main()
var out: VertexOutput; // create the output struct
out.position = vec4f(in.position, 0.0, 1.0); // same as what we used to directly return
out.color = in.color; // forward the color attribute to the fragment shader
return out;

// In fs_main()
return vec4f(in.color, 1.0); // use the interpolated color coming from the vertex shader

Device capabilities¶

🤓 Hey what is the maximum number of location attributes?

Good question! As a reminder, when creating our WGPUDevice objects, we have specified a list of required device limits. We let it to its default value but there are multiple limits related to what we explored in this chapter:

Maximum vertex attributes¶

The maxVertexAttributes limit tells how many attributes we can use at most as input of the vertex shader. Its default value is 16 but we could ask for less just for the sake of the exercise:

// In block "Specify required limits"
requiredLimits.maxVertexAttributes = 1;
//                                   ^ Intentionally use a limit that is too low

Maximum vertex buffers¶

There is a different limit for the maximum number of vertex buffers, namely maxVertexBuffers. We just saw how the number of buffers may or may not correspond to the number of attributes. This time the default value is 8.

Note that the total number of vertex buffers combined with the bind groups also has a dedicated limit, namely maxBindGroupsPlusVertexBuffers (default to 24).

Maximum byte stride¶

We can put many attributes in the same vertex buffers, but may eventually hit the maxVertexBufferArrayStride limit. It is set by default at 2048 bytes, which corresponds for instance to 512 floats.

It’s probably more than enough for a lot of use cases (especially if we are limited to 16 attributes anyways) but there could be edge cases where the attribute data is lost in the middle of something else.

Maximum inter-stage shader variables¶

The maximum number of vertex attributes does not say anything about the maximum @location available between the vertex and the fragment stages. For this, we look at a different limit, namely maxInterStageShaderVariables. Its default value is 16 as well, which means the @location index can go up to 15.

Maximum color attachments¶

And at the end of the pipeline, we also have a maximum number of output locations imposed to the fragment shader. In fact, the output locations of the fragment shader must correspond to the color attachments of the render pass, which are limited to maxColorAttachments, defaulting to 8.

Conclusion¶

All right, we know all about vertex attributes! In the next chapter, we will talk about indexed drawing, so that we do not have to repeat all vertex attributes when the same vertex is used in two different triangles.

With webgpu.hpp

Resulting code: step033-next

Vanilla webgpu.h

Resulting code: step033-vanilla-next

Multiple Attributes 🟢¶

Shader¶

Vertex input struct¶

Forwarding vertex attribute to fragments¶

Vertex Buffer Layout¶

Option A: Interleaved attributes¶

Vertex Data¶

Layout and Attributes¶

Option B: Multiple buffers¶

Vertex Data¶

Buffers¶

Layout and Attributes¶

Render Pass¶

Device capabilities¶

Maximum vertex attributes¶

Maximum vertex buffers¶

Maximum byte stride¶

Maximum inter-stage shader variables¶

Maximum color attachments¶

Conclusion¶