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;
sType
is a VkStructureType value identifying this structure.pNext
isNULL
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
isVK_TRUE
to enable anisotropic filtering, as described in the Texel Anisotropic Filtering section, orVK_FALSE
otherwise. maxAnisotropy
is the anisotropy value clamp used by the sampler whenanisotropyEnable
isVK_TRUE
. IfanisotropyEnable
isVK_FALSE
,maxAnisotropy
is ignored.compareEnable
isVK_TRUE
to enable comparison against a reference value during lookups, orVK_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, setmaxLod
to the constantVK_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. WhenunnormalizedCoordinates
isVK_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. WhenunnormalizedCoordinates
isVK_FALSE
, the range of image coordinates is zero to one.
WhenunnormalizedCoordinates
isVK_TRUE
, images the sampler is used with in the shader have the following requirements:- The
viewType
must be eitherVK_IMAGE_VIEW_TYPE_1D
orVK_IMAGE_VIEW_TYPE_2D
. - The image view must have a single layer and a single mip level.
WhenunnormalizedCoordinates
isVK_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
, 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-01646
If sampler Y′CBCR conversion is enabled,
addressModeU
, addressModeV
, and addressModeW
must be
VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE
, anisotropyEnable
must 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 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::customBorderColor
must 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, flags
must 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 mipmapMode
must 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 borderColor
must 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 struct 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