xref: /third_party/vk-gl-cts/external/vulkan-docs/src/chapters/samplers.txt

// Copyright 2015-2021 The Khronos Group, Inc.
//
// SPDX-License-Identifier: CC-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::{generated}/api/handles/VkSampler.txt[]
--

[open,refpage='vkCreateSampler',desc='Create a new sampler object',type='protos']
--
To create a sampler object, call:

include::{generated}/api/protos/vkCreateSampler.txt[]

  * pname:device is the logical device that creates the sampler.
  * pname:pCreateInfo is a pointer to a 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 is a pointer to a slink:VkSampler handle in which the
    resulting sampler object is returned.

.Valid Usage
****
  * [[VUID-vkCreateSampler-maxSamplerAllocationCount-04110]]
    There must: be less than
    slink:VkPhysicalDeviceLimits::pname:maxSamplerAllocationCount
    slink:VkSampler objects currently created on the device
****

include::{generated}/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::{generated}/api/structs/VkSamplerCreateInfo.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:flags is a bitmask of elink:VkSamplerCreateFlagBits describing
    additional parameters of the sampler.
  * 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 U coordinates outside [eq]#[0,1)#.
  * pname:addressModeV is a elink:VkSamplerAddressMode value specifying the
    addressing mode for V coordinates outside [eq]#[0,1)#.
  * pname:addressModeW is a elink:VkSamplerAddressMode value specifying the
    addressing mode for W coordinates outside [eq]#[0,1)#.
  * [[samplers-mipLodBias]] pname: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
    <<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 used by the sampler
    when pname:anisotropyEnable is ename:VK_TRUE.
    If pname:anisotropyEnable is ename:VK_FALSE, pname:maxAnisotropy is
    ignored.
  * 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 is used to clamp the <<textures-level-of-detail-operation,
    minimum of the computed LOD value>>.
  * pname:maxLod is used to clamp the <<textures-level-of-detail-operation,
    maximum of the computed LOD value>>.
    To avoid clamping the maximum value, set pname:maxLod to the constant
    ename:VK_LOD_CLAMP_NONE.
  * 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 size in each
    dimension.
    When set to ename:VK_FALSE the range of image coordinates is zero to
    one.
+
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
<<limits-maxSamplerAllocationCount,maxSamplerAllocationCount>> member of the
slink:VkPhysicalDeviceLimits structure.

[NOTE]
.Note
====
For historical reasons, if pname:maxSamplerAllocationCount is exceeded, some
implementations may return ename: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 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
ifdef::VK_KHR_portability_subset[]
  * [[VUID-VkSamplerCreateInfo-samplerMipLodBias-04467]]
    If the `apiext:VK_KHR_portability_subset` extension is enabled, and
    slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:samplerMipLodBias
    is ename:VK_FALSE, pname:mipLodBias must: be zero
endif::VK_KHR_portability_subset[]
  * [[VUID-VkSamplerCreateInfo-maxLod-01973]]
    pname:maxLod must: be greater than or equal to pname:minLod
  * [[VUID-VkSamplerCreateInfo-anisotropyEnable-01070]]
    If the <<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_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
  * [[VUID-VkSamplerCreateInfo-minFilter-01645]]
    If <<samplers-YCbCr-conversion,sampler {YCbCr} conversion>> is enabled
    and the <<potential-format-features, potential format features>> of the
    sampler {YCbCr} conversion do not support
    ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT,
    pname:minFilter and pname:magFilter must: be equal to the sampler
    {YCbCr} conversion's pname:chromaFilter
endif::VK_VERSION_1_1,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_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
  * [[VUID-VkSamplerCreateInfo-addressModeU-01646]]
    If <<samplers-YCbCr-conversion,sampler {YCbCr} 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_VERSION_1_2,VK_EXT_sampler_filter_minmax[]
  * [[VUID-VkSamplerCreateInfo-None-01647]]
    The sampler reduction mode must: be set to
    ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE if
    <<samplers-YCbCr-conversion,sampler {YCbCr} conversion>> is enabled
endif::VK_VERSION_1_2,VK_EXT_sampler_filter_minmax[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
  * [[VUID-VkSamplerCreateInfo-addressModeU-01079]]
    If <<features-samplerMirrorClampToEdge,samplerMirrorClampToEdge>> is not
    enabled, and if the `apiext: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,VK_EXT_filter_cubic[]
  * [[VUID-VkSamplerCreateInfo-magFilter-01081]]
    If either pname:magFilter or pname:minFilter is
    ename:VK_FILTER_CUBIC_EXT, pname:anisotropyEnable must: be
    ename:VK_FALSE
endif::VK_IMG_filter_cubic,VK_EXT_filter_cubic[]
ifdef::VK_IMG_filter_cubic+VK_EXT_sampler_filter_minmax[]
ifndef::VK_EXT_filter_cubic[]
  * [[VUID-VkSamplerCreateInfo-magFilter-01422]]
    If either pname:magFilter or pname:minFilter is
    ename:VK_FILTER_CUBIC_EXT, the pname:reductionMode member of
    slink:VkSamplerReductionModeCreateInfo must: be
    ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE
endif::VK_EXT_filter_cubic[]
endif::VK_IMG_filter_cubic+VK_EXT_sampler_filter_minmax[]
ifdef::VK_VERSION_1_2,VK_EXT_sampler_filter_minmax[]
  * [[VUID-VkSamplerCreateInfo-compareEnable-01423]]
    If pname:compareEnable is ename:VK_TRUE, the pname:reductionMode member
    of slink:VkSamplerReductionModeCreateInfo must: be
    ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE
endif::VK_VERSION_1_2,VK_EXT_sampler_filter_minmax[]
ifdef::VK_EXT_fragment_density_map[]
  * [[VUID-VkSamplerCreateInfo-flags-02574]]
    If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then
    pname:minFilter and pname:magFilter must: be equal
  * [[VUID-VkSamplerCreateInfo-flags-02575]]
    If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then
    pname:mipmapMode must: be ename:VK_SAMPLER_MIPMAP_MODE_NEAREST
  * [[VUID-VkSamplerCreateInfo-flags-02576]]
    If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then
    pname:minLod and pname:maxLod must: be zero
  * [[VUID-VkSamplerCreateInfo-flags-02577]]
    If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then
    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-flags-02578]]
    If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then
    pname:anisotropyEnable must: be ename:VK_FALSE
  * [[VUID-VkSamplerCreateInfo-flags-02579]]
    If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then
    pname:compareEnable must: be ename:VK_FALSE
  * [[VUID-VkSamplerCreateInfo-flags-02580]]
    If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then
    pname:unnormalizedCoordinates must: be ename:VK_FALSE
endif::VK_EXT_fragment_density_map[]
ifdef::VK_EXT_custom_border_color[]
  * [[VUID-VkSamplerCreateInfo-borderColor-04011]]
    If pname:borderColor is one of ename:VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or
    ename:VK_BORDER_COLOR_INT_CUSTOM_EXT, then a
    slink:VkSamplerCustomBorderColorCreateInfoEXT must: be included in the
    pname:pNext chain
  * [[VUID-VkSamplerCreateInfo-customBorderColors-04085]]
    If the <<features-customBorderColors, pname:customBorderColors>> feature
    is not enabled, pname:borderColor must: not be
    ename:VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or
    ename:VK_BORDER_COLOR_INT_CUSTOM_EXT
  * [[VUID-VkSamplerCreateInfo-borderColor-04442]]
    If pname:borderColor is one of ename:VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or
    ename:VK_BORDER_COLOR_INT_CUSTOM_EXT, and
    slink:VkSamplerCustomBorderColorCreateInfoEXT::pname:format is not
    ename:VK_FORMAT_UNDEFINED,
    slink:VkSamplerCustomBorderColorCreateInfoEXT::pname:customBorderColor
    must: be within the range of values representable in pname: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
    <<limits-maxCustomBorderColorSamplers,maxCustomBorderColorSamplers>>
    member of the slink:VkPhysicalDeviceCustomBorderColorPropertiesEXT
    structure
endif::VK_EXT_custom_border_color[]
****

include::{generated}/validity/structs/VkSamplerCreateInfo.txt[]
--

[open,refpage='VK_LOD_CLAMP_NONE',desc='Maximum level of detail unclamped access sentinel',type='consts']
--
ename:VK_LOD_CLAMP_NONE is a special constant value used for
slink:VkSamplerCreateInfo::pname:maxLod to indicate that maximum LOD
clamping should not be performed.

include::{generated}/api/enums/VK_LOD_CLAMP_NONE.txt[]
--

[open,refpage='VkSamplerCreateFlagBits',desc='Bitmask specifying additional parameters of sampler',type='enums']
--
Bits which can: be set in slink:VkSamplerCreateInfo::pname:flags, specifying
additional parameters of a sampler, are:

include::{generated}/api/enums/VkSamplerCreateFlagBits.txt[]

ifdef::VK_EXT_fragment_density_map[]
  * [[samplers-subsamplesampler]] ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT
    specifies that the sampler will read from an image created with
    pname:flags containing ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT.
  * ename:VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT
    specifies that the implementation may: use approximations when
    reconstructing a full color value for texture access from a subsampled
    image.

[NOTE]
.Note
====
The approximations used when
ename:VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT is
specified are implementation defined.
Some implementations may: interpolate between fragment density levels in a
subsampled image.
In that case, this bit may: be used to decide whether the interpolation
factors are calculated per fragment or at a coarser granularity.
====
endif::VK_EXT_fragment_density_map[]
--

[open,refpage='VkSamplerCreateFlags',desc='Reserved for future use',type='flags']
--
include::{generated}/api/flags/VkSamplerCreateFlags.txt[]

tname:VkSamplerCreateFlags is a bitmask type for setting a mask of zero or
more elink:VkSamplerCreateFlagBits.
--

ifdef::VK_VERSION_1_2,VK_EXT_sampler_filter_minmax[]
[open,refpage='VkSamplerReductionModeCreateInfo',desc='Structure specifying sampler reduction mode',type='structs',alias='VkSamplerReductionModeCreateInfoEXT']
--
The sname:VkSamplerReductionModeCreateInfo structure is defined as:

include::{generated}/api/structs/VkSamplerReductionModeCreateInfo.txt[]

ifdef::VK_EXT_sampler_filter_minmax[]
or the equivalent

include::{generated}/api/structs/VkSamplerReductionModeCreateInfoEXT.txt[]
endif::VK_EXT_sampler_filter_minmax[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:reductionMode is a elink:VkSamplerReductionMode value controlling
    how texture filtering combines texel values.

If the pname:pNext chain of slink:VkSamplerCreateInfo includes a
sname:VkSamplerReductionModeCreateInfo structure, then that structure
includes a mode controlling 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.

include::{generated}/validity/structs/VkSamplerReductionModeCreateInfo.txt[]
--

[open,refpage='VkSamplerReductionMode',desc='Specify reduction mode for texture filtering',type='enums',alias='VkSamplerReductionModeEXT']
--
Reduction modes are specified by elink:VkSamplerReductionMode, which takes
values:

include::{generated}/api/enums/VkSamplerReductionMode.txt[]

ifdef::VK_EXT_sampler_filter_minmax[]
or the equivalent

include::{generated}/api/enums/VkSamplerReductionModeEXT.txt[]
endif::VK_EXT_sampler_filter_minmax[]

  * ename: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
    <<textures-unnormalized-to-integer,the image operations chapter>>.
  * ename: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.
  * ename: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.
--
endif::VK_VERSION_1_2,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::{generated}/api/enums/VkFilter.txt[]

  * ename:VK_FILTER_NEAREST specifies nearest filtering.
  * ename:VK_FILTER_LINEAR specifies linear filtering.
ifdef::VK_IMG_filter_cubic,VK_EXT_filter_cubic[]
  * ename:VK_FILTER_CUBIC_EXT specifies cubic filtering.
endif::VK_IMG_filter_cubic,VK_EXT_filter_cubic[]

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::{generated}/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::{generated}/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.
ifdef::VK_VERSION_1_2,VK_KHR_sampler_mirror_clamp_to_edge[]
  * 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
ifdef::VK_VERSION_1_2[<<features-samplerMirrorClampToEdge,samplerMirrorClampToEdge>> is enabled, or if]
    the `apiext:VK_KHR_sampler_mirror_clamp_to_edge` extension is enabled.
endif::VK_VERSION_1_2,VK_KHR_sampler_mirror_clamp_to_edge[]
--

[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::{generated}/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.
ifdef::VK_EXT_custom_border_color[]
  * ename:VK_BORDER_COLOR_FLOAT_CUSTOM_EXT indicates that a
    slink:VkSamplerCustomBorderColorCreateInfoEXT structure is included in
    the slink:VkSamplerCreateInfo::pname:pNext chain containing the color
    data in floating-point format.
  * ename:VK_BORDER_COLOR_INT_CUSTOM_EXT indicates that a
    slink:VkSamplerCustomBorderColorCreateInfoEXT structure is included in
    the slink:VkSamplerCreateInfo::pname:pNext chain containing the color
    data in integer format.
endif::VK_EXT_custom_border_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::{generated}/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::{generated}/validity/protos/vkDestroySampler.txt[]
--


ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
[[samplers-YCbCr-conversion]]
== Sampler {YCbCr} conversion

[open,refpage='VkSamplerYcbcrConversionInfo',desc='Structure specifying {YCbCr} conversion to a sampler or image view',type='structs']
--
To create a sampler with {YCbCr} conversion enabled, add a
slink:VkSamplerYcbcrConversionInfo structure to the pname:pNext chain of the
slink:VkSamplerCreateInfo structure.
To create a sampler {YCbCr} conversion, the
<<features-samplerYcbcrConversion,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:VkSamplerYcbcrConversionInfo must: be provided for samplers to be
used with image views that access ename:VK_IMAGE_ASPECT_COLOR_BIT if the
format is one of the <<formats-requiring-sampler-ycbcr-conversion, formats
that require a sampler Y'C~B~C~R~ conversion>>
ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
, or if the image view has an
<<memory-external-android-hardware-buffer-external-formats,external format>>
endif::VK_ANDROID_external_memory_android_hardware_buffer[]
.

The sname:VkSamplerYcbcrConversionInfo structure is defined as:

include::{generated}/api/structs/VkSamplerYcbcrConversionInfo.txt[]

ifdef::VK_KHR_sampler_ycbcr_conversion[]
or the equivalent

include::{generated}/api/structs/VkSamplerYcbcrConversionInfoKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:conversion is a slink:VkSamplerYcbcrConversion handle created with
    flink:vkCreateSamplerYcbcrConversion.

include::{generated}/validity/structs/VkSamplerYcbcrConversionInfo.txt[]
--

[open,refpage='VkSamplerYcbcrConversion',desc='Opaque handle to a device-specific sampler {YCbCr} conversion description',type='handles']
--
A sampler {YCbCr} conversion is an opaque representation of a
device-specific sampler {YCbCr} conversion description, represented as a
sname:VkSamplerYcbcrConversion handle:

include::{generated}/api/handles/VkSamplerYcbcrConversion.txt[]

ifdef::VK_KHR_sampler_ycbcr_conversion[]
or the equivalent

include::{generated}/api/handles/VkSamplerYcbcrConversionKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]
--

[open,refpage='vkCreateSamplerYcbcrConversion',desc='Create a new {YCbCr} conversion',type='protos']
--
To create a slink:VkSamplerYcbcrConversion, call:

ifdef::VK_VERSION_1_1[]
include::{generated}/api/protos/vkCreateSamplerYcbcrConversion.txt[]
endif::VK_VERSION_1_1[]

ifdef::VK_VERSION_1_1+VK_KHR_sampler_ycbcr_conversion[or the equivalent command]

ifdef::VK_KHR_sampler_ycbcr_conversion[]
include::{generated}/api/protos/vkCreateSamplerYcbcrConversionKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]

  * pname:device is the logical device that creates the sampler {YCbCr}
    conversion.
  * pname:pCreateInfo is a pointer to a
    slink:VkSamplerYcbcrConversionCreateInfo structure specifying the
    requested sampler {YCbCr} conversion.
  * pname:pAllocator controls host memory allocation as described in the
    <<memory-allocation, Memory Allocation>> chapter.
  * pname:pYcbcrConversion is a pointer to a slink:VkSamplerYcbcrConversion
    handle in which the resulting sampler {YCbCr} conversion is returned.

The interpretation of the configured sampler {YCbCr} conversion is described
in more detail in <<textures-sampler-YCbCr-conversion,the description of
sampler {YCbCr} conversion>> in the <<textures,Image Operations>> chapter.

.Valid Usage
****
  * [[VUID-vkCreateSamplerYcbcrConversion-None-01648]]
    The <<features-samplerYcbcrConversion, sampler {YCbCr} conversion
    feature>> must: be enabled
****

include::{generated}/validity/protos/vkCreateSamplerYcbcrConversion.txt[]
--

[open,refpage='VkSamplerYcbcrConversionCreateInfo',desc='Structure specifying the parameters of the newly created conversion',type='structs']
--
The sname:VkSamplerYcbcrConversionCreateInfo structure is defined as:

include::{generated}/api/structs/VkSamplerYcbcrConversionCreateInfo.txt[]

ifdef::VK_KHR_sampler_ycbcr_conversion[]
or the equivalent

include::{generated}/api/structs/VkSamplerYcbcrConversionCreateInfoKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    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 components in the x dimension.
    pname:xChromaOffset has no effect for formats in which chroma components
    are not downsampled horizontally.
  * pname:yChromaOffset describes the
    <<textures-chroma-reconstruction,sample location>> associated with
    downsampled chroma components in the y dimension.
    pname:yChromaOffset has no effect for formats in which the chroma
    components 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.

If pname:format supports
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT
the pname:forceExplicitReconstruction value behaves as if it was set to
ename:VK_TRUE.
====

ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
If the pname:pNext chain includes a slink:VkExternalFormatANDROID structure
with non-zero pname:externalFormat member, the sampler {YCbCr} conversion
object represents an _external format conversion_, and pname:format must: be
ename:VK_FORMAT_UNDEFINED.
Such conversions must: only be used to sample image views with a matching
<<memory-external-android-hardware-buffer-external-formats,external
format>>.
When creating an external format conversion, the value of pname:components
is ignored.
endif::VK_ANDROID_external_memory_android_hardware_buffer[]
ifndef::VK_ANDROID_external_memory_android_hardware_buffer[]
Sampler {YCbCr} conversion objects do not support _external format
conversion_ without additional extensions defining _external formats_.
endif::VK_ANDROID_external_memory_android_hardware_buffer[]

.Valid Usage
****
ifndef::VK_ANDROID_external_memory_android_hardware_buffer[]
  * [[VUID-VkSamplerYcbcrConversionCreateInfo-format-04060]]
    pname:format must: represent unsigned normalized values (i.e. the format
    must be a etext:UNORM format)
endif::VK_ANDROID_external_memory_android_hardware_buffer[]
ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
  * [[VUID-VkSamplerYcbcrConversionCreateInfo-format-01904]]
    If an external format conversion is being created, pname:format must: be
    ename:VK_FORMAT_UNDEFINED
  * [[VUID-VkSamplerYcbcrConversionCreateInfo-format-04061]]
    If an external format conversion is not being created, pname:format
    must: represent unsigned normalized values (i.e. the format must be a
    etext:UNORM format)
endif::VK_ANDROID_external_memory_android_hardware_buffer[]
  * [[VUID-VkSamplerYcbcrConversionCreateInfo-format-01650]]
    The <<potential-format-features, potential format features>> of the
    sampler {YCbCr} conversion must: support
    ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT or
    ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT
  * [[VUID-VkSamplerYcbcrConversionCreateInfo-xChromaOffset-01651]]
    If the <<potential-format-features, potential format features>> of the
    sampler {YCbCr} conversion do not support
    ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT, pname:xChromaOffset
    and pname:yChromaOffset must: not be
    ename:VK_CHROMA_LOCATION_COSITED_EVEN if the corresponding components
    are <<textures-chroma-reconstruction, downsampled>>
  * [[VUID-VkSamplerYcbcrConversionCreateInfo-xChromaOffset-01652]]
    If the <<potential-format-features, potential format features>> of the
    sampler {YCbCr} conversion do not support
    ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT, pname:xChromaOffset
    and pname:yChromaOffset must: not be ename:VK_CHROMA_LOCATION_MIDPOINT
    if the corresponding components are <<textures-chroma-reconstruction,
    downsampled>>
  * [[VUID-VkSamplerYcbcrConversionCreateInfo-components-02581]]
    If the format has a etext:_422 or etext:_420 suffix, then
    pname:components.g must: be the
    <<resources-image-views-identity-mappings,identity swizzle>>
  * [[VUID-VkSamplerYcbcrConversionCreateInfo-components-02582]]
    If the format has a etext:_422 or etext:_420 suffix, then
    pname:components.a must: be the
    <<resources-image-views-identity-mappings,identity swizzle>>,
    ename:VK_COMPONENT_SWIZZLE_ONE, or ename:VK_COMPONENT_SWIZZLE_ZERO
  * [[VUID-VkSamplerYcbcrConversionCreateInfo-components-02583]]
    If the format has a etext:_422 or etext:_420 suffix, then
    pname:components.r must: be the
    <<resources-image-views-identity-mappings,identity swizzle>> or
    ename:VK_COMPONENT_SWIZZLE_B
  * [[VUID-VkSamplerYcbcrConversionCreateInfo-components-02584]]
    If the format has a etext:_422 or etext:_420 suffix, then
    pname:components.b must: be the
    <<resources-image-views-identity-mappings,identity swizzle>> or
    ename:VK_COMPONENT_SWIZZLE_R
  * [[VUID-VkSamplerYcbcrConversionCreateInfo-components-02585]]
    If the format has a etext:_422 or etext:_420 suffix, and if either
    pname:components.r or pname:components.b is the
    <<resources-image-views-identity-mappings,identity swizzle>>, both
    values must: be the identity swizzle
  * [[VUID-VkSamplerYcbcrConversionCreateInfo-ycbcrModel-01655]]
    If pname:ycbcrModel is not
    ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY, then
    pname:components.r, pname:components.g, and pname:components.b must:
    correspond to components 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 component containing zero or one as a
    consequence of <<textures-conversion-to-rgba,conversion to RGBA>>
  * [[VUID-VkSamplerYcbcrConversionCreateInfo-ycbcrRange-02748]]
    If pname:ycbcrRange is ename:VK_SAMPLER_YCBCR_RANGE_ITU_NARROW then the
    R, G and B components obtained by applying the pname:component swizzle
    to pname:format must: each have a bit-depth greater than or equal to 8
  * [[VUID-VkSamplerYcbcrConversionCreateInfo-forceExplicitReconstruction-01656]]
    If the <<potential-format-features, potential format features>> of the
    sampler {YCbCr} conversion do not support
    ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT
    pname:forceExplicitReconstruction must: be ename:VK_FALSE
  * [[VUID-VkSamplerYcbcrConversionCreateInfo-chromaFilter-01657]]
    If the <<potential-format-features, potential format features>> of the
    sampler {YCbCr} conversion do not support
    ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT,
    pname:chromaFilter must: not be ename:VK_FILTER_LINEAR
****

include::{generated}/validity/structs/VkSamplerYcbcrConversionCreateInfo.txt[]

If pname:chromaFilter is ename: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 <<textures-sampler-YCbCr-conversion,the
description of sampler {YCbCr} conversion>> in the <<textures,Image
Operations>> chapter.
--

[open,refpage='VkSamplerYcbcrModelConversion',desc='Color model component of a color space',type='enums']
--
elink:VkSamplerYcbcrModelConversion defines the conversion from the source
color model to the shader color model.
Possible values are:

include::{generated}/api/enums/VkSamplerYcbcrModelConversion.txt[]

ifdef::VK_KHR_sampler_ycbcr_conversion[]
or the equivalent

include::{generated}/api/enums/VkSamplerYcbcrModelConversionKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]

  * ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY specifies that the
    input values to the conversion are unmodified.
  * ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY specifies no
    model conversion but the inputs are range expanded as for {YCbCr}.
  * ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709 specifies the color
    model conversion from {YCbCr} to {RGBprime} defined in BT.709 and
    described in the "`BT.709 {YCbCr} conversion`" section of the
    <<data-format,Khronos Data Format Specification>>.
  * ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601 specifies the color
    model conversion from {YCbCr} to {RGBprime} defined in BT.601 and
    described in the "`BT.601 {YCbCr} conversion`" section of the
    <<data-format,Khronos Data Format Specification>>.
  * ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020 specifies the color
    model conversion from {YCbCr} to {RGBprime} defined in BT.2020 and
    described in the "`BT.2020 {YCbCr} conversion`" section of the
    <<data-format,Khronos Data Format Specification>>.

In the etext:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_* color models, for the
input to the sampler {YCbCr} range expansion and model conversion:

  * the Y (Y{prime} luma) component corresponds to the G component of an RGB
    image.
  * the CB (C~B~ or "`U`" blue color difference) component corresponds to
    the B component of an RGB image.
  * the CR (C~R~ 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
slink:VkSamplerYcbcrConversionCreateInfo::pname:components).

[NOTE]
.Note
====
For example, an "`YUVA`" 32-bit format comprising four 8-bit components 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='VkSamplerYcbcrRange',desc='Range of encoded values in a color space',type='enums']
--
The elink: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.
elink:VkSamplerYcbcrRange is defined as:

include::{generated}/api/enums/VkSamplerYcbcrRange.txt[]

ifdef::VK_KHR_sampler_ycbcr_conversion[]
or the equivalent

include::{generated}/api/enums/VkSamplerYcbcrRangeKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]

  * ename: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.
  * ename: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
<<textures-sampler-YCbCr-conversion-rangeexpand,Sampler {YCbCr} 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; the pname:ycbcrRange
field of slink:VkSamplerYcbcrConversionCreateInfo is ignored in this case.
--

[open,refpage='VkChromaLocation',desc='Position of downsampled chroma samples',type='enums']
--
The elink:VkChromaLocation enum defines the location of downsampled chroma
component samples relative to the luma samples, and is defined as:

include::{generated}/api/enums/VkChromaLocation.txt[]

ifdef::VK_KHR_sampler_ycbcr_conversion[]
or the equivalent

include::{generated}/api/enums/VkChromaLocationKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]

  * ename:VK_CHROMA_LOCATION_COSITED_EVEN specifies that downsampled chroma
    samples are aligned with luma samples with even coordinates.
  * ename: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.
--

[open,refpage='vkDestroySamplerYcbcrConversion',desc='Destroy a created {YCbCr} conversion',type='protos']
--
To destroy a sampler {YCbCr} conversion, call:

ifdef::VK_VERSION_1_1[]
include::{generated}/api/protos/vkDestroySamplerYcbcrConversion.txt[]
endif::VK_VERSION_1_1[]

ifdef::VK_VERSION_1_1+VK_KHR_sampler_ycbcr_conversion[or the equivalent command]

ifdef::VK_KHR_sampler_ycbcr_conversion[]
include::{generated}/api/protos/vkDestroySamplerYcbcrConversionKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]

  * pname:device is the logical device that destroys the {YCbCr} conversion.
  * pname:ycbcrConversion is the conversion to destroy.
  * pname:pAllocator controls host memory allocation as described in the
    <<memory-allocation, Memory Allocation>> chapter.

include::{generated}/validity/protos/vkDestroySamplerYcbcrConversion.txt[]
--
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]

ifdef::VK_EXT_custom_border_color[]
[open,refpage='VkSamplerCustomBorderColorCreateInfoEXT',desc='Structure specifying custom border color',type='structs']
--
In addition to the predefined border color values, applications can: provide
a custom border color value by including the
sname:VkSamplerCustomBorderColorCreateInfoEXT structure in the
slink:VkSamplerCreateInfo::pname:pNext chain.

The sname:VkSamplerCustomBorderColorCreateInfoEXT structure is defined as:

include::{generated}/api/structs/VkSamplerCustomBorderColorCreateInfoEXT.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:customBorderColor is a slink:VkClearColorValue representing the
    desired custom sampler border color.
  * pname:format is a elink:VkFormat representing the format of the sampled
    image view(s).
    This field may be ename:VK_FORMAT_UNDEFINED if the
    <<features-customBorderColorWithoutFormat,customBorderColorWithoutFormat>>
    feature is enabled.

.Valid Usage
****
  * [[VUID-VkSamplerCustomBorderColorCreateInfoEXT-format-04013]]
    If provided pname:format is not ename:VK_FORMAT_UNDEFINED then the
    slink:VkSamplerCreateInfo::pname:borderColor type must: match the
    sampled type of the provided pname:format, as shown in the _SPIR-V
    Sampled Type_ column of the <<formats-numericformat>> table
  * [[VUID-VkSamplerCustomBorderColorCreateInfoEXT-format-04014]]
    If the
    <<features-customBorderColorWithoutFormat,customBorderColorWithoutFormat>>
    feature is not enabled then pname:format must: not be
    ename:VK_FORMAT_UNDEFINED
  * [[VUID-VkSamplerCustomBorderColorCreateInfoEXT-format-04015]]
    If the sampler is used to sample an image view of
    ename:VK_FORMAT_B4G4R4A4_UNORM_PACK16,
    ename:VK_FORMAT_B5G6R5_UNORM_PACK16, or
    ename:VK_FORMAT_B5G5R5A1_UNORM_PACK16 format then pname:format must: not
    be ename:VK_FORMAT_UNDEFINED
****

include::{generated}/validity/structs/VkSamplerCustomBorderColorCreateInfoEXT.txt[]
--
endif::VK_EXT_custom_border_color[]

ifdef::VK_EXT_border_color_swizzle[]
[open,refpage='VkSamplerBorderColorComponentMappingCreateInfoEXT',desc='Structure specifying the component mapping of the border color',type='structs']
--

If the sampler is created with ename:VK_BORDER_COLOR_FLOAT_OPAQUE_BLACK,
ename:VK_BORDER_COLOR_INT_OPAQUE_BLACK,
ename:VK_BORDER_COLOR_FLOAT_CUSTOM_EXT, or
ename:VK_BORDER_COLOR_INT_CUSTOM_EXT pname:borderColor, and that sampler
will be combined with an image view that does not have an
<<resources-image-views-identity-mappings,identity swizzle>>, and
slink:VkPhysicalDeviceBorderColorSwizzleFeaturesEXT::pname:borderColorSwizzleFromImage
is not enabled, then it is necessary to specify the component mapping of the
border color, by including the
sname:VkSamplerBorderColorComponentMappingCreateInfoEXT structure in the
slink:VkSamplerCreateInfo::pname:pNext chain, to get defined results.

The sname:VkSamplerBorderColorComponentMappingCreateInfoEXT structure is
defined as:

include::{generated}/api/structs/VkSamplerBorderColorComponentMappingCreateInfoEXT.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:components is a slink:VkComponentMapping structure specifying a
    remapping of the border color components.
  * pname:srgb indicates that the sampler will be combined with an image
    view that has an image format which is sRGB encoded.

The slink:VkComponentMapping pname:components member describes a remapping
from components of the border color to components of the vector returned by
shader image instructions when the border color is used.

.Valid Usage
****
  * [[VUID-VkSamplerBorderColorComponentMappingCreateInfoEXT-borderColorSwizzle-06437]]
    The <<features-borderColorSwizzle, pname:borderColorSwizzle>> feature
    must: be enabled.
****

include::{generated}/validity/structs/VkSamplerBorderColorComponentMappingCreateInfoEXT.txt[]
--
endif::VK_EXT_border_color_swizzle[]