1// Copyright 2015-2021 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.txt[] 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.txt[] 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.txt[] 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.txt[] 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 function 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,maxSamplerAllocationCount>> member of the 150slink: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,anisotropic sampling>> feature is 182 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 The sampler reduction mode must: be set to 230 ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE if 231 <<samplers-YCbCr-conversion,sampler {YCbCr} conversion>> is enabled 232endif::VK_VERSION_1_2,VK_EXT_sampler_filter_minmax[] 233endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 234 * [[VUID-VkSamplerCreateInfo-addressModeU-01079]] 235 If <<features-samplerMirrorClampToEdge,samplerMirrorClampToEdge>> is not 236 enabled, and if the `apiext:VK_KHR_sampler_mirror_clamp_to_edge` 237 extension is not enabled, pname:addressModeU, pname:addressModeV and 238 pname:addressModeW must: not be 239 ename:VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE 240 * [[VUID-VkSamplerCreateInfo-compareEnable-01080]] 241 If pname:compareEnable is ename:VK_TRUE, pname:compareOp must: be a 242 valid elink:VkCompareOp value 243ifdef::VK_IMG_filter_cubic,VK_EXT_filter_cubic[] 244 * [[VUID-VkSamplerCreateInfo-magFilter-01081]] 245 If either pname:magFilter or pname:minFilter is 246 ename:VK_FILTER_CUBIC_EXT, pname:anisotropyEnable must: be 247 ename:VK_FALSE 248endif::VK_IMG_filter_cubic,VK_EXT_filter_cubic[] 249ifdef::VK_IMG_filter_cubic+VK_EXT_sampler_filter_minmax[] 250ifndef::VK_EXT_filter_cubic[] 251 * [[VUID-VkSamplerCreateInfo-magFilter-01422]] 252 If either pname:magFilter or pname:minFilter is 253 ename:VK_FILTER_CUBIC_EXT, the pname:reductionMode member of 254 slink:VkSamplerReductionModeCreateInfo must: be 255 ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE 256endif::VK_EXT_filter_cubic[] 257endif::VK_IMG_filter_cubic+VK_EXT_sampler_filter_minmax[] 258ifdef::VK_VERSION_1_2,VK_EXT_sampler_filter_minmax[] 259 * [[VUID-VkSamplerCreateInfo-compareEnable-01423]] 260 If pname:compareEnable is ename:VK_TRUE, the pname:reductionMode member 261 of slink:VkSamplerReductionModeCreateInfo must: be 262 ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE 263endif::VK_VERSION_1_2,VK_EXT_sampler_filter_minmax[] 264ifdef::VK_EXT_fragment_density_map[] 265 * [[VUID-VkSamplerCreateInfo-flags-02574]] 266 If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then 267 pname:minFilter and pname:magFilter must: be equal 268 * [[VUID-VkSamplerCreateInfo-flags-02575]] 269 If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then 270 pname:mipmapMode must: be ename:VK_SAMPLER_MIPMAP_MODE_NEAREST 271 * [[VUID-VkSamplerCreateInfo-flags-02576]] 272 If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then 273 pname:minLod and pname:maxLod must: be zero 274 * [[VUID-VkSamplerCreateInfo-flags-02577]] 275 If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then 276 pname:addressModeU and pname:addressModeV must: each be either 277 ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or 278 ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER 279 * [[VUID-VkSamplerCreateInfo-flags-02578]] 280 If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then 281 pname:anisotropyEnable must: be ename:VK_FALSE 282 * [[VUID-VkSamplerCreateInfo-flags-02579]] 283 If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then 284 pname:compareEnable must: be ename:VK_FALSE 285 * [[VUID-VkSamplerCreateInfo-flags-02580]] 286 If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then 287 pname:unnormalizedCoordinates must: be ename:VK_FALSE 288endif::VK_EXT_fragment_density_map[] 289ifdef::VK_EXT_custom_border_color[] 290 * [[VUID-VkSamplerCreateInfo-borderColor-04011]] 291 If pname:borderColor is one of ename:VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or 292 ename:VK_BORDER_COLOR_INT_CUSTOM_EXT, then a 293 slink:VkSamplerCustomBorderColorCreateInfoEXT must: be included in the 294 pname:pNext chain 295 * [[VUID-VkSamplerCreateInfo-customBorderColors-04085]] 296 If the <<features-customBorderColors, pname:customBorderColors>> feature 297 is not enabled, pname:borderColor must: not be 298 ename:VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or 299 ename:VK_BORDER_COLOR_INT_CUSTOM_EXT 300 * [[VUID-VkSamplerCreateInfo-borderColor-04442]] 301 If pname:borderColor is one of ename:VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or 302 ename:VK_BORDER_COLOR_INT_CUSTOM_EXT, and 303 slink:VkSamplerCustomBorderColorCreateInfoEXT::pname:format is not 304 ename:VK_FORMAT_UNDEFINED, 305 slink:VkSamplerCustomBorderColorCreateInfoEXT::pname:customBorderColor 306 must: be within the range of values representable in pname:format 307 * [[VUID-VkSamplerCreateInfo-None-04012]] 308 The maximum number of samplers with custom border colors which can: be 309 simultaneously created on a device is implementation-dependent and 310 specified by the 311 <<limits-maxCustomBorderColorSamplers,maxCustomBorderColorSamplers>> 312 member of the slink:VkPhysicalDeviceCustomBorderColorPropertiesEXT 313 structure 314endif::VK_EXT_custom_border_color[] 315**** 316 317include::{generated}/validity/structs/VkSamplerCreateInfo.txt[] 318-- 319 320[open,refpage='VK_LOD_CLAMP_NONE',desc='Maximum level of detail unclamped access sentinel',type='consts'] 321-- 322ename:VK_LOD_CLAMP_NONE is a special constant value used for 323slink:VkSamplerCreateInfo::pname:maxLod to indicate that maximum LOD 324clamping should not be performed. 325 326include::{generated}/api/enums/VK_LOD_CLAMP_NONE.txt[] 327-- 328 329[open,refpage='VkSamplerCreateFlagBits',desc='Bitmask specifying additional parameters of sampler',type='enums'] 330-- 331Bits which can: be set in slink:VkSamplerCreateInfo::pname:flags, specifying 332additional parameters of a sampler, are: 333 334include::{generated}/api/enums/VkSamplerCreateFlagBits.txt[] 335 336ifdef::VK_EXT_fragment_density_map[] 337 * [[samplers-subsamplesampler]] ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT 338 specifies that the sampler will read from an image created with 339 pname:flags containing ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT. 340 * ename:VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT 341 specifies that the implementation may: use approximations when 342 reconstructing a full color value for texture access from a subsampled 343 image. 344 345[NOTE] 346.Note 347==== 348The approximations used when 349ename:VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT is 350specified are implementation defined. 351Some implementations may: interpolate between fragment density levels in a 352subsampled image. 353In that case, this bit may: be used to decide whether the interpolation 354factors are calculated per fragment or at a coarser granularity. 355==== 356endif::VK_EXT_fragment_density_map[] 357-- 358 359[open,refpage='VkSamplerCreateFlags',desc='Reserved for future use',type='flags'] 360-- 361include::{generated}/api/flags/VkSamplerCreateFlags.txt[] 362 363tname:VkSamplerCreateFlags is a bitmask type for setting a mask of zero or 364more elink:VkSamplerCreateFlagBits. 365-- 366 367ifdef::VK_VERSION_1_2,VK_EXT_sampler_filter_minmax[] 368[open,refpage='VkSamplerReductionModeCreateInfo',desc='Structure specifying sampler reduction mode',type='structs',alias='VkSamplerReductionModeCreateInfoEXT'] 369-- 370The sname:VkSamplerReductionModeCreateInfo structure is defined as: 371 372include::{generated}/api/structs/VkSamplerReductionModeCreateInfo.txt[] 373 374ifdef::VK_EXT_sampler_filter_minmax[] 375or the equivalent 376 377include::{generated}/api/structs/VkSamplerReductionModeCreateInfoEXT.txt[] 378endif::VK_EXT_sampler_filter_minmax[] 379 380 * pname:sType is the type of this structure. 381 * pname:pNext is `NULL` or a pointer to a structure extending this 382 structure. 383 * pname:reductionMode is a elink:VkSamplerReductionMode value controlling 384 how texture filtering combines texel values. 385 386If the pname:pNext chain of slink:VkSamplerCreateInfo includes a 387sname:VkSamplerReductionModeCreateInfo structure, then that structure 388includes a mode controlling how texture filtering combines texel values. 389 390If this structure is not present, pname:reductionMode is considered to be 391ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE. 392 393include::{generated}/validity/structs/VkSamplerReductionModeCreateInfo.txt[] 394-- 395 396[open,refpage='VkSamplerReductionMode',desc='Specify reduction mode for texture filtering',type='enums',alias='VkSamplerReductionModeEXT'] 397-- 398Reduction modes are specified by elink:VkSamplerReductionMode, which takes 399values: 400 401include::{generated}/api/enums/VkSamplerReductionMode.txt[] 402 403ifdef::VK_EXT_sampler_filter_minmax[] 404or the equivalent 405 406include::{generated}/api/enums/VkSamplerReductionModeEXT.txt[] 407endif::VK_EXT_sampler_filter_minmax[] 408 409 * ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE specifies that texel 410 values are combined by computing a weighted average of values in the 411 footprint, using weights as specified in 412 <<textures-unnormalized-to-integer,the image operations chapter>>. 413 * ename:VK_SAMPLER_REDUCTION_MODE_MIN specifies that texel values are 414 combined by taking the component-wise minimum of values in the footprint 415 with non-zero weights. 416 * ename:VK_SAMPLER_REDUCTION_MODE_MAX specifies that texel values are 417 combined by taking the component-wise maximum of values in the footprint 418 with non-zero weights. 419-- 420endif::VK_VERSION_1_2,VK_EXT_sampler_filter_minmax[] 421 422[open,refpage='VkFilter',desc='Specify filters used for texture lookups',type='enums'] 423-- 424Possible values of the slink:VkSamplerCreateInfo::pname:magFilter and 425pname:minFilter parameters, specifying filters used for texture lookups, 426are: 427 428include::{generated}/api/enums/VkFilter.txt[] 429 430 * ename:VK_FILTER_NEAREST specifies nearest filtering. 431 * ename:VK_FILTER_LINEAR specifies linear filtering. 432ifdef::VK_IMG_filter_cubic,VK_EXT_filter_cubic[] 433 * ename:VK_FILTER_CUBIC_EXT specifies cubic filtering. 434endif::VK_IMG_filter_cubic,VK_EXT_filter_cubic[] 435 436These filters are described in detail in <<textures-texel-filtering, Texel 437Filtering>>. 438-- 439 440[open,refpage='VkSamplerMipmapMode',desc='Specify mipmap mode used for texture lookups',type='enums'] 441-- 442Possible values of the slink:VkSamplerCreateInfo::pname:mipmapMode, 443specifying the mipmap mode used for texture lookups, are: 444 445include::{generated}/api/enums/VkSamplerMipmapMode.txt[] 446 447 * ename:VK_SAMPLER_MIPMAP_MODE_NEAREST specifies nearest filtering. 448 * ename:VK_SAMPLER_MIPMAP_MODE_LINEAR specifies linear filtering. 449 450These modes are described in detail in <<textures-texel-filtering, Texel 451Filtering>>. 452-- 453 454[open,refpage='VkSamplerAddressMode',desc='Specify behavior of sampling with texture coordinates outside an image',type='enums'] 455-- 456Possible values of the slink:VkSamplerCreateInfo::ptext:addressMode* 457parameters, specifying the behavior of sampling with coordinates outside the 458range [eq]#[0,1]# for the respective [eq]#u#, [eq]#v#, or [eq]#w# coordinate 459as defined in the <<textures-wrapping-operation, Wrapping Operation>> 460section, are: 461 462include::{generated}/api/enums/VkSamplerAddressMode.txt[] 463 464 * ename:VK_SAMPLER_ADDRESS_MODE_REPEAT specifies that the repeat wrap mode 465 will be used. 466 * ename:VK_SAMPLER_ADDRESS_MODE_MIRRORED_REPEAT specifies that the 467 mirrored repeat wrap mode will be used. 468 * ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE specifies that the clamp to 469 edge wrap mode will be used. 470 * ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER specifies that the clamp 471 to border wrap mode will be used. 472ifdef::VK_VERSION_1_2,VK_KHR_sampler_mirror_clamp_to_edge[] 473 * ename:VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE specifies that the 474 mirror clamp to edge wrap mode will be used. 475 This is only valid if 476ifdef::VK_VERSION_1_2[<<features-samplerMirrorClampToEdge,samplerMirrorClampToEdge>> is enabled, or if] 477 the `apiext:VK_KHR_sampler_mirror_clamp_to_edge` extension is enabled. 478endif::VK_VERSION_1_2,VK_KHR_sampler_mirror_clamp_to_edge[] 479-- 480 481[open,refpage='VkBorderColor',desc='Specify border color used for texture lookups',type='enums'] 482-- 483Possible values of slink:VkSamplerCreateInfo::pname:borderColor, specifying 484the border color used for texture lookups, are: 485 486include::{generated}/api/enums/VkBorderColor.txt[] 487 488 * ename:VK_BORDER_COLOR_FLOAT_TRANSPARENT_BLACK specifies a transparent, 489 floating-point format, black color. 490 * ename:VK_BORDER_COLOR_INT_TRANSPARENT_BLACK specifies a transparent, 491 integer format, black color. 492 * ename:VK_BORDER_COLOR_FLOAT_OPAQUE_BLACK specifies an opaque, 493 floating-point format, black color. 494 * ename:VK_BORDER_COLOR_INT_OPAQUE_BLACK specifies an opaque, integer 495 format, black color. 496 * ename:VK_BORDER_COLOR_FLOAT_OPAQUE_WHITE specifies an opaque, 497 floating-point format, white color. 498 * ename:VK_BORDER_COLOR_INT_OPAQUE_WHITE specifies an opaque, integer 499 format, white color. 500ifdef::VK_EXT_custom_border_color[] 501 * ename:VK_BORDER_COLOR_FLOAT_CUSTOM_EXT indicates that a 502 slink:VkSamplerCustomBorderColorCreateInfoEXT structure is included in 503 the slink:VkSamplerCreateInfo::pname:pNext chain containing the color 504 data in floating-point format. 505 * ename:VK_BORDER_COLOR_INT_CUSTOM_EXT indicates that a 506 slink:VkSamplerCustomBorderColorCreateInfoEXT structure is included in 507 the slink:VkSamplerCreateInfo::pname:pNext chain containing the color 508 data in integer format. 509endif::VK_EXT_custom_border_color[] 510 511These colors are described in detail in <<textures-texel-replacement, Texel 512Replacement>>. 513-- 514 515[open,refpage='vkDestroySampler',desc='Destroy a sampler object',type='protos'] 516-- 517To destroy a sampler, call: 518 519include::{generated}/api/protos/vkDestroySampler.txt[] 520 521 * pname:device is the logical device that destroys the sampler. 522 * pname:sampler is the sampler to destroy. 523 * pname:pAllocator controls host memory allocation as described in the 524 <<memory-allocation, Memory Allocation>> chapter. 525 526.Valid Usage 527**** 528 * [[VUID-vkDestroySampler-sampler-01082]] 529 All submitted commands that refer to pname:sampler must: have completed 530 execution 531 * [[VUID-vkDestroySampler-sampler-01083]] 532 If sname:VkAllocationCallbacks were provided when pname:sampler was 533 created, a compatible set of callbacks must: be provided here 534 * [[VUID-vkDestroySampler-sampler-01084]] 535 If no sname:VkAllocationCallbacks were provided when pname:sampler was 536 created, pname:pAllocator must: be `NULL` 537**** 538 539include::{generated}/validity/protos/vkDestroySampler.txt[] 540-- 541 542 543ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 544[[samplers-YCbCr-conversion]] 545== Sampler {YCbCr} conversion 546 547[open,refpage='VkSamplerYcbcrConversionInfo',desc='Structure specifying {YCbCr} conversion to a sampler or image view',type='structs'] 548-- 549To create a sampler with {YCbCr} conversion enabled, add a 550slink:VkSamplerYcbcrConversionInfo structure to the pname:pNext chain of the 551slink:VkSamplerCreateInfo structure. 552To create a sampler {YCbCr} conversion, the 553<<features-samplerYcbcrConversion,pname:samplerYcbcrConversion feature>> 554must: be enabled. 555Conversion must: be fixed at pipeline creation time, through use of a 556combined image sampler with an immutable sampler in 557sname:VkDescriptorSetLayoutBinding. 558 559A slink:VkSamplerYcbcrConversionInfo must: be provided for samplers to be 560used with image views that access ename:VK_IMAGE_ASPECT_COLOR_BIT if the 561format is one of the <<formats-requiring-sampler-ycbcr-conversion, formats 562that require a sampler Y'C~B~C~R~ conversion>> 563ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 564, or if the image view has an 565<<memory-external-android-hardware-buffer-external-formats,external format>> 566endif::VK_ANDROID_external_memory_android_hardware_buffer[] 567. 568 569The sname:VkSamplerYcbcrConversionInfo structure is defined as: 570 571include::{generated}/api/structs/VkSamplerYcbcrConversionInfo.txt[] 572 573ifdef::VK_KHR_sampler_ycbcr_conversion[] 574or the equivalent 575 576include::{generated}/api/structs/VkSamplerYcbcrConversionInfoKHR.txt[] 577endif::VK_KHR_sampler_ycbcr_conversion[] 578 579 * pname:sType is the type of this structure. 580 * pname:pNext is `NULL` or a pointer to a structure extending this 581 structure. 582 * pname:conversion is a slink:VkSamplerYcbcrConversion handle created with 583 flink:vkCreateSamplerYcbcrConversion. 584 585include::{generated}/validity/structs/VkSamplerYcbcrConversionInfo.txt[] 586-- 587 588[open,refpage='VkSamplerYcbcrConversion',desc='Opaque handle to a device-specific sampler {YCbCr} conversion description',type='handles'] 589-- 590A sampler {YCbCr} conversion is an opaque representation of a 591device-specific sampler {YCbCr} conversion description, represented as a 592sname:VkSamplerYcbcrConversion handle: 593 594include::{generated}/api/handles/VkSamplerYcbcrConversion.txt[] 595 596ifdef::VK_KHR_sampler_ycbcr_conversion[] 597or the equivalent 598 599include::{generated}/api/handles/VkSamplerYcbcrConversionKHR.txt[] 600endif::VK_KHR_sampler_ycbcr_conversion[] 601-- 602 603[open,refpage='vkCreateSamplerYcbcrConversion',desc='Create a new {YCbCr} conversion',type='protos'] 604-- 605To create a slink:VkSamplerYcbcrConversion, call: 606 607ifdef::VK_VERSION_1_1[] 608include::{generated}/api/protos/vkCreateSamplerYcbcrConversion.txt[] 609endif::VK_VERSION_1_1[] 610 611ifdef::VK_VERSION_1_1+VK_KHR_sampler_ycbcr_conversion[or the equivalent command] 612 613ifdef::VK_KHR_sampler_ycbcr_conversion[] 614include::{generated}/api/protos/vkCreateSamplerYcbcrConversionKHR.txt[] 615endif::VK_KHR_sampler_ycbcr_conversion[] 616 617 * pname:device is the logical device that creates the sampler {YCbCr} 618 conversion. 619 * pname:pCreateInfo is a pointer to a 620 slink:VkSamplerYcbcrConversionCreateInfo structure specifying the 621 requested sampler {YCbCr} conversion. 622 * pname:pAllocator controls host memory allocation as described in the 623 <<memory-allocation, Memory Allocation>> chapter. 624 * pname:pYcbcrConversion is a pointer to a slink:VkSamplerYcbcrConversion 625 handle in which the resulting sampler {YCbCr} conversion is returned. 626 627The interpretation of the configured sampler {YCbCr} conversion is described 628in more detail in <<textures-sampler-YCbCr-conversion,the description of 629sampler {YCbCr} conversion>> in the <<textures,Image Operations>> chapter. 630 631.Valid Usage 632**** 633 * [[VUID-vkCreateSamplerYcbcrConversion-None-01648]] 634 The <<features-samplerYcbcrConversion, sampler {YCbCr} conversion 635 feature>> must: be enabled 636**** 637 638include::{generated}/validity/protos/vkCreateSamplerYcbcrConversion.txt[] 639-- 640 641[open,refpage='VkSamplerYcbcrConversionCreateInfo',desc='Structure specifying the parameters of the newly created conversion',type='structs'] 642-- 643The sname:VkSamplerYcbcrConversionCreateInfo structure is defined as: 644 645include::{generated}/api/structs/VkSamplerYcbcrConversionCreateInfo.txt[] 646 647ifdef::VK_KHR_sampler_ycbcr_conversion[] 648or the equivalent 649 650include::{generated}/api/structs/VkSamplerYcbcrConversionCreateInfoKHR.txt[] 651endif::VK_KHR_sampler_ycbcr_conversion[] 652 653 * pname:sType is the type of this structure. 654 * pname:pNext is `NULL` or a pointer to a structure extending this 655 structure. 656 * pname:format is the format of the image from which color information 657 will be retrieved. 658 * pname:ycbcrModel describes the color matrix for conversion between color 659 models. 660 * pname:ycbcrRange describes whether the encoded values have headroom and 661 foot room, or whether the encoding uses the full numerical range. 662 * pname:components applies a _swizzle_ based on elink:VkComponentSwizzle 663 enums prior to range expansion and color model conversion. 664 * pname:xChromaOffset describes the 665 <<textures-chroma-reconstruction,sample location>> associated with 666 downsampled chroma components in the x dimension. 667 pname:xChromaOffset has no effect for formats in which chroma components 668 are not downsampled horizontally. 669 * pname:yChromaOffset describes the 670 <<textures-chroma-reconstruction,sample location>> associated with 671 downsampled chroma components in the y dimension. 672 pname:yChromaOffset has no effect for formats in which the chroma 673 components are not downsampled vertically. 674 * pname:chromaFilter is the filter for chroma reconstruction. 675 * pname:forceExplicitReconstruction can: be used to ensure that 676 reconstruction is done explicitly, if supported. 677 678[NOTE] 679.Note 680==== 681Setting pname:forceExplicitReconstruction to ename:VK_TRUE may: have a 682performance penalty on implementations where explicit reconstruction is not 683the default mode of operation. 684 685If pname:format supports 686ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT 687the pname:forceExplicitReconstruction value behaves as if it was set to 688ename:VK_TRUE. 689==== 690 691ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 692If the pname:pNext chain includes a slink:VkExternalFormatANDROID structure 693with non-zero pname:externalFormat member, the sampler {YCbCr} conversion 694object represents an _external format conversion_, and pname:format must: be 695ename:VK_FORMAT_UNDEFINED. 696Such conversions must: only be used to sample image views with a matching 697<<memory-external-android-hardware-buffer-external-formats,external 698format>>. 699When creating an external format conversion, the value of pname:components 700is ignored. 701endif::VK_ANDROID_external_memory_android_hardware_buffer[] 702ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] 703Sampler {YCbCr} conversion objects do not support _external format 704conversion_ without additional extensions defining _external formats_. 705endif::VK_ANDROID_external_memory_android_hardware_buffer[] 706 707.Valid Usage 708**** 709ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] 710 * [[VUID-VkSamplerYcbcrConversionCreateInfo-format-04060]] 711 pname:format must: represent unsigned normalized values (i.e. the format 712 must be a etext:UNORM format) 713endif::VK_ANDROID_external_memory_android_hardware_buffer[] 714ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 715 * [[VUID-VkSamplerYcbcrConversionCreateInfo-format-01904]] 716 If an external format conversion is being created, pname:format must: be 717 ename:VK_FORMAT_UNDEFINED 718 * [[VUID-VkSamplerYcbcrConversionCreateInfo-format-04061]] 719 If an external format conversion is not being created, pname:format 720 must: represent unsigned normalized values (i.e. the format must be a 721 etext:UNORM format) 722endif::VK_ANDROID_external_memory_android_hardware_buffer[] 723 * [[VUID-VkSamplerYcbcrConversionCreateInfo-format-01650]] 724 The <<potential-format-features, potential format features>> of the 725 sampler {YCbCr} conversion must: support 726 ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT or 727 ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT 728 * [[VUID-VkSamplerYcbcrConversionCreateInfo-xChromaOffset-01651]] 729 If the <<potential-format-features, potential format features>> of the 730 sampler {YCbCr} conversion do not support 731 ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT, pname:xChromaOffset 732 and pname:yChromaOffset must: not be 733 ename:VK_CHROMA_LOCATION_COSITED_EVEN if the corresponding components 734 are <<textures-chroma-reconstruction, downsampled>> 735 * [[VUID-VkSamplerYcbcrConversionCreateInfo-xChromaOffset-01652]] 736 If the <<potential-format-features, potential format features>> of the 737 sampler {YCbCr} conversion do not support 738 ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT, pname:xChromaOffset 739 and pname:yChromaOffset must: not be ename:VK_CHROMA_LOCATION_MIDPOINT 740 if the corresponding components are <<textures-chroma-reconstruction, 741 downsampled>> 742 * [[VUID-VkSamplerYcbcrConversionCreateInfo-components-02581]] 743 If the format has a etext:_422 or etext:_420 suffix, then 744 pname:components.g must: be the 745 <<resources-image-views-identity-mappings,identity swizzle>> 746 * [[VUID-VkSamplerYcbcrConversionCreateInfo-components-02582]] 747 If the format has a etext:_422 or etext:_420 suffix, then 748 pname:components.a must: be the 749 <<resources-image-views-identity-mappings,identity swizzle>>, 750 ename:VK_COMPONENT_SWIZZLE_ONE, or ename:VK_COMPONENT_SWIZZLE_ZERO 751 * [[VUID-VkSamplerYcbcrConversionCreateInfo-components-02583]] 752 If the format has a etext:_422 or etext:_420 suffix, then 753 pname:components.r must: be the 754 <<resources-image-views-identity-mappings,identity swizzle>> or 755 ename:VK_COMPONENT_SWIZZLE_B 756 * [[VUID-VkSamplerYcbcrConversionCreateInfo-components-02584]] 757 If the format has a etext:_422 or etext:_420 suffix, then 758 pname:components.b must: be the 759 <<resources-image-views-identity-mappings,identity swizzle>> or 760 ename:VK_COMPONENT_SWIZZLE_R 761 * [[VUID-VkSamplerYcbcrConversionCreateInfo-components-02585]] 762 If the format has a etext:_422 or etext:_420 suffix, and if either 763 pname:components.r or pname:components.b is the 764 <<resources-image-views-identity-mappings,identity swizzle>>, both 765 values must: be the identity swizzle 766 * [[VUID-VkSamplerYcbcrConversionCreateInfo-ycbcrModel-01655]] 767 If pname:ycbcrModel is not 768 ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY, then 769 pname:components.r, pname:components.g, and pname:components.b must: 770 correspond to components of the pname:format; that is, 771 pname:components.r, pname:components.g, and pname:components.b must: not 772 be ename:VK_COMPONENT_SWIZZLE_ZERO or ename:VK_COMPONENT_SWIZZLE_ONE, 773 and must: not correspond to a component containing zero or one as a 774 consequence of <<textures-conversion-to-rgba,conversion to RGBA>> 775 * [[VUID-VkSamplerYcbcrConversionCreateInfo-ycbcrRange-02748]] 776 If pname:ycbcrRange is ename:VK_SAMPLER_YCBCR_RANGE_ITU_NARROW then the 777 R, G and B components obtained by applying the pname:component swizzle 778 to pname:format must: each have a bit-depth greater than or equal to 8 779 * [[VUID-VkSamplerYcbcrConversionCreateInfo-forceExplicitReconstruction-01656]] 780 If the <<potential-format-features, potential format features>> of the 781 sampler {YCbCr} conversion do not support 782 ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT 783 pname:forceExplicitReconstruction must: be ename:VK_FALSE 784 * [[VUID-VkSamplerYcbcrConversionCreateInfo-chromaFilter-01657]] 785 If the <<potential-format-features, potential format features>> of the 786 sampler {YCbCr} conversion do not support 787 ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT, 788 pname:chromaFilter must: not be ename:VK_FILTER_LINEAR 789**** 790 791include::{generated}/validity/structs/VkSamplerYcbcrConversionCreateInfo.txt[] 792 793If pname:chromaFilter is ename:VK_FILTER_NEAREST, chroma samples are 794reconstructed to luma component resolution using nearest-neighbour sampling. 795Otherwise, chroma samples are reconstructed using interpolation. 796More details can be found in <<textures-sampler-YCbCr-conversion,the 797description of sampler {YCbCr} conversion>> in the <<textures,Image 798Operations>> chapter. 799-- 800 801[open,refpage='VkSamplerYcbcrModelConversion',desc='Color model component of a color space',type='enums'] 802-- 803elink:VkSamplerYcbcrModelConversion defines the conversion from the source 804color model to the shader color model. 805Possible values are: 806 807include::{generated}/api/enums/VkSamplerYcbcrModelConversion.txt[] 808 809ifdef::VK_KHR_sampler_ycbcr_conversion[] 810or the equivalent 811 812include::{generated}/api/enums/VkSamplerYcbcrModelConversionKHR.txt[] 813endif::VK_KHR_sampler_ycbcr_conversion[] 814 815 * ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY specifies that the 816 input values to the conversion are unmodified. 817 * ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY specifies no 818 model conversion but the inputs are range expanded as for {YCbCr}. 819 * ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709 specifies the color 820 model conversion from {YCbCr} to {RGBprime} defined in BT.709 and 821 described in the "`BT.709 {YCbCr} conversion`" section of the 822 <<data-format,Khronos Data Format Specification>>. 823 * ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601 specifies the color 824 model conversion from {YCbCr} to {RGBprime} defined in BT.601 and 825 described in the "`BT.601 {YCbCr} conversion`" section of the 826 <<data-format,Khronos Data Format Specification>>. 827 * ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020 specifies the color 828 model conversion from {YCbCr} to {RGBprime} defined in BT.2020 and 829 described in the "`BT.2020 {YCbCr} conversion`" section of the 830 <<data-format,Khronos Data Format Specification>>. 831 832In the etext:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_* color models, for the 833input to the sampler {YCbCr} range expansion and model conversion: 834 835 * the Y (Y{prime} luma) component corresponds to the G component of an RGB 836 image. 837 * the CB (C~B~ or "`U`" blue color difference) component corresponds to 838 the B component of an RGB image. 839 * the CR (C~R~ or "`V`" red color difference) component corresponds to the 840 R component of an RGB image. 841 * the alpha component, if present, is not modified by color model 842 conversion. 843 844These rules reflect the mapping of components after the component swizzle 845operation (controlled by 846slink:VkSamplerYcbcrConversionCreateInfo::pname:components). 847 848[NOTE] 849.Note 850==== 851For example, an "`YUVA`" 32-bit format comprising four 8-bit components can 852be implemented as ename:VK_FORMAT_R8G8B8A8_UNORM with a component mapping: 853 854 * pname:components.a = ename:VK_COMPONENT_SWIZZLE_IDENTITY 855 * pname:components.r = ename:VK_COMPONENT_SWIZZLE_B 856 * pname:components.g = ename:VK_COMPONENT_SWIZZLE_R 857 * pname:components.b = ename:VK_COMPONENT_SWIZZLE_G 858==== 859-- 860 861[open,refpage='VkSamplerYcbcrRange',desc='Range of encoded values in a color space',type='enums'] 862-- 863The elink:VkSamplerYcbcrRange enum describes whether color components are 864encoded using the full range of numerical values or whether values are 865reserved for headroom and foot room. 866elink:VkSamplerYcbcrRange is defined as: 867 868include::{generated}/api/enums/VkSamplerYcbcrRange.txt[] 869 870ifdef::VK_KHR_sampler_ycbcr_conversion[] 871or the equivalent 872 873include::{generated}/api/enums/VkSamplerYcbcrRangeKHR.txt[] 874endif::VK_KHR_sampler_ycbcr_conversion[] 875 876 * ename:VK_SAMPLER_YCBCR_RANGE_ITU_FULL specifies that the full range of 877 the encoded values are valid and interpreted according to the ITU "`full 878 range`" quantization rules. 879 * ename:VK_SAMPLER_YCBCR_RANGE_ITU_NARROW specifies that headroom and foot 880 room are reserved in the numerical range of encoded values, and the 881 remaining values are expanded according to the ITU "`narrow range`" 882 quantization rules. 883 884The formulae for these conversions is described in the 885<<textures-sampler-YCbCr-conversion-rangeexpand,Sampler {YCbCr} Range 886Expansion>> section of the <<textures,Image Operations>> chapter. 887 888No range modification takes place if pname:ycbcrModel is 889ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY; the pname:ycbcrRange 890field of slink:VkSamplerYcbcrConversionCreateInfo is ignored in this case. 891-- 892 893[open,refpage='VkChromaLocation',desc='Position of downsampled chroma samples',type='enums'] 894-- 895The elink:VkChromaLocation enum defines the location of downsampled chroma 896component samples relative to the luma samples, and is defined as: 897 898include::{generated}/api/enums/VkChromaLocation.txt[] 899 900ifdef::VK_KHR_sampler_ycbcr_conversion[] 901or the equivalent 902 903include::{generated}/api/enums/VkChromaLocationKHR.txt[] 904endif::VK_KHR_sampler_ycbcr_conversion[] 905 906 * ename:VK_CHROMA_LOCATION_COSITED_EVEN specifies that downsampled chroma 907 samples are aligned with luma samples with even coordinates. 908 * ename:VK_CHROMA_LOCATION_MIDPOINT specifies that downsampled chroma 909 samples are located half way between each even luma sample and the 910 nearest higher odd luma sample. 911-- 912 913[open,refpage='vkDestroySamplerYcbcrConversion',desc='Destroy a created {YCbCr} conversion',type='protos'] 914-- 915To destroy a sampler {YCbCr} conversion, call: 916 917ifdef::VK_VERSION_1_1[] 918include::{generated}/api/protos/vkDestroySamplerYcbcrConversion.txt[] 919endif::VK_VERSION_1_1[] 920 921ifdef::VK_VERSION_1_1+VK_KHR_sampler_ycbcr_conversion[or the equivalent command] 922 923ifdef::VK_KHR_sampler_ycbcr_conversion[] 924include::{generated}/api/protos/vkDestroySamplerYcbcrConversionKHR.txt[] 925endif::VK_KHR_sampler_ycbcr_conversion[] 926 927 * pname:device is the logical device that destroys the {YCbCr} conversion. 928 * pname:ycbcrConversion is the conversion to destroy. 929 * pname:pAllocator controls host memory allocation as described in the 930 <<memory-allocation, Memory Allocation>> chapter. 931 932include::{generated}/validity/protos/vkDestroySamplerYcbcrConversion.txt[] 933-- 934endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 935 936ifdef::VK_EXT_custom_border_color[] 937[open,refpage='VkSamplerCustomBorderColorCreateInfoEXT',desc='Structure specifying custom border color',type='structs'] 938-- 939In addition to the predefined border color values, applications can: provide 940a custom border color value by including the 941sname:VkSamplerCustomBorderColorCreateInfoEXT structure in the 942slink:VkSamplerCreateInfo::pname:pNext chain. 943 944The sname:VkSamplerCustomBorderColorCreateInfoEXT structure is defined as: 945 946include::{generated}/api/structs/VkSamplerCustomBorderColorCreateInfoEXT.txt[] 947 948 * pname:sType is the type of this structure. 949 * pname:pNext is `NULL` or a pointer to a structure extending this 950 structure. 951 * pname:customBorderColor is a slink:VkClearColorValue representing the 952 desired custom sampler border color. 953 * pname:format is a elink:VkFormat representing the format of the sampled 954 image view(s). 955 This field may be ename:VK_FORMAT_UNDEFINED if the 956 <<features-customBorderColorWithoutFormat,customBorderColorWithoutFormat>> 957 feature is enabled. 958 959.Valid Usage 960**** 961 * [[VUID-VkSamplerCustomBorderColorCreateInfoEXT-format-04013]] 962 If provided pname:format is not ename:VK_FORMAT_UNDEFINED then the 963 slink:VkSamplerCreateInfo::pname:borderColor type must: match the 964 sampled type of the provided pname:format, as shown in the _SPIR-V 965 Sampled Type_ column of the <<formats-numericformat>> table 966 * [[VUID-VkSamplerCustomBorderColorCreateInfoEXT-format-04014]] 967 If the 968 <<features-customBorderColorWithoutFormat,customBorderColorWithoutFormat>> 969 feature is not enabled then pname:format must: not be 970 ename:VK_FORMAT_UNDEFINED 971 * [[VUID-VkSamplerCustomBorderColorCreateInfoEXT-format-04015]] 972 If the sampler is used to sample an image view of 973 ename:VK_FORMAT_B4G4R4A4_UNORM_PACK16, 974 ename:VK_FORMAT_B5G6R5_UNORM_PACK16, or 975 ename:VK_FORMAT_B5G5R5A1_UNORM_PACK16 format then pname:format must: not 976 be ename:VK_FORMAT_UNDEFINED 977**** 978 979include::{generated}/validity/structs/VkSamplerCustomBorderColorCreateInfoEXT.txt[] 980-- 981endif::VK_EXT_custom_border_color[] 982 983ifdef::VK_EXT_border_color_swizzle[] 984[open,refpage='VkSamplerBorderColorComponentMappingCreateInfoEXT',desc='Structure specifying the component mapping of the border color',type='structs'] 985-- 986 987If the sampler is created with ename:VK_BORDER_COLOR_FLOAT_OPAQUE_BLACK, 988ename:VK_BORDER_COLOR_INT_OPAQUE_BLACK, 989ename:VK_BORDER_COLOR_FLOAT_CUSTOM_EXT, or 990ename:VK_BORDER_COLOR_INT_CUSTOM_EXT pname:borderColor, and that sampler 991will be combined with an image view that does not have an 992<<resources-image-views-identity-mappings,identity swizzle>>, and 993slink:VkPhysicalDeviceBorderColorSwizzleFeaturesEXT::pname:borderColorSwizzleFromImage 994is not enabled, then it is necessary to specify the component mapping of the 995border color, by including the 996sname:VkSamplerBorderColorComponentMappingCreateInfoEXT structure in the 997slink:VkSamplerCreateInfo::pname:pNext chain, to get defined results. 998 999The sname:VkSamplerBorderColorComponentMappingCreateInfoEXT structure is 1000defined as: 1001 1002include::{generated}/api/structs/VkSamplerBorderColorComponentMappingCreateInfoEXT.txt[] 1003 1004 * pname:sType is the type of this structure. 1005 * pname:pNext is `NULL` or a pointer to a structure extending this 1006 structure. 1007 * pname:components is a slink:VkComponentMapping structure specifying a 1008 remapping of the border color components. 1009 * pname:srgb indicates that the sampler will be combined with an image 1010 view that has an image format which is sRGB encoded. 1011 1012The slink:VkComponentMapping pname:components member describes a remapping 1013from components of the border color to components of the vector returned by 1014shader image instructions when the border color is used. 1015 1016.Valid Usage 1017**** 1018 * [[VUID-VkSamplerBorderColorComponentMappingCreateInfoEXT-borderColorSwizzle-06437]] 1019 The <<features-borderColorSwizzle, pname:borderColorSwizzle>> feature 1020 must: be enabled. 1021**** 1022 1023include::{generated}/validity/structs/VkSamplerBorderColorComponentMappingCreateInfoEXT.txt[] 1024-- 1025endif::VK_EXT_border_color_swizzle[] 1026