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.
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
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 (level-of-detail) calculation and bias provided by image sampling functions in SPIR-V, as described in the Level-of-Detail 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. When set toVK_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 toVK_FALSE
the range of image coordinates is zero to one.When
unnormalizedCoordinates
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.
When
unnormalizedCoordinates
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.
-
Mapping of OpenGL to Vulkan filter modes
There are no Vulkan filter modes that directly correspond to OpenGL
minification filters of Note that using a |
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 |
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.
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.
The VkSamplerReductionModeCreateInfo
structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkSamplerReductionModeCreateInfo {
VkStructureType sType;
const void* pNext;
VkSamplerReductionMode reductionMode;
} VkSamplerReductionModeCreateInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
reductionMode
is a VkSamplerReductionMode value controlling how texture filtering combines texel values.
If the pNext
chain of VkSamplerCreateInfo includes a
VkSamplerReductionModeCreateInfo
structure, then that structure
includes a mode controlling how texture filtering combines texel values.
If this structure is not present, reductionMode
is considered to be
VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE
.
Reduction modes are specified by VkSamplerReductionMode, which takes values:
// Provided by VK_VERSION_1_2
typedef enum VkSamplerReductionMode {
VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE = 0,
VK_SAMPLER_REDUCTION_MODE_MIN = 1,
VK_SAMPLER_REDUCTION_MODE_MAX = 2,
} VkSamplerReductionMode;
-
VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE
specifies that texel values are combined by computing a weighted average of values in the footprint, using weights as specified in the image operations chapter. -
VK_SAMPLER_REDUCTION_MODE_MIN
specifies that texel values are combined by taking the component-wise minimum of values in the footprint with non-zero weights. -
VK_SAMPLER_REDUCTION_MODE_MAX
specifies that texel values are combined by taking the component-wise maximum of values in the footprint with non-zero weights.
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,
// Provided by VK_VERSION_1_2
VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE = 4,
} 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. -
VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE
specifies that the mirror clamp to edge wrap mode will be used. This is only valid ifsamplerMirrorClampToEdge
is enabled, or if the
extension is enabled.VK_KHR_sampler_mirror_clamp_to_edge
Comparison operators compare a reference and a test value, and return a true (“passed”) or false (“failed”) value depending on the comparison operator chosen. The supported operators are:
// Provided by VK_VERSION_1_0
typedef enum VkCompareOp {
VK_COMPARE_OP_NEVER = 0,
VK_COMPARE_OP_LESS = 1,
VK_COMPARE_OP_EQUAL = 2,
VK_COMPARE_OP_LESS_OR_EQUAL = 3,
VK_COMPARE_OP_GREATER = 4,
VK_COMPARE_OP_NOT_EQUAL = 5,
VK_COMPARE_OP_GREATER_OR_EQUAL = 6,
VK_COMPARE_OP_ALWAYS = 7,
} VkCompareOp;
-
VK_COMPARE_OP_NEVER
specifies that the comparison always evaluates false. -
VK_COMPARE_OP_LESS
specifies that the comparison evaluates reference < test. -
VK_COMPARE_OP_EQUAL
specifies that the comparison evaluates reference = test. -
VK_COMPARE_OP_LESS_OR_EQUAL
specifies that the comparison evaluates reference ≤ test. -
VK_COMPARE_OP_GREATER
specifies that the comparison evaluates reference > test. -
VK_COMPARE_OP_NOT_EQUAL
specifies that the comparison evaluates reference ≠ test. -
VK_COMPARE_OP_GREATER_OR_EQUAL
specifies that the comparison evaluates reference ≥ test. -
VK_COMPARE_OP_ALWAYS
specifies that the comparison always evaluates true.
Comparison operators are used for:
-
The Depth Compare Operation operator for a sampler, specified by VkSamplerCreateInfo::
compareOp
. -
The stencil comparison operator for the stencil test, specified by vkCmdSetStencilOp::
compareOp
or VkStencilOpState::compareOp
. -
The Depth Comparison operator for the depth test, specified by vkCmdSetDepthCompareOp::
depthCompareOp
or VkPipelineDepthStencilStateCreateInfo::depthCompareOp
.
Each such use describes how the reference and test values for that comparison are determined.
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.
13.1. Sampler Y′CBCR conversion
To create a sampler with Y′CBCR conversion enabled, add a
VkSamplerYcbcrConversionInfo structure to the pNext
chain of the
VkSamplerCreateInfo structure.
To create a sampler Y′CBCR conversion, the
samplerYcbcrConversion
feature
must be enabled.
Conversion must be fixed at pipeline creation time, through use of a
combined image sampler with an immutable sampler in
VkDescriptorSetLayoutBinding
.
A VkSamplerYcbcrConversionInfo must be provided for samplers to be
used with image views that access VK_IMAGE_ASPECT_COLOR_BIT
if the
format is one of the formats
that require a sampler Y′CBCR conversion
.
The VkSamplerYcbcrConversionInfo
structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkSamplerYcbcrConversionInfo {
VkStructureType sType;
const void* pNext;
VkSamplerYcbcrConversion conversion;
} VkSamplerYcbcrConversionInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
conversion
is a VkSamplerYcbcrConversion handle created with vkCreateSamplerYcbcrConversion.
A sampler Y′CBCR conversion is an opaque representation of a
device-specific sampler Y′CBCR conversion description, represented as a
VkSamplerYcbcrConversion
handle:
// Provided by VK_VERSION_1_1
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSamplerYcbcrConversion)
To create a VkSamplerYcbcrConversion, call:
// Provided by VK_VERSION_1_1
VkResult vkCreateSamplerYcbcrConversion(
VkDevice device,
const VkSamplerYcbcrConversionCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSamplerYcbcrConversion* pYcbcrConversion);
-
device
is the logical device that creates the sampler Y′CBCR conversion. -
pCreateInfo
is a pointer to a VkSamplerYcbcrConversionCreateInfo structure specifying the requested sampler Y′CBCR conversion. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter. -
pYcbcrConversion
is a pointer to a VkSamplerYcbcrConversion handle in which the resulting sampler Y′CBCR conversion is returned.
The interpretation of the configured sampler Y′CBCR conversion is described in more detail in the description of sampler Y′CBCR conversion in the Image Operations chapter.
The VkSamplerYcbcrConversionCreateInfo
structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkSamplerYcbcrConversionCreateInfo {
VkStructureType sType;
const void* pNext;
VkFormat format;
VkSamplerYcbcrModelConversion ycbcrModel;
VkSamplerYcbcrRange ycbcrRange;
VkComponentMapping components;
VkChromaLocation xChromaOffset;
VkChromaLocation yChromaOffset;
VkFilter chromaFilter;
VkBool32 forceExplicitReconstruction;
} VkSamplerYcbcrConversionCreateInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
format
is the format of the image from which color information will be retrieved. -
ycbcrModel
describes the color matrix for conversion between color models. -
ycbcrRange
describes whether the encoded values have headroom and foot room, or whether the encoding uses the full numerical range. -
components
applies a swizzle based on VkComponentSwizzle enums prior to range expansion and color model conversion. -
xChromaOffset
describes the sample location associated with downsampled chroma components in the x dimension.xChromaOffset
has no effect for formats in which chroma components are not downsampled horizontally. -
yChromaOffset
describes the sample location associated with downsampled chroma components in the y dimension.yChromaOffset
has no effect for formats in which the chroma components are not downsampled vertically. -
chromaFilter
is the filter for chroma reconstruction. -
forceExplicitReconstruction
can be used to ensure that reconstruction is done explicitly, if supported.
Note
Setting If |
Sampler Y′CBCR conversion objects do not support external format conversion without additional extensions defining external formats.
If chromaFilter
is VK_FILTER_NEAREST
, chroma samples are
reconstructed to luma component resolution using nearest-neighbour sampling.
Otherwise, chroma samples are reconstructed using interpolation.
More details can be found in the
description of sampler Y′CBCR conversion in the Image
Operations chapter.
VkSamplerYcbcrModelConversion defines the conversion from the source color model to the shader color model. Possible values are:
// Provided by VK_VERSION_1_1
typedef enum VkSamplerYcbcrModelConversion {
VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY = 0,
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY = 1,
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709 = 2,
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601 = 3,
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020 = 4,
} VkSamplerYcbcrModelConversion;
-
VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY
specifies that the input values to the conversion are unmodified. -
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY
specifies no model conversion but the inputs are range expanded as for Y′CBCR. -
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709
specifies the color model conversion from Y′CBCR to R′G′B′ defined in BT.709 and described in the “BT.709 Y′CBCR conversion” section of the Khronos Data Format Specification. -
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601
specifies the color model conversion from Y′CBCR to R′G′B′ defined in BT.601 and described in the “BT.601 Y′CBCR conversion” section of the Khronos Data Format Specification. -
VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020
specifies the color model conversion from Y′CBCR to R′G′B′ defined in BT.2020 and described in the “BT.2020 Y′CBCR conversion” section of the Khronos Data Format Specification.
In the VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_*
color models, for the
input to the sampler Y′CBCR range expansion and model conversion:
-
the Y (Y′ luma) component corresponds to the G component of an RGB image.
-
the CB (CB or “U” blue color difference) component corresponds to the B component of an RGB image.
-
the CR (CR or “V” red color difference) component corresponds to the R component of an RGB image.
-
the alpha component, if present, is not modified by color model conversion.
These rules reflect the mapping of components after the component swizzle
operation (controlled by
VkSamplerYcbcrConversionCreateInfo::components
).
Note
For example, an “YUVA” 32-bit format comprising four 8-bit components can
be implemented as
|
The VkSamplerYcbcrRange enum describes whether color components are encoded using the full range of numerical values or whether values are reserved for headroom and foot room. VkSamplerYcbcrRange is defined as:
// Provided by VK_VERSION_1_1
typedef enum VkSamplerYcbcrRange {
VK_SAMPLER_YCBCR_RANGE_ITU_FULL = 0,
VK_SAMPLER_YCBCR_RANGE_ITU_NARROW = 1,
} VkSamplerYcbcrRange;
-
VK_SAMPLER_YCBCR_RANGE_ITU_FULL
specifies that the full range of the encoded values are valid and interpreted according to the ITU “full range” quantization rules. -
VK_SAMPLER_YCBCR_RANGE_ITU_NARROW
specifies that headroom and foot room are reserved in the numerical range of encoded values, and the remaining values are expanded according to the ITU “narrow range” quantization rules.
The formulae for these conversions is described in the Sampler Y′CBCR Range Expansion section of the Image Operations chapter.
No range modification takes place if ycbcrModel
is
VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY
; the ycbcrRange
field of VkSamplerYcbcrConversionCreateInfo is ignored in this case.
The VkChromaLocation enum defines the location of downsampled chroma component samples relative to the luma samples, and is defined as:
// Provided by VK_VERSION_1_1
typedef enum VkChromaLocation {
VK_CHROMA_LOCATION_COSITED_EVEN = 0,
VK_CHROMA_LOCATION_MIDPOINT = 1,
} VkChromaLocation;
-
VK_CHROMA_LOCATION_COSITED_EVEN
specifies that downsampled chroma samples are aligned with luma samples with even coordinates. -
VK_CHROMA_LOCATION_MIDPOINT
specifies that downsampled chroma samples are located half way between each even luma sample and the nearest higher odd luma sample.
To destroy a sampler Y′CBCR conversion, call:
// Provided by VK_VERSION_1_1
void vkDestroySamplerYcbcrConversion(
VkDevice device,
VkSamplerYcbcrConversion ycbcrConversion,
const VkAllocationCallbacks* pAllocator);
-
device
is the logical device that destroys the Y′CBCR conversion. -
ycbcrConversion
is the conversion to destroy. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter.