VkSamplerCreateInfo
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;
sTypeis a VkStructureType value identifying this structure.pNextisNULLor a pointer to a structure extending this structure.flagsis a bitmask of VkSamplerCreateFlagBits describing additional parameters of the sampler.magFilteris a VkFilter value specifying the magnification filter to apply to lookups.minFilteris a VkFilter value specifying the minification filter to apply to lookups.mipmapModeis a VkSamplerMipmapMode value specifying the mipmap filter to apply to lookups.addressModeUis a VkSamplerAddressMode value specifying the addressing mode for U coordinates outside [0,1).addressModeVis a VkSamplerAddressMode value specifying the addressing mode for V coordinates outside [0,1).addressModeWis a VkSamplerAddressMode value specifying the addressing mode for W coordinates outside [0,1).-
mipLodBiasis 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. -
anisotropyEnableisVK_TRUEto enable anisotropic filtering, as described in the Texel Anisotropic Filtering section, orVK_FALSEotherwise. maxAnisotropyis the anisotropy value clamp used by the sampler whenanisotropyEnableisVK_TRUE. IfanisotropyEnableisVK_FALSE,maxAnisotropyis ignored.compareEnableisVK_TRUEto enable comparison against a reference value during lookups, orVK_FALSEotherwise.- Note: Some implementations will default to shader state if this member does not match.
compareOpis a VkCompareOp value specifying the comparison operator to apply to fetched data before filtering as described in the Depth Compare Operation section.minLodis used to clamp the minimum of the computed LOD value.maxLodis used to clamp the maximum of the computed LOD value. To avoid clamping the maximum value, setmaxLodto the constantVK_LOD_CLAMP_NONE.borderColoris a VkBorderColor value specifying the predefined border color to use.-
unnormalizedCoordinatescontrols whether to use unnormalized or normalized texel coordinates to address texels of the image. WhenunnormalizedCoordinatesisVK_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. WhenunnormalizedCoordinatesisVK_FALSE, the range of image coordinates is zero to one.
WhenunnormalizedCoordinatesisVK_TRUE, images the sampler is used with in the shader have the following requirements:- The
viewTypemust be eitherVK_IMAGE_VIEW_TYPE_1DorVK_IMAGE_VIEW_TYPE_2D. - The image view must have a single layer and a single mip level.
WhenunnormalizedCoordinatesisVK_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.
- The
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 VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE
VUID-VkSamplerCreateInfo-addressModeU-01079
If the samplerMirrorClampToEdge feature 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
Valid Usage (Implicit)
VUID-VkSamplerCreateInfo-sType-sType
sType must be VK_STRUCTURE_TYPE_SAMPLER_CREATE_INFO
VUID-VkSamplerCreateInfo-pNext-pNext
Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkOpaqueCaptureDescriptorDataCreateInfoEXT, VkSamplerBlockMatchWindowCreateInfoQCOM, VkSamplerBorderColorComponentMappingCreateInfoEXT, VkSamplerCubicWeightsCreateInfoQCOM, VkSamplerCustomBorderColorCreateInfoEXT, VkSamplerReductionModeCreateInfo, or VkSamplerYcbcrConversionInfo
VUID-VkSamplerCreateInfo-sType-unique
The sType value of each structure in the pNext chain must be unique
VUID-VkSamplerCreateInfo-flags-parameter
flags must be a valid combination of VkSamplerCreateFlagBits values
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