Structures

VkSamplerCreateInfo

Structure specifying parameters of a newly created sampler

The VkSamplerCreateInfo structure is defined as:

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

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-samplerMipLodBias-04467

If the VK_KHR_portability_subset extension is enabled, and VkPhysicalDevicePortabilitySubsetFeaturesKHR::samplerMipLodBias is VK_FALSE, mipLodBias must be zero

VUID-VkSamplerCreateInfo-maxLod-01973

maxLod must be greater than or equal to minLod

VUID-VkSamplerCreateInfo-anisotropyEnable-01070

If the samplerAnisotropy 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-minFilter-01645

If sampler Y′CBCR conversion is enabled and the potential format features of the sampler Y′CBCR conversion do not support VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT, minFilter and magFilter must be equal to the sampler Y′CBCR conversion’s chromaFilter

VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01072

If unnormalizedCoordinates is VK_TRUE, minFilter and magFilter must be equal

VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01073

If unnormalizedCoordinates is VK_TRUE, mipmapModemust 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, compareEnablemust be VK_FALSE

VUID-VkSamplerCreateInfo-addressModeU-01078

If any of addressModeU, addressModeV or addressModeW are VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER, borderColormust be a valid VkBorderColor value

VUID-VkSamplerCreateInfo-addressModeU-01646

If sampler Y′CBCR conversion is enabled, addressModeU, addressModeV, and addressModeW must be VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE, anisotropyEnablemust be VK_FALSE, and unnormalizedCoordinates must be VK_FALSE

VUID-VkSamplerCreateInfo-None-01647

If sampler Y′CBCR conversion is enabled and the pNext chain includes a VkSamplerReductionModeCreateInfo structure, then the sampler reduction mode must be set to VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE

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

VUID-VkSamplerCreateInfo-magFilter-01081

If either magFilter or minFilter is VK_FILTER_CUBIC_EXT, anisotropyEnable must be VK_FALSE

VUID-VkSamplerCreateInfo-magFilter-07911

If the VK_EXT_filter_cubic extension is not enabled and either magFilter or minFilter is VK_FILTER_CUBIC_IMG, the reductionMode member of VkSamplerReductionModeCreateInfomust be VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE

VUID-VkSamplerCreateInfo-compareEnable-01423

If compareEnable is VK_TRUE, the reductionMode member of VkSamplerReductionModeCreateInfo must be VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE

VUID-VkSamplerCreateInfo-flags-02574

If flags includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then minFilter and magFilter must be equal

VUID-VkSamplerCreateInfo-flags-02575

If flags includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then mipmapMode must be VK_SAMPLER_MIPMAP_MODE_NEAREST

VUID-VkSamplerCreateInfo-flags-02576

If flags includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then minLod and maxLod must be zero

VUID-VkSamplerCreateInfo-flags-02577

If flags includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then addressModeU and addressModeV must each be either VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER

VUID-VkSamplerCreateInfo-flags-02578

If flags includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then anisotropyEnable must be VK_FALSE

VUID-VkSamplerCreateInfo-flags-02579

If flags includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then compareEnable must be VK_FALSE

VUID-VkSamplerCreateInfo-flags-02580

If flags includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then unnormalizedCoordinates must be VK_FALSE

VUID-VkSamplerCreateInfo-nonSeamlessCubeMap-06788

If the nonSeamlessCubeMap feature is not enabled, flags must not include VK_SAMPLER_CREATE_NON_SEAMLESS_CUBE_MAP_BIT_EXT

VUID-VkSamplerCreateInfo-borderColor-04011

If borderColor is one of VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or VK_BORDER_COLOR_INT_CUSTOM_EXT, then a VkSamplerCustomBorderColorCreateInfoEXT must be included in the pNext chain

VUID-VkSamplerCreateInfo-customBorderColors-04085

If the customBorderColors feature is not enabled, borderColor must not be VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or VK_BORDER_COLOR_INT_CUSTOM_EXT

VUID-VkSamplerCreateInfo-borderColor-04442

If borderColor is one of VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or VK_BORDER_COLOR_INT_CUSTOM_EXT, and VkSamplerCustomBorderColorCreateInfoEXT::format is not VK_FORMAT_UNDEFINED, VkSamplerCustomBorderColorCreateInfoEXT::customBorderColormust be within the range of values representable in format

VUID-VkSamplerCreateInfo-None-04012

The maximum number of samplers with custom border colors which can be simultaneously created on a device is implementation-dependent and specified by the maxCustomBorderColorSamplers member of the VkPhysicalDeviceCustomBorderColorPropertiesEXT structure

VUID-VkSamplerCreateInfo-flags-08110

If flags includes VK_SAMPLER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT, the descriptorBufferCaptureReplay feature must be enabled

VUID-VkSamplerCreateInfo-pNext-08111

If the pNext chain includes a VkOpaqueCaptureDescriptorDataCreateInfoEXT structure, flagsmust contain VK_SAMPLER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT

VUID-VkSamplerCreateInfo-flags-06964

If flags includes VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then minFilter and magFilter must be VK_FILTER_NEAREST

VUID-VkSamplerCreateInfo-flags-06965

If flags includes VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then mipmapModemust be VK_SAMPLER_MIPMAP_MODE_NEAREST

VUID-VkSamplerCreateInfo-flags-06966

[If flags includes VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then minLod and maxLod must be zero

VUID-VkSamplerCreateInfo-flags-06967

If flags includes VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then addressModeU and addressModeV must each be either VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER

VUID-VkSamplerCreateInfo-flags-06968

If flags includes VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, and if addressModeU or addressModeV is VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER, then borderColormust be VK_BORDER_COLOR_FLOAT_TRANSPARENT_BLACK

VUID-VkSamplerCreateInfo-flags-06969

If flags includes VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then anisotropyEnable must be VK_FALSE

VUID-VkSamplerCreateInfo-flags-06970

If flags includes VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then compareEnable must be VK_FALSE