Skip to content

KDGpu::Sampler

Module: Public API

Defines how textures are sampled in shaders. More...

#include <KDGpu/sampler.h>

Public Functions

Name
Sampler()
~Sampler()
Sampler(Sampler && other)
Sampler & operator=(Sampler && other)
Sampler(const Sampler & ) =delete
Sampler & operator=(const Sampler & ) =delete
Handle< Sampler_t > handle() const
bool isValid() const
operator Handle< Sampler_t >() const

Friends

Name
class Device
KDGPU_EXPORT bool operator==(const Sampler & a, const Sampler & b)

Detailed Description

1
class KDGpu::Sampler;

Defines how textures are sampled in shaders.

Vulkan equivalent:VkSampler

Sampler controls how texture data is read in shaders: filtering modes, addressing modes for coordinates outside [0,1], anisotropic filtering, and more.

Key features:

  • Minification and magnification filtering
  • Mipmap filtering
  • Address modes (repeat, clamp, mirror)
  • Anisotropic filtering
  • Comparison operations for shadow mapping

Lifetime: Samplers are created by Device and must remain valid while referenced by bind groups. They use RAII and clean up automatically.

Usage

Creating a basic sampler:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
    KDGpu::Sampler sampler = device.createSampler(KDGpu::SamplerOptions{
            .magFilter = KDGpu::FilterMode::Linear,
            .minFilter = KDGpu::FilterMode::Linear,
            .mipmapFilter = KDGpu::MipmapFilterMode::Linear,
            .u = KDGpu::AddressMode::Repeat,
            .v = KDGpu::AddressMode::Repeat,
            .w = KDGpu::AddressMode::Repeat,
    });

    // Use with texture in bind group
    KDGpu::BindGroup bindGroup = device.createBindGroup(KDGpu::BindGroupOptions{
            .layout = layout.handle(),
            .resources = {
                    {
                            .binding = 0,
                            .resource = KDGpu::TextureViewSamplerBinding{
                                    .textureView = textureView,
                                    .sampler = sampler,
                            },
                    },
            },
    });

Filename: kdgpu_doc_snippets.cpp

Nearest-neighbor filtering (pixel art):

1
2
3
4
5
6
    KDGpu::Sampler pixelSampler = device.createSampler(KDGpu::SamplerOptions{
            .magFilter = KDGpu::FilterMode::Nearest, // No interpolation
            .minFilter = KDGpu::FilterMode::Nearest,
            .u = KDGpu::AddressMode::ClampToEdge,
            .v = KDGpu::AddressMode::ClampToEdge,
    });

Filename: kdgpu_doc_snippets.cpp

Linear filtering:

1
2
3
4
5
6
    KDGpu::Sampler linearSampler = device.createSampler(KDGpu::SamplerOptions{
            .magFilter = KDGpu::FilterMode::Linear,
            .minFilter = KDGpu::FilterMode::Linear,
            .u = KDGpu::AddressMode::ClampToEdge,
            .v = KDGpu::AddressMode::ClampToEdge,
    });

Filename: kdgpu_doc_snippets.cpp

Anisotropic filtering (high quality):

1
2
3
4
5
6
7
8
9
    KDGpu::Sampler anisotropicSampler = device.createSampler(KDGpu::SamplerOptions{
            .magFilter = KDGpu::FilterMode::Linear,
            .minFilter = KDGpu::FilterMode::Linear,
            .mipmapFilter = KDGpu::MipmapFilterMode::Linear,
            .u = KDGpu::AddressMode::Repeat,
            .v = KDGpu::AddressMode::Repeat,
            .anisotropyEnabled = true,
            .maxAnisotropy = 16.0f,
    }); // Check adapter limits

Filename: kdgpu_doc_snippets.cpp

Clamp to edge sampler:

1
2
3
4
5
6
    KDGpu::Sampler edgeSampler = device.createSampler(KDGpu::SamplerOptions{
            .magFilter = KDGpu::FilterMode::Linear,
            .minFilter = KDGpu::FilterMode::Linear,
            .u = KDGpu::AddressMode::ClampToEdge,
            .v = KDGpu::AddressMode::ClampToEdge,
    });

Filename: kdgpu_doc_snippets.cpp

Clamp to border with custom color:

1
2
3
4
5
6
    KDGpu::Sampler borderSampler = device.createSampler(KDGpu::SamplerOptions{
            .magFilter = KDGpu::FilterMode::Linear,
            .minFilter = KDGpu::FilterMode::Linear,
            .u = KDGpu::AddressMode::ClampToBorder,
            .v = KDGpu::AddressMode::ClampToBorder,
    });

Filename: kdgpu_doc_snippets.cpp

Common addressing modes:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// Repeat: Texture tiles infinitely
KDGpu::AddressMode::Repeat

// Mirror: Texture mirrors at each integer boundary
KDGpu::AddressMode::MirroredRepeat

// Clamp to edge: Extends edge pixels
KDGpu::AddressMode::ClampToEdge

// Clamp to border: Uses border color outside [0,1]
KDGpu::AddressMode::ClampToBorder

Mipmap LOD control:

1
2
3
4
5
6
7
8
9
    KDGpu::Sampler lodSampler = device.createSampler(KDGpu::SamplerOptions{
            .magFilter = KDGpu::FilterMode::Linear,
            .minFilter = KDGpu::FilterMode::Linear,
            .mipmapFilter = KDGpu::MipmapFilterMode::Linear,
            .u = KDGpu::AddressMode::Repeat,
            .v = KDGpu::AddressMode::Repeat,
            .lodMinClamp = 0.0f, // Finest mip level
            .lodMaxClamp = 10.0f,
    }); // Coarsest mip level

Filename: kdgpu_doc_snippets.cpp

Reusing samplers:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
    // Create once, use many times
    KDGpu::Sampler linearRepeat = device.createSampler(linearRepeatOptions);

    // Use with multiple textures
    KDGpu::BindGroup bindGroup1 = device.createBindGroup({
            .layout = layout.handle(),
            .resources = {
                    {
                            .binding = 0,
                            .resource = KDGpu::TextureViewSamplerBinding{
                                    .textureView = albedoView.handle(),
                                    .sampler = linearRepeat.handle() // Shared sampler
                            },
                    },
            },
    });

    KDGpu::BindGroup bindGroup2 = device.createBindGroup({
            .layout = layout.handle(),
            .resources = {
                    {
                            .binding = 0,
                            .resource = KDGpu::TextureViewSamplerBinding{
                                    .textureView = normalView.handle(),
                                    .sampler = linearRepeat.handle() // Same sampler
                            },
                    },
            },
    });

Filename: kdgpu_doc_snippets.cpp

Corresponding shader code (GLSL):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
// Combined image sampler
layout(set = 1, binding = 0) uniform sampler2D diffuseTexture;

void main() {
    vec4 color = texture(diffuseTexture, texCoord);
    // Sampler settings (filtering, addressing) applied automatically
}

// Separate texture and sampler
layout(set = 1, binding = 0) uniform sampler edgeSampler;
layout(set = 1, binding = 1) uniform texture2D colorTex;

void main() {
    vec4 color = texture(samplee2D(colorTex, edgeSampler), texCoord);
}

Vulkan mapping:

  • Sampler creation -> vkCreateSampler()
  • Used in VkDescriptorImageInfo with texture views

See also

SamplerOptions, TextureView, BindGroup, Device, Texture

KDGpu API Overview

KDGpu to Vulkan API Mapping

Public Functions Documentation

function Sampler

1
Sampler()

function ~Sampler

1
~Sampler()

function Sampler

1
2
3
Sampler(
    Sampler && other
)

function operator=

1
2
3
Sampler & operator=(
    Sampler && other
)

function Sampler

1
2
3
Sampler(
    const Sampler & 
) =delete

function operator=

1
2
3
Sampler & operator=(
    const Sampler & 
) =delete

function handle

1
inline Handle< Sampler_t > handle() const

function isValid

1
inline bool isValid() const

function operator Handle< Sampler_t >

1
inline operator Handle< Sampler_t >() const

Friends

friend Device

1
2
3
friend class Device(
    Device 
);

friend operator==

1
2
3
4
5
friend KDGPU_EXPORT bool operator==(
    const Sampler & a,

    const Sampler & b
);

Updated on 2026-03-31 at 00:02:07 +0000