C Specification

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;

Members

  • sType is a VkStructureType value identifying 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 wrapping operation used when the i coordinate used to sample the image would be out of bounds.

  • addressModeV is a VkSamplerAddressMode value specifying the wrapping operation used when the j coordinate used to sample the image would be out of bounds.

  • addressModeW is a VkSamplerAddressMode value specifying the wrapping operation used when the k coordinate used to sample the image would be out of bounds. If unnormalizedCoordinates is VK_TRUE, addressModeW is ignored.

  • mipLodBias is the bias to be added to mipmap LOD calculation and bias provided by image sampling functions in SPIR-V, as described in the LOD 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 operator 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 unnormalizedCoordinates is 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 unnormalizedCoordinates is 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.

Description

Note
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.

When this structure is used to write a descriptor via vkWriteSamplerDescriptorsEXT, applications can give the descriptor a debug name in a similar way to naming an object, via the VkDebugUtilsObjectNameInfoEXT structure. However, as there is no actual object, VkDebugUtilsObjectNameInfoEXT must be passed via the pNext chain of this structure, with a objectType of VK_OBJECT_TYPE_UNKNOWN and a objectHandle of VK_NULL_HANDLE. The name is attached to the unique set of descriptor bits written by the implementation, and writing the same bits again with new debug info may rename the original descriptor.

Note

Implementations are not prevented from returning the same bits for different descriptors. This can result in multiple different samplers mapping to the same name.

VkDescriptorSetAndBindingMappingEXT can also be chained in the same way when defining an embedded sampler via VkDescriptorSetAndBindingMappingEXT, naming the embedded sampler.

Valid Usage
Valid Usage (Implicit)

See Also

VK_VERSION_1_0, VkBool32, VkBorderColor, VkCompareOp, VkDescriptorMappingSourceConstantOffsetEXT, VkDescriptorMappingSourceIndirectIndexArrayEXT, VkDescriptorMappingSourceIndirectIndexEXT, VkDescriptorMappingSourcePushIndexEXT, VkDescriptorMappingSourceShaderRecordIndexEXT, VkFilter, VkSamplerAddressMode, VkSamplerCreateFlags, VkSamplerMipmapMode, VkStructureType, vkCreateSampler, vkWriteSamplerDescriptorsEXT

Document Notes

For more information, see the Vulkan Specification.

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2026 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0