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