1// Copyright (c) 2015-2018 Khronos Group. This work is licensed under a 2// Creative Commons Attribution 4.0 International License; see 3// http://creativecommons.org/licenses/by/4.0/ 4 5[[samplers]] 6= Samplers 7 8[open,refpage='VkSampler',desc='Opaque handle to a sampler object',type='handles'] 9-- 10 11sname:VkSampler objects represent the state of an image sampler which is 12used by the implementation to read image data and apply filtering and other 13transformations for the shader. 14 15Samplers are represented by sname:VkSampler handles: 16 17include::../api/handles/VkSampler.txt[] 18 19-- 20 21[open,refpage='vkCreateSampler',desc='Create a new sampler object',type='protos'] 22-- 23 24To create a sampler object, call: 25 26include::../api/protos/vkCreateSampler.txt[] 27 28 * pname:device is the logical device that creates the sampler. 29 * pname:pCreateInfo is a pointer to an instance of the 30 slink:VkSamplerCreateInfo structure specifying the state of the sampler 31 object. 32 * pname:pAllocator controls host memory allocation as described in the 33 <<memory-allocation, Memory Allocation>> chapter. 34 * pname:pSampler points to a slink:VkSampler handle in which the resulting 35 sampler object is returned. 36 37include::../validity/protos/vkCreateSampler.txt[] 38-- 39 40[open,refpage='VkSamplerCreateInfo',desc='Structure specifying parameters of a newly created sampler',type='structs'] 41-- 42 43The sname:VkSamplerCreateInfo structure is defined as: 44 45include::../api/structs/VkSamplerCreateInfo.txt[] 46 47 * pname:sType is the type of this structure. 48 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 49 * pname:flags is reserved for future use. 50 * pname:magFilter is a elink:VkFilter value specifying the magnification 51 filter to apply to lookups. 52 * pname:minFilter is a elink:VkFilter value specifying the minification 53 filter to apply to lookups. 54 * pname:mipmapMode is a elink:VkSamplerMipmapMode value specifying the 55 mipmap filter to apply to lookups. 56 * pname:addressModeU is a elink:VkSamplerAddressMode value specifying the 57 addressing mode for outside [0..1] range for U coordinate. 58 * pname:addressModeV is a elink:VkSamplerAddressMode value specifying the 59 addressing mode for outside [0..1] range for V coordinate. 60 * pname:addressModeW is a elink:VkSamplerAddressMode value specifying the 61 addressing mode for outside [0..1] range for W coordinate. 62 * [[samplers-mipLodBias]] pname:mipLodBias is the bias to be added to 63 mipmap LOD (level-of-detail) calculation and bias provided by image 64 sampling functions in SPIR-V, as described in the 65 <<textures-level-of-detail-operation, Level-of-Detail Operation>> 66 section. 67 * [[samplers-maxAnisotropy]] pname:anisotropyEnable is ename:VK_TRUE to 68 enable anisotropic filtering, as described in the 69 <<textures-texel-anisotropic-filtering, Texel Anisotropic Filtering>> 70 section, or ename:VK_FALSE otherwise. 71 * pname:maxAnisotropy is the anisotropy value clamp used by the sampler 72 when pname:anisotropyEnable is ename:VK_TRUE. 73 If pname:anisotropyEnable is ename:VK_FALSE, pname:maxAnisotropy is 74 ignored. 75 * pname:compareEnable is ename:VK_TRUE to enable comparison against a 76 reference value during lookups, or ename:VK_FALSE otherwise. 77 ** Note: Some implementations will default to shader state if this member 78 does not match. 79 * pname:compareOp is a elink:VkCompareOp value specifying the comparison 80 function to apply to fetched data before filtering as described in the 81 <<textures-depth-compare-operation, Depth Compare Operation>> section. 82 * pname:minLod and pname:maxLod are the values used to clamp the computed 83 LOD value, as described in the <<textures-level-of-detail-operation, 84 Level-of-Detail Operation>> section. 85 * pname:borderColor is a elink:VkBorderColor value specifying the 86 predefined border color to use. 87 * [[samplers-unnormalizedCoordinates]] pname:unnormalizedCoordinates 88 controls whether to use unnormalized or normalized texel coordinates to 89 address texels of the image. 90 When set to ename:VK_TRUE, the range of the image coordinates used to 91 lookup the texel is in the range of zero to the image dimensions for x, 92 y and z. 93 When set to ename:VK_FALSE the range of image coordinates is zero to 94 one. 95 When pname:unnormalizedCoordinates is ename:VK_TRUE, samplers have the 96 following requirements: 97 ** pname:minFilter and pname:magFilter must: be equal. 98 ** pname:mipmapMode must: be ename:VK_SAMPLER_MIPMAP_MODE_NEAREST. 99 ** pname:minLod and pname:maxLod must: be zero. 100 ** pname:addressModeU and pname:addressModeV must: each be either 101 ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or 102 ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER. 103 ** pname:anisotropyEnable must: be ename:VK_FALSE. 104 ** pname:compareEnable must: be ename:VK_FALSE. 105ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 106 ** The sampler must: not enable sampler Y'C~B~C~R~ conversion. 107endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 108 * When pname:unnormalizedCoordinates is ename:VK_TRUE, images the sampler 109 is used with in the shader have the following requirements: 110 ** The pname:viewType must: be either ename:VK_IMAGE_VIEW_TYPE_1D or 111 ename:VK_IMAGE_VIEW_TYPE_2D. 112 ** The image view must: have a single layer and a single mip level. 113 * When pname:unnormalizedCoordinates is ename:VK_TRUE, image built-in 114 functions in the shader that use the sampler have the following 115 requirements: 116 ** The functions must: not use projection. 117 ** The functions must: not use offsets. 118 119[NOTE] 120.Mapping of OpenGL to Vulkan filter modes 121==== 122pname:magFilter values of ename:VK_FILTER_NEAREST and ename:VK_FILTER_LINEAR 123directly correspond to code:GL_NEAREST and code:GL_LINEAR magnification 124filters. 125pname:minFilter and pname:mipmapMode combine to correspond to the similarly 126named OpenGL minification filter of code:GL_minFilter_MIPMAP_mipmapMode 127(e.g. pname:minFilter of ename:VK_FILTER_LINEAR and pname:mipmapMode of 128ename:VK_SAMPLER_MIPMAP_MODE_NEAREST correspond to 129code:GL_LINEAR_MIPMAP_NEAREST). 130 131There are no Vulkan filter modes that directly correspond to OpenGL 132minification filters of code:GL_LINEAR or code:GL_NEAREST, but they can: be 133emulated using ename:VK_SAMPLER_MIPMAP_MODE_NEAREST, pname:minLod = 0, and 134pname:maxLod = 0.25, and using pname:minFilter = ename:VK_FILTER_LINEAR or 135pname:minFilter = ename:VK_FILTER_NEAREST, respectively. 136 137Note that using a pname:maxLod of zero would cause 138<<textures-texel-filtering,magnification>> to always be performed, and the 139pname:magFilter to always be used. 140This is valid, just not an exact match for OpenGL behavior. 141Clamping the maximum LOD to 0.25 allows the [eq]#{lambda}# value to be 142non-zero and minification to be performed, while still always rounding down 143to the base level. 144If the pname:minFilter and pname:magFilter are equal, then using a 145pname:maxLod of zero also works. 146==== 147 148The maximum number of sampler objects which can: be simultaneously created 149on a device is implementation-dependent and specified by the 150<<features-limits-maxSamplerAllocationCount,maxSamplerAllocationCount>> 151member of the slink:VkPhysicalDeviceLimits structure. 152If pname:maxSamplerAllocationCount is exceeded, fname:vkCreateSampler will 153return ename:VK_ERROR_TOO_MANY_OBJECTS. 154 155Since slink:VkSampler is a non-dispatchable handle type, implementations 156may: return the same handle for sampler state vectors that are identical. 157In such cases, all such objects would only count once against the 158pname:maxSamplerAllocationCount limit. 159 160.Valid Usage 161**** 162 * [[VUID-VkSamplerCreateInfo-mipLodBias-01069]] 163 The absolute value of pname:mipLodBias must: be less than or equal to 164 sname:VkPhysicalDeviceLimits::pname:maxSamplerLodBias 165 * [[VUID-VkSamplerCreateInfo-maxLod-01973]] 166 pname:maxLod must: be greater than or equal to pname:minLod 167 * [[VUID-VkSamplerCreateInfo-anisotropyEnable-01070]] 168 If the <<features-features-samplerAnisotropy,anisotropic sampling>> 169 feature is not enabled, pname:anisotropyEnable must: be ename:VK_FALSE 170 * [[VUID-VkSamplerCreateInfo-anisotropyEnable-01071]] 171 If pname:anisotropyEnable is ename:VK_TRUE, pname:maxAnisotropy must: be 172 between `1.0` and 173 sname:VkPhysicalDeviceLimits::pname:maxSamplerAnisotropy, inclusive 174ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 175 * [[VUID-VkSamplerCreateInfo-minFilter-01645]] 176 If <<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>> is 177 enabled and 178 ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT 179 is not set for the format, pname:minFilter and pname:magFilter must: be 180 equal to the sampler Y'C~B~C~R~ conversion's pname:chromaFilter 181endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 182 * [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01072]] 183 If pname:unnormalizedCoordinates is ename:VK_TRUE, pname:minFilter and 184 pname:magFilter must: be equal 185 * [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01073]] 186 If pname:unnormalizedCoordinates is ename:VK_TRUE, pname:mipmapMode 187 must: be ename:VK_SAMPLER_MIPMAP_MODE_NEAREST 188 * [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01074]] 189 If pname:unnormalizedCoordinates is ename:VK_TRUE, pname:minLod and 190 pname:maxLod must: be zero 191 * [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01075]] 192 If pname:unnormalizedCoordinates is ename:VK_TRUE, pname:addressModeU 193 and pname:addressModeV must: each be either 194 ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or 195 ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER 196 * [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01076]] 197 If pname:unnormalizedCoordinates is ename:VK_TRUE, 198 pname:anisotropyEnable must: be ename:VK_FALSE 199 * [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01077]] 200 If pname:unnormalizedCoordinates is ename:VK_TRUE, pname:compareEnable 201 must: be ename:VK_FALSE 202 * [[VUID-VkSamplerCreateInfo-addressModeU-01078]] 203 If any of pname:addressModeU, pname:addressModeV or pname:addressModeW 204 are ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER, pname:borderColor 205 must: be a valid elink:VkBorderColor value 206ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 207 * [[VUID-VkSamplerCreateInfo-addressModeU-01646]] 208 If <<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>> is 209 enabled, pname:addressModeU, pname:addressModeV, and pname:addressModeW 210 must: be ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE, 211 pname:anisotropyEnable must: be ename:VK_FALSE, and 212 pname:unnormalizedCoordinates must: be ename:VK_FALSE 213ifdef::VK_EXT_sampler_filter_minmax[] 214 * [[VUID-VkSamplerCreateInfo-None-01647]] 215 The sampler reduction mode must: be set to 216 ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT if 217 <<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>> is enabled 218endif::VK_EXT_sampler_filter_minmax[] 219endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 220 * [[VUID-VkSamplerCreateInfo-addressModeU-01079]] 221 If the `<<VK_KHR_sampler_mirror_clamp_to_edge>>` extension is not 222 enabled, pname:addressModeU, pname:addressModeV and pname:addressModeW 223 must: not be ename:VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE 224 * [[VUID-VkSamplerCreateInfo-compareEnable-01080]] 225 If pname:compareEnable is ename:VK_TRUE, pname:compareOp must: be a 226 valid elink:VkCompareOp value 227ifdef::VK_IMG_filter_cubic[] 228 * [[VUID-VkSamplerCreateInfo-magFilter-01081]] 229 If either pname:magFilter or pname:minFilter is 230 ename:VK_FILTER_CUBIC_IMG, pname:anisotropyEnable must: be 231 ename:VK_FALSE 232endif::VK_IMG_filter_cubic[] 233ifdef::VK_IMG_filter_cubic+VK_EXT_sampler_filter_minmax[] 234 * [[VUID-VkSamplerCreateInfo-magFilter-01422]] 235 If either pname:magFilter or pname:minFilter is 236 ename:VK_FILTER_CUBIC_IMG, the pname:reductionMode member of 237 slink:VkSamplerReductionModeCreateInfoEXT must: be 238 ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT 239endif::VK_IMG_filter_cubic+VK_EXT_sampler_filter_minmax[] 240ifdef::VK_EXT_sampler_filter_minmax[] 241 * [[VUID-VkSamplerCreateInfo-compareEnable-01423]] 242 If pname:compareEnable is ename:VK_TRUE, the pname:reductionMode member 243 of slink:VkSamplerReductionModeCreateInfoEXT must: be 244 ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT 245endif::VK_EXT_sampler_filter_minmax[] 246**** 247 248include::../validity/structs/VkSamplerCreateInfo.txt[] 249-- 250 251[open,refpage='VkSamplerCreateFlags',desc='Reserved for future use',type='enums'] 252-- 253include::../api/flags/VkSamplerCreateFlags.txt[] 254 255sname:VkSamplerCreateFlags is a bitmask type for setting a mask, but is 256currently reserved for future use. 257-- 258 259ifdef::VK_EXT_sampler_filter_minmax[] 260 261[open,refpage='VkSamplerReductionModeCreateInfoEXT',desc='Structure specifying sampler reduction mode',type='structs'] 262-- 263If the pname:pNext chain of slink:VkSamplerCreateInfo includes a 264sname:VkSamplerReductionModeCreateInfoEXT structure, then that structure 265includes a mode that controls how texture filtering combines texel values. 266 267The sname:VkSamplerReductionModeCreateInfoEXT structure is defined as: 268 269include::../api/structs/VkSamplerReductionModeCreateInfoEXT.txt[] 270 271 * pname:sType is the type of this structure. 272 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 273 * pname:reductionMode is an enum of type elink:VkSamplerReductionModeEXT 274 that controls how texture filtering combines texel values. 275 276If this structure is not present, pname:reductionMode is considered to be 277ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT. 278 279include::../validity/structs/VkSamplerReductionModeCreateInfoEXT.txt[] 280-- 281 282[open,refpage='VkSamplerReductionModeEXT',desc='Specify reduction mode for texture filtering',type='enums'] 283-- 284Reduction modes are specified by elink:VkSamplerReductionModeEXT, which 285takes values: 286 287include::../api/enums/VkSamplerReductionModeEXT.txt[] 288 289 * ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT specifies that 290 texel values are combined by computing a weighted average of values in 291 the footprint, using weights as specified in 292 <<textures-unnormalized-to-integer,the image operations chapter>>. 293 * ename:VK_SAMPLER_REDUCTION_MODE_MIN_EXT specifies that texel values are 294 combined by taking the component-wise minimum of values in the footprint 295 with non-zero weights. 296 * ename:VK_SAMPLER_REDUCTION_MODE_MAX_EXT specifies that texel values are 297 combined by taking the component-wise maximum of values in the footprint 298 with non-zero weights. 299-- 300 301endif::VK_EXT_sampler_filter_minmax[] 302 303[open,refpage='VkFilter',desc='Specify filters used for texture lookups',type='enums'] 304-- 305Possible values of the slink:VkSamplerCreateInfo::pname:magFilter and 306pname:minFilter parameters, specifying filters used for texture lookups, 307are: 308 309include::../api/enums/VkFilter.txt[] 310 311 * ename:VK_FILTER_NEAREST specifies nearest filtering. 312 * ename:VK_FILTER_LINEAR specifies linear filtering. 313ifdef::VK_IMG_filter_cubic[] 314 * ename:VK_FILTER_CUBIC_IMG specifies cubic filtering. 315endif::VK_IMG_filter_cubic[] 316 317These filters are described in detail in <<textures-texel-filtering, Texel 318Filtering>>. 319 320-- 321 322[open,refpage='VkSamplerMipmapMode',desc='Specify mipmap mode used for texture lookups',type='enums'] 323-- 324 325Possible values of the slink:VkSamplerCreateInfo::pname:mipmapMode, 326specifying the mipmap mode used for texture lookups, are: 327 328include::../api/enums/VkSamplerMipmapMode.txt[] 329 330 * ename:VK_SAMPLER_MIPMAP_MODE_NEAREST specifies nearest filtering. 331 * ename:VK_SAMPLER_MIPMAP_MODE_LINEAR specifies linear filtering. 332 333These modes are described in detail in <<textures-texel-filtering, Texel 334Filtering>>. 335 336-- 337 338[open,refpage='VkSamplerAddressMode',desc='Specify behavior of sampling with texture coordinates outside an image',type='enums'] 339-- 340 341Possible values of the slink:VkSamplerCreateInfo::ptext:addressMode* 342parameters, specifying the behavior of sampling with coordinates outside the 343range [eq]#[0,1]# for the respective [eq]#u#, [eq]#v#, or [eq]#w# coordinate 344as defined in the <<textures-wrapping-operation, Wrapping Operation>> 345section, are: 346 347include::../api/enums/VkSamplerAddressMode.txt[] 348 349 * ename:VK_SAMPLER_ADDRESS_MODE_REPEAT specifies that the repeat wrap mode 350 will be used. 351 * ename:VK_SAMPLER_ADDRESS_MODE_MIRRORED_REPEAT specifies that the 352 mirrored repeat wrap mode will be used. 353 * ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE specifies that the clamp to 354 edge wrap mode will be used. 355 * ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER specifies that the clamp 356 to border wrap mode will be used. 357 * ename:VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE specifies that the 358 mirror clamp to edge wrap mode will be used. 359 This is only valid if the `<<VK_KHR_sampler_mirror_clamp_to_edge>>` 360 extension is enabled. 361 362-- 363 364[open,refpage='VkBorderColor',desc='Specify border color used for texture lookups',type='enums'] 365-- 366 367Possible values of slink:VkSamplerCreateInfo::pname:borderColor, specifying 368the border color used for texture lookups, are: 369 370include::../api/enums/VkBorderColor.txt[] 371 372 * ename:VK_BORDER_COLOR_FLOAT_TRANSPARENT_BLACK specifies a transparent, 373 floating-point format, black color. 374 * ename:VK_BORDER_COLOR_INT_TRANSPARENT_BLACK specifies a transparent, 375 integer format, black color. 376 * ename:VK_BORDER_COLOR_FLOAT_OPAQUE_BLACK specifies an opaque, 377 floating-point format, black color. 378 * ename:VK_BORDER_COLOR_INT_OPAQUE_BLACK specifies an opaque, integer 379 format, black color. 380 * ename:VK_BORDER_COLOR_FLOAT_OPAQUE_WHITE specifies an opaque, 381 floating-point format, white color. 382 * ename:VK_BORDER_COLOR_INT_OPAQUE_WHITE specifies an opaque, integer 383 format, white color. 384 385These colors are described in detail in <<textures-texel-replacement, Texel 386Replacement>>. 387 388-- 389 390[open,refpage='vkDestroySampler',desc='Destroy a sampler object',type='protos'] 391-- 392 393To destroy a sampler, call: 394 395include::../api/protos/vkDestroySampler.txt[] 396 397 * pname:device is the logical device that destroys the sampler. 398 * pname:sampler is the sampler to destroy. 399 * pname:pAllocator controls host memory allocation as described in the 400 <<memory-allocation, Memory Allocation>> chapter. 401 402.Valid Usage 403**** 404 * [[VUID-vkDestroySampler-sampler-01082]] 405 All submitted commands that refer to pname:sampler must: have completed 406 execution 407 * [[VUID-vkDestroySampler-sampler-01083]] 408 If sname:VkAllocationCallbacks were provided when pname:sampler was 409 created, a compatible set of callbacks must: be provided here 410 * [[VUID-vkDestroySampler-sampler-01084]] 411 If no sname:VkAllocationCallbacks were provided when pname:sampler was 412 created, pname:pAllocator must: be `NULL` 413**** 414 415include::../validity/protos/vkDestroySampler.txt[] 416-- 417 418 419ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 420 421[[samplers-YCbCr-conversion]] 422== Sampler Y'C~B~C~R~ conversion 423 424[open,refpage='VkSamplerYcbcrConversionInfo',desc='Structure specifying Y\'CbCr conversion to a sampler or image view',type='structs'] 425-- 426 427To create a sampler with Y'C~B~C~R~ conversion enabled, add a 428slink:VkSamplerYcbcrConversionInfo to the pname:pNext chain of the 429slink:VkSamplerCreateInfo structure. 430To create a sampler Y'C~B~C~R~ conversion, the 431<<features-features-sampler-YCbCr-conversion,pname:samplerYcbcrConversion 432feature>> must: be enabled. 433Conversion must: be fixed at pipeline creation time, through use of a 434combined image sampler with an immutable sampler in 435sname:VkDescriptorSetLayoutBinding. 436 437A slink:VkSamplerYcbcrConversionInfo must: be provided for samplers to be 438used with image views that access ename:VK_IMAGE_ASPECT_COLOR_BIT if the 439format appears in <<features-formats-requiring-sampler-ycbcr-conversion>> 440ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 441, or if the image view has an 442<<memory-external-android-hardware-buffer-external-formats,external format>> 443endif::VK_ANDROID_external_memory_android_hardware_buffer[] 444. 445 446The sname:VkSamplerYcbcrConversionInfo structure is defined as: 447 448include::../api/structs/VkSamplerYcbcrConversionInfo.txt[] 449 450ifdef::VK_KHR_sampler_ycbcr_conversion[] 451or the equivalent 452 453include::../api/structs/VkSamplerYcbcrConversionInfoKHR.txt[] 454endif::VK_KHR_sampler_ycbcr_conversion[] 455 456 * pname:sType is the type of this structure. 457 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 458 * pname:conversion is a slink:VkSamplerYcbcrConversion handle created with 459 flink:vkCreateSamplerYcbcrConversion. 460 461include::../validity/structs/VkSamplerYcbcrConversionInfo.txt[] 462 463-- 464 465[open,refpage='VkSamplerYcbcrConversion',desc='',type='handles'] 466-- 467 468A sampler Y'C~B~C~R~ conversion is an opaque representation of a 469device-specific sampler Y'C~B~C~R~ conversion description, represented as a 470sname:VkSamplerYcbcrConversion handle: 471 472include::../api/handles/VkSamplerYcbcrConversion.txt[] 473 474ifdef::VK_KHR_sampler_ycbcr_conversion[] 475or the equivalent 476 477include::../api/handles/VkSamplerYcbcrConversionKHR.txt[] 478endif::VK_KHR_sampler_ycbcr_conversion[] 479 480-- 481 482[open,refpage='vkCreateSamplerYcbcrConversion',desc='Create a new Ycbcr conversion',type='protos'] 483-- 484 485To create a slink:VkSamplerYcbcrConversion, call: 486 487ifdef::VK_VERSION_1_1[] 488include::../api/protos/vkCreateSamplerYcbcrConversion.txt[] 489endif::VK_VERSION_1_1[] 490 491ifdef::VK_VERSION_1_1+VK_KHR_sampler_ycbcr_conversion[or the equivalent command] 492 493ifdef::VK_KHR_sampler_ycbcr_conversion[] 494include::../api/protos/vkCreateSamplerYcbcrConversionKHR.txt[] 495endif::VK_KHR_sampler_ycbcr_conversion[] 496 497 * pname:device is the logical device that creates the sampler Y'C~B~C~R~ 498 conversion. 499 * pname:pCreateInfo is a pointer to an instance of the 500 slink:VkSamplerYcbcrConversionCreateInfo specifying the requested 501 sampler Y'C~B~C~R~ conversion. 502 * pname:pAllocator controls host memory allocation as described in the 503 <<memory-allocation, Memory Allocation>> chapter. 504 * pname:pYcbcrConversion points to a slink:VkSamplerYcbcrConversion handle 505 in which the resulting sampler Y'C~B~C~R~ conversion is returned. 506 507The interpretation of the configured sampler Y'C~B~C~R~ conversion is 508described in more detail in <<textures-sampler-YCbCr-conversion,the 509description of sampler Y'C~B~C~R~ conversion>> in the <<textures,Image 510Operations>> chapter. 511 512.Valid Usage 513**** 514 * [[VUID-vkCreateSamplerYcbcrConversion-None-01648]] 515 The <<features-features-sampler-YCbCr-conversion, sampler Y'C~B~C~R~ 516 conversion feature>> must: be enabled 517**** 518 519include::../validity/protos/vkCreateSamplerYcbcrConversion.txt[] 520 521-- 522 523[open,refpage='VkSamplerYcbcrConversionCreateInfo',desc='Structure specifying the parameters of the newly created conversion',type='structs'] 524-- 525 526The sname:VkSamplerYcbcrConversionCreateInfo structure is defined as: 527 528include::../api/structs/VkSamplerYcbcrConversionCreateInfo.txt[] 529 530ifdef::VK_KHR_sampler_ycbcr_conversion[] 531or the equivalent 532 533include::../api/structs/VkSamplerYcbcrConversionCreateInfoKHR.txt[] 534endif::VK_KHR_sampler_ycbcr_conversion[] 535 536 * pname:sType is the type of this structure. 537 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 538 * pname:format is the format of the image from which color information 539 will be retrieved. 540 * pname:ycbcrModel describes the color matrix for conversion between color 541 models. 542 * pname:ycbcrRange describes whether the encoded values have headroom and 543 foot room, or whether the encoding uses the full numerical range. 544 * pname:components applies a _swizzle_ based on elink:VkComponentSwizzle 545 enums prior to range expansion and color model conversion. 546 * pname:xChromaOffset describes the 547 <<textures-chroma-reconstruction,sample location>> associated with 548 downsampled chroma channels in the x dimension. 549 pname:xChromaOffset has no effect for formats in which chroma channels 550 are the same resolution as the luma channel. 551 * pname:yChromaOffset describes the 552 <<textures-chroma-reconstruction,sample location>> associated with 553 downsampled chroma channels in the y dimension. 554 pname:yChromaOffset has no effect for formats in which the chroma 555 channels are not downsampled vertically. 556 * pname:chromaFilter is the filter for chroma reconstruction. 557 * pname:forceExplicitReconstruction can: be used to ensure that 558 reconstruction is done explicitly, if supported. 559 560[NOTE] 561.Note 562==== 563Setting pname:forceExplicitReconstruction to ename:VK_TRUE may: have a 564performance penalty on implementations where explicit reconstruction is not 565the default mode of operation. 566==== 567 568ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 569If the pname:pNext chain has an instance of slink:VkExternalFormatANDROID 570with non-zero pname:externalFormat member, the sampler Y'C~B~C~R~ conversion 571object represents an _external format conversion_, and pname:format must: be 572ename:VK_FORMAT_UNDEFINED. 573Such conversions must: only be used to sample image views with a matching 574<<memory-external-android-hardware-buffer-external-formats,external 575format>>. 576When creating an external format conversion, the value of pname:components 577is ignored. 578endif::VK_ANDROID_external_memory_android_hardware_buffer[] 579ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] 580Sampler Y'C~B~C~R~ conversion objects do not support _external format 581conversion_ without additional extensions defining _external formats_. 582endif::VK_ANDROID_external_memory_android_hardware_buffer[] 583 584.Valid Usage 585**** 586ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] 587 * [[VUID-VkSamplerYcbcrConversionCreateInfo-format-01649]] 588 pname:format must: not be ename:VK_FORMAT_UNDEFINED 589endif::VK_ANDROID_external_memory_android_hardware_buffer[] 590ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 591 * [[VUID-VkSamplerYcbcrConversionCreateInfo-format-01904]] 592 If an external format conversion is being created, pname:format must: be 593 ename:VK_FORMAT_UNDEFINED, otherwise it must: not be 594 ename:VK_FORMAT_UNDEFINED. 595endif::VK_ANDROID_external_memory_android_hardware_buffer[] 596 * [[VUID-VkSamplerYcbcrConversionCreateInfo-format-01650]] 597 pname:format must: support 598 ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT or 599 ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT 600 * [[VUID-VkSamplerYcbcrConversionCreateInfo-xChromaOffset-01651]] 601 If the format does not support 602 ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT, pname:xChromaOffset 603 and pname:yChromaOffset must: not be 604 ename:VK_CHROMA_LOCATION_COSITED_EVEN 605 * [[VUID-VkSamplerYcbcrConversionCreateInfo-xChromaOffset-01652]] 606 If the format does not support 607 ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT, pname:xChromaOffset 608 and pname:yChromaOffset must: not be ename:VK_CHROMA_LOCATION_MIDPOINT 609 * [[VUID-VkSamplerYcbcrConversionCreateInfo-format-01653]] 610 pname:format must: represent unsigned normalized values (i.e. the format 611 must be a etext:UNORM format) 612 * [[VUID-VkSamplerYcbcrConversionCreateInfo-None-01654]] 613 If the format has a etext:_422 or etext:_420 suffix: 614 ** pname:components.g must: be ename:VK_COMPONENT_SWIZZLE_IDENTITY 615 ** pname:components.a must: be ename:VK_COMPONENT_SWIZZLE_IDENTITY, 616 ename:VK_COMPONENT_SWIZZLE_ONE, or ename:VK_COMPONENT_SWIZZLE_ZERO 617 ** pname:components.r must: be ename:VK_COMPONENT_SWIZZLE_IDENTITY or 618 ename:VK_COMPONENT_SWIZZLE_B 619 ** pname:components.b must: be ename:VK_COMPONENT_SWIZZLE_IDENTITY or 620 ename:VK_COMPONENT_SWIZZLE_R 621 ** If either pname:components.r or pname:components.b is 622 ename:VK_COMPONENT_SWIZZLE_IDENTITY, both values must: be 623 ename:VK_COMPONENT_SWIZZLE_IDENTITY 624 * [[VUID-VkSamplerYcbcrConversionCreateInfo-ycbcrModel-01655]] 625 If pname:ycbcrModel is not 626 ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY, then 627 pname:components.r, pname:components.g, and pname:components.b must: 628 correspond to channels of the pname:format; that is, pname:components.r, 629 pname:components.g, and pname:components.b must: not be 630 ename:VK_COMPONENT_SWIZZLE_ZERO or ename:VK_COMPONENT_SWIZZLE_ONE, and 631 must: not correspond to a channel which contains zero or one as a 632 consequence of <<textures-conversion-to-rgba,conversion to RGBA>> 633 * [[VUID-VkSamplerYcbcrConversionCreateInfo-forceExplicitReconstruction-01656]] 634 If the format does not support 635 ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT, 636 pname:forceExplicitReconstruction must: be FALSE 637 * [[VUID-VkSamplerYcbcrConversionCreateInfo-chromaFilter-01657]] 638 If the format does not support 639 ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT, 640 pname:chromaFilter must: be ename:VK_FILTER_NEAREST 641**** 642 643include::../validity/structs/VkSamplerYcbcrConversionCreateInfo.txt[] 644 645If pname:chromaFilter is ename:VK_FILTER_NEAREST, chroma samples are 646reconstructed to luma channel resolution using nearest-neighbour sampling. 647Otherwise, chroma samples are reconstructed using interpolation. 648More details can be found in <<textures-sampler-YCbCr-conversion,the 649description of sampler Y'C~B~C~R~ conversion>> in the <<textures,Image 650Operations>> chapter. 651 652-- 653 654[open,refpage='VkSamplerYcbcrModelConversion',desc='Color model component of a color space',type='enums'] 655-- 656 657elink:VkSamplerYcbcrModelConversion defines the conversion from the source 658color model to the shader color model. 659Possible values are: 660 661include::../api/enums/VkSamplerYcbcrModelConversion.txt[] 662 663ifdef::VK_KHR_sampler_ycbcr_conversion[] 664or the equivalent 665 666include::../api/enums/VkSamplerYcbcrModelConversionKHR.txt[] 667endif::VK_KHR_sampler_ycbcr_conversion[] 668 669 * ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY specifies that the 670 input values to the conversion are unmodified. 671 * ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY specifies no 672 model conversion but the inputs are range expanded as for Y'C~B~C~R~. 673 * ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709 specifies the color 674 model conversion from Y'C~B~C~R~ to R'G'B' defined in BT.709 and 675 described in the "`BT.709 Y’C~B~C~R~ conversion`" section of the 676 <<data-format,Khronos Data Format Specification>>. 677 * ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601 specifies the color 678 model conversion from Y'C~B~C~R~ to R'G'B' defined in BT.601 and 679 described in the "`BT.601 Y’C~B~C~R~ conversion`" section of the 680 <<data-format,Khronos Data Format Specification>>. 681 * ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020 specifies the color 682 model conversion from Y'C~B~C~R~ to R'G'B' defined in BT.2020 and 683 described in the "`BT.2020 Y’C~B~C~R~ conversion`" section of the 684 <<data-format,Khronos Data Format Specification>>. 685 686In the etext:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_* color models, for the 687input to the sampler Y'C~B~C~R~ range expansion and model conversion: 688 689 * the Y (Y' luma) channel corresponds to the G channel of an RGB image. 690 * the CB (C~B~ or "`U`" blue color difference) channel corresponds to the 691 B channel of an RGB image. 692 * the CR (C~R~ or "`V`" red color difference) channel corresponds to the R 693 channel of an RGB image. 694 * the alpha channel, if present, is not modified by color model 695 conversion. 696 697These rules reflect the mapping of channels after the channel swizzle 698operation (controlled by 699slink:VkSamplerYcbcrConversionCreateInfo::pname:components). 700 701[NOTE] 702.Note 703==== 704For example, an "`YUVA`" 32-bit format comprising four 8-bit channels can be 705implemented as ename:VK_FORMAT_R8G8B8A8_UNORM with a component mapping: 706 707 * pname:components.a = ename:VK_COMPONENT_SWIZZLE_IDENTITY 708 * pname:components.r = ename:VK_COMPONENT_SWIZZLE_B 709 * pname:components.g = ename:VK_COMPONENT_SWIZZLE_R 710 * pname:components.b = ename:VK_COMPONENT_SWIZZLE_G 711==== 712 713-- 714 715[open,refpage='VkSamplerYcbcrRange',desc='Range of encoded values in a color space',type='enums'] 716-- 717 718The elink:VkSamplerYcbcrRange enum describes whether color channels are 719encoded using the full range of numerical values or whether values are 720reserved for headroom and foot room. 721elink:VkSamplerYcbcrRange is defined as: 722 723include::../api/enums/VkSamplerYcbcrRange.txt[] 724 725ifdef::VK_KHR_sampler_ycbcr_conversion[] 726or the equivalent 727 728include::../api/enums/VkSamplerYcbcrRangeKHR.txt[] 729endif::VK_KHR_sampler_ycbcr_conversion[] 730 731 * ename:VK_SAMPLER_YCBCR_RANGE_ITU_FULL specifies that the full range of 732 the encoded values are valid and interpreted according to the ITU "`full 733 range`" quantization rules. 734 * ename:VK_SAMPLER_YCBCR_RANGE_ITU_NARROW specifies that headroom and foot 735 room are reserved in the numerical range of encoded values, and the 736 remaining values are expanded according to the ITU "`narrow range`" 737 quantization rules. 738 739The formulae for these conversions is described in the 740<<textures-sampler-YCbCr-conversion-rangeexpand,Sampler Y'C~B~C~R~ Range 741Expansion>> section of the <<textures,Image Operations>> chapter. 742 743No range modification takes place if pname:ycbcrModel is 744ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY; the pname:ycbcrRange 745field of sname:VkSamplerYcbcrConversionCreateInfo is ignored in this case. 746 747-- 748 749[open,refpage='VkChromaLocation',desc='Position of downsampled chroma samples',type='enums'] 750-- 751 752The elink:VkChromaLocation enum, which defines the location of downsampled 753chroma channel samples relative to the luma samples, is defined as: 754 755include::../api/enums/VkChromaLocation.txt[] 756 757ifdef::VK_KHR_sampler_ycbcr_conversion[] 758or the equivalent 759 760include::../api/enums/VkChromaLocationKHR.txt[] 761endif::VK_KHR_sampler_ycbcr_conversion[] 762 763 * ename:VK_CHROMA_LOCATION_COSITED_EVEN specifies that downsampled chroma 764 samples are aligned with luma samples with even coordinates. 765 * ename:VK_CHROMA_LOCATION_MIDPOINT specifies that downsampled chroma 766 samples are located half way between each even luma sample and the 767 nearest higher odd luma sample. 768 769-- 770 771[open,refpage='vkDestroySamplerYcbcrConversion',desc='Destroy a created Y\'CbCr conversion',type='protos'] 772-- 773 774To destroy a sampler Y'C~B~C~R~ conversion, call: 775 776ifdef::VK_VERSION_1_1[] 777include::../api/protos/vkDestroySamplerYcbcrConversion.txt[] 778endif::VK_VERSION_1_1[] 779 780ifdef::VK_VERSION_1_1+VK_KHR_sampler_ycbcr_conversion[or the equivalent command] 781 782ifdef::VK_KHR_sampler_ycbcr_conversion[] 783include::../api/protos/vkDestroySamplerYcbcrConversionKHR.txt[] 784endif::VK_KHR_sampler_ycbcr_conversion[] 785 786 * pname:device is the logical device that destroys the Y'C~B~C~R~ 787 conversion. 788 * pname:ycbcrConversion is the conversion to destroy. 789 * pname:pAllocator controls host memory allocation as described in the 790 <<memory-allocation, Memory Allocation>> chapter. 791 792include::../validity/protos/vkDestroySamplerYcbcrConversion.txt[] 793 794-- 795 796endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 797