12. 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:
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSampler)
To create a sampler object, call:
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:
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 an extension-specific 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 outside [0..1] range for U coordinate. -
addressModeV
is a VkSamplerAddressMode value specifying the addressing mode for outside [0..1] range for V coordinate. -
addressModeW
is a VkSamplerAddressMode value specifying the addressing mode for outside [0..1] range for W coordinate. -
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 function to apply to fetched data before filtering as described in the Depth Compare Operation section. -
minLod
andmaxLod
are the values used to clamp the computed LOD value, as described in the Level-of-Detail Operation section. -
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 dimensions for x, y and z. 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.
If maxSamplerAllocationCount
is exceeded, vkCreateSampler
will
return VK_ERROR_TOO_MANY_OBJECTS
.
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.
Bits which can be set in VkSamplerCreateInfo::flags
, specifying
additional parameters of a sampler, are:
typedef enum VkSamplerCreateFlagBits {
VK_SAMPLER_CREATE_FLAG_BITS_MAX_ENUM = 0x7FFFFFFF
} VkSamplerCreateFlagBits;
typedef VkFlags VkSamplerCreateFlags;
VkSamplerCreateFlags
is a bitmask type for setting a mask of zero or
more VkSamplerCreateFlagBits.
Possible values of the VkSamplerCreateInfo::magFilter
and
minFilter
parameters, specifying filters used for texture lookups,
are:
typedef enum VkFilter {
VK_FILTER_NEAREST = 0,
VK_FILTER_LINEAR = 1,
VK_FILTER_MAX_ENUM = 0x7FFFFFFF
} 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:
typedef enum VkSamplerMipmapMode {
VK_SAMPLER_MIPMAP_MODE_NEAREST = 0,
VK_SAMPLER_MIPMAP_MODE_LINEAR = 1,
VK_SAMPLER_MIPMAP_MODE_MAX_ENUM = 0x7FFFFFFF
} 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:
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,
VK_SAMPLER_ADDRESS_MODE_MAX_ENUM = 0x7FFFFFFF
} 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.
Possible values of VkSamplerCreateInfo::borderColor
, specifying
the border color used for texture lookups, are:
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,
VK_BORDER_COLOR_MAX_ENUM = 0x7FFFFFFF
} 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:
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.
12.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 appears in Formats requiring sampler Y’CBCR conversion for VK_IMAGE_ASPECT_COLOR_BIT
image views
.
The VkSamplerYcbcrConversionInfo
structure is defined as:
typedef struct VkSamplerYcbcrConversionInfo {
VkStructureType sType;
const void* pNext;
VkSamplerYcbcrConversion conversion;
} VkSamplerYcbcrConversionInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to an extension-specific 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:
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSamplerYcbcrConversion)
To create a VkSamplerYcbcrConversion, call:
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:
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 an extension-specific 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 channels in the x dimension.xChromaOffset
has no effect for formats in which chroma channels are the same resolution as the luma channel. -
yChromaOffset
describes the sample location associated with downsampled chroma channels in the y dimension.yChromaOffset
has no effect for formats in which the chroma channels 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 |
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 channel 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:
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,
VK_SAMPLER_YCBCR_MODEL_CONVERSION_MAX_ENUM = 0x7FFFFFFF
} 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) channel corresponds to the G channel of an RGB image.
-
the CB (CB or “U” blue color difference) channel corresponds to the B channel of an RGB image.
-
the CR (CR or “V” red color difference) channel corresponds to the R channel of an RGB image.
-
the alpha channel, if present, is not modified by color model conversion.
These rules reflect the mapping of channels after the channel swizzle
operation (controlled by
VkSamplerYcbcrConversionCreateInfo::components
).
Note
For example, an “YUVA” 32-bit format comprising four 8-bit channels can be
implemented as
|
The VkSamplerYcbcrRange enum describes whether color channels are encoded using the full range of numerical values or whether values are reserved for headroom and foot room. VkSamplerYcbcrRange is defined as:
typedef enum VkSamplerYcbcrRange {
VK_SAMPLER_YCBCR_RANGE_ITU_FULL = 0,
VK_SAMPLER_YCBCR_RANGE_ITU_NARROW = 1,
VK_SAMPLER_YCBCR_RANGE_MAX_ENUM = 0x7FFFFFFF
} 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 channel samples relative to the luma samples, and is defined as:
typedef enum VkChromaLocation {
VK_CHROMA_LOCATION_COSITED_EVEN = 0,
VK_CHROMA_LOCATION_MIDPOINT = 1,
VK_CHROMA_LOCATION_MAX_ENUM = 0x7FFFFFFF
} 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:
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.