Contents

Restricting access to specific mipmaps

Set the range of mipmap levels that a sampler can access.

Overview

Sometimes, you want to control the specific mipmap levels that the sampler can read from. For example, you might do this when you haven’t provided texture data for all of the mipmaps, and you want to constrain access to the mipmaps that have data. You can configure a sampler to read from a subset of the texture’s mipmaps.

Limit the sampler when you create it in your Metal app

When you configure the MTLSamplerDescriptor instance, set the lodMinClamp and lodMaxClamp properties to the range of permitted values.

This example creates a sampler that ignores mipmaps 0, 1, and 2.

Limit the sampler when you create it in your shader

If you create your sampler in your shader, specify the range of mipmap levels that it can access:

constexpr sampler s(filter::linear, mip_filter::linear, lod_clamp(3.0f, MAXFLOAT))

Control mipmap selection when you sample the texture

Some GPUs can apply additional constraints on the sample operation itself, passing in dynamic information about which mipmap levels the GPU can sample.

Not all GPUs support clamping at the moment it samples a texture. Verify that GPU’s device instance supports clamping to a minimum level-of-detail (LOD) by checking whether it supports one of the following:

In your shader, call one of the variants of the sample function that takes additional LOD parameters. For example, the following code limits sampling to a specific level or lower in the mipmap chain. The shader has a minimum level parameter that it uses to sample the texture:

fragment float4
samplingShader(RasterizerData in [[stage_in]],
               texture2d<half> colorTexture [[ texture(0) ]],
               constant float &minimumLOD [[buffer(0)]])
{
    constexpr sampler textureSampler (mag_filter::linear,
                                      min_filter::linear,
                                      mip_filter::linear);

    const half4 colorSample = colorTexture.sample(textureSampler,
                                                  in.textureCoordinate,
                                                  min_lod_clamp(minimumLOD));
    
    return float4(colorSample);
}

This example limits sampling to a specific level or lower in the mipmap chain. The shader has a minimum level parameter, minimumLOD, that it uses to sample the texture.

The Metal Shading Language Guide describes other options for controlling mipmap selection. You can choose to sample a specific mipmap level, specify a minimum mipmap level, bias the selection process that the hardware chooses, or use some combination of these options.

See Also

Texture mipmapping