1// Copyright 2015-2021 The Khronos Group, Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[capabilities]] 6= Additional Capabilities 7 8This chapter describes additional capabilities beyond the minimum 9capabilities described in the <<limits,Limits>> and <<formats,Formats>> 10chapters, including: 11 12 * <<capabilities-image, Additional Image Capabilities>> 13ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] 14 * <<capabilities-buffer, Additional Buffer Capabilities>> 15endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] 16ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[] 17 * <<capabilities-semaphore, Optional Semaphore Capabilities>> 18endif::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[] 19ifdef::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] 20 * <<capabilities-fence, Optional Fence Capabilities>> 21endif::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] 22ifdef::VK_EXT_calibrated_timestamps[] 23 * <<features-timestamp-calibration, Timestamp Calibration Capabilities>> 24endif::VK_EXT_calibrated_timestamps[] 25 26 27[[capabilities-image]] 28== Additional Image Capabilities 29 30Additional image capabilities, such as larger dimensions or additional 31sample counts for certain image types, or additional capabilities for 32_linear_ tiling format images, are described in this section. 33 34[open,refpage='vkGetPhysicalDeviceImageFormatProperties',desc='Lists physical device\'s image format capabilities',type='protos'] 35-- 36To query additional capabilities specific to image types, call: 37 38include::{generated}/api/protos/vkGetPhysicalDeviceImageFormatProperties.txt[] 39 40 * pname:physicalDevice is the physical device from which to query the 41 image capabilities. 42 * pname:format is a elink:VkFormat value specifying the image format, 43 corresponding to slink:VkImageCreateInfo::pname:format. 44 * pname:type is a elink:VkImageType value specifying the image type, 45 corresponding to slink:VkImageCreateInfo::pname:imageType. 46 * pname:tiling is a elink:VkImageTiling value specifying the image tiling, 47 corresponding to slink:VkImageCreateInfo::pname:tiling. 48 * pname:usage is a bitmask of elink:VkImageUsageFlagBits specifying the 49 intended usage of the image, corresponding to 50 slink:VkImageCreateInfo::pname:usage. 51 * pname:flags is a bitmask of elink:VkImageCreateFlagBits specifying 52 additional parameters of the image, corresponding to 53 slink:VkImageCreateInfo::pname:flags. 54 * pname:pImageFormatProperties is a pointer to a 55 slink:VkImageFormatProperties structure in which capabilities are 56 returned. 57 58The pname:format, pname:type, pname:tiling, pname:usage, and pname:flags 59parameters correspond to parameters that would be consumed by 60flink:vkCreateImage (as members of slink:VkImageCreateInfo). 61 62If pname:format is not a supported image format, or if the combination of 63pname:format, pname:type, pname:tiling, pname:usage, and pname:flags is not 64supported for images, then fname:vkGetPhysicalDeviceImageFormatProperties 65returns ename:VK_ERROR_FORMAT_NOT_SUPPORTED. 66 67The limitations on an image format that are reported by 68fname:vkGetPhysicalDeviceImageFormatProperties have the following property: 69if code:usage1 and code:usage2 of type tlink:VkImageUsageFlags are such that 70the bits set in code:usage1 are a subset of the bits set in code:usage2, and 71code:flags1 and code:flags2 of type tlink:VkImageCreateFlags are such that 72the bits set in code:flags1 are a subset of the bits set in code:flags2, 73then the limitations for code:usage1 and code:flags1 must: be no more strict 74than the limitations for code:usage2 and code:flags2, for all values of 75pname:format, pname:type, and pname:tiling. 76 77ifdef::VK_EXT_image_drm_format_modifier[] 78.Valid Usage 79**** 80 * [[VUID-vkGetPhysicalDeviceImageFormatProperties-tiling-02248]] 81 pname:tiling must: not be ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT. 82 (Use flink:vkGetPhysicalDeviceImageFormatProperties2 instead) 83**** 84endif::VK_EXT_image_drm_format_modifier[] 85 86include::{generated}/validity/protos/vkGetPhysicalDeviceImageFormatProperties.txt[] 87-- 88 89[open,refpage='VkImageFormatProperties',desc='Structure specifying an image format properties',type='structs'] 90-- 91The sname:VkImageFormatProperties structure is defined as: 92 93include::{generated}/api/structs/VkImageFormatProperties.txt[] 94 95 * pname:maxExtent are the maximum image dimensions. 96 See the <<features-extentperimagetype,Allowed Extent Values>> section 97 below for how these values are constrained by pname:type. 98 * pname:maxMipLevels is the maximum number of mipmap levels. 99 pname:maxMipLevels must: be equal to the number of levels in the 100 complete mipmap chain based on the [eq]#pname:maxExtent.width#, 101 [eq]#pname:maxExtent.height#, and [eq]#pname:maxExtent.depth#, except 102 when one of the following conditions is true, in which case it may: 103 instead be `1`: 104 ** fname:vkGetPhysicalDeviceImageFormatProperties::pname:tiling was 105 ename:VK_IMAGE_TILING_LINEAR 106ifdef::VK_EXT_image_drm_format_modifier[] 107 ** slink:VkPhysicalDeviceImageFormatInfo2::pname:tiling was 108 ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT 109endif::VK_EXT_image_drm_format_modifier[] 110ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] 111 ** the slink:VkPhysicalDeviceImageFormatInfo2::pname:pNext chain included 112 a slink:VkPhysicalDeviceExternalImageFormatInfo structure with a handle 113 type included in the pname:handleTypes member for which mipmap image 114 support is not required 115endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] 116ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 117 ** image pname:format is one of the 118 <<formats-requiring-sampler-ycbcr-conversion, formats that require a 119 sampler Y'C~B~C~R~ conversion>> 120endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 121ifdef::VK_EXT_fragment_density_map[] 122 ** pname:flags contains ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT 123endif::VK_EXT_fragment_density_map[] 124 * pname:maxArrayLayers is the maximum number of array layers. 125 pname:maxArrayLayers must: be no less than 126 slink:VkPhysicalDeviceLimits::pname:maxImageArrayLayers, except when one 127 of the following conditions is true, in which case it may: instead be 128 `1`: 129 ** pname:tiling is ename:VK_IMAGE_TILING_LINEAR 130 ** pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL and pname:type is 131 ename:VK_IMAGE_TYPE_3D 132ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 133 ** pname:format is one of the 134 <<formats-requiring-sampler-ycbcr-conversion, formats that require a 135 sampler Y'C~B~C~R~ conversion>> 136endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 137ifdef::VK_EXT_image_drm_format_modifier[] 138 * If pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then 139 pname:maxArrayLayers must: not be 0. 140endif::VK_EXT_image_drm_format_modifier[] 141 * pname:sampleCounts is a bitmask of elink:VkSampleCountFlagBits 142 specifying all the supported sample counts for this image as described 143 <<features-supported-sample-counts, below>>. 144 * pname:maxResourceSize is an upper bound on the total image size in 145 bytes, inclusive of all image subresources. 146 Implementations may: have an address space limit on total size of a 147 resource, which is advertised by this property. 148 pname:maxResourceSize must: be at least 2^31^. 149 150[NOTE] 151.Note 152==== 153There is no mechanism to query the size of an image before creating it, to 154compare that size against pname:maxResourceSize. 155If an application attempts to create an image that exceeds this limit, the 156creation will fail and flink:vkCreateImage will return 157ename:VK_ERROR_OUT_OF_DEVICE_MEMORY. 158While the advertised limit must: be at least 2^31^, it may: not be possible 159to create an image that approaches that size, particularly for 160ename:VK_IMAGE_TYPE_1D. 161==== 162 163If the combination of parameters to 164fname:vkGetPhysicalDeviceImageFormatProperties is not supported by the 165implementation for use in flink:vkCreateImage, then all members of 166sname:VkImageFormatProperties will be filled with zero. 167 168[NOTE] 169.Note 170==== 171Filling sname:VkImageFormatProperties with zero for unsupported formats is 172an exception to the usual rule that output structures have undefined: 173contents on error. 174This exception was unintentional, but is preserved for backwards 175compatibility. 176==== 177 178include::{generated}/validity/structs/VkImageFormatProperties.txt[] 179-- 180 181ifdef::VK_NV_external_memory_capabilities[] 182include::{chapters}/VK_NV_external_memory_capabilities/external_image_format.txt[] 183endif::VK_NV_external_memory_capabilities[] 184 185ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 186 187[open,refpage='vkGetPhysicalDeviceImageFormatProperties2',desc='Lists physical device\'s image format capabilities',type='protos'] 188-- 189To query additional capabilities specific to image types, call: 190 191ifdef::VK_VERSION_1_1[] 192include::{generated}/api/protos/vkGetPhysicalDeviceImageFormatProperties2.txt[] 193endif::VK_VERSION_1_1[] 194 195ifdef::VK_VERSION_1_1+VK_KHR_get_physical_device_properties2[or the equivalent command] 196 197ifdef::VK_KHR_get_physical_device_properties2[] 198include::{generated}/api/protos/vkGetPhysicalDeviceImageFormatProperties2KHR.txt[] 199endif::VK_KHR_get_physical_device_properties2[] 200 201 * pname:physicalDevice is the physical device from which to query the 202 image capabilities. 203 * pname:pImageFormatInfo is a pointer to a 204 slink:VkPhysicalDeviceImageFormatInfo2 structure describing the 205 parameters that would be consumed by flink:vkCreateImage. 206 * pname:pImageFormatProperties is a pointer to a 207 slink:VkImageFormatProperties2 structure in which capabilities are 208 returned. 209 210fname:vkGetPhysicalDeviceImageFormatProperties2 behaves similarly to 211flink:vkGetPhysicalDeviceImageFormatProperties, with the ability to return 212extended information in a pname:pNext chain of output structures. 213 214ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 215.Valid Usage 216**** 217 * [[VUID-vkGetPhysicalDeviceImageFormatProperties2-pNext-01868]] 218 If the pname:pNext chain of pname:pImageFormatProperties includes a 219 slink:VkAndroidHardwareBufferUsageANDROID structure, the pname:pNext 220 chain of pname:pImageFormatInfo must: include a 221 slink:VkPhysicalDeviceExternalImageFormatInfo structure with 222 pname:handleType set to 223 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID 224**** 225endif::VK_ANDROID_external_memory_android_hardware_buffer[] 226 227include::{generated}/validity/protos/vkGetPhysicalDeviceImageFormatProperties2.txt[] 228-- 229 230[open,refpage='VkPhysicalDeviceImageFormatInfo2',desc='Structure specifying image creation parameters',type='structs'] 231-- 232The sname:VkPhysicalDeviceImageFormatInfo2 structure is defined as: 233 234include::{generated}/api/structs/VkPhysicalDeviceImageFormatInfo2.txt[] 235 236ifdef::VK_KHR_get_physical_device_properties2[] 237or the equivalent 238 239include::{generated}/api/structs/VkPhysicalDeviceImageFormatInfo2KHR.txt[] 240endif::VK_KHR_get_physical_device_properties2[] 241 242 * pname:sType is the type of this structure. 243 * pname:pNext is `NULL` or a pointer to a structure extending this 244 structure. 245 The pname:pNext chain of sname:VkPhysicalDeviceImageFormatInfo2 is used 246 to provide additional image parameters to 247 fname:vkGetPhysicalDeviceImageFormatProperties2. 248 * pname:format is a elink:VkFormat value indicating the image format, 249 corresponding to slink:VkImageCreateInfo::pname:format. 250 * pname:type is a elink:VkImageType value indicating the image type, 251 corresponding to slink:VkImageCreateInfo::pname:imageType. 252 * pname:tiling is a elink:VkImageTiling value indicating the image tiling, 253 corresponding to slink:VkImageCreateInfo::pname:tiling. 254 * pname:usage is a bitmask of elink:VkImageUsageFlagBits indicating the 255 intended usage of the image, corresponding to 256 slink:VkImageCreateInfo::pname:usage. 257 * pname:flags is a bitmask of elink:VkImageCreateFlagBits indicating 258 additional parameters of the image, corresponding to 259 slink:VkImageCreateInfo::pname:flags. 260 261The members of sname:VkPhysicalDeviceImageFormatInfo2 correspond to the 262arguments to flink:vkGetPhysicalDeviceImageFormatProperties, with 263pname:sType and pname:pNext added for extensibility. 264 265ifdef::VK_EXT_image_drm_format_modifier[] 266.Valid Usage 267**** 268 * [[VUID-VkPhysicalDeviceImageFormatInfo2-tiling-02249]] 269 pname:tiling must: be ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT if 270 and only if the pname:pNext chain includes 271 slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT 272 * [[VUID-VkPhysicalDeviceImageFormatInfo2-tiling-02313]] 273 If pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and 274 pname:flags contains ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, then the 275 pname:pNext chain must: include a slink:VkImageFormatListCreateInfo 276 structure with non-zero pname:viewFormatCount 277**** 278endif::VK_EXT_image_drm_format_modifier[] 279 280include::{generated}/validity/structs/VkPhysicalDeviceImageFormatInfo2.txt[] 281-- 282 283[open,refpage='VkImageFormatProperties2',desc='Structure specifying an image format properties',type='structs'] 284-- 285The sname:VkImageFormatProperties2 structure is defined as: 286 287include::{generated}/api/structs/VkImageFormatProperties2.txt[] 288 289ifdef::VK_KHR_get_physical_device_properties2[] 290or the equivalent 291 292include::{generated}/api/structs/VkImageFormatProperties2KHR.txt[] 293endif::VK_KHR_get_physical_device_properties2[] 294 295 * pname:sType is the type of this structure. 296 * pname:pNext is `NULL` or a pointer to a structure extending this 297 structure. 298 The pname:pNext chain of sname:VkImageFormatProperties2 is used to allow 299 the specification of additional capabilities to be returned from 300 fname:vkGetPhysicalDeviceImageFormatProperties2. 301 * pname:imageFormatProperties is a slink:VkImageFormatProperties structure 302 in which capabilities are returned. 303 304If the combination of parameters to 305fname:vkGetPhysicalDeviceImageFormatProperties2 is not supported by the 306implementation for use in flink:vkCreateImage, then all members of 307pname:imageFormatProperties will be filled with zero. 308 309[NOTE] 310.Note 311==== 312Filling pname:imageFormatProperties with zero for unsupported formats is an 313exception to the usual rule that output structures have undefined: contents 314on error. 315This exception was unintentional, but is preserved for backwards 316compatibility. 317This exeption only applies to pname:imageFormatProperties, not pname:sType, 318pname:pNext, or any structures chained from pname:pNext. 319==== 320 321include::{generated}/validity/structs/VkImageFormatProperties2.txt[] 322-- 323 324ifdef::VK_AMD_texture_gather_bias_lod[] 325[open,refpage='VkTextureLODGatherFormatPropertiesAMD',desc='Structure informing whether or not texture gather bias/LOD functionality is supported for a given image format and a given physical device.',type='structs'] 326-- 327To determine if texture gather functions that take explicit LOD and/or bias 328argument values can: be used with a given image format, add a 329slink:VkTextureLODGatherFormatPropertiesAMD structure to the pname:pNext 330chain of the slink:VkImageFormatProperties2 structure in a call to 331fname:vkGetPhysicalDeviceImageFormatProperties2. 332 333The sname:VkTextureLODGatherFormatPropertiesAMD structure is defined as: 334 335include::{generated}/api/structs/VkTextureLODGatherFormatPropertiesAMD.txt[] 336 337 * pname:sType is the type of this structure. 338 * pname:pNext is `NULL` or a pointer to a structure extending this 339 structure. 340 * pname:supportsTextureGatherLODBiasAMD tells if the image format can be 341 used with texture gather bias/LOD functions, as introduced by the 342 `apiext:VK_AMD_texture_gather_bias_lod` extension. 343 This field is set by the implementation. 344 User-specified value is ignored. 345 346include::{generated}/validity/structs/VkTextureLODGatherFormatPropertiesAMD.txt[] 347-- 348endif::VK_AMD_texture_gather_bias_lod[] 349 350ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] 351[open,refpage='VkPhysicalDeviceExternalImageFormatInfo',desc='Structure specifying external image creation parameters',type='structs'] 352-- 353To determine the image capabilities compatible with an external memory 354handle type, add a slink:VkPhysicalDeviceExternalImageFormatInfo structure 355to the pname:pNext chain of the slink:VkPhysicalDeviceImageFormatInfo2 356structure and a sname:VkExternalImageFormatProperties structure to the 357pname:pNext chain of the slink:VkImageFormatProperties2 structure. 358 359The sname:VkPhysicalDeviceExternalImageFormatInfo structure is defined as: 360 361include::{generated}/api/structs/VkPhysicalDeviceExternalImageFormatInfo.txt[] 362 363ifdef::VK_KHR_external_memory_capabilities[] 364or the equivalent 365 366include::{generated}/api/structs/VkPhysicalDeviceExternalImageFormatInfoKHR.txt[] 367endif::VK_KHR_external_memory_capabilities[] 368 369 * pname:sType is the type of this structure. 370 * pname:pNext is `NULL` or a pointer to a structure extending this 371 structure. 372 * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value 373 specifying the memory handle type that will be used with the memory 374 associated with the image. 375 376If pname:handleType is 0, flink:vkGetPhysicalDeviceImageFormatProperties2 377will behave as if slink:VkPhysicalDeviceExternalImageFormatInfo was not 378present, and slink:VkExternalImageFormatProperties will be ignored. 379 380If pname:handleType is not compatible with the pname:format, pname:type, 381pname:tiling, pname:usage, and pname:flags specified in 382slink:VkPhysicalDeviceImageFormatInfo2, then 383flink:vkGetPhysicalDeviceImageFormatProperties2 returns 384ename:VK_ERROR_FORMAT_NOT_SUPPORTED. 385 386include::{generated}/validity/structs/VkPhysicalDeviceExternalImageFormatInfo.txt[] 387-- 388 389[open,refpage='VkExternalMemoryHandleTypeFlagBits',desc='Bit specifying external memory handle types',type='enums'] 390-- 391Possible values of 392slink:VkPhysicalDeviceExternalImageFormatInfo::pname:handleType, specifying 393an external memory handle type, are: 394 395include::{generated}/api/enums/VkExternalMemoryHandleTypeFlagBits.txt[] 396 397ifdef::VK_KHR_external_memory_capabilities[] 398or the equivalent 399 400include::{generated}/api/enums/VkExternalMemoryHandleTypeFlagBitsKHR.txt[] 401endif::VK_KHR_external_memory_capabilities[] 402 403 * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT specifies a POSIX 404 file descriptor handle that has only limited valid usage outside of 405 Vulkan and other compatible APIs. 406 It must: be compatible with the POSIX system calls code:dup, code:dup2, 407 code:close, and the non-standard system call code:dup3. 408 Additionally, it must: be transportable over a socket using an 409 code:SCM_RIGHTS control message. 410 It owns a reference to the underlying memory resource represented by its 411 Vulkan memory object. 412 * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT specifies an NT 413 handle that has only limited valid usage outside of Vulkan and other 414 compatible APIs. 415 It must: be compatible with the functions code:DuplicateHandle, 416 code:CloseHandle, code:CompareObjectHandles, code:GetHandleInformation, 417 and code:SetHandleInformation. 418 It owns a reference to the underlying memory resource represented by its 419 Vulkan memory object. 420 * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT specifies a 421 global share handle that has only limited valid usage outside of Vulkan 422 and other compatible APIs. 423 It is not compatible with any native APIs. 424 It does not own a reference to the underlying memory resource 425 represented by its Vulkan memory object, and will therefore become 426 invalid when all Vulkan memory objects associated with it are destroyed. 427 * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT specifies an NT 428 handle returned by code:IDXGIResource1::code:CreateSharedHandle 429 referring to a Direct3D 10 or 11 texture resource. 430 It owns a reference to the memory used by the Direct3D resource. 431 * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT specifies a 432 global share handle returned by code:IDXGIResource::code:GetSharedHandle 433 referring to a Direct3D 10 or 11 texture resource. 434 It does not own a reference to the underlying Direct3D resource, and 435 will therefore become invalid when all Vulkan memory objects and 436 Direct3D resources associated with it are destroyed. 437 * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT specifies an NT 438 handle returned by code:ID3D12Device::code:CreateSharedHandle referring 439 to a Direct3D 12 heap resource. 440 It owns a reference to the resources used by the Direct3D heap. 441 * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT specifies an NT 442 handle returned by code:ID3D12Device::code:CreateSharedHandle referring 443 to a Direct3D 12 committed resource. 444 It owns a reference to the memory used by the Direct3D resource. 445ifdef::VK_EXT_external_memory_host[] 446 * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT specifies a 447 host pointer returned by a host memory allocation command. 448 It does not own a reference to the underlying memory resource, and will 449 therefore become invalid if the host memory is freed. 450 * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT 451 specifies a host pointer to _host mapped foreign memory_. 452 It does not own a reference to the underlying memory resource, and will 453 therefore become invalid if the foreign memory is unmapped or otherwise 454 becomes no longer available. 455endif::VK_EXT_external_memory_host[] 456ifdef::VK_EXT_external_memory_dma_buf[] 457 * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT is a file 458 descriptor for a Linux dma_buf. 459 It owns a reference to the underlying memory resource represented by its 460 Vulkan memory object. 461endif::VK_EXT_external_memory_dma_buf[] 462ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 463 * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID 464 specifies an basetype:AHardwareBuffer object defined by the Android NDK. 465 See <<memory-external-android-hardware-buffer,Android Hardware Buffers>> 466 for more details of this handle type. 467endif::VK_ANDROID_external_memory_android_hardware_buffer[] 468ifdef::VK_FUCHSIA_external_memory[] 469 * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA is a Zircon 470 handle to a virtual memory object. 471endif::VK_FUCHSIA_external_memory[] 472ifdef::VK_NV_external_memory_rdma[] 473 * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_RDMA_ADDRESS_BIT_NV is a handle to 474 an allocation accessible by remote devices. 475 It owns a reference to the underlying memory resource represented by its 476 Vulkan memory object. 477endif::VK_NV_external_memory_rdma[] 478 479<<< 480 481Some external memory handle types can only be shared within the same 482underlying physical device and/or the same driver version, as defined in the 483following table: 484 485[[external-memory-handle-types-compatibility]] 486.External memory handle types compatibility 487|==== 488| Handle type | sname:VkPhysicalDeviceIDProperties{wbro}::pname:driverUUID | sname:VkPhysicalDeviceIDProperties{wbro}::pname:deviceUUID 489| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT | Must match | Must match 490| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT | Must match | Must match 491| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT | Must match | Must match 492| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT | Must match | Must match 493| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT | Must match | Must match 494| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT | Must match | Must match 495| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT | Must match | Must match 496ifdef::VK_EXT_external_memory_host[] 497| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT | No restriction | No restriction 498| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT | No restriction | No restriction 499endif::VK_EXT_external_memory_host[] 500ifdef::VK_EXT_external_memory_dma_buf[] 501| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT | No restriction | No restriction 502endif::VK_EXT_external_memory_dma_buf[] 503ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 504| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID | No restriction | No restriction 505endif::VK_ANDROID_external_memory_android_hardware_buffer[] 506ifdef::VK_FUCHSIA_external_memory[] 507| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA | No restriction | No restriction 508endif::VK_FUCHSIA_external_memory[] 509ifdef::VK_NV_external_memory_rdma[] 510| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_RDMA_ADDRESS_BIT_NV | No restriction | No restriction 511endif::VK_NV_external_memory_rdma[] 512|==== 513 514ifdef::VK_EXT_external_memory_host[] 515[NOTE] 516.Note 517==== 518The above table does not restrict the drivers and devices with which 519ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT and 520ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT may: 521be shared, as these handle types inherently mean memory that does not come 522from the same device, as they import memory from the host or a foreign 523device, respectively. 524==== 525endif::VK_EXT_external_memory_host[] 526 527ifdef::VK_EXT_external_memory_dma_buf[] 528[NOTE] 529.Note 530==== 531Even though the above table does not restrict the drivers and devices with 532which ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT may: be shared, 533query mechanisms exist in the Vulkan API that prevent the import of 534incompatible dma-bufs (such as flink:vkGetMemoryFdPropertiesKHR) and that 535prevent incompatible usage of dma-bufs (such as 536slink:VkPhysicalDeviceExternalBufferInfo and 537slink:VkPhysicalDeviceExternalImageFormatInfo). 538==== 539endif::VK_EXT_external_memory_dma_buf[] 540-- 541 542[open,refpage='VkExternalMemoryHandleTypeFlags',desc='Bitmask of VkExternalMemoryHandleTypeFlagBits',type='flags'] 543-- 544include::{generated}/api/flags/VkExternalMemoryHandleTypeFlags.txt[] 545 546ifdef::VK_KHR_external_memory_capabilities[] 547or the equivalent 548 549include::{generated}/api/flags/VkExternalMemoryHandleTypeFlagsKHR.txt[] 550endif::VK_KHR_external_memory_capabilities[] 551 552tname:VkExternalMemoryHandleTypeFlags is a bitmask type for setting a mask 553of zero or more elink:VkExternalMemoryHandleTypeFlagBits. 554-- 555 556[open,refpage='VkExternalImageFormatProperties',desc='Structure specifying supported external handle properties',type='structs'] 557-- 558The sname:VkExternalImageFormatProperties structure is defined as: 559 560include::{generated}/api/structs/VkExternalImageFormatProperties.txt[] 561 562ifdef::VK_KHR_external_memory_capabilities[] 563or the equivalent 564 565include::{generated}/api/structs/VkExternalImageFormatPropertiesKHR.txt[] 566endif::VK_KHR_external_memory_capabilities[] 567 568 * pname:sType is the type of this structure. 569 * pname:pNext is `NULL` or a pointer to a structure extending this 570 structure. 571 * pname:externalMemoryProperties is a slink:VkExternalMemoryProperties 572 structure specifying various capabilities of the external handle type 573 when used with the specified image creation parameters. 574 575include::{generated}/validity/structs/VkExternalImageFormatProperties.txt[] 576-- 577 578[open,refpage='VkExternalMemoryProperties',desc='Structure specifying external memory handle type capabilities',type='structs'] 579-- 580The sname:VkExternalMemoryProperties structure is defined as: 581 582include::{generated}/api/structs/VkExternalMemoryProperties.txt[] 583 584ifdef::VK_KHR_external_memory_capabilities[] 585or the equivalent 586 587include::{generated}/api/structs/VkExternalMemoryPropertiesKHR.txt[] 588endif::VK_KHR_external_memory_capabilities[] 589 590 * pname:externalMemoryFeatures is a bitmask of 591 elink:VkExternalMemoryFeatureFlagBits specifying the features of 592 pname:handleType. 593 * pname:exportFromImportedHandleTypes is a bitmask of 594 elink:VkExternalMemoryHandleTypeFlagBits specifying which types of 595 imported handle pname:handleType can: be exported from. 596 * pname:compatibleHandleTypes is a bitmask of 597 elink:VkExternalMemoryHandleTypeFlagBits specifying handle types which 598 can: be specified at the same time as pname:handleType when creating an 599 image compatible with external memory. 600 601pname:compatibleHandleTypes must: include at least pname:handleType. 602Inclusion of a handle type in pname:compatibleHandleTypes does not imply the 603values returned in slink:VkImageFormatProperties2 will be the same when 604slink:VkPhysicalDeviceExternalImageFormatInfo::pname:handleType is set to 605that type. 606The application is responsible for querying the capabilities of all handle 607types intended for concurrent use in a single image and intersecting them to 608obtain the compatible set of capabilities. 609 610include::{generated}/validity/structs/VkExternalMemoryProperties.txt[] 611-- 612 613[open,refpage='VkExternalMemoryFeatureFlagBits',desc='Bitmask specifying features of an external memory handle type',type='enums'] 614-- 615Bits which may: be set in 616slink:VkExternalMemoryProperties::pname:externalMemoryFeatures, specifying 617features of an external memory handle type, are: 618 619include::{generated}/api/enums/VkExternalMemoryFeatureFlagBits.txt[] 620 621ifdef::VK_KHR_external_memory_capabilities[] 622or the equivalent 623 624include::{generated}/api/enums/VkExternalMemoryFeatureFlagBitsKHR.txt[] 625endif::VK_KHR_external_memory_capabilities[] 626 627 * ename:VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT specifies that 628 images or buffers created with the specified parameters and handle type 629 must: use the mechanisms defined by slink:VkMemoryDedicatedRequirements 630 and slink:VkMemoryDedicatedAllocateInfo to create (or import) a 631 dedicated allocation for the image or buffer. 632 * ename:VK_EXTERNAL_MEMORY_FEATURE_EXPORTABLE_BIT specifies that handles 633 of this type can: be exported from Vulkan memory objects. 634 * ename:VK_EXTERNAL_MEMORY_FEATURE_IMPORTABLE_BIT specifies that handles 635 of this type can: be imported as Vulkan memory objects. 636 637Because their semantics in external APIs roughly align with that of an image 638or buffer with a dedicated allocation in Vulkan, implementations are 639required: to report ename:VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT for 640the following external handle types: 641 642 * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT 643 * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT 644 * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT 645ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 646 * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID 647 for images only 648endif::VK_ANDROID_external_memory_android_hardware_buffer[] 649 650ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 651Implementations must: not report 652ename:VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT for buffers with 653external handle type 654ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID. 655endif::VK_ANDROID_external_memory_android_hardware_buffer[] 656ifdef::VK_EXT_external_memory_host[] 657Implementations must: not report 658ename:VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT for images or buffers 659with external handle type 660ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT, or 661ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT. 662endif::VK_EXT_external_memory_host[] 663 664-- 665 666[open,refpage='VkExternalMemoryFeatureFlags',desc='Bitmask of VkExternalMemoryFeatureFlagBits',type='flags'] 667-- 668include::{generated}/api/flags/VkExternalMemoryFeatureFlags.txt[] 669 670ifdef::VK_KHR_external_memory_capabilities[] 671or the equivalent 672 673include::{generated}/api/flags/VkExternalMemoryFeatureFlagsKHR.txt[] 674endif::VK_KHR_external_memory_capabilities[] 675 676tname:VkExternalMemoryFeatureFlags is a bitmask type for setting a mask of 677zero or more elink:VkExternalMemoryFeatureFlagBits. 678-- 679 680endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] 681 682ifdef::VK_EXT_image_drm_format_modifier[] 683[open,refpage='VkPhysicalDeviceImageDrmFormatModifierInfoEXT',desc='Structure specifying a DRM format modifier as image creation parameter',type='structs'] 684-- 685To query the image capabilities that are compatible with a 686<<glossary-drm-format-modifier,Linux DRM format modifier>>, set 687slink:VkPhysicalDeviceImageFormatInfo2::pname:tiling to 688ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and add a 689slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT structure to the 690pname:pNext chain of slink:VkPhysicalDeviceImageFormatInfo2. 691 692The slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT structure is defined 693as: 694 695include::{generated}/api/structs/VkPhysicalDeviceImageDrmFormatModifierInfoEXT.txt[] 696 697 * pname:sType is the type of this structure. 698 * pname:pNext is `NULL` or a pointer to a structure extending this 699 structure. 700 * pname:drmFormatModifier is the image's _Linux DRM format modifier_, 701 corresponding to 702 slink:VkImageDrmFormatModifierExplicitCreateInfoEXT::pname:modifier or 703 to slink:VkImageDrmFormatModifierListCreateInfoEXT::pname:pModifiers. 704 * pname:sharingMode specifies how the image will be accessed by multiple 705 queue families. 706 * pname:queueFamilyIndexCount is the number of entries in the 707 pname:pQueueFamilyIndices array. 708 * pname:pQueueFamilyIndices is a pointer to an array of queue families 709 that will access the image. 710 It is ignored if pname:sharingMode is not 711 ename:VK_SHARING_MODE_CONCURRENT. 712 713If the pname:drmFormatModifier is incompatible with the parameters specified 714in slink:VkPhysicalDeviceImageFormatInfo2 and its pname:pNext chain, then 715flink:vkGetPhysicalDeviceImageFormatProperties2 returns 716ename:VK_ERROR_FORMAT_NOT_SUPPORTED. 717The implementation must: support the query of any pname:drmFormatModifier, 718including unknown and invalid modifier values. 719 720.Valid Usage 721**** 722 * [[VUID-VkPhysicalDeviceImageDrmFormatModifierInfoEXT-sharingMode-02314]] 723 If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, then 724 pname:pQueueFamilyIndices must: be a valid pointer to an array of 725 pname:queueFamilyIndexCount code:uint32_t values 726 * [[VUID-VkPhysicalDeviceImageDrmFormatModifierInfoEXT-sharingMode-02315]] 727 If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, then 728 pname:queueFamilyIndexCount must: be greater than `1` 729 * [[VUID-VkPhysicalDeviceImageDrmFormatModifierInfoEXT-sharingMode-02316]] 730 If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, each element 731 of pname:pQueueFamilyIndices must: be unique and must: be less than the 732 pname:pQueueFamilyPropertyCount returned by 733 flink:vkGetPhysicalDeviceQueueFamilyProperties2 for the 734 pname:physicalDevice that was used to create pname:device 735**** 736 737include::{generated}/validity/structs/VkPhysicalDeviceImageDrmFormatModifierInfoEXT.txt[] 738-- 739endif::VK_EXT_image_drm_format_modifier[] 740 741ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 742 743[open,refpage='VkSamplerYcbcrConversionImageFormatProperties',desc='Structure specifying combined image sampler descriptor count for multi-planar images',type='structs'] 744-- 745To determine the number of combined image samplers required to support a 746multi-planar format, add slink:VkSamplerYcbcrConversionImageFormatProperties 747to the pname:pNext chain of the slink:VkImageFormatProperties2 structure in 748a call to fname:vkGetPhysicalDeviceImageFormatProperties2. 749 750The sname:VkSamplerYcbcrConversionImageFormatProperties structure is defined 751as: 752 753include::{generated}/api/structs/VkSamplerYcbcrConversionImageFormatProperties.txt[] 754 755ifdef::VK_KHR_sampler_ycbcr_conversion[] 756or the equivalent 757 758include::{generated}/api/structs/VkSamplerYcbcrConversionImageFormatPropertiesKHR.txt[] 759endif::VK_KHR_sampler_ycbcr_conversion[] 760 761 * pname:sType is the type of this structure. 762 * pname:pNext is `NULL` or a pointer to a structure extending this 763 structure. 764 * pname:combinedImageSamplerDescriptorCount is the number of combined 765 image sampler descriptors that the implementation uses to access the 766 format. 767 768include::{generated}/validity/structs/VkSamplerYcbcrConversionImageFormatProperties.txt[] 769-- 770 771pname:combinedImageSamplerDescriptorCount is a number between 1 and the 772number of planes in the format. 773A descriptor set layout binding with immutable {YCbCr} conversion samplers 774will have a maximum pname:combinedImageSamplerDescriptorCount which is the 775maximum across all formats supported by its samplers of the 776pname:combinedImageSamplerDescriptorCount for each format. 777Descriptor sets with that layout will internally use that maximum 778pname:combinedImageSamplerDescriptorCount descriptors for each descriptor in 779the binding. 780This expanded number of descriptors will be consumed from the descriptor 781pool when a descriptor set is allocated, and counts towards the 782pname:maxDescriptorSetSamplers, pname:maxDescriptorSetSampledImages, 783pname:maxPerStageDescriptorSamplers, and 784pname:maxPerStageDescriptorSampledImages limits. 785 786.Note 787[NOTE] 788==== 789All descriptors in a binding use the same maximum 790pname:combinedImageSamplerDescriptorCount descriptors to allow 791implementations to use a uniform stride for dynamic indexing of the 792descriptors in the binding. 793 794For example, consider a descriptor set layout binding with two descriptors 795and immutable samplers for multi-planar formats that have 796sname:VkSamplerYcbcrConversionImageFormatProperties::pname:combinedImageSamplerDescriptorCount 797values of `2` and `3` respectively. 798There are two descriptors in the binding and the maximum 799pname:combinedImageSamplerDescriptorCount is `3`, so descriptor sets with 800this layout consume `6` descriptors from the descriptor pool. 801To create a descriptor pool that allows allocating four descriptor sets with 802this layout, pname:descriptorCount must be at least `24`. 803==== 804 805endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 806 807ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 808 809[open,refpage='VkAndroidHardwareBufferUsageANDROID',desc='Struct containing Android hardware buffer usage flags',type='structs'] 810-- 811To obtain optimal Android hardware buffer usage flags for specific image 812creation parameters, add a sname:VkAndroidHardwareBufferUsageANDROID 813structure to the pname:pNext chain of a slink:VkImageFormatProperties2 814structure passed to flink:vkGetPhysicalDeviceImageFormatProperties2. 815This structure is defined as: 816 817include::{generated}/api/structs/VkAndroidHardwareBufferUsageANDROID.txt[] 818 819 * pname:sType is the type of this structure. 820 * pname:pNext is `NULL` or a pointer to a structure extending this 821 structure. 822 * pname:androidHardwareBufferUsage returns the Android hardware buffer 823 usage flags. 824 825The pname:androidHardwareBufferUsage field must: include Android hardware 826buffer usage flags listed in the 827<<memory-external-android-hardware-buffer-usage,AHardwareBuffer Usage 828Equivalence>> table when the corresponding Vulkan image usage or image 829creation flags are included in the pname:usage or pname:flags fields of 830slink:VkPhysicalDeviceImageFormatInfo2. 831It must: include at least one GPU usage flag 832(code:AHARDWAREBUFFER_USAGE_GPU_*), even if none of the corresponding Vulkan 833usages or flags are requested. 834 835.Note 836[NOTE] 837==== 838Requiring at least one GPU usage flag ensures that Android hardware buffer 839memory will be allocated in a memory pool accessible to the Vulkan 840implementation, and that specializing the memory layout based on usage flags 841does not prevent it from being compatible with Vulkan. 842Implementations may: avoid unnecessary restrictions caused by this 843requirement by using vendor usage flags to indicate that only the Vulkan 844uses indicated in slink:VkImageFormatProperties2 are required. 845==== 846 847include::{generated}/validity/structs/VkAndroidHardwareBufferUsageANDROID.txt[] 848-- 849 850endif::VK_ANDROID_external_memory_android_hardware_buffer[] 851 852ifdef::VK_EXT_filter_cubic[] 853 854 855 856To determine if cubic filtering can be used with a given image format and a 857given image view type add a 858slink:VkPhysicalDeviceImageViewImageFormatInfoEXT structure to the 859pname:pNext chain of the slink:VkPhysicalDeviceImageFormatInfo2 structure, 860and a slink:VkFilterCubicImageViewImageFormatPropertiesEXT structure to the 861pname:pNext chain of the slink:VkImageFormatProperties2 structure. 862 863[open,refpage='VkPhysicalDeviceImageViewImageFormatInfoEXT',desc='Structure for providing image view type',type='structs'] 864-- 865The sname:VkPhysicalDeviceImageViewImageFormatInfoEXT structure is defined 866as: 867 868include::{generated}/api/structs/VkPhysicalDeviceImageViewImageFormatInfoEXT.txt[] 869 870 * pname:sType is the type of this structure. 871 * pname:pNext is `NULL` or a pointer to a structure extending this 872 structure. 873 * pname:imageViewType is a elink:VkImageViewType value specifying the type 874 of the image view. 875 876include::{generated}/validity/structs/VkPhysicalDeviceImageViewImageFormatInfoEXT.txt[] 877-- 878 879[open,refpage='VkFilterCubicImageViewImageFormatPropertiesEXT',desc='Structure for querying cubic filtering capabilities of an image view type',type='structs'] 880-- 881The sname:VkFilterCubicImageViewImageFormatPropertiesEXT structure is 882defined as: 883 884include::{generated}/api/structs/VkFilterCubicImageViewImageFormatPropertiesEXT.txt[] 885 886 * pname:sType is the type of this structure. 887 * pname:pNext is `NULL` or a pointer to a structure extending this 888 structure. 889 * pname:filterCubic tells if image format, image type and image view type 890 can: be used with cubic filtering. 891 This field is set by the implementation. 892 User-specified value is ignored. 893 * pname:filterCubicMinmax tells if image format, image type and image view 894 type can: be used with cubic filtering and minmax filtering. 895 This field is set by the implementation. 896 User-specified value is ignored. 897 898include::{generated}/validity/structs/VkFilterCubicImageViewImageFormatPropertiesEXT.txt[] 899 900.Valid Usage 901**** 902 * [[VUID-VkFilterCubicImageViewImageFormatPropertiesEXT-pNext-02627]] 903 If the pname:pNext chain of the slink:VkImageFormatProperties2 structure 904 includes a slink:VkFilterCubicImageViewImageFormatPropertiesEXT 905 structure, the pname:pNext chain of the 906 slink:VkPhysicalDeviceImageFormatInfo2 structure must: include a 907 slink:VkPhysicalDeviceImageViewImageFormatInfoEXT structure with an 908 pname:imageViewType that is compatible with pname:imageType 909**** 910-- 911 912endif::VK_EXT_filter_cubic[] 913 914endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 915 916 917[[features-supported-sample-counts]] 918=== Supported Sample Counts 919fname:vkGetPhysicalDeviceImageFormatProperties returns a bitmask of 920elink:VkSampleCountFlagBits in pname:sampleCounts specifying the supported 921sample counts for the image parameters. 922 923pname:sampleCounts will be set to ename:VK_SAMPLE_COUNT_1_BIT if at least 924one of the following conditions is true: 925 926 * pname:tiling is ename:VK_IMAGE_TILING_LINEAR 927 * pname:type is not ename:VK_IMAGE_TYPE_2D 928 * pname:flags contains ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT 929 * Neither the ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT flag nor the 930 ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT flag in 931 sname:VkFormatProperties::pname:optimalTilingFeatures returned by 932 flink:vkGetPhysicalDeviceFormatProperties is set 933ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] 934 * slink:VkPhysicalDeviceExternalImageFormatInfo::pname:handleType is an 935 external handle type for which multisampled image support is not 936 required. 937endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] 938ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 939 * pname:format is one of the <<formats-requiring-sampler-ycbcr-conversion, 940 formats that require a sampler Y'C~B~C~R~ conversion>> 941endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 942ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 943 * pname:usage contains 944 ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR 945endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 946ifdef::VK_EXT_fragment_density_map[] 947 * pname:usage contains ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT 948endif::VK_EXT_fragment_density_map[] 949 950Otherwise, the bits set in pname:sampleCounts will be the sample counts 951supported for the specified values of pname:usage and pname:format. 952For each bit set in pname:usage, the supported sample counts relate to the 953limits in sname:VkPhysicalDeviceLimits as follows: 954 955 * If pname:usage includes ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT and 956 pname:format is a floating- or fixed-point color format, a superset of 957 sname:VkPhysicalDeviceLimits::pname:framebufferColorSampleCounts 958ifdef::VK_VERSION_1_2[] 959 * If pname:usage includes ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT and 960 pname:format is an integer format, a superset of 961 sname:VkPhysicalDeviceVulkan12Properties::pname:framebufferIntegerColorSampleCounts 962endif::VK_VERSION_1_2[] 963 * If pname:usage includes 964 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and pname:format 965 includes a depth aspect, a superset of 966 sname:VkPhysicalDeviceLimits::pname:framebufferDepthSampleCounts 967 * If pname:usage includes 968 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and pname:format 969 includes a stencil aspect, a superset of 970 sname:VkPhysicalDeviceLimits::pname:framebufferStencilSampleCounts 971 * If pname:usage includes ename:VK_IMAGE_USAGE_SAMPLED_BIT, and 972 pname:format includes a color aspect, a superset of 973 sname:VkPhysicalDeviceLimits::pname:sampledImageColorSampleCounts 974 * If pname:usage includes ename:VK_IMAGE_USAGE_SAMPLED_BIT, and 975 pname:format includes a depth aspect, a superset of 976 sname:VkPhysicalDeviceLimits::pname:sampledImageDepthSampleCounts 977 * If pname:usage includes ename:VK_IMAGE_USAGE_SAMPLED_BIT, and 978 pname:format is an integer format, a superset of 979 sname:VkPhysicalDeviceLimits::pname:sampledImageIntegerSampleCounts 980 * If pname:usage includes ename:VK_IMAGE_USAGE_STORAGE_BIT, a superset of 981 sname:VkPhysicalDeviceLimits::pname:storageImageSampleCounts 982 983If multiple bits are set in pname:usage, pname:sampleCounts will be the 984intersection of the per-usage values described above. 985 986If none of the bits described above are set in pname:usage, then there is no 987corresponding limit in sname:VkPhysicalDeviceLimits. 988In this case, pname:sampleCounts must: include at least 989ename:VK_SAMPLE_COUNT_1_BIT. 990 991 992[[features-extentperimagetype]] 993=== Allowed Extent Values Based On Image Type 994 995Implementations may: support extent values larger than the <<limits-minmax, 996required minimum/maximum values>> for certain types of images. 997slink:VkImageFormatProperties::pname:maxExtent for each type is subject to 998the constraints below. 999 1000[NOTE] 1001.Note 1002==== 1003Implementations must: support images with dimensions up to the 1004<<limits-minmax, required minimum/maximum values>> for all types of images. 1005It follows that the query for additional capabilities must: return extent 1006values that are at least as large as the required values. 1007==== 1008 1009For ename:VK_IMAGE_TYPE_1D: 1010 1011 * [eq]#pname:maxExtent.width {geq} 1012 slink:VkPhysicalDeviceLimits::pname:maxImageDimension1D# 1013 * [eq]#pname:maxExtent.height = 1# 1014 * [eq]#pname:maxExtent.depth = 1# 1015 1016For ename:VK_IMAGE_TYPE_2D when pname:flags does not contain 1017ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT: 1018 1019 * [eq]#pname:maxExtent.width {geq} 1020 slink:VkPhysicalDeviceLimits::pname:maxImageDimension2D# 1021 * [eq]#pname:maxExtent.height {geq} 1022 slink:VkPhysicalDeviceLimits::pname:maxImageDimension2D# 1023 * [eq]#pname:maxExtent.depth = 1# 1024 1025For ename:VK_IMAGE_TYPE_2D when pname:flags contains 1026ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT: 1027 1028 * [eq]#pname:maxExtent.width {geq} 1029 slink:VkPhysicalDeviceLimits::pname:maxImageDimensionCube# 1030 * [eq]#pname:maxExtent.height {geq} 1031 slink:VkPhysicalDeviceLimits::pname:maxImageDimensionCube# 1032 * [eq]#pname:maxExtent.depth = 1# 1033 1034For ename:VK_IMAGE_TYPE_3D: 1035 1036 * [eq]#pname:maxExtent.width {geq} 1037 slink:VkPhysicalDeviceLimits::pname:maxImageDimension3D# 1038 * [eq]#pname:maxExtent.height {geq} 1039 slink:VkPhysicalDeviceLimits::pname:maxImageDimension3D# 1040 * [eq]#pname:maxExtent.depth {geq} 1041 slink:VkPhysicalDeviceLimits::pname:maxImageDimension3D# 1042 1043 1044ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] 1045[[capabilities-buffer]] 1046== Additional Buffer Capabilities 1047 1048[open,refpage='vkGetPhysicalDeviceExternalBufferProperties',desc='Query external handle types supported by buffers',type='protos'] 1049-- 1050To query the external handle types supported by buffers, call: 1051 1052ifdef::VK_VERSION_1_1[] 1053include::{generated}/api/protos/vkGetPhysicalDeviceExternalBufferProperties.txt[] 1054endif::VK_VERSION_1_1[] 1055 1056ifdef::VK_VERSION_1_1+VK_KHR_external_memory_capabilities[or the equivalent command] 1057 1058ifdef::VK_KHR_external_memory_capabilities[] 1059include::{generated}/api/protos/vkGetPhysicalDeviceExternalBufferPropertiesKHR.txt[] 1060endif::VK_KHR_external_memory_capabilities[] 1061 1062 * pname:physicalDevice is the physical device from which to query the 1063 buffer capabilities. 1064 * pname:pExternalBufferInfo is a pointer to a 1065 slink:VkPhysicalDeviceExternalBufferInfo structure describing the 1066 parameters that would be consumed by flink:vkCreateBuffer. 1067 * pname:pExternalBufferProperties is a pointer to a 1068 slink:VkExternalBufferProperties structure in which capabilities are 1069 returned. 1070 1071include::{generated}/validity/protos/vkGetPhysicalDeviceExternalBufferProperties.txt[] 1072-- 1073 1074[open,refpage='VkPhysicalDeviceExternalBufferInfo',desc='Structure specifying buffer creation parameters',type='structs'] 1075-- 1076The sname:VkPhysicalDeviceExternalBufferInfo structure is defined as: 1077 1078include::{generated}/api/structs/VkPhysicalDeviceExternalBufferInfo.txt[] 1079 1080ifdef::VK_KHR_external_memory_capabilities[] 1081or the equivalent 1082 1083include::{generated}/api/structs/VkPhysicalDeviceExternalBufferInfoKHR.txt[] 1084endif::VK_KHR_external_memory_capabilities[] 1085 1086 * pname:sType is the type of this structure. 1087 * pname:pNext is `NULL` or a pointer to a structure extending this 1088 structure. 1089 * pname:flags is a bitmask of elink:VkBufferCreateFlagBits describing 1090 additional parameters of the buffer, corresponding to 1091 slink:VkBufferCreateInfo::pname:flags. 1092 * pname:usage is a bitmask of elink:VkBufferUsageFlagBits describing the 1093 intended usage of the buffer, corresponding to 1094 slink:VkBufferCreateInfo::pname:usage. 1095 * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value 1096 specifying the memory handle type that will be used with the memory 1097 associated with the buffer. 1098 1099include::{generated}/validity/structs/VkPhysicalDeviceExternalBufferInfo.txt[] 1100-- 1101 1102[open,refpage='VkExternalBufferProperties',desc='Structure specifying supported external handle capabilities',type='structs'] 1103-- 1104The sname:VkExternalBufferProperties structure is defined as: 1105 1106include::{generated}/api/structs/VkExternalBufferProperties.txt[] 1107 1108ifdef::VK_KHR_external_memory_capabilities[] 1109or the equivalent 1110 1111include::{generated}/api/structs/VkExternalBufferPropertiesKHR.txt[] 1112endif::VK_KHR_external_memory_capabilities[] 1113 1114 * pname:sType is the type of this structure. 1115 * pname:pNext is `NULL` or a pointer to a structure extending this 1116 structure. 1117 * pname:externalMemoryProperties is a slink:VkExternalMemoryProperties 1118 structure specifying various capabilities of the external handle type 1119 when used with the specified buffer creation parameters. 1120 1121include::{generated}/validity/structs/VkExternalBufferProperties.txt[] 1122-- 1123endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] 1124 1125 1126ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[] 1127[[capabilities-semaphore]] 1128== Optional Semaphore Capabilities 1129 1130[open,refpage='vkGetPhysicalDeviceExternalSemaphoreProperties',desc='Function for querying external semaphore handle capabilities.',type='protos'] 1131-- 1132Semaphores may: support import and export of their 1133<<synchronization-semaphores-payloads, payload>> to external handles. 1134To query the external handle types supported by semaphores, call: 1135 1136ifdef::VK_VERSION_1_1[] 1137include::{generated}/api/protos/vkGetPhysicalDeviceExternalSemaphoreProperties.txt[] 1138endif::VK_VERSION_1_1[] 1139 1140ifdef::VK_VERSION_1_1+VK_KHR_external_semaphore_capabilities[or the equivalent command] 1141 1142ifdef::VK_KHR_external_semaphore_capabilities[] 1143include::{generated}/api/protos/vkGetPhysicalDeviceExternalSemaphorePropertiesKHR.txt[] 1144endif::VK_KHR_external_semaphore_capabilities[] 1145 1146 * pname:physicalDevice is the physical device from which to query the 1147 semaphore capabilities. 1148 * pname:pExternalSemaphoreInfo is a pointer to a 1149 slink:VkPhysicalDeviceExternalSemaphoreInfo structure describing the 1150 parameters that would be consumed by flink:vkCreateSemaphore. 1151 * pname:pExternalSemaphoreProperties is a pointer to a 1152 slink:VkExternalSemaphoreProperties structure in which capabilities are 1153 returned. 1154 1155include::{generated}/validity/protos/vkGetPhysicalDeviceExternalSemaphoreProperties.txt[] 1156-- 1157 1158[open,refpage='VkPhysicalDeviceExternalSemaphoreInfo',desc='Structure specifying semaphore creation parameters.',type='structs'] 1159-- 1160The sname:VkPhysicalDeviceExternalSemaphoreInfo structure is defined as: 1161 1162include::{generated}/api/structs/VkPhysicalDeviceExternalSemaphoreInfo.txt[] 1163 1164ifdef::VK_KHR_external_semaphore_capabilities[] 1165or the equivalent 1166 1167include::{generated}/api/structs/VkPhysicalDeviceExternalSemaphoreInfoKHR.txt[] 1168endif::VK_KHR_external_semaphore_capabilities[] 1169 1170 * pname:sType is the type of this structure. 1171 * pname:pNext is `NULL` or a pointer to a structure extending this 1172 structure. 1173 * pname:handleType is a elink:VkExternalSemaphoreHandleTypeFlagBits value 1174 specifying the external semaphore handle type for which capabilities 1175 will be returned. 1176 1177include::{generated}/validity/structs/VkPhysicalDeviceExternalSemaphoreInfo.txt[] 1178-- 1179 1180[open,refpage='VkExternalSemaphoreHandleTypeFlagBits',desc='Bitmask of valid external semaphore handle types',type='enums'] 1181-- 1182Bits which may: be set in 1183slink:VkPhysicalDeviceExternalSemaphoreInfo::pname:handleType, specifying an 1184external semaphore handle type, are: 1185 1186include::{generated}/api/enums/VkExternalSemaphoreHandleTypeFlagBits.txt[] 1187 1188ifdef::VK_KHR_external_semaphore_capabilities[] 1189or the equivalent 1190 1191include::{generated}/api/enums/VkExternalSemaphoreHandleTypeFlagBitsKHR.txt[] 1192endif::VK_KHR_external_semaphore_capabilities[] 1193 1194 * ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT specifies a POSIX 1195 file descriptor handle that has only limited valid usage outside of 1196 Vulkan and other compatible APIs. 1197 It must: be compatible with the POSIX system calls code:dup, code:dup2, 1198 code:close, and the non-standard system call code:dup3. 1199 Additionally, it must: be transportable over a socket using an 1200 code:SCM_RIGHTS control message. 1201 It owns a reference to the underlying synchronization primitive 1202 represented by its Vulkan semaphore object. 1203 * ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT specifies an NT 1204 handle that has only limited valid usage outside of Vulkan and other 1205 compatible APIs. 1206 It must: be compatible with the functions code:DuplicateHandle, 1207 code:CloseHandle, code:CompareObjectHandles, code:GetHandleInformation, 1208 and code:SetHandleInformation. 1209 It owns a reference to the underlying synchronization primitive 1210 represented by its Vulkan semaphore object. 1211 * ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT specifies a 1212 global share handle that has only limited valid usage outside of Vulkan 1213 and other compatible APIs. 1214 It is not compatible with any native APIs. 1215 It does not own a reference to the underlying synchronization primitive 1216 represented by its Vulkan semaphore object, and will therefore become 1217 invalid when all Vulkan semaphore objects associated with it are 1218 destroyed. 1219 * ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT specifies an NT 1220 handle returned by code:ID3D12Device::code:CreateSharedHandle referring 1221 to a Direct3D 12 fence, or code:ID3D11Device5::code:CreateFence 1222 referring to a Direct3D 11 fence. 1223 It owns a reference to the underlying synchronization primitive 1224 associated with the Direct3D fence. 1225 * ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D11_FENCE_BIT is an alias of 1226 ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT with the same 1227 meaning. 1228 It is provided for convenience and code clarity when interacting with 1229 D3D11 fences. 1230 * ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT specifies a POSIX 1231 file descriptor handle to a Linux Sync File or Android Fence object. 1232 It can be used with any native API accepting a valid sync file or fence 1233 as input. 1234 It owns a reference to the underlying synchronization primitive 1235 associated with the file descriptor. 1236 Implementations which support importing this handle type must: accept 1237 any type of sync or fence FD supported by the native system they are 1238 running on. 1239ifdef::VK_FUCHSIA_external_semaphore[] 1240 * ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_ZIRCON_EVENT_BIT_FUCHSIA 1241 specifies a handle to a Zircon event object. 1242 It can be used with any native API that accepts a Zircon event handle. 1243 Zircon event handles are created with code:ZX_RIGHTS_BASIC and 1244 code:ZX_RIGHTS_SIGNAL rights. 1245 Vulkan on Fuchsia uses only the ZX_EVENT_SIGNALED bit when signaling or 1246 waiting. 1247endif::VK_FUCHSIA_external_semaphore[] 1248 1249[NOTE] 1250.Note 1251==== 1252Handles of type ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT 1253generated by the implementation may represent either Linux Sync Files or 1254Android Fences at the implementation's discretion. 1255Applications should: only use operations defined for both types of file 1256descriptors, unless they know via means external to Vulkan the type of the 1257file descriptor, or are prepared to deal with the system-defined operation 1258failures resulting from using the wrong type. 1259==== 1260 1261<<< 1262 1263Some external semaphore handle types can only be shared within the same 1264underlying physical device and/or the same driver version, as defined in the 1265following table: 1266 1267[[external-semaphore-handle-types-compatibility]] 1268.External semaphore handle types compatibility 1269|==== 1270| Handle type | sname:VkPhysicalDeviceIDProperties{wbro}::pname:driverUUID | sname:VkPhysicalDeviceIDProperties{wbro}::pname:deviceUUID 1271| ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD_BIT | Must match | Must match 1272| ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_BIT | Must match | Must match 1273| ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT | Must match | Must match 1274| ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE_BIT | Must match | Must match 1275| ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_SYNC_FD_BIT | No restriction | No restriction 1276| ename:VK_EXTERNAL_SEMAPHORE_HANDLE_TYPE_ZIRCON_EVENT_BIT_FUCHSIA | No restriction | No restriction 1277|==== 1278-- 1279 1280[open,refpage='VkExternalSemaphoreHandleTypeFlags',desc='Bitmask of VkExternalSemaphoreHandleTypeFlagBits',type='flags'] 1281-- 1282include::{generated}/api/flags/VkExternalSemaphoreHandleTypeFlags.txt[] 1283 1284ifdef::VK_KHR_external_semaphore_capabilities[] 1285or the equivalent 1286 1287include::{generated}/api/flags/VkExternalSemaphoreHandleTypeFlagsKHR.txt[] 1288endif::VK_KHR_external_semaphore_capabilities[] 1289 1290tname:VkExternalSemaphoreHandleTypeFlags is a bitmask type for setting a 1291mask of zero or more elink:VkExternalSemaphoreHandleTypeFlagBits. 1292-- 1293 1294[open,refpage='VkExternalSemaphoreProperties',desc='Structure describing supported external semaphore handle features',type='structs'] 1295-- 1296The sname:VkExternalSemaphoreProperties structure is defined as: 1297 1298include::{generated}/api/structs/VkExternalSemaphoreProperties.txt[] 1299 1300ifdef::VK_KHR_external_semaphore_capabilities[] 1301or the equivalent 1302 1303include::{generated}/api/structs/VkExternalSemaphorePropertiesKHR.txt[] 1304endif::VK_KHR_external_semaphore_capabilities[] 1305 1306 * pname:sType is the type of this structure 1307 * pname:pNext is `NULL` or a pointer to a structure extending this 1308 structure. 1309 * pname:exportFromImportedHandleTypes is a bitmask of 1310 elink:VkExternalSemaphoreHandleTypeFlagBits specifying which types of 1311 imported handle pname:handleType can: be exported from. 1312 * pname:compatibleHandleTypes is a bitmask of 1313 elink:VkExternalSemaphoreHandleTypeFlagBits specifying handle types 1314 which can: be specified at the same time as pname:handleType when 1315 creating a semaphore. 1316 * pname:externalSemaphoreFeatures is a bitmask of 1317 elink:VkExternalSemaphoreFeatureFlagBits describing the features of 1318 pname:handleType. 1319 1320If pname:handleType is not supported by the implementation, then 1321slink:VkExternalSemaphoreProperties::pname:externalSemaphoreFeatures will be 1322set to zero. 1323 1324include::{generated}/validity/structs/VkExternalSemaphoreProperties.txt[] 1325-- 1326 1327[open,refpage='VkExternalSemaphoreFeatureFlagBits',desc='Bitfield describing features of an external semaphore handle type',type='enums'] 1328-- 1329Possible values of 1330slink:VkExternalSemaphoreProperties::pname:externalSemaphoreFeatures, 1331specifying the features of an external semaphore handle type, are: 1332 1333include::{generated}/api/enums/VkExternalSemaphoreFeatureFlagBits.txt[] 1334 1335ifdef::VK_KHR_external_semaphore_capabilities[] 1336or the equivalent 1337 1338include::{generated}/api/enums/VkExternalSemaphoreFeatureFlagBitsKHR.txt[] 1339endif::VK_KHR_external_semaphore_capabilities[] 1340 1341 * ename:VK_EXTERNAL_SEMAPHORE_FEATURE_EXPORTABLE_BIT specifies that 1342 handles of this type can: be exported from Vulkan semaphore objects. 1343 * ename:VK_EXTERNAL_SEMAPHORE_FEATURE_IMPORTABLE_BIT specifies that 1344 handles of this type can: be imported as Vulkan semaphore objects. 1345-- 1346 1347[open,refpage='VkExternalSemaphoreFeatureFlags',desc='Bitmask of VkExternalSemaphoreFeatureFlagBitsKHR',type='flags'] 1348-- 1349include::{generated}/api/flags/VkExternalSemaphoreFeatureFlags.txt[] 1350 1351ifdef::VK_KHR_external_semaphore_capabilities[] 1352or the equivalent 1353 1354include::{generated}/api/flags/VkExternalSemaphoreFeatureFlagsKHR.txt[] 1355endif::VK_KHR_external_semaphore_capabilities[] 1356 1357tname:VkExternalSemaphoreFeatureFlags is a bitmask type for setting a mask 1358of zero or more elink:VkExternalSemaphoreFeatureFlagBits. 1359-- 1360endif::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[] 1361 1362 1363ifdef::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] 1364[[capabilities-fence]] 1365== Optional Fence Capabilities 1366 1367[open,refpage='vkGetPhysicalDeviceExternalFenceProperties',desc='Function for querying external fence handle capabilities.',type='protos'] 1368-- 1369Fences may: support import and export of their 1370<<synchronization-fences-payloads, payload>> to external handles. 1371To query the external handle types supported by fences, call: 1372 1373ifdef::VK_VERSION_1_1[] 1374include::{generated}/api/protos/vkGetPhysicalDeviceExternalFenceProperties.txt[] 1375endif::VK_VERSION_1_1[] 1376 1377ifdef::VK_VERSION_1_1+VK_KHR_external_fence_capabilities[or the equivalent command] 1378 1379ifdef::VK_KHR_external_fence_capabilities[] 1380include::{generated}/api/protos/vkGetPhysicalDeviceExternalFencePropertiesKHR.txt[] 1381endif::VK_KHR_external_fence_capabilities[] 1382 1383 * pname:physicalDevice is the physical device from which to query the 1384 fence capabilities. 1385 * pname:pExternalFenceInfo is a pointer to a 1386 slink:VkPhysicalDeviceExternalFenceInfo structure describing the 1387 parameters that would be consumed by flink:vkCreateFence. 1388 * pname:pExternalFenceProperties is a pointer to a 1389 slink:VkExternalFenceProperties structure in which capabilities are 1390 returned. 1391 1392include::{generated}/validity/protos/vkGetPhysicalDeviceExternalFenceProperties.txt[] 1393-- 1394 1395[open,refpage='VkPhysicalDeviceExternalFenceInfo',desc='Structure specifying fence creation parameters.',type='structs'] 1396-- 1397The sname:VkPhysicalDeviceExternalFenceInfo structure is defined as: 1398 1399include::{generated}/api/structs/VkPhysicalDeviceExternalFenceInfo.txt[] 1400 1401ifdef::VK_KHR_external_fence_capabilities[] 1402or the equivalent 1403 1404include::{generated}/api/structs/VkPhysicalDeviceExternalFenceInfoKHR.txt[] 1405endif::VK_KHR_external_fence_capabilities[] 1406 1407 * pname:sType is the type of this structure. 1408 * pname:pNext is `NULL` or a pointer to a structure extending this 1409 structure. 1410 * pname:handleType is a elink:VkExternalFenceHandleTypeFlagBits value 1411 specifying an external fence handle type for which capabilities will be 1412 returned. 1413 1414[NOTE] 1415.Note 1416==== 1417Handles of type ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT generated by 1418the implementation may represent either Linux Sync Files or Android Fences 1419at the implementation's discretion. 1420Applications should: only use operations defined for both types of file 1421descriptors, unless they know via means external to Vulkan the type of the 1422file descriptor, or are prepared to deal with the system-defined operation 1423failures resulting from using the wrong type. 1424==== 1425 1426include::{generated}/validity/structs/VkPhysicalDeviceExternalFenceInfo.txt[] 1427-- 1428 1429[open,refpage='VkExternalFenceHandleTypeFlagBits',desc='Bitmask of valid external fence handle types',type='enums'] 1430-- 1431Bits which may: be set in 1432slink:VkPhysicalDeviceExternalFenceInfo::pname:handleType, and in the 1433pname:exportFromImportedHandleTypes and pname:compatibleHandleTypes members 1434of slink:VkExternalFenceProperties, to indicate external fence handle types, 1435are: 1436 1437include::{generated}/api/enums/VkExternalFenceHandleTypeFlagBits.txt[] 1438 1439ifdef::VK_KHR_external_fence_capabilities[] 1440or the equivalent 1441 1442include::{generated}/api/enums/VkExternalFenceHandleTypeFlagBitsKHR.txt[] 1443endif::VK_KHR_external_fence_capabilities[] 1444 1445 * ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_FD_BIT specifies a POSIX file 1446 descriptor handle that has only limited valid usage outside of Vulkan 1447 and other compatible APIs. 1448 It must: be compatible with the POSIX system calls code:dup, code:dup2, 1449 code:close, and the non-standard system call code:dup3. 1450 Additionally, it must: be transportable over a socket using an 1451 code:SCM_RIGHTS control message. 1452 It owns a reference to the underlying synchronization primitive 1453 represented by its Vulkan fence object. 1454 * ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT specifies an NT 1455 handle that has only limited valid usage outside of Vulkan and other 1456 compatible APIs. 1457 It must: be compatible with the functions code:DuplicateHandle, 1458 code:CloseHandle, code:CompareObjectHandles, code:GetHandleInformation, 1459 and code:SetHandleInformation. 1460 It owns a reference to the underlying synchronization primitive 1461 represented by its Vulkan fence object. 1462 * ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT specifies a 1463 global share handle that has only limited valid usage outside of Vulkan 1464 and other compatible APIs. 1465 It is not compatible with any native APIs. 1466 It does not own a reference to the underlying synchronization primitive 1467 represented by its Vulkan fence object, and will therefore become 1468 invalid when all Vulkan fence objects associated with it are destroyed. 1469 * ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT specifies a POSIX file 1470 descriptor handle to a Linux Sync File or Android Fence. 1471 It can be used with any native API accepting a valid sync file or fence 1472 as input. 1473 It owns a reference to the underlying synchronization primitive 1474 associated with the file descriptor. 1475 Implementations which support importing this handle type must: accept 1476 any type of sync or fence FD supported by the native system they are 1477 running on. 1478 1479<<< 1480 1481Some external fence handle types can only be shared within the same 1482underlying physical device and/or the same driver version, as defined in the 1483following table: 1484 1485[[external-fence-handle-types-compatibility]] 1486.External fence handle types compatibility 1487|==== 1488| Handle type | sname:VkPhysicalDeviceIDProperties{wbro}::pname:driverUUID | sname:VkPhysicalDeviceIDProperties{wbro}::pname:deviceUUID 1489| ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_FD_BIT | Must match | Must match 1490| ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_BIT | Must match | Must match 1491| ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT | Must match | Must match 1492| ename:VK_EXTERNAL_FENCE_HANDLE_TYPE_SYNC_FD_BIT | No restriction | No restriction 1493|==== 1494-- 1495 1496[open,refpage='VkExternalFenceHandleTypeFlags',desc='Bitmask of VkExternalFenceHandleTypeFlagBits',type='flags'] 1497-- 1498include::{generated}/api/flags/VkExternalFenceHandleTypeFlags.txt[] 1499 1500ifdef::VK_KHR_external_fence_capabilities[] 1501or the equivalent 1502 1503include::{generated}/api/flags/VkExternalFenceHandleTypeFlagsKHR.txt[] 1504endif::VK_KHR_external_fence_capabilities[] 1505 1506tname:VkExternalFenceHandleTypeFlags is a bitmask type for setting a mask of 1507zero or more elink:VkExternalFenceHandleTypeFlagBits. 1508-- 1509 1510[open,refpage='VkExternalFenceProperties',desc='Structure describing supported external fence handle features',type='structs'] 1511-- 1512The sname:VkExternalFenceProperties structure is defined as: 1513 1514include::{generated}/api/structs/VkExternalFenceProperties.txt[] 1515 1516ifdef::VK_KHR_external_fence_capabilities[] 1517or the equivalent 1518 1519include::{generated}/api/structs/VkExternalFencePropertiesKHR.txt[] 1520endif::VK_KHR_external_fence_capabilities[] 1521 1522 * pname:exportFromImportedHandleTypes is a bitmask of 1523 elink:VkExternalFenceHandleTypeFlagBits indicating which types of 1524 imported handle pname:handleType can: be exported from. 1525 * pname:compatibleHandleTypes is a bitmask of 1526 elink:VkExternalFenceHandleTypeFlagBits specifying handle types which 1527 can: be specified at the same time as pname:handleType when creating a 1528 fence. 1529 * pname:externalFenceFeatures is a bitmask of 1530 elink:VkExternalFenceFeatureFlagBits indicating the features of 1531 pname:handleType. 1532 1533If pname:handleType is not supported by the implementation, then 1534slink:VkExternalFenceProperties::pname:externalFenceFeatures will be set to 1535zero. 1536 1537include::{generated}/validity/structs/VkExternalFenceProperties.txt[] 1538-- 1539 1540[open,refpage='VkExternalFenceFeatureFlagBits',desc='Bitfield describing features of an external fence handle type',type='enums'] 1541-- 1542Bits which may: be set in 1543slink:VkExternalFenceProperties::pname:externalFenceFeatures, indicating 1544features of a fence external handle type, are: 1545 1546include::{generated}/api/enums/VkExternalFenceFeatureFlagBits.txt[] 1547 1548ifdef::VK_KHR_external_fence_capabilities[] 1549or the equivalent 1550 1551include::{generated}/api/enums/VkExternalFenceFeatureFlagBitsKHR.txt[] 1552endif::VK_KHR_external_fence_capabilities[] 1553 1554 * ename:VK_EXTERNAL_FENCE_FEATURE_EXPORTABLE_BIT specifies handles of this 1555 type can: be exported from Vulkan fence objects. 1556 * ename:VK_EXTERNAL_FENCE_FEATURE_IMPORTABLE_BIT specifies handles of this 1557 type can: be imported to Vulkan fence objects. 1558-- 1559 1560[open,refpage='VkExternalFenceFeatureFlags',desc='Bitmask of VkExternalFenceFeatureFlagBits',type='flags'] 1561-- 1562include::{generated}/api/flags/VkExternalFenceFeatureFlags.txt[] 1563 1564ifdef::VK_KHR_external_fence_capabilities[] 1565or the equivalent 1566 1567include::{generated}/api/flags/VkExternalFenceFeatureFlagsKHR.txt[] 1568endif::VK_KHR_external_fence_capabilities[] 1569 1570tname:VkExternalFenceFeatureFlags is a bitmask type for setting a mask of 1571zero or more elink:VkExternalFenceFeatureFlagBits. 1572-- 1573endif::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] 1574 1575 1576ifdef::VK_EXT_calibrated_timestamps[] 1577[[features-timestamp-calibration]] 1578== Timestamp Calibration Capabilities 1579 1580[open,refpage='vkGetPhysicalDeviceCalibrateableTimeDomainsEXT',desc='Query calibrateable time domains',type='protos'] 1581-- 1582To query the set of time domains for which a physical device supports 1583timestamp calibration, call: 1584 1585include::{generated}/api/protos/vkGetPhysicalDeviceCalibrateableTimeDomainsEXT.txt[] 1586 1587 * pname:physicalDevice is the physical device from which to query the set 1588 of calibrateable time domains. 1589 * pname:pTimeDomainCount is a pointer to an integer related to the number 1590 of calibrateable time domains available or queried, as described below. 1591 * pname:pTimeDomains is either `NULL` or a pointer to an array of 1592 elink:VkTimeDomainEXT values, indicating the supported calibrateable 1593 time domains. 1594 1595If pname:pTimeDomains is `NULL`, then the number of calibrateable time 1596domains supported for the given pname:physicalDevice is returned in 1597pname:pTimeDomainCount. 1598Otherwise, pname:pTimeDomainCount must: point to a variable set by the user 1599to the number of elements in the pname:pTimeDomains array, and on return the 1600variable is overwritten with the number of values actually written to 1601pname:pTimeDomains. 1602If the value of pname:pTimeDomainCount is less than the number of 1603calibrateable time domains supported, at most pname:pTimeDomainCount values 1604will be written to pname:pTimeDomains, and ename:VK_INCOMPLETE will be 1605returned instead of ename:VK_SUCCESS, to indicate that not all the available 1606time domains were returned. 1607 1608include::{generated}/validity/protos/vkGetPhysicalDeviceCalibrateableTimeDomainsEXT.txt[] 1609-- 1610endif::VK_EXT_calibrated_timestamps[] 1611