1// Copyright 2015-2022 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[samplers]] 6= Samplers 7 8[open,refpage='VkSampler',desc='Opaque handle to a sampler object',type='handles'] 9-- 10sname:VkSampler objects represent the state of an image sampler which is 11used by the implementation to read image data and apply filtering and other 12transformations for the shader. 13 14Samplers are represented by sname:VkSampler handles: 15 16include::{generated}/api/handles/VkSampler.adoc[] 17-- 18 19[open,refpage='vkCreateSampler',desc='Create a new sampler object',type='protos'] 20-- 21To create a sampler object, call: 22 23include::{generated}/api/protos/vkCreateSampler.adoc[] 24 25 * pname:device is the logical device that creates the sampler. 26 * pname:pCreateInfo is a pointer to a slink:VkSamplerCreateInfo structure 27 specifying the state of the sampler object. 28 * pname:pAllocator controls host memory allocation as described in the 29 <<memory-allocation, Memory Allocation>> chapter. 30 * pname:pSampler is a pointer to a slink:VkSampler handle in which the 31 resulting sampler object is returned. 32 33.Valid Usage 34**** 35 * [[VUID-vkCreateSampler-maxSamplerAllocationCount-04110]] 36 There must: be less than 37 slink:VkPhysicalDeviceLimits::pname:maxSamplerAllocationCount 38 slink:VkSampler objects currently created on the device 39**** 40 41include::{generated}/validity/protos/vkCreateSampler.adoc[] 42-- 43 44[open,refpage='VkSamplerCreateInfo',desc='Structure specifying parameters of a newly created sampler',type='structs'] 45-- 46The sname:VkSamplerCreateInfo structure is defined as: 47 48include::{generated}/api/structs/VkSamplerCreateInfo.adoc[] 49 50 * pname:sType is the type of this structure. 51 * pname:pNext is `NULL` or a pointer to a structure extending this 52 structure. 53 * pname:flags is a bitmask of elink:VkSamplerCreateFlagBits describing 54 additional parameters of the sampler. 55 * pname:magFilter is a elink:VkFilter value specifying the magnification 56 filter to apply to lookups. 57 * pname:minFilter is a elink:VkFilter value specifying the minification 58 filter to apply to lookups. 59 * pname:mipmapMode is a elink:VkSamplerMipmapMode value specifying the 60 mipmap filter to apply to lookups. 61 * pname:addressModeU is a elink:VkSamplerAddressMode value specifying the 62 addressing mode for U coordinates outside [eq]#[0,1)#. 63 * pname:addressModeV is a elink:VkSamplerAddressMode value specifying the 64 addressing mode for V coordinates outside [eq]#[0,1)#. 65 * pname:addressModeW is a elink:VkSamplerAddressMode value specifying the 66 addressing mode for W coordinates outside [eq]#[0,1)#. 67 * [[samplers-mipLodBias]] pname:mipLodBias is the bias to be added to 68 mipmap LOD (level-of-detail) calculation and bias provided by image 69 sampling functions in SPIR-V, as described in the 70 <<textures-level-of-detail-operation, Level-of-Detail Operation>> 71 section. 72 * [[samplers-maxAnisotropy]] pname:anisotropyEnable is ename:VK_TRUE to 73 enable anisotropic filtering, as described in the 74 <<textures-texel-anisotropic-filtering, Texel Anisotropic Filtering>> 75 section, or ename:VK_FALSE otherwise. 76 * pname:maxAnisotropy is the anisotropy value clamp used by the sampler 77 when pname:anisotropyEnable is ename:VK_TRUE. 78 If pname:anisotropyEnable is ename:VK_FALSE, pname:maxAnisotropy is 79 ignored. 80 * pname:compareEnable is ename:VK_TRUE to enable comparison against a 81 reference value during lookups, or ename:VK_FALSE otherwise. 82 ** Note: Some implementations will default to shader state if this member 83 does not match. 84 * pname:compareOp is a elink:VkCompareOp value specifying the comparison 85 operator to apply to fetched data before filtering as described in the 86 <<textures-depth-compare-operation, Depth Compare Operation>> section. 87 * pname:minLod is used to clamp the <<textures-level-of-detail-operation, 88 minimum of the computed LOD value>>. 89 * pname:maxLod is used to clamp the <<textures-level-of-detail-operation, 90 maximum of the computed LOD value>>. 91 To avoid clamping the maximum value, set pname:maxLod to the constant 92 ename:VK_LOD_CLAMP_NONE. 93 * pname:borderColor is a elink:VkBorderColor value specifying the 94 predefined border color to use. 95 * [[samplers-unnormalizedCoordinates]] pname:unnormalizedCoordinates 96 controls whether to use unnormalized or normalized texel coordinates to 97 address texels of the image. 98 When set to ename:VK_TRUE, the range of the image coordinates used to 99 lookup the texel is in the range of zero to the image size in each 100 dimension. 101 When set to ename:VK_FALSE the range of image coordinates is zero to 102 one. 103+ 104When pname:unnormalizedCoordinates is ename:VK_TRUE, images the sampler is 105used with in the shader have the following requirements: 106+ 107 ** The pname:viewType must: be either ename:VK_IMAGE_VIEW_TYPE_1D or 108 ename:VK_IMAGE_VIEW_TYPE_2D. 109 ** The image view must: have a single layer and a single mip level. 110+ 111When pname:unnormalizedCoordinates is ename:VK_TRUE, image built-in 112functions in the shader that use the sampler have the following 113requirements: 114+ 115 ** The functions must: not use projection. 116 ** The functions must: not use offsets. 117 118[NOTE] 119.Mapping of OpenGL to Vulkan filter modes 120==== 121pname:magFilter values of ename:VK_FILTER_NEAREST and ename:VK_FILTER_LINEAR 122directly correspond to code:GL_NEAREST and code:GL_LINEAR magnification 123filters. 124pname:minFilter and pname:mipmapMode combine to correspond to the similarly 125named OpenGL minification filter of code:GL_minFilter_MIPMAP_mipmapMode 126(e.g. pname:minFilter of ename:VK_FILTER_LINEAR and pname:mipmapMode of 127ename:VK_SAMPLER_MIPMAP_MODE_NEAREST correspond to 128code:GL_LINEAR_MIPMAP_NEAREST). 129 130There are no Vulkan filter modes that directly correspond to OpenGL 131minification filters of code:GL_LINEAR or code:GL_NEAREST, but they can: be 132emulated using ename:VK_SAMPLER_MIPMAP_MODE_NEAREST, pname:minLod = 0, and 133pname:maxLod = 0.25, and using pname:minFilter = ename:VK_FILTER_LINEAR or 134pname:minFilter = ename:VK_FILTER_NEAREST, respectively. 135 136Note that using a pname:maxLod of zero would cause 137<<textures-texel-filtering,magnification>> to always be performed, and the 138pname:magFilter to always be used. 139This is valid, just not an exact match for OpenGL behavior. 140Clamping the maximum LOD to 0.25 allows the [eq]#{lambda}# value to be 141non-zero and minification to be performed, while still always rounding down 142to the base level. 143If the pname:minFilter and pname:magFilter are equal, then using a 144pname:maxLod of zero also works. 145==== 146 147The maximum number of sampler objects which can: be simultaneously created 148on a device is implementation-dependent and specified by the 149<<limits-maxSamplerAllocationCount, pname:maxSamplerAllocationCount>> member 150of the slink:VkPhysicalDeviceLimits structure. 151 152[NOTE] 153.Note 154==== 155For historical reasons, if pname:maxSamplerAllocationCount is exceeded, some 156implementations may return ename:VK_ERROR_TOO_MANY_OBJECTS. 157Exceeding this limit will result in undefined: behavior, and an application 158should not rely on the use of the returned error code in order to identify 159when the limit is reached. 160==== 161 162Since slink:VkSampler is a non-dispatchable handle type, implementations 163may: return the same handle for sampler state vectors that are identical. 164In such cases, all such objects would only count once against the 165pname:maxSamplerAllocationCount limit. 166 167.Valid Usage 168**** 169 * [[VUID-VkSamplerCreateInfo-mipLodBias-01069]] 170 The absolute value of pname:mipLodBias must: be less than or equal to 171 sname:VkPhysicalDeviceLimits::pname:maxSamplerLodBias 172ifdef::VK_KHR_portability_subset[] 173 * [[VUID-VkSamplerCreateInfo-samplerMipLodBias-04467]] 174 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 175 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:samplerMipLodBias 176 is ename:VK_FALSE, pname:mipLodBias must: be zero 177endif::VK_KHR_portability_subset[] 178 * [[VUID-VkSamplerCreateInfo-maxLod-01973]] 179 pname:maxLod must: be greater than or equal to pname:minLod 180 * [[VUID-VkSamplerCreateInfo-anisotropyEnable-01070]] 181 If the <<features-samplerAnisotropy, pname:samplerAnisotropy>> feature 182 is not enabled, pname:anisotropyEnable must: be ename:VK_FALSE 183 * [[VUID-VkSamplerCreateInfo-anisotropyEnable-01071]] 184 If pname:anisotropyEnable is ename:VK_TRUE, pname:maxAnisotropy must: be 185 between `1.0` and 186 sname:VkPhysicalDeviceLimits::pname:maxSamplerAnisotropy, inclusive 187ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 188 * [[VUID-VkSamplerCreateInfo-minFilter-01645]] 189 If <<samplers-YCbCr-conversion,sampler {YCbCr} conversion>> is enabled 190 and the <<potential-format-features, potential format features>> of the 191 sampler {YCbCr} conversion do not support 192 ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT, 193 pname:minFilter and pname:magFilter must: be equal to the sampler 194 {YCbCr} conversion's pname:chromaFilter 195endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 196 * [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01072]] 197 If pname:unnormalizedCoordinates is ename:VK_TRUE, pname:minFilter and 198 pname:magFilter must: be equal 199 * [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01073]] 200 If pname:unnormalizedCoordinates is ename:VK_TRUE, pname:mipmapMode 201 must: be ename:VK_SAMPLER_MIPMAP_MODE_NEAREST 202 * [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01074]] 203 If pname:unnormalizedCoordinates is ename:VK_TRUE, pname:minLod and 204 pname:maxLod must: be zero 205 * [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01075]] 206 If pname:unnormalizedCoordinates is ename:VK_TRUE, pname:addressModeU 207 and pname:addressModeV must: each be either 208 ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or 209 ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER 210 * [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01076]] 211 If pname:unnormalizedCoordinates is ename:VK_TRUE, 212 pname:anisotropyEnable must: be ename:VK_FALSE 213 * [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01077]] 214 If pname:unnormalizedCoordinates is ename:VK_TRUE, pname:compareEnable 215 must: be ename:VK_FALSE 216 * [[VUID-VkSamplerCreateInfo-addressModeU-01078]] 217 If any of pname:addressModeU, pname:addressModeV or pname:addressModeW 218 are ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER, pname:borderColor 219 must: be a valid elink:VkBorderColor value 220ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 221 * [[VUID-VkSamplerCreateInfo-addressModeU-01646]] 222 If <<samplers-YCbCr-conversion,sampler {YCbCr} conversion>> is enabled, 223 pname:addressModeU, pname:addressModeV, and pname:addressModeW must: be 224 ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE, pname:anisotropyEnable 225 must: be ename:VK_FALSE, and pname:unnormalizedCoordinates must: be 226 ename:VK_FALSE 227ifdef::VK_VERSION_1_2,VK_EXT_sampler_filter_minmax[] 228 * [[VUID-VkSamplerCreateInfo-None-01647]] 229 if <<samplers-YCbCr-conversion,sampler {YCbCr} conversion>> is enabled 230 and the pname:pNext chain includes a 231 slink:VkSamplerReductionModeCreateInfo structure, then the sampler 232 reduction mode must: be set to 233 ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE 234endif::VK_VERSION_1_2,VK_EXT_sampler_filter_minmax[] 235endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 236ifdef::VK_VERSION_1_2[] 237 * [[VUID-VkSamplerCreateInfo-pNext-06726]] 238 If <<features-samplerFilterMinmax, pname:samplerFilterMinmax>> is not 239 enabled and the pname:pNext chain includes a 240 slink:VkSamplerReductionModeCreateInfo structure, then the sampler 241 reduction mode must: be set to 242 ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE 243endif::VK_VERSION_1_2[] 244 * [[VUID-VkSamplerCreateInfo-addressModeU-01079]] 245 If <<features-samplerMirrorClampToEdge, pname:samplerMirrorClampToEdge>> 246 is not enabled, and if the `apiext:VK_KHR_sampler_mirror_clamp_to_edge` 247 extension is not enabled, pname:addressModeU, pname:addressModeV and 248 pname:addressModeW must: not be 249 ename:VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE 250 * [[VUID-VkSamplerCreateInfo-compareEnable-01080]] 251 If pname:compareEnable is ename:VK_TRUE, pname:compareOp must: be a 252 valid elink:VkCompareOp value 253ifdef::VK_IMG_filter_cubic,VK_EXT_filter_cubic[] 254 * [[VUID-VkSamplerCreateInfo-magFilter-01081]] 255 If either pname:magFilter or pname:minFilter is 256 ename:VK_FILTER_CUBIC_EXT, pname:anisotropyEnable must: be 257 ename:VK_FALSE 258endif::VK_IMG_filter_cubic,VK_EXT_filter_cubic[] 259ifdef::VK_IMG_filter_cubic+VK_EXT_sampler_filter_minmax[] 260ifndef::VK_EXT_filter_cubic[] 261 * [[VUID-VkSamplerCreateInfo-magFilter-01422]] 262 If either pname:magFilter or pname:minFilter is 263 ename:VK_FILTER_CUBIC_EXT, the pname:reductionMode member of 264 slink:VkSamplerReductionModeCreateInfo must: be 265 ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE 266endif::VK_EXT_filter_cubic[] 267endif::VK_IMG_filter_cubic+VK_EXT_sampler_filter_minmax[] 268ifdef::VK_VERSION_1_2,VK_EXT_sampler_filter_minmax[] 269 * [[VUID-VkSamplerCreateInfo-compareEnable-01423]] 270 If pname:compareEnable is ename:VK_TRUE, the pname:reductionMode member 271 of slink:VkSamplerReductionModeCreateInfo must: be 272 ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE 273endif::VK_VERSION_1_2,VK_EXT_sampler_filter_minmax[] 274ifdef::VK_EXT_fragment_density_map[] 275 * [[VUID-VkSamplerCreateInfo-flags-02574]] 276 If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then 277 pname:minFilter and pname:magFilter must: be equal 278 * [[VUID-VkSamplerCreateInfo-flags-02575]] 279 If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then 280 pname:mipmapMode must: be ename:VK_SAMPLER_MIPMAP_MODE_NEAREST 281 * [[VUID-VkSamplerCreateInfo-flags-02576]] 282 If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then 283 pname:minLod and pname:maxLod must: be zero 284 * [[VUID-VkSamplerCreateInfo-flags-02577]] 285 If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then 286 pname:addressModeU and pname:addressModeV must: each be either 287 ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or 288 ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER 289 * [[VUID-VkSamplerCreateInfo-flags-02578]] 290 If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then 291 pname:anisotropyEnable must: be ename:VK_FALSE 292 * [[VUID-VkSamplerCreateInfo-flags-02579]] 293 If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then 294 pname:compareEnable must: be ename:VK_FALSE 295 * [[VUID-VkSamplerCreateInfo-flags-02580]] 296 If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then 297 pname:unnormalizedCoordinates must: be ename:VK_FALSE 298endif::VK_EXT_fragment_density_map[] 299ifdef::VK_EXT_non_seamless_cube_map[] 300 * [[VUID-VkSamplerCreateInfo-nonSeamlessCubeMap-06788]] 301 If the <<features-nonSeamlessCubeMap, pname:nonSeamlessCubeMap>> feature 302 is not enabled, pname:flags must: not include 303 ename:VK_SAMPLER_CREATE_NON_SEAMLESS_CUBE_MAP_BIT_EXT 304endif::VK_EXT_non_seamless_cube_map[] 305ifdef::VK_EXT_custom_border_color[] 306 * [[VUID-VkSamplerCreateInfo-borderColor-04011]] 307 If pname:borderColor is one of ename:VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or 308 ename:VK_BORDER_COLOR_INT_CUSTOM_EXT, then a 309 slink:VkSamplerCustomBorderColorCreateInfoEXT must: be included in the 310 pname:pNext chain 311 * [[VUID-VkSamplerCreateInfo-customBorderColors-04085]] 312 If the <<features-customBorderColors, pname:customBorderColors>> feature 313 is not enabled, pname:borderColor must: not be 314 ename:VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or 315 ename:VK_BORDER_COLOR_INT_CUSTOM_EXT 316 * [[VUID-VkSamplerCreateInfo-borderColor-04442]] 317 If pname:borderColor is one of ename:VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or 318 ename:VK_BORDER_COLOR_INT_CUSTOM_EXT, and 319 slink:VkSamplerCustomBorderColorCreateInfoEXT::pname:format is not 320 ename:VK_FORMAT_UNDEFINED, 321 slink:VkSamplerCustomBorderColorCreateInfoEXT::pname:customBorderColor 322 must: be within the range of values representable in pname:format 323 * [[VUID-VkSamplerCreateInfo-None-04012]] 324 The maximum number of samplers with custom border colors which can: be 325 simultaneously created on a device is implementation-dependent and 326 specified by the <<limits-maxCustomBorderColorSamplers, 327 pname:maxCustomBorderColorSamplers>> member of the 328 slink:VkPhysicalDeviceCustomBorderColorPropertiesEXT structure 329endif::VK_EXT_custom_border_color[] 330ifdef::VK_EXT_descriptor_buffer[] 331 * [[VUID-VkSamplerCreateInfo-flags-08110]] 332 If pname:flags includes 333 ename:VK_SAMPLER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT, the 334 <<features-descriptorBufferCaptureReplay, 335 pname:descriptorBufferCaptureReplay>> feature must: be enabled 336 * [[VUID-VkSamplerCreateInfo-pNext-08111]] 337 If the pname:pNext chain includes a 338 slink:VkOpaqueCaptureDescriptorDataCreateInfoEXT structure, pname:flags 339 must: contain 340 ename:VK_SAMPLER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT 341endif::VK_EXT_descriptor_buffer[] 342ifdef::VK_QCOM_image_processing[] 343 * [[VUID-VkSamplerCreateInfo-flags-06964]] 344 If pname:flags includes 345 ename:VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then pname:minFilter 346 and pname:magFilter must: be ename:VK_FILTER_NEAREST 347 * [[VUID-VkSamplerCreateInfo-flags-06965]] 348 If pname:flags includes 349 ename:VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then pname:mipmapMode 350 must: be ename:VK_SAMPLER_MIPMAP_MODE_NEAREST 351 * [[VUID-VkSamplerCreateInfo-flags-06966]] 352 [If pname:flags includes 353 ename:VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then pname:minLod and 354 pname:maxLod must: be zero 355 * [[VUID-VkSamplerCreateInfo-flags-06967]] 356 If pname:flags includes 357 ename:VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then 358 pname:addressModeU and pname:addressModeV must: each be either 359 ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or 360 ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER 361 * [[VUID-VkSamplerCreateInfo-flags-06968]] 362 If pname:flags includes 363 ename:VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, and if 364 pname:addressModeU or pname:addressModeV is 365 ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER, then pname:borderColor 366 must: be ename:VK_BORDER_COLOR_FLOAT_TRANSPARENT_BLACK 367 * [[VUID-VkSamplerCreateInfo-flags-06969]] 368 If pname:flags includes 369 ename:VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then 370 pname:anisotropyEnable must: be ename:VK_FALSE 371 * [[VUID-VkSamplerCreateInfo-flags-06970]] 372 If pname:flags includes 373 ename:VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then 374 pname:compareEnable must: be ename:VK_FALSE 375endif::VK_QCOM_image_processing[] 376**** 377 378include::{generated}/validity/structs/VkSamplerCreateInfo.adoc[] 379-- 380 381[open,refpage='VK_LOD_CLAMP_NONE',desc='Maximum level of detail unclamped access sentinel',type='consts'] 382-- 383ename:VK_LOD_CLAMP_NONE is a special constant value used for 384slink:VkSamplerCreateInfo::pname:maxLod to indicate that maximum LOD 385clamping should not be performed. 386 387include::{generated}/api/enums/VK_LOD_CLAMP_NONE.adoc[] 388-- 389 390[open,refpage='VkSamplerCreateFlagBits',desc='Bitmask specifying additional parameters of sampler',type='enums'] 391-- 392Bits which can: be set in slink:VkSamplerCreateInfo::pname:flags, specifying 393additional parameters of a sampler, are: 394 395include::{generated}/api/enums/VkSamplerCreateFlagBits.adoc[] 396 397ifdef::VK_EXT_fragment_density_map[] 398 * [[samplers-subsamplesampler]] ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT 399 specifies that the sampler will read from an image created with 400 pname:flags containing ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT. 401 * ename:VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT 402 specifies that the implementation may: use approximations when 403 reconstructing a full color value for texture access from a subsampled 404 image. 405endif::VK_EXT_fragment_density_map[] 406ifdef::VK_EXT_non_seamless_cube_map[] 407 * ename:VK_SAMPLER_CREATE_NON_SEAMLESS_CUBE_MAP_BIT_EXT specifies that 408 <<textures-cubemapedge, cube map edge handling>> is not performed. 409endif::VK_EXT_non_seamless_cube_map[] 410ifdef::VK_QCOM_image_processing[] 411 * [[samplers-imageprocessingsampler]] 412 ename:VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM specifies that the 413 sampler will read from images using only code:OpImageWeightedSampleQCOM, 414 code:OpImageBoxFilterQCOM, code:OpImageBlockMatchSSDQCOM, or 415 code:OpImageBlockMatchSADQCOM. 416endif::VK_QCOM_image_processing[] 417 418ifdef::VK_EXT_fragment_density_map[] 419[NOTE] 420.Note 421==== 422The approximations used when 423ename:VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT is 424specified are implementation defined. 425Some implementations may: interpolate between fragment density levels in a 426subsampled image. 427In that case, this bit may: be used to decide whether the interpolation 428factors are calculated per fragment or at a coarser granularity. 429==== 430endif::VK_EXT_fragment_density_map[] 431ifdef::VK_EXT_descriptor_buffer[] 432 * ename:VK_SAMPLER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT 433 specifies that the sampler can: be used with descriptor buffers when 434 capturing and replaying (e.g. for trace capture and replay), see 435 slink:VkOpaqueCaptureDescriptorDataCreateInfoEXT for more detail. 436endif::VK_EXT_descriptor_buffer[] 437-- 438 439[open,refpage='VkSamplerCreateFlags',desc='Reserved for future use',type='flags'] 440-- 441include::{generated}/api/flags/VkSamplerCreateFlags.adoc[] 442 443tname:VkSamplerCreateFlags is a bitmask type for setting a mask of zero or 444more elink:VkSamplerCreateFlagBits. 445-- 446 447ifdef::VK_VERSION_1_2,VK_EXT_sampler_filter_minmax[] 448[open,refpage='VkSamplerReductionModeCreateInfo',desc='Structure specifying sampler reduction mode',type='structs',alias='VkSamplerReductionModeCreateInfoEXT'] 449-- 450The sname:VkSamplerReductionModeCreateInfo structure is defined as: 451 452include::{generated}/api/structs/VkSamplerReductionModeCreateInfo.adoc[] 453 454ifdef::VK_EXT_sampler_filter_minmax[] 455or the equivalent 456 457include::{generated}/api/structs/VkSamplerReductionModeCreateInfoEXT.adoc[] 458endif::VK_EXT_sampler_filter_minmax[] 459 460 * pname:sType is the type of this structure. 461 * pname:pNext is `NULL` or a pointer to a structure extending this 462 structure. 463 * pname:reductionMode is a elink:VkSamplerReductionMode value controlling 464 how texture filtering combines texel values. 465 466If the pname:pNext chain of slink:VkSamplerCreateInfo includes a 467sname:VkSamplerReductionModeCreateInfo structure, then that structure 468includes a mode controlling how texture filtering combines texel values. 469 470If this structure is not present, pname:reductionMode is considered to be 471ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE. 472 473include::{generated}/validity/structs/VkSamplerReductionModeCreateInfo.adoc[] 474-- 475 476[open,refpage='VkSamplerReductionMode',desc='Specify reduction mode for texture filtering',type='enums',alias='VkSamplerReductionModeEXT'] 477-- 478Reduction modes are specified by elink:VkSamplerReductionMode, which takes 479values: 480 481include::{generated}/api/enums/VkSamplerReductionMode.adoc[] 482 483ifdef::VK_EXT_sampler_filter_minmax[] 484or the equivalent 485 486include::{generated}/api/enums/VkSamplerReductionModeEXT.adoc[] 487endif::VK_EXT_sampler_filter_minmax[] 488 489 * ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE specifies that texel 490 values are combined by computing a weighted average of values in the 491 footprint, using weights as specified in 492 <<textures-unnormalized-to-integer,the image operations chapter>>. 493 * ename:VK_SAMPLER_REDUCTION_MODE_MIN specifies that texel values are 494 combined by taking the component-wise minimum of values in the footprint 495 with non-zero weights. 496 * ename:VK_SAMPLER_REDUCTION_MODE_MAX specifies that texel values are 497 combined by taking the component-wise maximum of values in the footprint 498 with non-zero weights. 499-- 500endif::VK_VERSION_1_2,VK_EXT_sampler_filter_minmax[] 501 502[open,refpage='VkFilter',desc='Specify filters used for texture lookups',type='enums'] 503-- 504Possible values of the slink:VkSamplerCreateInfo::pname:magFilter and 505pname:minFilter parameters, specifying filters used for texture lookups, 506are: 507 508include::{generated}/api/enums/VkFilter.adoc[] 509 510 * ename:VK_FILTER_NEAREST specifies nearest filtering. 511 * ename:VK_FILTER_LINEAR specifies linear filtering. 512ifdef::VK_IMG_filter_cubic,VK_EXT_filter_cubic[] 513 * ename:VK_FILTER_CUBIC_EXT specifies cubic filtering. 514endif::VK_IMG_filter_cubic,VK_EXT_filter_cubic[] 515 516These filters are described in detail in <<textures-texel-filtering, Texel 517Filtering>>. 518-- 519 520[open,refpage='VkSamplerMipmapMode',desc='Specify mipmap mode used for texture lookups',type='enums'] 521-- 522Possible values of the slink:VkSamplerCreateInfo::pname:mipmapMode, 523specifying the mipmap mode used for texture lookups, are: 524 525include::{generated}/api/enums/VkSamplerMipmapMode.adoc[] 526 527 * ename:VK_SAMPLER_MIPMAP_MODE_NEAREST specifies nearest filtering. 528 * ename:VK_SAMPLER_MIPMAP_MODE_LINEAR specifies linear filtering. 529 530These modes are described in detail in <<textures-texel-filtering, Texel 531Filtering>>. 532-- 533 534[open,refpage='VkSamplerAddressMode',desc='Specify behavior of sampling with texture coordinates outside an image',type='enums'] 535-- 536Possible values of the slink:VkSamplerCreateInfo::ptext:addressMode* 537parameters, specifying the behavior of sampling with coordinates outside the 538range [eq]#[0,1]# for the respective [eq]#u#, [eq]#v#, or [eq]#w# coordinate 539as defined in the <<textures-wrapping-operation, Wrapping Operation>> 540section, are: 541 542include::{generated}/api/enums/VkSamplerAddressMode.adoc[] 543 544 * ename:VK_SAMPLER_ADDRESS_MODE_REPEAT specifies that the repeat wrap mode 545 will be used. 546 * ename:VK_SAMPLER_ADDRESS_MODE_MIRRORED_REPEAT specifies that the 547 mirrored repeat wrap mode will be used. 548 * ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE specifies that the clamp to 549 edge wrap mode will be used. 550 * ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER specifies that the clamp 551 to border wrap mode will be used. 552ifdef::VK_VERSION_1_2,VK_KHR_sampler_mirror_clamp_to_edge[] 553 * ename:VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE specifies that the 554 mirror clamp to edge wrap mode will be used. 555 This is only valid if 556ifdef::VK_VERSION_1_2[<<features-samplerMirrorClampToEdge, pname:samplerMirrorClampToEdge>> is enabled, or if] 557 the `apiext:VK_KHR_sampler_mirror_clamp_to_edge` extension is enabled. 558endif::VK_VERSION_1_2,VK_KHR_sampler_mirror_clamp_to_edge[] 559-- 560 561[open,refpage='VkCompareOp',desc='Comparison operator for depth, stencil, and sampler operations',type='enums'] 562-- 563_Comparison operators_ compare a _reference_ and a _test_ value, and return 564a true ("`passed`") or false ("`failed`") value depending on the comparison 565operator chosen. 566The supported operators are: 567 568include::{generated}/api/enums/VkCompareOp.adoc[] 569 570 * ename:VK_COMPARE_OP_NEVER specifies that the comparison always evaluates 571 false. 572 * ename:VK_COMPARE_OP_LESS specifies that the comparison evaluates 573 [eq]#_reference_ < _test_#. 574 * ename:VK_COMPARE_OP_EQUAL specifies that the comparison evaluates 575 [eq]#_reference_ = _test_#. 576 * ename:VK_COMPARE_OP_LESS_OR_EQUAL specifies that the comparison 577 evaluates [eq]#_reference_ {leq} _test_#. 578 * ename:VK_COMPARE_OP_GREATER specifies that the comparison evaluates 579 [eq]#_reference_ > _test_#. 580 * ename:VK_COMPARE_OP_NOT_EQUAL specifies that the comparison evaluates 581 [eq]#_reference_ {neq} _test_#. 582 * ename:VK_COMPARE_OP_GREATER_OR_EQUAL specifies that the comparison 583 evaluates [eq]#_reference_ {geq} _test_#. 584 * ename:VK_COMPARE_OP_ALWAYS specifies that the comparison always 585 evaluates true. 586 587Comparison operators are used for: 588 589 * The <<textures-depth-compare-operation, Depth Compare Operation>> 590 operator for a sampler, specified by 591 slink:VkSamplerCreateInfo::pname:compareOp. 592 * The stencil comparison operator for the <<fragops-stencil, stencil 593 test>>, specified by 594ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 595flink:vkCmdSetStencilOp::pname:compareOp or 596endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 597 slink:VkStencilOpState::pname:compareOp. 598 * The <<fragops-depth-comparison, Depth Comparison>> operator for the 599 <<fragops-depth,depth test>>, specified by 600ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 601flink:vkCmdSetDepthCompareOp::pname:depthCompareOp or 602endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] 603 slink:VkPipelineDepthStencilStateCreateInfo::pname:depthCompareOp. 604 605Each such use describes how the _reference_ and _test_ values for that 606comparison are determined. 607-- 608 609[open,refpage='VkBorderColor',desc='Specify border color used for texture lookups',type='enums'] 610-- 611Possible values of slink:VkSamplerCreateInfo::pname:borderColor, specifying 612the border color used for texture lookups, are: 613 614include::{generated}/api/enums/VkBorderColor.adoc[] 615 616 * ename:VK_BORDER_COLOR_FLOAT_TRANSPARENT_BLACK specifies a transparent, 617 floating-point format, black color. 618 * ename:VK_BORDER_COLOR_INT_TRANSPARENT_BLACK specifies a transparent, 619 integer format, black color. 620 * ename:VK_BORDER_COLOR_FLOAT_OPAQUE_BLACK specifies an opaque, 621 floating-point format, black color. 622 * ename:VK_BORDER_COLOR_INT_OPAQUE_BLACK specifies an opaque, integer 623 format, black color. 624 * ename:VK_BORDER_COLOR_FLOAT_OPAQUE_WHITE specifies an opaque, 625 floating-point format, white color. 626 * ename:VK_BORDER_COLOR_INT_OPAQUE_WHITE specifies an opaque, integer 627 format, white color. 628ifdef::VK_EXT_custom_border_color[] 629 * ename:VK_BORDER_COLOR_FLOAT_CUSTOM_EXT indicates that a 630 slink:VkSamplerCustomBorderColorCreateInfoEXT structure is included in 631 the slink:VkSamplerCreateInfo::pname:pNext chain containing the color 632 data in floating-point format. 633 * ename:VK_BORDER_COLOR_INT_CUSTOM_EXT indicates that a 634 slink:VkSamplerCustomBorderColorCreateInfoEXT structure is included in 635 the slink:VkSamplerCreateInfo::pname:pNext chain containing the color 636 data in integer format. 637endif::VK_EXT_custom_border_color[] 638 639These colors are described in detail in <<textures-texel-replacement, Texel 640Replacement>>. 641-- 642 643[open,refpage='vkDestroySampler',desc='Destroy a sampler object',type='protos'] 644-- 645To destroy a sampler, call: 646 647include::{generated}/api/protos/vkDestroySampler.adoc[] 648 649 * pname:device is the logical device that destroys the sampler. 650 * pname:sampler is the sampler to destroy. 651 * pname:pAllocator controls host memory allocation as described in the 652 <<memory-allocation, Memory Allocation>> chapter. 653 654.Valid Usage 655**** 656 * [[VUID-vkDestroySampler-sampler-01082]] 657 All submitted commands that refer to pname:sampler must: have completed 658 execution 659 * [[VUID-vkDestroySampler-sampler-01083]] 660 If sname:VkAllocationCallbacks were provided when pname:sampler was 661 created, a compatible set of callbacks must: be provided here 662 * [[VUID-vkDestroySampler-sampler-01084]] 663 If no sname:VkAllocationCallbacks were provided when pname:sampler was 664 created, pname:pAllocator must: be `NULL` 665**** 666 667include::{generated}/validity/protos/vkDestroySampler.adoc[] 668-- 669 670 671ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 672[[samplers-YCbCr-conversion]] 673== Sampler {YCbCr} conversion 674 675[open,refpage='VkSamplerYcbcrConversionInfo',desc='Structure specifying {YCbCr} conversion to a sampler or image view',type='structs'] 676-- 677To create a sampler with {YCbCr} conversion enabled, add a 678slink:VkSamplerYcbcrConversionInfo structure to the pname:pNext chain of the 679slink:VkSamplerCreateInfo structure. 680To create a sampler {YCbCr} conversion, the 681<<features-samplerYcbcrConversion, pname:samplerYcbcrConversion>> feature 682must: be enabled. 683Conversion must: be fixed at pipeline creation time, through use of a 684combined image sampler with an immutable sampler in 685sname:VkDescriptorSetLayoutBinding. 686 687A slink:VkSamplerYcbcrConversionInfo must: be provided for samplers to be 688used with image views that access ename:VK_IMAGE_ASPECT_COLOR_BIT if the 689format is one of the <<formats-requiring-sampler-ycbcr-conversion, formats 690that require a sampler {YCbCr} conversion>> 691ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 692, or if the image view has an 693<<memory-external-android-hardware-buffer-external-formats,external format>> 694endif::VK_ANDROID_external_memory_android_hardware_buffer[] 695. 696 697The sname:VkSamplerYcbcrConversionInfo structure is defined as: 698 699include::{generated}/api/structs/VkSamplerYcbcrConversionInfo.adoc[] 700 701ifdef::VK_KHR_sampler_ycbcr_conversion[] 702or the equivalent 703 704include::{generated}/api/structs/VkSamplerYcbcrConversionInfoKHR.adoc[] 705endif::VK_KHR_sampler_ycbcr_conversion[] 706 707 * pname:sType is the type of this structure. 708 * pname:pNext is `NULL` or a pointer to a structure extending this 709 structure. 710 * pname:conversion is a slink:VkSamplerYcbcrConversion handle created with 711 flink:vkCreateSamplerYcbcrConversion. 712 713include::{generated}/validity/structs/VkSamplerYcbcrConversionInfo.adoc[] 714-- 715 716[open,refpage='VkSamplerYcbcrConversion',desc='Opaque handle to a device-specific sampler {YCbCr} conversion description',type='handles'] 717-- 718A sampler {YCbCr} conversion is an opaque representation of a 719device-specific sampler {YCbCr} conversion description, represented as a 720sname:VkSamplerYcbcrConversion handle: 721 722include::{generated}/api/handles/VkSamplerYcbcrConversion.adoc[] 723 724ifdef::VK_KHR_sampler_ycbcr_conversion[] 725or the equivalent 726 727include::{generated}/api/handles/VkSamplerYcbcrConversionKHR.adoc[] 728endif::VK_KHR_sampler_ycbcr_conversion[] 729-- 730 731[open,refpage='vkCreateSamplerYcbcrConversion',desc='Create a new {YCbCr} conversion',type='protos'] 732-- 733To create a slink:VkSamplerYcbcrConversion, call: 734 735ifdef::VK_VERSION_1_1[] 736include::{generated}/api/protos/vkCreateSamplerYcbcrConversion.adoc[] 737endif::VK_VERSION_1_1[] 738 739ifdef::VK_VERSION_1_1+VK_KHR_sampler_ycbcr_conversion[or the equivalent command] 740 741ifdef::VK_KHR_sampler_ycbcr_conversion[] 742include::{generated}/api/protos/vkCreateSamplerYcbcrConversionKHR.adoc[] 743endif::VK_KHR_sampler_ycbcr_conversion[] 744 745 * pname:device is the logical device that creates the sampler {YCbCr} 746 conversion. 747 * pname:pCreateInfo is a pointer to a 748 slink:VkSamplerYcbcrConversionCreateInfo structure specifying the 749 requested sampler {YCbCr} conversion. 750 * pname:pAllocator controls host memory allocation as described in the 751 <<memory-allocation, Memory Allocation>> chapter. 752 * pname:pYcbcrConversion is a pointer to a slink:VkSamplerYcbcrConversion 753 handle in which the resulting sampler {YCbCr} conversion is returned. 754 755The interpretation of the configured sampler {YCbCr} conversion is described 756in more detail in <<textures-sampler-YCbCr-conversion,the description of 757sampler {YCbCr} conversion>> in the <<textures,Image Operations>> chapter. 758 759.Valid Usage 760**** 761 * [[VUID-vkCreateSamplerYcbcrConversion-None-01648]] 762 The <<features-samplerYcbcrConversion, pname:samplerYcbcrConversion>> 763 feature must: be enabled 764**** 765 766include::{generated}/validity/protos/vkCreateSamplerYcbcrConversion.adoc[] 767-- 768 769[open,refpage='VkSamplerYcbcrConversionCreateInfo',desc='Structure specifying the parameters of the newly created conversion',type='structs'] 770-- 771The sname:VkSamplerYcbcrConversionCreateInfo structure is defined as: 772 773include::{generated}/api/structs/VkSamplerYcbcrConversionCreateInfo.adoc[] 774 775ifdef::VK_KHR_sampler_ycbcr_conversion[] 776or the equivalent 777 778include::{generated}/api/structs/VkSamplerYcbcrConversionCreateInfoKHR.adoc[] 779endif::VK_KHR_sampler_ycbcr_conversion[] 780 781 * pname:sType is the type of this structure. 782 * pname:pNext is `NULL` or a pointer to a structure extending this 783 structure. 784 * pname:format is the format of the image from which color information 785 will be retrieved. 786 * pname:ycbcrModel describes the color matrix for conversion between color 787 models. 788 * pname:ycbcrRange describes whether the encoded values have headroom and 789 foot room, or whether the encoding uses the full numerical range. 790 * pname:components applies a _swizzle_ based on elink:VkComponentSwizzle 791 enums prior to range expansion and color model conversion. 792 * pname:xChromaOffset describes the 793 <<textures-chroma-reconstruction,sample location>> associated with 794 downsampled chroma components in the x dimension. 795 pname:xChromaOffset has no effect for formats in which chroma components 796 are not downsampled horizontally. 797 * pname:yChromaOffset describes the 798 <<textures-chroma-reconstruction,sample location>> associated with 799 downsampled chroma components in the y dimension. 800 pname:yChromaOffset has no effect for formats in which the chroma 801 components are not downsampled vertically. 802 * pname:chromaFilter is the filter for chroma reconstruction. 803 * pname:forceExplicitReconstruction can: be used to ensure that 804 reconstruction is done explicitly, if supported. 805 806[NOTE] 807.Note 808==== 809Setting pname:forceExplicitReconstruction to ename:VK_TRUE may: have a 810performance penalty on implementations where explicit reconstruction is not 811the default mode of operation. 812 813If pname:format supports 814ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT 815the pname:forceExplicitReconstruction value behaves as if it was set to 816ename:VK_TRUE. 817==== 818 819ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 820If the pname:pNext chain includes a slink:VkExternalFormatANDROID structure 821with non-zero pname:externalFormat member, the sampler {YCbCr} conversion 822object represents an _external format conversion_, and pname:format must: be 823ename:VK_FORMAT_UNDEFINED. 824Such conversions must: only be used to sample image views with a matching 825<<memory-external-android-hardware-buffer-external-formats,external 826format>>. 827When creating an external format conversion, the value of pname:components 828is ignored. 829endif::VK_ANDROID_external_memory_android_hardware_buffer[] 830ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] 831Sampler {YCbCr} conversion objects do not support _external format 832conversion_ without additional extensions defining _external formats_. 833endif::VK_ANDROID_external_memory_android_hardware_buffer[] 834 835.Valid Usage 836**** 837ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] 838 * [[VUID-VkSamplerYcbcrConversionCreateInfo-format-04060]] 839 pname:format must: represent unsigned normalized values (i.e. the format 840 must be a etext:UNORM format) 841endif::VK_ANDROID_external_memory_android_hardware_buffer[] 842ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 843 * [[VUID-VkSamplerYcbcrConversionCreateInfo-format-01904]] 844 If an external format conversion is being created, pname:format must: be 845 ename:VK_FORMAT_UNDEFINED 846 * [[VUID-VkSamplerYcbcrConversionCreateInfo-format-04061]] 847 If an external format conversion is not being created, pname:format 848 must: represent unsigned normalized values (i.e. the format must be a 849 etext:UNORM format) 850endif::VK_ANDROID_external_memory_android_hardware_buffer[] 851 * [[VUID-VkSamplerYcbcrConversionCreateInfo-format-01650]] 852 The <<potential-format-features, potential format features>> of the 853 sampler {YCbCr} conversion must: support 854 ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT or 855 ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT 856 * [[VUID-VkSamplerYcbcrConversionCreateInfo-xChromaOffset-01651]] 857 If the <<potential-format-features, potential format features>> of the 858 sampler {YCbCr} conversion do not support 859 ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT, pname:xChromaOffset 860 and pname:yChromaOffset must: not be 861 ename:VK_CHROMA_LOCATION_COSITED_EVEN if the corresponding components 862 are <<textures-chroma-reconstruction, downsampled>> 863 * [[VUID-VkSamplerYcbcrConversionCreateInfo-xChromaOffset-01652]] 864 If the <<potential-format-features, potential format features>> of the 865 sampler {YCbCr} conversion do not support 866 ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT, pname:xChromaOffset 867 and pname:yChromaOffset must: not be ename:VK_CHROMA_LOCATION_MIDPOINT 868 if the corresponding components are <<textures-chroma-reconstruction, 869 downsampled>> 870 * [[VUID-VkSamplerYcbcrConversionCreateInfo-components-02581]] 871 If the format has a etext:_422 or etext:_420 suffix, then 872 pname:components.g must: be the 873 <<resources-image-views-identity-mappings,identity swizzle>> 874 * [[VUID-VkSamplerYcbcrConversionCreateInfo-components-02582]] 875 If the format has a etext:_422 or etext:_420 suffix, then 876 pname:components.a must: be the 877 <<resources-image-views-identity-mappings,identity swizzle>>, 878 ename:VK_COMPONENT_SWIZZLE_ONE, or ename:VK_COMPONENT_SWIZZLE_ZERO 879 * [[VUID-VkSamplerYcbcrConversionCreateInfo-components-02583]] 880 If the format has a etext:_422 or etext:_420 suffix, then 881 pname:components.r must: be the 882 <<resources-image-views-identity-mappings,identity swizzle>> or 883 ename:VK_COMPONENT_SWIZZLE_B 884 * [[VUID-VkSamplerYcbcrConversionCreateInfo-components-02584]] 885 If the format has a etext:_422 or etext:_420 suffix, then 886 pname:components.b must: be the 887 <<resources-image-views-identity-mappings,identity swizzle>> or 888 ename:VK_COMPONENT_SWIZZLE_R 889 * [[VUID-VkSamplerYcbcrConversionCreateInfo-components-02585]] 890 If the format has a etext:_422 or etext:_420 suffix, and if either 891 pname:components.r or pname:components.b is the 892 <<resources-image-views-identity-mappings,identity swizzle>>, both 893 values must: be the identity swizzle 894 * [[VUID-VkSamplerYcbcrConversionCreateInfo-ycbcrModel-01655]] 895 If pname:ycbcrModel is not 896 ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY, then 897 pname:components.r, pname:components.g, and pname:components.b must: 898 correspond to components of the pname:format; that is, 899 pname:components.r, pname:components.g, and pname:components.b must: not 900 be ename:VK_COMPONENT_SWIZZLE_ZERO or ename:VK_COMPONENT_SWIZZLE_ONE, 901 and must: not correspond to a component containing zero or one as a 902 consequence of <<textures-conversion-to-rgba,conversion to RGBA>> 903 * [[VUID-VkSamplerYcbcrConversionCreateInfo-ycbcrRange-02748]] 904 If pname:ycbcrRange is ename:VK_SAMPLER_YCBCR_RANGE_ITU_NARROW then the 905 R, G and B components obtained by applying the pname:component swizzle 906 to pname:format must: each have a bit-depth greater than or equal to 8 907 * [[VUID-VkSamplerYcbcrConversionCreateInfo-forceExplicitReconstruction-01656]] 908 If the <<potential-format-features, potential format features>> of the 909 sampler {YCbCr} conversion do not support 910 ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT 911 pname:forceExplicitReconstruction must: be ename:VK_FALSE 912 * [[VUID-VkSamplerYcbcrConversionCreateInfo-chromaFilter-01657]] 913 If the <<potential-format-features, potential format features>> of the 914 sampler {YCbCr} conversion do not support 915 ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT, 916 pname:chromaFilter must: not be ename:VK_FILTER_LINEAR 917**** 918 919include::{generated}/validity/structs/VkSamplerYcbcrConversionCreateInfo.adoc[] 920 921If pname:chromaFilter is ename:VK_FILTER_NEAREST, chroma samples are 922reconstructed to luma component resolution using nearest-neighbour sampling. 923Otherwise, chroma samples are reconstructed using interpolation. 924More details can be found in <<textures-sampler-YCbCr-conversion,the 925description of sampler {YCbCr} conversion>> in the <<textures,Image 926Operations>> chapter. 927-- 928 929[open,refpage='VkSamplerYcbcrModelConversion',desc='Color model component of a color space',type='enums'] 930-- 931elink:VkSamplerYcbcrModelConversion defines the conversion from the source 932color model to the shader color model. 933Possible values are: 934 935include::{generated}/api/enums/VkSamplerYcbcrModelConversion.adoc[] 936 937ifdef::VK_KHR_sampler_ycbcr_conversion[] 938or the equivalent 939 940include::{generated}/api/enums/VkSamplerYcbcrModelConversionKHR.adoc[] 941endif::VK_KHR_sampler_ycbcr_conversion[] 942 943 * ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY specifies that the 944 input values to the conversion are unmodified. 945 * ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY specifies no 946 model conversion but the inputs are range expanded as for {YCbCr}. 947 * ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709 specifies the color 948 model conversion from {YCbCr} to {RGBprime} defined in BT.709 and 949 described in the "`BT.709 {YCbCr} conversion`" section of the 950 <<data-format,Khronos Data Format Specification>>. 951 * ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601 specifies the color 952 model conversion from {YCbCr} to {RGBprime} defined in BT.601 and 953 described in the "`BT.601 {YCbCr} conversion`" section of the 954 <<data-format,Khronos Data Format Specification>>. 955 * ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020 specifies the color 956 model conversion from {YCbCr} to {RGBprime} defined in BT.2020 and 957 described in the "`BT.2020 {YCbCr} conversion`" section of the 958 <<data-format,Khronos Data Format Specification>>. 959 960In the etext:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_* color models, for the 961input to the sampler {YCbCr} range expansion and model conversion: 962 963 * the Y (Y{prime} luma) component corresponds to the G component of an RGB 964 image. 965 * the CB (C~B~ or "`U`" blue color difference) component corresponds to 966 the B component of an RGB image. 967 * the CR (C~R~ or "`V`" red color difference) component corresponds to the 968 R component of an RGB image. 969 * the alpha component, if present, is not modified by color model 970 conversion. 971 972These rules reflect the mapping of components after the component swizzle 973operation (controlled by 974slink:VkSamplerYcbcrConversionCreateInfo::pname:components). 975 976[NOTE] 977.Note 978==== 979For example, an "`YUVA`" 32-bit format comprising four 8-bit components can 980be implemented as ename:VK_FORMAT_R8G8B8A8_UNORM with a component mapping: 981 982 * pname:components.a = ename:VK_COMPONENT_SWIZZLE_IDENTITY 983 * pname:components.r = ename:VK_COMPONENT_SWIZZLE_B 984 * pname:components.g = ename:VK_COMPONENT_SWIZZLE_R 985 * pname:components.b = ename:VK_COMPONENT_SWIZZLE_G 986==== 987-- 988 989[open,refpage='VkSamplerYcbcrRange',desc='Range of encoded values in a color space',type='enums'] 990-- 991The elink:VkSamplerYcbcrRange enum describes whether color components are 992encoded using the full range of numerical values or whether values are 993reserved for headroom and foot room. 994elink:VkSamplerYcbcrRange is defined as: 995 996include::{generated}/api/enums/VkSamplerYcbcrRange.adoc[] 997 998ifdef::VK_KHR_sampler_ycbcr_conversion[] 999or the equivalent 1000 1001include::{generated}/api/enums/VkSamplerYcbcrRangeKHR.adoc[] 1002endif::VK_KHR_sampler_ycbcr_conversion[] 1003 1004 * ename:VK_SAMPLER_YCBCR_RANGE_ITU_FULL specifies that the full range of 1005 the encoded values are valid and interpreted according to the ITU "`full 1006 range`" quantization rules. 1007 * ename:VK_SAMPLER_YCBCR_RANGE_ITU_NARROW specifies that headroom and foot 1008 room are reserved in the numerical range of encoded values, and the 1009 remaining values are expanded according to the ITU "`narrow range`" 1010 quantization rules. 1011 1012The formulae for these conversions is described in the 1013<<textures-sampler-YCbCr-conversion-rangeexpand,Sampler {YCbCr} Range 1014Expansion>> section of the <<textures,Image Operations>> chapter. 1015 1016No range modification takes place if pname:ycbcrModel is 1017ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY; the pname:ycbcrRange 1018field of slink:VkSamplerYcbcrConversionCreateInfo is ignored in this case. 1019-- 1020 1021[open,refpage='VkChromaLocation',desc='Position of downsampled chroma samples',type='enums'] 1022-- 1023The elink:VkChromaLocation enum defines the location of downsampled chroma 1024component samples relative to the luma samples, and is defined as: 1025 1026include::{generated}/api/enums/VkChromaLocation.adoc[] 1027 1028ifdef::VK_KHR_sampler_ycbcr_conversion[] 1029or the equivalent 1030 1031include::{generated}/api/enums/VkChromaLocationKHR.adoc[] 1032endif::VK_KHR_sampler_ycbcr_conversion[] 1033 1034 * ename:VK_CHROMA_LOCATION_COSITED_EVEN specifies that downsampled chroma 1035 samples are aligned with luma samples with even coordinates. 1036 * ename:VK_CHROMA_LOCATION_MIDPOINT specifies that downsampled chroma 1037 samples are located half way between each even luma sample and the 1038 nearest higher odd luma sample. 1039-- 1040 1041[open,refpage='vkDestroySamplerYcbcrConversion',desc='Destroy a created {YCbCr} conversion',type='protos'] 1042-- 1043To destroy a sampler {YCbCr} conversion, call: 1044 1045ifdef::VK_VERSION_1_1[] 1046include::{generated}/api/protos/vkDestroySamplerYcbcrConversion.adoc[] 1047endif::VK_VERSION_1_1[] 1048 1049ifdef::VK_VERSION_1_1+VK_KHR_sampler_ycbcr_conversion[or the equivalent command] 1050 1051ifdef::VK_KHR_sampler_ycbcr_conversion[] 1052include::{generated}/api/protos/vkDestroySamplerYcbcrConversionKHR.adoc[] 1053endif::VK_KHR_sampler_ycbcr_conversion[] 1054 1055 * pname:device is the logical device that destroys the {YCbCr} conversion. 1056 * pname:ycbcrConversion is the conversion to destroy. 1057 * pname:pAllocator controls host memory allocation as described in the 1058 <<memory-allocation, Memory Allocation>> chapter. 1059 1060include::{generated}/validity/protos/vkDestroySamplerYcbcrConversion.adoc[] 1061-- 1062endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 1063 1064ifdef::VK_EXT_custom_border_color[] 1065[open,refpage='VkSamplerCustomBorderColorCreateInfoEXT',desc='Structure specifying custom border color',type='structs'] 1066-- 1067In addition to the predefined border color values, applications can: provide 1068a custom border color value by including the 1069sname:VkSamplerCustomBorderColorCreateInfoEXT structure in the 1070slink:VkSamplerCreateInfo::pname:pNext chain. 1071 1072The sname:VkSamplerCustomBorderColorCreateInfoEXT structure is defined as: 1073 1074include::{generated}/api/structs/VkSamplerCustomBorderColorCreateInfoEXT.adoc[] 1075 1076 * pname:sType is the type of this structure. 1077 * pname:pNext is `NULL` or a pointer to a structure extending this 1078 structure. 1079 * pname:customBorderColor is a slink:VkClearColorValue representing the 1080 desired custom sampler border color. 1081 * pname:format is a elink:VkFormat representing the format of the sampled 1082 image view(s). 1083 This field may be ename:VK_FORMAT_UNDEFINED if the 1084 <<features-customBorderColorWithoutFormat, 1085 pname:customBorderColorWithoutFormat>> feature is enabled. 1086 1087[NOTE] 1088.Note 1089==== 1090If pname:format is a combined depth stencil format, the aspect is determined 1091by the value of slink:VkSamplerCreateInfo::pname:pname:borderColor. 1092If slink:VkSamplerCreateInfo::pname:pname:borderColor is 1093ename:VK_BORDER_COLOR_FLOAT_CUSTOM_EXT, the depth aspect is considered. 1094If slink:VkSamplerCreateInfo::pname:pname:borderColor is 1095ename:VK_BORDER_COLOR_INT_CUSTOM_EXT, the stencil aspect is considered. 1096==== 1097 1098.Valid Usage 1099**** 1100 * [[VUID-VkSamplerCustomBorderColorCreateInfoEXT-format-07605]] 1101 If pname:format is not ename:VK_FORMAT_UNDEFINED and pname:format is not 1102 a combined depth stencil format then the 1103 slink:VkSamplerCreateInfo::pname:borderColor type must: match the 1104 sampled type of the provided pname:format, as shown in the _SPIR-V 1105 Sampled Type_ column of the <<formats-numericformat>> table 1106 * [[VUID-VkSamplerCustomBorderColorCreateInfoEXT-format-04014]] 1107 If the <<features-customBorderColorWithoutFormat, 1108 pname:customBorderColorWithoutFormat>> feature is not enabled then 1109 pname:format must: not be ename:VK_FORMAT_UNDEFINED 1110 * [[VUID-VkSamplerCustomBorderColorCreateInfoEXT-format-04015]] 1111 If the sampler is used to sample an image view of 1112 ename:VK_FORMAT_B4G4R4A4_UNORM_PACK16, 1113 ename:VK_FORMAT_B5G6R5_UNORM_PACK16, or 1114 ename:VK_FORMAT_B5G5R5A1_UNORM_PACK16 format then pname:format must: not 1115 be ename:VK_FORMAT_UNDEFINED 1116**** 1117 1118include::{generated}/validity/structs/VkSamplerCustomBorderColorCreateInfoEXT.adoc[] 1119-- 1120endif::VK_EXT_custom_border_color[] 1121 1122ifdef::VK_EXT_border_color_swizzle[] 1123[open,refpage='VkSamplerBorderColorComponentMappingCreateInfoEXT',desc='Structure specifying the component mapping of the border color',type='structs'] 1124-- 1125If the sampler is created with ename:VK_BORDER_COLOR_FLOAT_OPAQUE_BLACK, 1126ename:VK_BORDER_COLOR_INT_OPAQUE_BLACK, 1127ename:VK_BORDER_COLOR_FLOAT_CUSTOM_EXT, or 1128ename:VK_BORDER_COLOR_INT_CUSTOM_EXT pname:borderColor, and that sampler 1129will be combined with an image view that does not have an 1130<<resources-image-views-identity-mappings,identity swizzle>>, and 1131slink:VkPhysicalDeviceBorderColorSwizzleFeaturesEXT::pname:borderColorSwizzleFromImage 1132is not enabled, then it is necessary to specify the component mapping of the 1133border color, by including the 1134sname:VkSamplerBorderColorComponentMappingCreateInfoEXT structure in the 1135slink:VkSamplerCreateInfo::pname:pNext chain, to get defined results. 1136 1137The sname:VkSamplerBorderColorComponentMappingCreateInfoEXT structure is 1138defined as: 1139 1140include::{generated}/api/structs/VkSamplerBorderColorComponentMappingCreateInfoEXT.adoc[] 1141 1142 * pname:sType is the type of this structure. 1143 * pname:pNext is `NULL` or a pointer to a structure extending this 1144 structure. 1145 * pname:components is a slink:VkComponentMapping structure specifying a 1146 remapping of the border color components. 1147 * pname:srgb indicates that the sampler will be combined with an image 1148 view that has an image format which is sRGB encoded. 1149 1150The slink:VkComponentMapping pname:components member describes a remapping 1151from components of the border color to components of the vector returned by 1152shader image instructions when the border color is used. 1153 1154.Valid Usage 1155**** 1156 * [[VUID-VkSamplerBorderColorComponentMappingCreateInfoEXT-borderColorSwizzle-06437]] 1157 The <<features-borderColorSwizzle, pname:borderColorSwizzle>> feature 1158 must: be enabled 1159**** 1160 1161include::{generated}/validity/structs/VkSamplerBorderColorComponentMappingCreateInfoEXT.adoc[] 1162-- 1163endif::VK_EXT_border_color_swizzle[] 1164