13. Samplers

VkSampler objects represent the state of an image sampler which is used by the implementation to read image data and apply filtering and other transformations for the shader.

Samplers are represented by VkSampler handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSampler)

To create a sampler object, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateSampler(
    VkDevice                                    device,
    const VkSamplerCreateInfo*                  pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkSampler*                                  pSampler);
  • device is the logical device that creates the sampler.

  • pCreateInfo is a pointer to a VkSamplerCreateInfo structure specifying the state of the sampler object.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pSampler is a pointer to a VkSampler handle in which the resulting sampler object is returned.

Valid Usage
  • VUID-vkCreateSampler-maxSamplerAllocationCount-04110
    There must be less than VkPhysicalDeviceLimits::maxSamplerAllocationCount VkSampler objects currently created on the device

Valid Usage (Implicit)
  • VUID-vkCreateSampler-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateSampler-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkSamplerCreateInfo structure

  • VUID-vkCreateSampler-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateSampler-pSampler-parameter
    pSampler must be a valid pointer to a VkSampler handle

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkSamplerCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkSamplerCreateInfo {
    VkStructureType         sType;
    const void*             pNext;
    VkSamplerCreateFlags    flags;
    VkFilter                magFilter;
    VkFilter                minFilter;
    VkSamplerMipmapMode     mipmapMode;
    VkSamplerAddressMode    addressModeU;
    VkSamplerAddressMode    addressModeV;
    VkSamplerAddressMode    addressModeW;
    float                   mipLodBias;
    VkBool32                anisotropyEnable;
    float                   maxAnisotropy;
    VkBool32                compareEnable;
    VkCompareOp             compareOp;
    float                   minLod;
    float                   maxLod;
    VkBorderColor           borderColor;
    VkBool32                unnormalizedCoordinates;
} VkSamplerCreateInfo;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkSamplerCreateFlagBits describing additional parameters of the sampler.

  • magFilter is a VkFilter value specifying the magnification filter to apply to lookups.

  • minFilter is a VkFilter value specifying the minification filter to apply to lookups.

  • mipmapMode is a VkSamplerMipmapMode value specifying the mipmap filter to apply to lookups.

  • addressModeU is a VkSamplerAddressMode value specifying the addressing mode for U coordinates outside [0,1).

  • addressModeV is a VkSamplerAddressMode value specifying the addressing mode for V coordinates outside [0,1).

  • addressModeW is a VkSamplerAddressMode value specifying the addressing mode for W coordinates outside [0,1).

  • mipLodBias is the bias to be added to mipmap LOD (level-of-detail) calculation and bias provided by image sampling functions in SPIR-V, as described in the Level-of-Detail Operation section.

  • anisotropyEnable is VK_TRUE to enable anisotropic filtering, as described in the Texel Anisotropic Filtering section, or VK_FALSE otherwise.

  • maxAnisotropy is the anisotropy value clamp used by the sampler when anisotropyEnable is VK_TRUE. If anisotropyEnable is VK_FALSE, maxAnisotropy is ignored.

  • compareEnable is VK_TRUE to enable comparison against a reference value during lookups, or VK_FALSE otherwise.

    • Note: Some implementations will default to shader state if this member does not match.

  • compareOp is a VkCompareOp value specifying the comparison function to apply to fetched data before filtering as described in the Depth Compare Operation section.

  • minLod is used to clamp the minimum of the computed LOD value.

  • maxLod is used to clamp the maximum of the computed LOD value. To avoid clamping the maximum value, set maxLod to the constant VK_LOD_CLAMP_NONE.

  • borderColor is a VkBorderColor value specifying the predefined border color to use.

  • unnormalizedCoordinates controls whether to use unnormalized or normalized texel coordinates to address texels of the image. When set to VK_TRUE, the range of the image coordinates used to lookup the texel is in the range of zero to the image size in each dimension. When set to VK_FALSE the range of image coordinates is zero to one.

    When unnormalizedCoordinates is VK_TRUE, images the sampler is used with in the shader have the following requirements:

    • The viewType must be either VK_IMAGE_VIEW_TYPE_1D or VK_IMAGE_VIEW_TYPE_2D.

    • The image view must have a single layer and a single mip level.

    When unnormalizedCoordinates is VK_TRUE, image built-in functions in the shader that use the sampler have the following requirements:

    • The functions must not use projection.

    • The functions must not use offsets.

Mapping of OpenGL to Vulkan filter modes

magFilter values of VK_FILTER_NEAREST and VK_FILTER_LINEAR directly correspond to GL_NEAREST and GL_LINEAR magnification filters. minFilter and mipmapMode combine to correspond to the similarly named OpenGL minification filter of GL_minFilter_MIPMAP_mipmapMode (e.g. minFilter of VK_FILTER_LINEAR and mipmapMode of VK_SAMPLER_MIPMAP_MODE_NEAREST correspond to GL_LINEAR_MIPMAP_NEAREST).

There are no Vulkan filter modes that directly correspond to OpenGL minification filters of GL_LINEAR or GL_NEAREST, but they can be emulated using VK_SAMPLER_MIPMAP_MODE_NEAREST, minLod = 0, and maxLod = 0.25, and using minFilter = VK_FILTER_LINEAR or minFilter = VK_FILTER_NEAREST, respectively.

Note that using a maxLod of zero would cause magnification to always be performed, and the magFilter to always be used. This is valid, just not an exact match for OpenGL behavior. Clamping the maximum LOD to 0.25 allows the λ value to be non-zero and minification to be performed, while still always rounding down to the base level. If the minFilter and magFilter are equal, then using a maxLod of zero also works.

The maximum number of sampler objects which can be simultaneously created on a device is implementation-dependent and specified by the maxSamplerAllocationCount member of the VkPhysicalDeviceLimits structure.

Note

For historical reasons, if maxSamplerAllocationCount is exceeded, some implementations may return VK_ERROR_TOO_MANY_OBJECTS. Exceeding this limit will result in undefined behavior, and an application should not rely on the use of the returned error code in order to identify when the limit is reached.

Since VkSampler is a non-dispatchable handle type, implementations may return the same handle for sampler state vectors that are identical. In such cases, all such objects would only count once against the maxSamplerAllocationCount limit.

Valid Usage
  • VUID-VkSamplerCreateInfo-mipLodBias-01069
    The absolute value of mipLodBias must be less than or equal to VkPhysicalDeviceLimits::maxSamplerLodBias

  • VUID-VkSamplerCreateInfo-maxLod-01973
    maxLod must be greater than or equal to minLod

  • VUID-VkSamplerCreateInfo-anisotropyEnable-01070
    If the anisotropic sampling feature is not enabled, anisotropyEnable must be VK_FALSE

  • VUID-VkSamplerCreateInfo-anisotropyEnable-01071
    If anisotropyEnable is VK_TRUE, maxAnisotropy must be between 1.0 and VkPhysicalDeviceLimits::maxSamplerAnisotropy, inclusive

  • VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01072
    If unnormalizedCoordinates is VK_TRUE, minFilter and magFilter must be equal

  • VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01073
    If unnormalizedCoordinates is VK_TRUE, mipmapMode must be VK_SAMPLER_MIPMAP_MODE_NEAREST

  • VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01074
    If unnormalizedCoordinates is VK_TRUE, minLod and maxLod must be zero

  • VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01075
    If unnormalizedCoordinates is VK_TRUE, addressModeU and addressModeV must each be either VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER

  • VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01076
    If unnormalizedCoordinates is VK_TRUE, anisotropyEnable must be VK_FALSE

  • VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01077
    If unnormalizedCoordinates is VK_TRUE, compareEnable must be VK_FALSE

  • VUID-VkSamplerCreateInfo-addressModeU-01078
    If any of addressModeU, addressModeV or addressModeW are VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER, borderColor must be a valid VkBorderColor value

  • VUID-VkSamplerCreateInfo-addressModeU-01079
    If samplerMirrorClampToEdge is not enabled, and if the VK_KHR_sampler_mirror_clamp_to_edge extension is not enabled, addressModeU, addressModeV and addressModeW must not be VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE

  • VUID-VkSamplerCreateInfo-compareEnable-01080
    If compareEnable is VK_TRUE, compareOp must be a valid VkCompareOp value

Valid Usage (Implicit)
  • VUID-VkSamplerCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_SAMPLER_CREATE_INFO

  • VUID-VkSamplerCreateInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkSamplerCreateInfo-flags-zerobitmask
    flags must be 0

  • VUID-VkSamplerCreateInfo-magFilter-parameter
    magFilter must be a valid VkFilter value

  • VUID-VkSamplerCreateInfo-minFilter-parameter
    minFilter must be a valid VkFilter value

  • VUID-VkSamplerCreateInfo-mipmapMode-parameter
    mipmapMode must be a valid VkSamplerMipmapMode value

  • VUID-VkSamplerCreateInfo-addressModeU-parameter
    addressModeU must be a valid VkSamplerAddressMode value

  • VUID-VkSamplerCreateInfo-addressModeV-parameter
    addressModeV must be a valid VkSamplerAddressMode value

  • VUID-VkSamplerCreateInfo-addressModeW-parameter
    addressModeW must be a valid VkSamplerAddressMode value

VK_LOD_CLAMP_NONE is a special constant value used for VkSamplerCreateInfo::maxLod to indicate that maximum LOD clamping should not be performed.

#define VK_LOD_CLAMP_NONE                 1000.0F

Bits which can be set in VkSamplerCreateInfo::flags, specifying additional parameters of a sampler, are:

// Provided by VK_VERSION_1_0
typedef enum VkSamplerCreateFlagBits {
} VkSamplerCreateFlagBits;
// Provided by VK_VERSION_1_0
typedef VkFlags VkSamplerCreateFlags;

VkSamplerCreateFlags is a bitmask type for setting a mask of zero or more VkSamplerCreateFlagBits.

Possible values of the VkSamplerCreateInfo::magFilter and minFilter parameters, specifying filters used for texture lookups, are:

// Provided by VK_VERSION_1_0
typedef enum VkFilter {
    VK_FILTER_NEAREST = 0,
    VK_FILTER_LINEAR = 1,
} VkFilter;
  • VK_FILTER_NEAREST specifies nearest filtering.

  • VK_FILTER_LINEAR specifies linear filtering.

These filters are described in detail in Texel Filtering.

Possible values of the VkSamplerCreateInfo::mipmapMode, specifying the mipmap mode used for texture lookups, are:

// Provided by VK_VERSION_1_0
typedef enum VkSamplerMipmapMode {
    VK_SAMPLER_MIPMAP_MODE_NEAREST = 0,
    VK_SAMPLER_MIPMAP_MODE_LINEAR = 1,
} VkSamplerMipmapMode;
  • VK_SAMPLER_MIPMAP_MODE_NEAREST specifies nearest filtering.

  • VK_SAMPLER_MIPMAP_MODE_LINEAR specifies linear filtering.

These modes are described in detail in Texel Filtering.

Possible values of the VkSamplerCreateInfo::addressMode* parameters, specifying the behavior of sampling with coordinates outside the range [0,1] for the respective u, v, or w coordinate as defined in the Wrapping Operation section, are:

// Provided by VK_VERSION_1_0
typedef enum VkSamplerAddressMode {
    VK_SAMPLER_ADDRESS_MODE_REPEAT = 0,
    VK_SAMPLER_ADDRESS_MODE_MIRRORED_REPEAT = 1,
    VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE = 2,
    VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER = 3,
} VkSamplerAddressMode;
  • VK_SAMPLER_ADDRESS_MODE_REPEAT specifies that the repeat wrap mode will be used.

  • VK_SAMPLER_ADDRESS_MODE_MIRRORED_REPEAT specifies that the mirrored repeat wrap mode will be used.

  • VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE specifies that the clamp to edge wrap mode will be used.

  • VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER specifies that the clamp to border wrap mode will be used.

Possible values of VkSamplerCreateInfo::borderColor, specifying the border color used for texture lookups, are:

// Provided by VK_VERSION_1_0
typedef enum VkBorderColor {
    VK_BORDER_COLOR_FLOAT_TRANSPARENT_BLACK = 0,
    VK_BORDER_COLOR_INT_TRANSPARENT_BLACK = 1,
    VK_BORDER_COLOR_FLOAT_OPAQUE_BLACK = 2,
    VK_BORDER_COLOR_INT_OPAQUE_BLACK = 3,
    VK_BORDER_COLOR_FLOAT_OPAQUE_WHITE = 4,
    VK_BORDER_COLOR_INT_OPAQUE_WHITE = 5,
} VkBorderColor;
  • VK_BORDER_COLOR_FLOAT_TRANSPARENT_BLACK specifies a transparent, floating-point format, black color.

  • VK_BORDER_COLOR_INT_TRANSPARENT_BLACK specifies a transparent, integer format, black color.

  • VK_BORDER_COLOR_FLOAT_OPAQUE_BLACK specifies an opaque, floating-point format, black color.

  • VK_BORDER_COLOR_INT_OPAQUE_BLACK specifies an opaque, integer format, black color.

  • VK_BORDER_COLOR_FLOAT_OPAQUE_WHITE specifies an opaque, floating-point format, white color.

  • VK_BORDER_COLOR_INT_OPAQUE_WHITE specifies an opaque, integer format, white color.

These colors are described in detail in Texel Replacement.

To destroy a sampler, call:

// Provided by VK_VERSION_1_0
void vkDestroySampler(
    VkDevice                                    device,
    VkSampler                                   sampler,
    const VkAllocationCallbacks*                pAllocator);
  • device is the logical device that destroys the sampler.

  • sampler is the sampler to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage
  • VUID-vkDestroySampler-sampler-01082
    All submitted commands that refer to sampler must have completed execution

  • VUID-vkDestroySampler-sampler-01083
    If VkAllocationCallbacks were provided when sampler was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroySampler-sampler-01084
    If no VkAllocationCallbacks were provided when sampler was created, pAllocator must be NULL

Valid Usage (Implicit)
  • VUID-vkDestroySampler-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroySampler-sampler-parameter
    If sampler is not VK_NULL_HANDLE, sampler must be a valid VkSampler handle

  • VUID-vkDestroySampler-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroySampler-sampler-parent
    If sampler is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization
  • Host access to sampler must be externally synchronized