Sampler 🟡¶

With webgpu.hpp

Resulting code: step070

Vanilla webgpu.h

Resulting code: step070-vanilla

The textureLoad function, that we used in our shader accesses the texture data, acts almost as if a texture was a basic buffer. It does not benefit from the interpolation and mip level selection features that the GPU is capable of.

To sample values from a texture with all these capabilities, we define another resource called a sampler. We see below why this proper way of fetching texture data is important to avoid aliasing artifacts.

Sampler setup¶

Sampler creation¶

I am going to detail the sampler settings in the second part of this chapter, once everything is wired up. For now just copy it, so that we can start experimenting right away.

With webgpu.hpp

// Create a texture
// [...]

// Create a sampler
SamplerDescriptor samplerDesc;
samplerDesc.addressModeU = AddressMode::ClampToEdge;
samplerDesc.addressModeV = AddressMode::ClampToEdge;
samplerDesc.addressModeW = AddressMode::ClampToEdge;
samplerDesc.magFilter = FilterMode::Linear;
samplerDesc.minFilter = FilterMode::Linear;
samplerDesc.mipmapFilter = MipmapFilterMode::Linear;
samplerDesc.lodMinClamp = 0.0f;
samplerDesc.lodMaxClamp = 1.0f;
samplerDesc.compare = CompareFunction::Undefined;
samplerDesc.maxAnisotropy = 1;
Sampler sampler = device.createSampler(samplerDesc);

Vanilla webgpu.h

// Create a texture
// [...]

// Create a sampler
WGPUSamplerDescriptor samplerDesc;
samplerDesc.addressModeU = WGPUAddressMode_ClampToEdge;
samplerDesc.addressModeV = WGPUAddressMode_ClampToEdge;
samplerDesc.addressModeW = WGPUAddressMode_ClampToEdge;
samplerDesc.magFilter = WGPUFilterMode_Linear;
samplerDesc.minFilter = WGPUFilterMode_Linear;
samplerDesc.mipmapFilter = WGPUMipmapFilterMode_Linear;
samplerDesc.lodMinClamp = 0.0f;
samplerDesc.lodMaxClamp = 1.0f;
samplerDesc.compare = WGPUCompareFunction_Undefined;
samplerDesc.maxAnisotropy = 1;
WGPUSampler sampler = wgpuDeviceCreateSampler(device, samplerDesc);

We also need to raise the following device limit:

requiredLimits.limits.maxSamplersPerShaderStage = 1;

Sampler binding¶

Adding a new binding should feel rather straightforward by now:

With webgpu.hpp

std::vector<BindGroupLayoutEntry> bindingLayoutEntries(3, Default);
//                                                     ^ This was a 2

// The texture sampler binding
BindGroupLayoutEntry& samplerBindingLayout = bindingLayoutEntries[2];
samplerBindingLayout.binding = 2;
samplerBindingLayout.visibility = ShaderStage::Fragment;
samplerBindingLayout.sampler.type = SamplerBindingType::Filtering;

// [...]

std::vector<BindGroupEntry> bindings(3);
//                                   ^ This was a 2

bindings[2].binding = 2;
bindings[2].sampler = sampler;

Vanilla webgpu.h

std::vector<WGPUBindGroupLayoutEntry> bindingLayoutEntries(3, Default);
//                                                         ^ This was a 2

// The texture sampler binding
WGPUBindGroupLayoutEntry& samplerBindingLayout = bindingLayoutEntries[2];
samplerBindingLayout.binding = 2;
samplerBindingLayout.visibility = WGPUShaderStage_Fragment;
samplerBindingLayout.sampler.type = WGPUSamplerBindingType_Filtering;

// [...]

std::vector<WGPUBindGroupEntry> bindings(3);
//                                       ^ This was a 2

bindings[2].binding = 2;
bindings[2].sampler = sampler;

Sampler usage¶

In the shaders, the sampler simply uses the sampler type. Once bound, we can use textureSample(t, s, uv) to sample the texture t at UV uv using the sampler s:

@group(0) @binding(2) var textureSampler: sampler;

// [...]

@fragment
fn fs_main(in: VertexOutput) -> @location(0) vec4<f32> {
    let color = textureSample(gradientTexture, textureSampler, in.uv).rgb;
    // [...]
}

../../_images/sampled-cube.png — The cube, textured using a filtering sampler.¶

Note

We can already see the effect of using a sampler: since our texture has a low resolution, the sampler interpolates neighbor texels when asked to sample at a non-integer texel coordinate, hence this less pixelated result.

Addressing¶

The first part of the sampler settings is rather easy to understand. The address modes (addressModeU, …) tell for each axis of the coordinate space (U, V, and W for 3D textures) how to handle values that are out of the range \((0,1)\).

To illustrate this, we go back to our plane example and edit the vertex shader to scale and offset the UVs.

out.uv = in.uv * 2.0 - 0.5;

../../_images/clamp-to-edge.png — With the ClampToEdge mode, UVs out of the \((0,1)\) range are clamped to \(0\) or \(1\).¶

Note that if we switch back to raw texture loading, out of bounds texels return a null color:

// With the method from the previous chapter:
let texelCoords = vec2i(in.uv * vec2f(textureDimensions(gradientTexture)));
let color = textureLoad(gradientTexture, texelCoords, 0).rgb;

../../_images/transformed-uv.png — Raw texture loading returns a null color when out of bounds.¶

Back to a sampled texture, let us now try a different value for the U address mode:

With webgpu.hpp

samplerDesc.addressModeU = AddressMode::Repeat;

Vanilla webgpu.h

samplerDesc.addressModeU = WGPUAddressMode_Repeat;

../../_images/repeat-u.png — The Repeat mode set on U repeats the texture infinitly.¶

The last address mode, which we can try on the V axis, repeats with a mirroring effect:

With webgpu.hpp

samplerDesc.addressModeV = AddressMode::MirrorRepeat;

Vanilla webgpu.h

samplerDesc.addressModeV = WGPUAddressMode_MirrorRepeat;

../../_images/mirror-v.png — The Repeat mode set on V repeats the texture with mirroring.¶

Conclusion¶

We can now properly use textures in our scenes!

We have seen how to fill-in mip maps, which can be computed in any way you want. Even though they very often contain averages, filtering is a complex topic, and other operations can be used. For mip-mapping depth buffers, one would use a max (and the compare option that I did not detail). For normal and roughness data (which we’ll discover in the Lighting and Material chapter), other techniques must be found because an average is not physically correct.

With webgpu.hpp

Resulting code: step070

Vanilla webgpu.h

Resulting code: step070-vanilla

Sampler 🟡¶

Sampler setup¶

Sampler creation¶

Sampler binding¶

Sampler usage¶

Addressing¶

Filtering¶

Magnifying filtering¶

Minifying filtering¶

Aliasing¶

Mip-mapping¶

Mip-level data¶

Conclusion¶