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