704 lines
31 KiB
Plaintext
704 lines
31 KiB
Plaintext
// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a
|
||
// Creative Commons Attribution 4.0 International License; see
|
||
// http://creativecommons.org/licenses/by/4.0/
|
||
|
||
[[samplers]]
|
||
= Samplers
|
||
|
||
[open,refpage='VkSampler',desc='Opaque handle to a sampler object',type='handles']
|
||
--
|
||
|
||
sname: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 sname:VkSampler handles:
|
||
|
||
include::../api/handles/VkSampler.txt[]
|
||
|
||
--
|
||
|
||
[open,refpage='vkCreateSampler',desc='Create a new sampler object',type='protos']
|
||
--
|
||
|
||
To create a sampler object, call:
|
||
|
||
include::../api/protos/vkCreateSampler.txt[]
|
||
|
||
* pname:device is the logical device that creates the sampler.
|
||
* pname:pCreateInfo is a pointer to an instance of the
|
||
slink:VkSamplerCreateInfo structure specifying the state of the sampler
|
||
object.
|
||
* pname:pAllocator controls host memory allocation as described in the
|
||
<<memory-allocation, Memory Allocation>> chapter.
|
||
* pname:pSampler points to a slink:VkSampler handle in which the resulting
|
||
sampler object is returned.
|
||
|
||
include::../validity/protos/vkCreateSampler.txt[]
|
||
--
|
||
|
||
[open,refpage='VkSamplerCreateInfo',desc='Structure specifying parameters of a newly created sampler',type='structs']
|
||
--
|
||
|
||
The sname:VkSamplerCreateInfo structure is defined as:
|
||
|
||
include::../api/structs/VkSamplerCreateInfo.txt[]
|
||
|
||
* pname:sType is the type of this structure.
|
||
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
||
* pname:flags is reserved for future use.
|
||
* pname:magFilter is a elink:VkFilter value specifying the magnification
|
||
filter to apply to lookups.
|
||
* pname:minFilter is a elink:VkFilter value specifying the minification
|
||
filter to apply to lookups.
|
||
* pname:mipmapMode is a elink:VkSamplerMipmapMode value specifying the
|
||
mipmap filter to apply to lookups.
|
||
* pname:addressModeU is a elink:VkSamplerAddressMode value specifying the
|
||
addressing mode for outside [0..1] range for U coordinate.
|
||
* pname:addressModeV is a elink:VkSamplerAddressMode value specifying the
|
||
addressing mode for outside [0..1] range for V coordinate.
|
||
* pname:addressModeW is a elink:VkSamplerAddressMode value specifying the
|
||
addressing mode for outside [0..1] range for W coordinate.
|
||
* [[samplers-mipLodBias]] pname: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 <<textures-level-of-detail-operation,
|
||
Level-of-Detail Operation>> section.
|
||
* [[samplers-maxAnisotropy]] pname:anisotropyEnable is ename:VK_TRUE to
|
||
enable anisotropic filtering, as described in the
|
||
<<textures-texel-anisotropic-filtering, Texel Anisotropic Filtering>>
|
||
section, or ename:VK_FALSE otherwise.
|
||
* pname:maxAnisotropy is the anisotropy value clamp.
|
||
* pname:compareEnable is ename:VK_TRUE to enable comparison against a
|
||
reference value during lookups, or ename:VK_FALSE otherwise.
|
||
** Note: Some implementations will default to shader state if this member
|
||
does not match.
|
||
* pname:compareOp is a elink:VkCompareOp value specifying the comparison
|
||
function to apply to fetched data before filtering as described in the
|
||
<<textures-depth-compare-operation, Depth Compare Operation>> section.
|
||
* pname:minLod and pname:maxLod are the values used to clamp the computed
|
||
level-of-detail value, as described in the
|
||
<<textures-level-of-detail-operation, Level-of-Detail Operation>>
|
||
section.
|
||
pname:maxLod must: be greater than or equal to pname:minLod.
|
||
* pname:borderColor is a elink:VkBorderColor value specifying the
|
||
predefined border color to use.
|
||
* [[samplers-unnormalizedCoordinates]] pname:unnormalizedCoordinates
|
||
controls whether to use unnormalized or normalized texel coordinates to
|
||
address texels of the image.
|
||
When set to ename:VK_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 to ename:VK_FALSE the range of image coordinates is zero to
|
||
one.
|
||
When pname:unnormalizedCoordinates is ename:VK_TRUE, samplers have the
|
||
following requirements:
|
||
** pname:minFilter and pname:magFilter must: be equal.
|
||
** pname:mipmapMode must: be ename:VK_SAMPLER_MIPMAP_MODE_NEAREST.
|
||
** pname:minLod and pname:maxLod must: be zero.
|
||
** pname:addressModeU and pname:addressModeV must: each be either
|
||
ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or
|
||
ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER.
|
||
** pname:anisotropyEnable must: be ename:VK_FALSE.
|
||
** pname:compareEnable must: be ename:VK_FALSE.
|
||
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
||
** The sampler must: not enable sampler Y'C~B~C~R~ conversion.
|
||
endif::VK_KHR_sampler_ycbcr_conversion[]
|
||
* When pname:unnormalizedCoordinates is ename:VK_TRUE, images the sampler
|
||
is used with in the shader have the following requirements:
|
||
** The pname:viewType must: be either ename:VK_IMAGE_VIEW_TYPE_1D or
|
||
ename:VK_IMAGE_VIEW_TYPE_2D.
|
||
** The image view must: have a single layer and a single mip level.
|
||
* When pname:unnormalizedCoordinates is ename: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.
|
||
|
||
[NOTE]
|
||
.Mapping of OpenGL to Vulkan filter modes
|
||
==================
|
||
pname:magFilter values of ename:VK_FILTER_NEAREST and ename:VK_FILTER_LINEAR
|
||
directly correspond to code:GL_NEAREST and code:GL_LINEAR magnification
|
||
filters.
|
||
pname:minFilter and pname:mipmapMode combine to correspond to the similarly
|
||
named OpenGL minification filter of code:GL_minFilter_MIPMAP_mipmapMode
|
||
(e.g. pname:minFilter of ename:VK_FILTER_LINEAR and pname:mipmapMode of
|
||
ename:VK_SAMPLER_MIPMAP_MODE_NEAREST correspond to
|
||
code:GL_LINEAR_MIPMAP_NEAREST).
|
||
|
||
There are no Vulkan filter modes that directly correspond to OpenGL
|
||
minification filters of code:GL_LINEAR or code:GL_NEAREST, but they can: be
|
||
emulated using ename:VK_SAMPLER_MIPMAP_MODE_NEAREST, pname:minLod = 0, and
|
||
pname:maxLod = 0.25, and using pname:minFilter = ename:VK_FILTER_LINEAR or
|
||
pname:minFilter = ename:VK_FILTER_NEAREST, respectively.
|
||
|
||
Note that using a pname:maxLod of zero would cause
|
||
<<textures-texel-filtering,magnification>> to always be performed, and the
|
||
pname: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 [eq]#{lambda}# value to be
|
||
non-zero and minification to be performed, while still always rounding down
|
||
to the base level.
|
||
If the pname:minFilter and pname:magFilter are equal, then using a
|
||
pname: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
|
||
<<features-limits-maxSamplerAllocationCount,pname:maxSamplerAllocationCount>>
|
||
member of the slink:VkPhysicalDeviceLimits structure.
|
||
If pname:maxSamplerAllocationCount is exceeded, fname:vkCreateSampler will
|
||
return ename:VK_ERROR_TOO_MANY_OBJECTS.
|
||
|
||
Since slink: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
|
||
pname:maxSamplerAllocationCount limit.
|
||
|
||
.Valid Usage
|
||
****
|
||
* [[VUID-VkSamplerCreateInfo-mipLodBias-01069]]
|
||
The absolute value of pname:mipLodBias must: be less than or equal to
|
||
sname:VkPhysicalDeviceLimits::pname:maxSamplerLodBias
|
||
* [[VUID-VkSamplerCreateInfo-anisotropyEnable-01070]]
|
||
If the <<features-features-samplerAnisotropy,anisotropic sampling>>
|
||
feature is not enabled, pname:anisotropyEnable must: be ename:VK_FALSE
|
||
* [[VUID-VkSamplerCreateInfo-anisotropyEnable-01071]]
|
||
If pname:anisotropyEnable is ename:VK_TRUE, pname:maxAnisotropy must: be
|
||
between `1.0` and
|
||
sname:VkPhysicalDeviceLimits::pname:maxSamplerAnisotropy, inclusive
|
||
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
||
* [[VUID-VkSamplerCreateInfo-minFilter-01645]]
|
||
If <<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>> is
|
||
enabled and
|
||
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT_KHR
|
||
is not set for the format, pname:minFilter and pname:magFilter must: be
|
||
equal to the sampler Y'C~B~C~R~ conversion's pname:chromaFilter
|
||
endif::VK_KHR_sampler_ycbcr_conversion[]
|
||
* [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01072]]
|
||
If pname:unnormalizedCoordinates is ename:VK_TRUE, pname:minFilter and
|
||
pname:magFilter must: be equal
|
||
* [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01073]]
|
||
If pname:unnormalizedCoordinates is ename:VK_TRUE, pname:mipmapMode
|
||
must: be ename:VK_SAMPLER_MIPMAP_MODE_NEAREST
|
||
* [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01074]]
|
||
If pname:unnormalizedCoordinates is ename:VK_TRUE, pname:minLod and
|
||
pname:maxLod must: be zero
|
||
* [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01075]]
|
||
If pname:unnormalizedCoordinates is ename:VK_TRUE, pname:addressModeU
|
||
and pname:addressModeV must: each be either
|
||
ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or
|
||
ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER
|
||
* [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01076]]
|
||
If pname:unnormalizedCoordinates is ename:VK_TRUE,
|
||
pname:anisotropyEnable must: be ename:VK_FALSE
|
||
* [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01077]]
|
||
If pname:unnormalizedCoordinates is ename:VK_TRUE, pname:compareEnable
|
||
must: be ename:VK_FALSE
|
||
* [[VUID-VkSamplerCreateInfo-addressModeU-01078]]
|
||
If any of pname:addressModeU, pname:addressModeV or pname:addressModeW
|
||
are ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER, pname:borderColor
|
||
must: be a valid elink:VkBorderColor value
|
||
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
||
* [[VUID-VkSamplerCreateInfo-addressModeU-01646]]
|
||
If <<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>> is
|
||
enabled, pname:addressModeU, pname:addressModeV, and pname:addressModeW
|
||
must: be ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE,
|
||
pname:anisotropyEnable must: be ename:VK_FALSE, and
|
||
pname:unnormalizedCoordinates must: be ename:VK_FALSE
|
||
ifdef::VK_EXT_sampler_filter_minmax[]
|
||
* [[VUID-VkSamplerCreateInfo-None-01647]]
|
||
The sampler reduction mode must: be set to
|
||
ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT if
|
||
<<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>> is enabled
|
||
endif::VK_EXT_sampler_filter_minmax[]
|
||
endif::VK_KHR_sampler_ycbcr_conversion[]
|
||
* [[VUID-VkSamplerCreateInfo-addressModeU-01079]]
|
||
If the +VK_KHR_sampler_mirror_clamp_to_edge+ extension is not enabled,
|
||
pname:addressModeU, pname:addressModeV and pname:addressModeW must: not
|
||
be ename:VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE
|
||
* [[VUID-VkSamplerCreateInfo-compareEnable-01080]]
|
||
If pname:compareEnable is ename:VK_TRUE, pname:compareOp must: be a
|
||
valid elink:VkCompareOp value
|
||
ifdef::VK_IMG_filter_cubic[]
|
||
* [[VUID-VkSamplerCreateInfo-magFilter-01081]]
|
||
If either pname:magFilter or pname:minFilter is
|
||
ename:VK_FILTER_CUBIC_IMG, pname:anisotropyEnable must: be
|
||
ename:VK_FALSE
|
||
endif::VK_IMG_filter_cubic[]
|
||
ifdef::VK_IMG_filter_cubic+VK_EXT_sampler_filter_minmax[]
|
||
* [[VUID-VkSamplerCreateInfo-magFilter-01422]]
|
||
If either pname:magFilter or pname:minFilter is
|
||
ename:VK_FILTER_CUBIC_IMG, the pname:reductionMode member of
|
||
slink:VkSamplerReductionModeCreateInfoEXT must: be
|
||
ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT
|
||
endif::VK_IMG_filter_cubic+VK_EXT_sampler_filter_minmax[]
|
||
ifdef::VK_EXT_sampler_filter_minmax[]
|
||
* [[VUID-VkSamplerCreateInfo-compareEnable-01423]]
|
||
If pname:compareEnable is ename:VK_TRUE, the pname:reductionMode member
|
||
of slink:VkSamplerReductionModeCreateInfoEXT must: be
|
||
ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT
|
||
endif::VK_EXT_sampler_filter_minmax[]
|
||
****
|
||
|
||
include::../validity/structs/VkSamplerCreateInfo.txt[]
|
||
--
|
||
|
||
ifdef::VK_EXT_sampler_filter_minmax[]
|
||
|
||
[open,refpage='VkSamplerReductionModeCreateInfoEXT',desc='Structure specifying sampler reduction mode',type='structs']
|
||
--
|
||
If the pname:pNext chain of slink:VkSamplerCreateInfo includes a
|
||
sname:VkSamplerReductionModeCreateInfoEXT structure, then that structure
|
||
includes a mode that controls how texture filtering combines texel values.
|
||
|
||
The sname:VkSamplerReductionModeCreateInfoEXT structure is defined as:
|
||
|
||
include::../api/structs/VkSamplerReductionModeCreateInfoEXT.txt[]
|
||
|
||
* pname:sType is the type of this structure.
|
||
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
||
* pname:reductionMode is an enum of type elink:VkSamplerReductionModeEXT
|
||
that controls how texture filtering combines texel values.
|
||
|
||
If this structure is not present, pname:reductionMode is considered to be
|
||
ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT.
|
||
|
||
include::../validity/structs/VkSamplerReductionModeCreateInfoEXT.txt[]
|
||
--
|
||
|
||
[open,refpage='VkSamplerReductionModeEXT',desc='Specify reduction mode for texture filtering',type='enums']
|
||
--
|
||
Reduction modes are specified by elink:VkSamplerReductionModeEXT, which
|
||
takes values:
|
||
|
||
include::../api/enums/VkSamplerReductionModeEXT.txt[]
|
||
|
||
* ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT indicates that
|
||
texel values are combined by computing a weighted average of values in
|
||
the footprint, using weights as specified in
|
||
<<textures-unnormalized-to-integer,the image operations chapter>>.
|
||
* ename:VK_SAMPLER_REDUCTION_MODE_MIN_EXT indicates that texel values are
|
||
combined by taking the component-wise minimum of values in the footprint
|
||
with non-zero weights.
|
||
* ename:VK_SAMPLER_REDUCTION_MODE_MAX_EXT indicates that texel values are
|
||
combined by taking the component-wise maximum of values in the footprint
|
||
with non-zero weights.
|
||
--
|
||
|
||
endif::VK_EXT_sampler_filter_minmax[]
|
||
|
||
[open,refpage='VkFilter',desc='Specify filters used for texture lookups',type='enums']
|
||
--
|
||
Possible values of the slink:VkSamplerCreateInfo::pname:magFilter and
|
||
pname:minFilter parameters, specifying filters used for texture lookups,
|
||
are:
|
||
|
||
include::../api/enums/VkFilter.txt[]
|
||
|
||
* ename:VK_FILTER_NEAREST specifies nearest filtering.
|
||
* ename:VK_FILTER_LINEAR specifies linear filtering.
|
||
|
||
These filters are described in detail in <<textures-texel-filtering, Texel
|
||
Filtering>>.
|
||
|
||
--
|
||
|
||
[open,refpage='VkSamplerMipmapMode',desc='Specify mipmap mode used for texture lookups',type='enums']
|
||
--
|
||
|
||
Possible values of the slink:VkSamplerCreateInfo::pname:mipmapMode,
|
||
specifying the mipmap mode used for texture lookups, are:
|
||
|
||
include::../api/enums/VkSamplerMipmapMode.txt[]
|
||
|
||
* ename:VK_SAMPLER_MIPMAP_MODE_NEAREST specifies nearest filtering.
|
||
* ename:VK_SAMPLER_MIPMAP_MODE_LINEAR specifies linear filtering.
|
||
|
||
These modes are described in detail in <<textures-texel-filtering, Texel
|
||
Filtering>>.
|
||
|
||
--
|
||
|
||
[open,refpage='VkSamplerAddressMode',desc='Specify behavior of sampling with texture coordinates outside an image',type='enums']
|
||
--
|
||
|
||
Possible values of the slink:VkSamplerCreateInfo::ptext:addressMode*
|
||
parameters, specifying the behavior of sampling with coordinates outside the
|
||
range [eq]#[0,1]# for the respective [eq]#u#, [eq]#v#, or [eq]#w# coordinate
|
||
as defined in the <<textures-wrapping-operation, Wrapping Operation>>
|
||
section, are:
|
||
|
||
include::../api/enums/VkSamplerAddressMode.txt[]
|
||
|
||
* ename:VK_SAMPLER_ADDRESS_MODE_REPEAT specifies that the repeat wrap mode
|
||
will be used.
|
||
* ename:VK_SAMPLER_ADDRESS_MODE_MIRRORED_REPEAT specifies that the
|
||
mirrored repeat wrap mode will be used.
|
||
* ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE specifies that the clamp to
|
||
edge wrap mode will be used.
|
||
* ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER specifies that the clamp
|
||
to border wrap mode will be used.
|
||
* ename:VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE specifies that the
|
||
mirror clamp to edge wrap mode will be used.
|
||
This is only valid if the +VK_KHR_mirror_clamp_to_edge+ extension is
|
||
enabled.
|
||
|
||
--
|
||
|
||
[open,refpage='VkBorderColor',desc='Specify border color used for texture lookups',type='enums']
|
||
--
|
||
|
||
Possible values of slink:VkSamplerCreateInfo::pname:borderColor, specifying
|
||
the border color used for texture lookups, are:
|
||
|
||
include::../api/enums/VkBorderColor.txt[]
|
||
|
||
* ename:VK_BORDER_COLOR_FLOAT_TRANSPARENT_BLACK specifies a transparent,
|
||
floating-point format, black color.
|
||
* ename:VK_BORDER_COLOR_INT_TRANSPARENT_BLACK specifies a transparent,
|
||
integer format, black color.
|
||
* ename:VK_BORDER_COLOR_FLOAT_OPAQUE_BLACK specifies an opaque,
|
||
floating-point format, black color.
|
||
* ename:VK_BORDER_COLOR_INT_OPAQUE_BLACK specifies an opaque, integer
|
||
format, black color.
|
||
* ename:VK_BORDER_COLOR_FLOAT_OPAQUE_WHITE specifies an opaque,
|
||
floating-point format, white color.
|
||
* ename:VK_BORDER_COLOR_INT_OPAQUE_WHITE specifies an opaque, integer
|
||
format, white color.
|
||
|
||
These colors are described in detail in <<textures-texel-replacement, Texel
|
||
Replacement>>.
|
||
|
||
--
|
||
|
||
[open,refpage='vkDestroySampler',desc='Destroy a sampler object',type='protos']
|
||
--
|
||
|
||
To destroy a sampler, call:
|
||
|
||
include::../api/protos/vkDestroySampler.txt[]
|
||
|
||
* pname:device is the logical device that destroys the sampler.
|
||
* pname:sampler is the sampler to destroy.
|
||
* pname:pAllocator controls host memory allocation as described in the
|
||
<<memory-allocation, Memory Allocation>> chapter.
|
||
|
||
.Valid Usage
|
||
****
|
||
* [[VUID-vkDestroySampler-sampler-01082]]
|
||
All submitted commands that refer to pname:sampler must: have completed
|
||
execution
|
||
* [[VUID-vkDestroySampler-sampler-01083]]
|
||
If sname:VkAllocationCallbacks were provided when pname:sampler was
|
||
created, a compatible set of callbacks must: be provided here
|
||
* [[VUID-vkDestroySampler-sampler-01084]]
|
||
If no sname:VkAllocationCallbacks were provided when pname:sampler was
|
||
created, pname:pAllocator must: be `NULL`
|
||
****
|
||
|
||
include::../validity/protos/vkDestroySampler.txt[]
|
||
--
|
||
|
||
|
||
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
||
|
||
[[samplers-YCbCr-conversion]]
|
||
== Sampler Y'C~B~C~R~ conversion
|
||
|
||
[open,refpage='VkSamplerYcbcrConversionInfoKHR',desc='Structure specifying Y\'CbCr conversion to a sampler or image view',type='structs']
|
||
--
|
||
|
||
To create a sampler with Y'C~B~C~R~ conversion enabled, add a
|
||
slink:VkSamplerYcbcrConversionInfoKHR to the pname:pNext chain of the
|
||
slink:VkSamplerCreateInfo structure.
|
||
To create a sampler Y'C~B~C~R~ conversion, the
|
||
<<features-features-sampler-YCbCr-conversion,pname: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
|
||
sname:VkDescriptorSetLayoutBinding.
|
||
|
||
A slink:VkSamplerYcbcrConversionInfoKHR must: be provided for samplers to be
|
||
used with image views that access ename:VK_IMAGE_ASPECT_COLOR_BIT if the
|
||
format appears in <<features-formats-requiring-sampler-ycbcr-conversion>>.
|
||
|
||
The sname:VkSamplerYcbcrConversionInfoKHR structure is defined as:
|
||
|
||
include::../api/structs/VkSamplerYcbcrConversionInfoKHR.txt[]
|
||
|
||
* pname:sType is the type of this structure.
|
||
* pname:pNext is 'NULL' or a pointer to an extension-specific structure.
|
||
* pname:conversion is a slink:VkSamplerYcbcrConversionKHR handle created
|
||
with flink:vkCreateSamplerYcbcrConversionKHR.
|
||
|
||
include::../validity/structs/VkSamplerYcbcrConversionInfoKHR.txt[]
|
||
|
||
--
|
||
|
||
[open,refpage='VkSamplerYcbcrConversionKHR',desc='',type='handles']
|
||
--
|
||
|
||
A sampler Y'C~B~C~R~ conversion is an opaque representation of a
|
||
device-specific sampler Y'C~B~C~R~ conversion description, represented as a
|
||
sname:VkSamplerYcbcrConversionKHR handle:
|
||
|
||
include::../api/handles/VkSamplerYcbcrConversionKHR.txt[]
|
||
|
||
--
|
||
|
||
[open,refpage='vkCreateSamplerYcbcrConversionKHR',desc='Create a new Ycbcr conversion',type='protos']
|
||
--
|
||
|
||
To create a slink:VkSamplerYcbcrConversionKHR, call:
|
||
|
||
include::../api/protos/vkCreateSamplerYcbcrConversionKHR.txt[]
|
||
|
||
* pname:device is the logical device that creates the sampler Y'C~B~C~R~
|
||
conversion.
|
||
* pname:pCreateInfo is a pointer to an instance of the
|
||
slink:VkSamplerYcbcrConversionCreateInfoKHR specifying the requested
|
||
sampler Y'C~B~C~R~ conversion.
|
||
* pname:pAllocator controls host memory allocation as described in the
|
||
<<memory-allocation, Memory Allocation>> chapter.
|
||
* pname:pYcbcrConversion points to a slink:VkSamplerYcbcrConversionKHR
|
||
handle in which the resulting sampler Y'C~B~C~R~ conversion is returned.
|
||
|
||
The interpretation of the configured sampler Y'C~B~C~R~ conversion is
|
||
described in more detail in <<textures-sampler-YCbCr-conversion,the
|
||
description of sampler Y'C~B~C~R~ conversion>> in the <<textures,Image
|
||
Operations>> chapter.
|
||
|
||
.Valid Usage
|
||
****
|
||
* [[VUID-vkCreateSamplerYcbcrConversionKHR-None-01648]]
|
||
The <<features-features-sampler-YCbCr-conversion, sampler Y'C~B~C~R~
|
||
conversion feature>> must: be enabled
|
||
****
|
||
|
||
include::../validity/protos/vkCreateSamplerYcbcrConversionKHR.txt[]
|
||
|
||
--
|
||
|
||
[open,refpage='VkSamplerYcbcrConversionCreateInfoKHR',desc='Structure specifying the parameters of the newly created conversion',type='structs']
|
||
--
|
||
|
||
The sname:VkSamplerYcbcrConversionCreateInfoKHR structure is defined as:
|
||
|
||
include::../api/structs/VkSamplerYcbcrConversionCreateInfoKHR.txt[]
|
||
|
||
* pname:sType is the type of this structure.
|
||
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
||
* pname:format is the format of the image from which color information
|
||
will be retrieved.
|
||
* pname:ycbcrModel describes the color matrix for conversion between color
|
||
models.
|
||
* pname:ycbcrRange describes whether the encoded values have headroom and
|
||
foot room, or whether the encoding uses the full numerical range.
|
||
* pname:components applies a _swizzle_ based on elink:VkComponentSwizzle
|
||
enums prior to range expansion and color model conversion.
|
||
* pname:xChromaOffset describes the
|
||
<<textures-chroma-reconstruction,sample location>> associated with
|
||
downsampled chroma channels in the x dimension.
|
||
pname:xChromaOffset has no effect for formats in which chroma channels
|
||
are the same resolution as the luma channel.
|
||
* pname:yChromaOffset describes the
|
||
<<textures-chroma-reconstruction,sample location>> associated with
|
||
downsampled chroma channels in the y dimension.
|
||
pname:yChromaOffset has no effect for formats in which the chroma
|
||
channels are not downsampled vertically.
|
||
* pname:chromaFilter is the filter for chroma reconstruction.
|
||
* pname:forceExplicitReconstruction can: be used to ensure that
|
||
reconstruction is done explicitly, if supported.
|
||
|
||
.Note
|
||
[NOTE]
|
||
====
|
||
Setting pname:forceExplicitReconstruction to ename:VK_TRUE may: have a
|
||
performance penalty on implementations where explicit reconstruction is not
|
||
the default mode of operation.
|
||
====
|
||
|
||
.Valid Usage
|
||
****
|
||
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-format-01649]]
|
||
pname:format must: not be ename:VK_FORMAT_UNDEFINED
|
||
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-format-01650]]
|
||
pname:format must: support
|
||
ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT_KHR or
|
||
ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT_KHR
|
||
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-xChromaOffset-01651]]
|
||
If the format does not support
|
||
ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT_KHR,
|
||
pname:xChromaOffset and pname:yChromaOffset must: not be
|
||
ename:VK_CHROMA_LOCATION_COSITED_EVEN_KHR
|
||
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-xChromaOffset-01652]]
|
||
If the format does not support
|
||
ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT_KHR,
|
||
pname:xChromaOffset and pname:yChromaOffset must: not be
|
||
ename:VK_CHROMA_LOCATION_MIDPOINT_KHR
|
||
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-format-01653]]
|
||
pname:format must: represent unsigned normalized values (i.e. the format
|
||
must be a etext:UNORM format)
|
||
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-None-01654]]
|
||
If the format has a _422 or _420 suffix:
|
||
** pname:components.g must: be ename:VK_COMPONENT_SWIZZLE_IDENTITY
|
||
** pname:components.a must: be ename:VK_COMPONENT_SWIZZLE_IDENTITY,
|
||
ename:VK_COMPONENT_SWIZZLE_ONE, or ename:VK_COMPONENT_SWIZZLE_ZERO
|
||
** pname:components.r must: be ename:VK_COMPONENT_SWIZZLE_IDENTITY or
|
||
ename:VK_COMPONENT_SWIZZLE_B
|
||
** pname:components.b must: be ename:VK_COMPONENT_SWIZZLE_IDENTITY or
|
||
ename:VK_COMPONENT_SWIZZLE_R
|
||
** If either pname:components.r or pname:components.b is
|
||
ename:VK_COMPONENT_SWIZZLE_IDENTITY, both values must: be
|
||
ename:VK_COMPONENT_SWIZZLE_IDENTITY
|
||
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-ycbcrModel-01655]]
|
||
If pname:ycbcrModel is not
|
||
ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY_KHR, then
|
||
pname:components.r, pname:components.g, and pname:components.b must:
|
||
correspond to channels of the pname:format; that is, pname:components.r,
|
||
pname:components.g, and pname:components.b must: not be
|
||
ename:VK_COMPONENT_SWIZZLE_ZERO or ename:VK_COMPONENT_SWIZZLE_ONE, and
|
||
must: not correspond to a channel which contains zero or one as a
|
||
consequence of <<textures-conversion-to-rgba,conversion to RGBA>>
|
||
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-forceExplicitReconstruction-01656]]
|
||
If the format does not support
|
||
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT_KHR,
|
||
pname:forceExplicitReconstruction must: be FALSE
|
||
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-chromaFilter-01657]]
|
||
If the format does not support
|
||
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT_KHR,
|
||
pname:chromaFilter must: be ename:VK_FILTER_NEAREST
|
||
****
|
||
|
||
include::../validity/structs/VkSamplerYcbcrConversionCreateInfoKHR.txt[]
|
||
|
||
If pname:chromaFilter is ename: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 <<textures-sampler-YCbCr-conversion,the
|
||
description of sampler Y'C~B~C~R~ conversion>> in the <<textures,Image
|
||
Operations>> chapter.
|
||
|
||
--
|
||
|
||
[open,refpage='VkSamplerYcbcrModelConversionKHR',desc='Color model component of a color space',type='enums']
|
||
--
|
||
|
||
elink:VkSamplerYcbcrModelConversionKHR defines the conversion from the
|
||
source color model to the shader color model.
|
||
Possible values are:
|
||
|
||
include::../api/enums/VkSamplerYcbcrModelConversionKHR.txt[]
|
||
|
||
* ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY_KHR specifies that
|
||
the input values to the conversion are unmodified.
|
||
* ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY_KHR specifies no
|
||
model conversion but the inputs are range expanded as for Y'C~B~C~R~.
|
||
* ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709_KHR specifies the
|
||
color model conversion from Y'C~B~C~R~ to R'G'B' defined in BT.709 and
|
||
described in the "`BT.709 Y’C~B~C~R~ conversion`" section of the
|
||
<<data-format,Khronos Data Format Specification>>.
|
||
* ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601_KHR specifies the
|
||
color model conversion from Y'C~B~C~R~ to R'G'B' defined in BT.601 and
|
||
described in the "`BT.601 Y’C~B~C~R~ conversion`" section of the
|
||
<<data-format,Khronos Data Format Specification>>.
|
||
* ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020_KHR specifies the
|
||
color model conversion from Y'C~B~C~R~ to R'G'B' defined in BT.2020 and
|
||
described in the "`BT.2020 Y’C~B~C~R~ conversion`" section of the
|
||
<<data-format,Khronos Data Format Specification>>.
|
||
|
||
In the etext:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_*_KHR color models, for
|
||
the input to the sampler Y'C~B~C~R~ range expansion and model conversion:
|
||
|
||
* the Y (Y' luma) channel corresponds to the G channel of an RGB image.
|
||
* the CB (C~B~ or "`U`" blue color difference) channel corresponds to the
|
||
B channel of an RGB image.
|
||
* the CR (C~R~ 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
|
||
slink:VkSamplerYcbcrConversionCreateInfoKHR::pname:components).
|
||
|
||
[NOTE]
|
||
.Note
|
||
====
|
||
For example, an "YUVA" 32-bit format comprising four 8-bit channels can be
|
||
implemented as ename:VK_FORMAT_R8G8B8A8_UNORM with a component mapping:
|
||
|
||
* pname:components.a = ename:VK_COMPONENT_SWIZZLE_IDENTITY
|
||
* pname:components.r = ename:VK_COMPONENT_SWIZZLE_B
|
||
* pname:components.g = ename:VK_COMPONENT_SWIZZLE_R
|
||
* pname:components.b = ename:VK_COMPONENT_SWIZZLE_G
|
||
====
|
||
|
||
--
|
||
|
||
[open,refpage='VkSamplerYcbcrRangeKHR',desc='Range of encoded values in a color space',type='enums']
|
||
--
|
||
|
||
The elink:VkSamplerYcbcrRangeKHR enum describes whether color channels are
|
||
encoded using the full range of numerical values or whether values are
|
||
reserved for headroom and foot room.
|
||
elink:VkSamplerYcbcrRangeKHR is defined as:
|
||
|
||
include::../api/enums/VkSamplerYcbcrRangeKHR.txt[]
|
||
|
||
* ename:VK_SAMPLER_YCBCR_RANGE_ITU_FULL_KHR indicates that the full range
|
||
of the encoded values are valid and interpreted according to the ITU
|
||
"`full range`" quantization rules.
|
||
* ename:VK_SAMPLER_YCBCR_RANGE_ITU_NARROW_KHR indicates 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
|
||
<<textures-sampler-YCbCr-conversion-rangeexpand,Sampler Y'C~B~C~R~ Range
|
||
Expansion>> section of the <<textures,Image Operations>> chapter.
|
||
|
||
No range modification takes place if pname:ycbcrModel is
|
||
ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY_KHR; the
|
||
pname:ycbcrRange field of sname:VkSamplerYcbcrConversionCreateInfoKHR is
|
||
ignored in this case.
|
||
|
||
--
|
||
|
||
[open,refpage='VkChromaLocationKHR',desc='Position of downsampled chroma samples',type='enums']
|
||
--
|
||
|
||
The elink:VkChromaLocationKHR enum, which defines the location of
|
||
downsampled chroma channel samples relative to the luma samples, is defined
|
||
as:
|
||
|
||
include::../api/enums/VkChromaLocationKHR.txt[]
|
||
|
||
* ename:VK_CHROMA_LOCATION_COSITED_EVEN_KHR indicates that downsampled
|
||
chroma samples are aligned with luma samples with even coordinates.
|
||
* ename:VK_CHROMA_LOCATION_MIDPOINT_KHR indicates that downsampled chroma
|
||
samples are located half way between each even luma sample and the
|
||
nearest higher odd luma sample.
|
||
|
||
--
|
||
|
||
[open,refpage='vkDestroySamplerYcbcrConversionKHR',desc='Destroy a created Y\'CbCr conversion',type='protos']
|
||
--
|
||
|
||
To destroy a sampler Y'C~B~C~R~ conversion, call:
|
||
|
||
include::../api/protos/vkDestroySamplerYcbcrConversionKHR.txt[]
|
||
|
||
* pname:device is the logical device that destroys the Y'C~B~C~R~
|
||
conversion.
|
||
* pname:ycbcrConversion is the conversion to destroy.
|
||
* pname:pAllocator controls host memory allocation as described in the
|
||
<<memory-allocation, Memory Allocation>> chapter.
|
||
|
||
include::../validity/protos/vkDestroySamplerYcbcrConversionKHR.txt[]
|
||
|
||
--
|
||
|
||
endif::VK_KHR_sampler_ycbcr_conversion[]
|