1// Copyright 2015-2023 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[sparsememory]] 6= Sparse Resources 7 8As documented in <<resources-association,Resource Memory Association>>, 9sname:VkBuffer and sname:VkImage resources in Vulkan must: be bound 10completely and contiguously to a single sname:VkDeviceMemory object. 11This binding must: be done before the resource is used, and the binding is 12immutable for the lifetime of the resource. 13 14_Sparse resources_ relax these restrictions and provide these additional 15features: 16 17 * Sparse resources can: be bound non-contiguously to one or more 18 sname:VkDeviceMemory allocations. 19 * Sparse resources can: be re-bound to different memory allocations over 20 the lifetime of the resource. 21 * Sparse resources can: have descriptors generated and used orthogonally 22 with memory binding commands. 23 24ifdef::VKSC_VERSION_1_0[] 25Sparse resources are not supported in Vulkan SC, due to complexity and the 26necessity of being able to update page table mappings at runtime <<SCID-8>>. 27However, the sparse resource features, properties, resource creation flags, 28and definitions have been retained for completeness and compatibility. 29 30All sparse resource <<sparsememory-physicalfeatures,physical device 31features>> must: not be advertised as supported, and the related 32<<sparsememory-physicalprops,physical device sparse properties>> and 33<<limits,physical device limits>> must: be reported accordingly. 34 35ifdef::hidden[] 36// tag::scremoved[] 37 * elink:VkStructureType 38 ** ename:VK_STRUCTURE_TYPE_BIND_SPARSE_INFO <<SCID-8>> 39 ** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_BIND_SPARSE_INFO <<SCID-8>> 40 ** ename:VK_STRUCTURE_TYPE_IMAGE_SPARSE_MEMORY_REQUIREMENTS_INFO_2 41 <<SCID-8>> 42 ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SPARSE_IMAGE_FORMAT_INFO_2 43 <<SCID-8>> 44 ** ename:VK_STRUCTURE_TYPE_SPARSE_IMAGE_FORMAT_PROPERTIES_2 <<SCID-8>> 45 ** ename:VK_STRUCTURE_TYPE_SPARSE_IMAGE_MEMORY_REQUIREMENTS_2 <<SCID-8>> 46 * sname:VkSparseImageFormatProperties <<SCID-8>> 47 * ename:VkSparseImageFormatFlagBits <<SCID-8>> 48 * tname:VkSparseImageFormatFlags <<SCID-8>> 49 * fname:vkGetPhysicalDeviceSparseImageFormatProperties <<SCID-8>> 50 * fname:vkGetPhysicalDeviceSparseImageFormatProperties2 <<SCID-8>> 51 * sname:VkPhysicalDeviceSparseImageFormatInfo2 <<SCID-8>> 52 * sname:VkSparseImageFormatProperties2 <<SCID-8>> 53 * sname:VkSparseImageMemoryRequirements <<SCID-8>> 54 * fname:vkGetImageSparseMemoryRequirements <<SCID-8>> 55 * fname:vkGetImageSparseMemoryRequirements2 <<SCID-8>> 56 * sname:VkImageSparseMemoryRequirementsInfo2 <<SCID-8>> 57 * sname:VkSparseImageMemoryRequirements2 <<SCID-8>> 58 * sname:VkSparseMemoryBind <<SCID-8>> 59 * ename:VkSparseMemoryBindFlagBits <<SCID-8>> 60 * tname:VkSparseMemoryBindFlags <<SCID-8>> 61 * sname:VkSparseBufferMemoryBindInfo <<SCID-8>> 62 * sname:VkSparseImageOpaqueMemoryBindInfo <<SCID-8>> 63 * sname:VkSparseImageMemoryBindInfo <<SCID-8>> 64 * sname:VkSparseImageMemoryBind <<SCID-8>> 65 * fname:vkQueueBindSparse <<SCID-8>> 66 * sname:VkBindSparseInfo <<SCID-8>> 67 * sname:VkDeviceGroupBindSparseInfo <<SCID-8>> 68// end::scremoved[] 69endif::hidden[] 70endif::VKSC_VERSION_1_0[] 71 72[[sparsememory-sparseresourcefeatures]] 73== Sparse Resource Features 74 75Sparse resources have several features that must: be enabled explicitly at 76resource creation time. 77The features are enabled by including bits in the pname:flags parameter of 78slink:VkImageCreateInfo or slink:VkBufferCreateInfo. 79Each feature also has one or more corresponding feature enables specified in 80slink:VkPhysicalDeviceFeatures. 81 82 * The <<features-sparseBinding, pname:sparseBinding>> feature is the base, 83 and provides the following capabilities: 84 85 ** Resources can: be bound at some defined (sparse block) granularity. 86 ** The entire resource must: be bound to memory before use regardless of 87 regions actually accessed. 88 ** No specific mapping of image region to memory offset is defined, i.e. 89 the location that each texel corresponds to in memory is 90 implementation-dependent. 91 ** Sparse buffers have a well-defined mapping of buffer range to memory 92 range, where an offset into a range of the buffer that is bound to a 93 single contiguous range of memory corresponds to an identical offset 94 within that range of memory. 95 ** Requested via the ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT and 96 ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT bits. 97 ** A sparse image created using ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT 98 (but not ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT) supports all 99 formats that non-sparse usage supports, and supports both 100 ename:VK_IMAGE_TILING_OPTIMAL and ename:VK_IMAGE_TILING_LINEAR tiling. 101 102 * _Sparse Residency_ builds on (and requires) the pname:sparseBinding 103 feature. 104 It includes the following capabilities: 105 106 ** Resources do not have to be completely bound to memory before use on 107 the device. 108 ** Images have a prescribed sparse image block layout, allowing specific 109 rectangular regions of the image to be bound to specific offsets in 110 memory allocations. 111 ** Consistency of access to unbound regions of the resource is defined by 112 the absence or presence of 113 sname:VkPhysicalDeviceSparseProperties::pname:residencyNonResidentStrict. 114 If this property is present, accesses to unbound regions of the 115 resource are well defined and behave as if the data bound is populated 116 with all zeros; writes are discarded. 117 When this property is absent, accesses are considered safe, but reads 118 will return undefined: values. 119 ** Requested via the ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT and 120 ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT bits. 121 ** [[features-sparseResidency]] Sparse residency support is advertised on 122 a finer grain via the following features: 123+ 124 *** The <<features-sparseResidencyBuffer, pname:sparseResidencyBuffer>> 125 feature provides support for creating sname:VkBuffer objects with the 126 ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT. 127 *** The <<features-sparseResidencyImage2D, pname:sparseResidencyImage2D>> 128 feature provides support for creating 2D single-sampled sname:VkImage 129 objects with ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. 130 *** The <<features-sparseResidencyImage3D, pname:sparseResidencyImage3D>> 131 feature provides support for creating 3D sname:VkImage objects with 132 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. 133 *** The <<features-sparseResidency2Samples, 134 pname:sparseResidency2Samples>> feature provides support for creating 135 2D sname:VkImage objects with 2 samples and 136 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. 137 *** The <<features-sparseResidency4Samples, 138 pname:sparseResidency4Samples>> feature provides support for creating 139 2D sname:VkImage objects with 4 samples and 140 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. 141 *** The <<features-sparseResidency8Samples, 142 pname:sparseResidency8Samples>> feature provides support for creating 143 2D sname:VkImage objects with 8 samples and 144 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. 145 *** The <<features-sparseResidency16Samples, 146 pname:sparseResidency16Samples>> feature provides support for creating 147 2D sname:VkImage objects with 16 samples and 148 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. 149+ 150Implementations supporting pname:sparseResidencyImage2D are only required: 151to support sparse 2D, single-sampled images. 152Support for sparse 3D and MSAA images is optional: and can: be enabled via 153pname:sparseResidencyImage3D, pname:sparseResidency2Samples, 154pname:sparseResidency4Samples, pname:sparseResidency8Samples, and 155pname:sparseResidency16Samples. 156 157 ** A sparse image created using ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT 158 supports all non-compressed color formats with power-of-two element 159 size that non-sparse usage supports. 160 Additional formats may: also be supported and can: be queried via 161 flink:vkGetPhysicalDeviceSparseImageFormatProperties. 162 ename:VK_IMAGE_TILING_LINEAR tiling is not supported. 163 164 * The <<features-sparseResidencyAliased, pname:sparseResidencyAliased>> 165 feature provides the following capability that can: be enabled per 166 resource: 167+ 168Allows physical memory ranges to be shared between multiple locations in the 169same sparse resource or between multiple sparse resources, with each binding 170of a memory location observing a consistent interpretation of the memory 171contents. 172+ 173-- 174ifndef::VKSC_VERSION_1_0[] 175See <<sparsememory-sparse-memory-aliasing,Sparse Memory Aliasing>> for more 176information. 177endif::VKSC_VERSION_1_0[] 178-- 179 180 181ifndef::VKSC_VERSION_1_0[] 182[[sparsememory-fully-resident]] 183== Sparse Buffers and Fully-Resident Images 184 185Both sname:VkBuffer and sname:VkImage objects created with the 186ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT or 187ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT bits can: be thought of as a 188linear region of address space. 189In the sname:VkImage case if ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT is 190not used, this linear region is entirely opaque, meaning that there is no 191application-visible mapping between texel location and memory offset. 192 193Unless ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT or 194ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT are also used, the entire 195resource must: be bound to one or more sname:VkDeviceMemory objects before 196use. 197 198 199=== Sparse Buffer and Fully-Resident Image Block Size 200 201The sparse block size in bytes for sparse buffers and fully-resident images 202is reported as sname:VkMemoryRequirements::pname:alignment. 203pname:alignment represents both the memory alignment requirement and the 204binding granularity (in bytes) for sparse resources. 205 206 207[[sparsememory-partially-resident-buffers]] 208== Sparse Partially-Resident Buffers 209 210sname:VkBuffer objects created with the 211ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT bit allow the buffer to be made 212only partially resident. 213Partially resident sname:VkBuffer objects are allocated and bound 214identically to sname:VkBuffer objects using only the 215ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT feature. 216The only difference is the ability for some regions of the buffer to be 217unbound during device use. 218 219 220[[sparsememory-partially-resident-images]] 221== Sparse Partially-Resident Images 222 223sname:VkImage objects created with the 224ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT bit allow specific rectangular 225regions of the image called sparse image blocks to be bound to specific 226ranges of memory. 227This allows the application to manage residency at either image subresource 228or sparse image block granularity. 229Each image subresource (outside of the <<sparsememory-miptail,mip tail>>) 230starts on a sparse block boundary and has dimensions that are integer 231multiples of the corresponding dimensions of the sparse image block. 232 233[NOTE] 234.Note 235==== 236Applications can: use these types of images to control LOD based on total 237memory consumption. 238If memory pressure becomes an issue the application can: unbind and disable 239specific mipmap levels of images without having to recreate resources or 240modify texel data of unaffected levels. 241 242The application can: also use this functionality to access subregions of the 243image in a "`megatexture`" fashion. 244The application can: create a large image and only populate the region of 245the image that is currently being used in the scene. 246==== 247 248 249[[sparsememory-accessing-unbound]] 250=== Accessing Unbound Regions 251 252The following member of sname:VkPhysicalDeviceSparseProperties affects how 253data in unbound regions of sparse resources are handled by the 254implementation: 255 256 * pname:residencyNonResidentStrict 257 258If this property is not present, reads of unbound regions of the image will 259return undefined: values. 260Both reads and writes are still considered _safe_ and will not affect other 261resources or populated regions of the image. 262 263If this property is present, all reads of unbound regions of the image will 264behave as if the region was bound to memory populated with all zeros; writes 265will be discarded. 266 267<<textures,Image operations>> performed on unbound memory may: still alter 268some component values in the natural way for those accesses, e.g. 269substituting a value of one for alpha in formats that do not have an alpha 270component. 271 272==== 273Example: Reading the alpha component of an unbacked ename:VK_FORMAT_R8_UNORM 274image will return a value of [eq]#1.0f#. 275==== 276 277See <<devsandqueues-physical-device-enumeration,Physical Device 278Enumeration>> for instructions for retrieving physical device properties. 279 280ifdef::implementation-guide[] 281.Implementor's Note 282**** 283For implementations that cannot: natively handle access to unbound regions 284of a resource, the implementation may: allocate and bind memory to the 285unbound regions. 286Reads and writes to unbound regions will access the implementation-managed 287memory instead. 288 289Given that the values resulting from reads of unbound regions are undefined: 290in this scenario, implementations may: use the same physical memory for all 291unbound regions of multiple resources within the same process. 292**** 293endif::implementation-guide[] 294 295 296[[sparsememory-miptail]] 297=== Mip Tail Regions 298 299Sparse images created using ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT 300(without also using ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT) have no 301specific mapping of image region or image subresource to memory offset 302defined, so the entire image can: be thought of as a linear opaque address 303region. 304However, images created with ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT do 305have a prescribed sparse image block layout, and hence each image 306subresource must: start on a sparse block boundary. 307Within each array layer, the set of mip levels that have a smaller size than 308the sparse block size in bytes are grouped together into a _mip tail 309region_. 310 311If the ename:VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT flag is present in 312the pname:flags member of sname:VkSparseImageFormatProperties, for the 313image's pname:format, then any mip level which has dimensions that are not 314integer multiples of the corresponding dimensions of the sparse image block, 315and all subsequent mip levels, are also included in the mip tail region. 316 317The following member of sname:VkPhysicalDeviceSparseProperties may: affect 318how the implementation places mip levels in the mip tail region: 319 320 * pname:residencyAlignedMipSize 321 322Each mip tail region is bound to memory as an opaque region (i.e. must: be 323bound using a slink:VkSparseImageOpaqueMemoryBindInfo structure) and may: be 324of a size greater than or equal to the sparse block size in bytes. 325This size is guaranteed to be an integer multiple of the sparse block size 326in bytes. 327 328An implementation may: choose to allow each array-layer's mip tail region to 329be bound to memory independently or require that all array-layer's mip tail 330regions be treated as one. 331This is dictated by ename:VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT in 332sname:VkSparseImageMemoryRequirements::pname:flags. 333 334The following diagrams depict how 335ename:VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT and 336ename:VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT alter memory usage and 337requirements. 338 339image::{images}/sparseimage.svg[align="center",title="Sparse Image",opts="{imageopts}"] 340 341In the absence of ename:VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT and 342ename:VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT, each array layer contains a 343mip tail region containing texel data for all mip levels smaller than the 344sparse image block in any dimension. 345 346Mip levels that are as large or larger than a sparse image block in all 347dimensions can: be bound individually. 348Right-edges and bottom-edges of each level are allowed to have partially 349used sparse blocks. 350Any bound partially-used-sparse-blocks must: still have their full sparse 351block size in bytes allocated in memory. 352 353image::{images}/sparseimage_singlemiptail.svg[align="center",title="Sparse Image with Single Mip Tail",opts="{imageopts}"] 354 355When ename:VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT is present all array 356layers will share a single mip tail region. 357 358image::{images}/sparseimage_alignedmipsize.svg[align="center",title="Sparse Image with Aligned Mip Size",opts="{imageopts}"] 359 360[NOTE] 361.Note 362==== 363The mip tail regions are presented here in 2D arrays simply for figure size 364reasons. 365Each mip tail is logically a single array of sparse blocks with an 366implementation-dependent mapping of texels or compressed texel blocks to 367sparse blocks. 368==== 369 370When ename:VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT is present the first 371mip level that would contain partially used sparse blocks begins the mip 372tail region. 373This level and all subsequent levels are placed in the mip tail. 374Only the first [eq]#N# mip levels whose dimensions are an exact multiple of 375the sparse image block dimensions can: be bound and unbound on a sparse 376block basis. 377 378image::{images}/sparseimage_alignedmipsize_singlemiptail.svg[align="center",title="Sparse Image with Aligned Mip Size and Single Mip Tail",opts="{imageopts}"] 379 380[NOTE] 381.Note 382==== 383The mip tail region is presented here in a 2D array simply for figure size 384reasons. 385It is logically a single array of sparse blocks with an 386implementation-dependent mapping of texels or compressed texel blocks to 387sparse blocks. 388==== 389 390When both ename:VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT and 391ename:VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT are present the constraints 392from each of these flags are in effect. 393 394 395[[sparsememory-standard-shapes]] 396=== Standard Sparse Image Block Shapes 397 398Standard sparse image block shapes define a standard set of dimensions for 399sparse image blocks that depend on the format of the image. 400Layout of texels or compressed texel blocks within a sparse image block is 401implementation-dependent. 402All currently defined standard sparse image block shapes are 64 KB in size. 403 404For block-compressed formats (e.g. ename:VK_FORMAT_BC5_UNORM_BLOCK), the 405texel size is the size of the compressed texel block (e.g. 128-bit for 406etext:BC5) thus the dimensions of the standard sparse image block shapes 407apply in terms of compressed texel blocks. 408 409[NOTE] 410.Note 411==== 412For block-compressed formats, the dimensions of a sparse image block in 413terms of texels can: be calculated by multiplying the sparse image block 414dimensions by the compressed texel block dimensions. 415==== 416 417<<< 418 419[[sparsememory-sparseblockshapessingle]] 420.Standard Sparse Image Block Shapes (Single Sample) 421[options="header"] 422|==== 423| TEXEL SIZE (bits) | Block Shape (2D) | Block Shape (3D) 424| *8-Bit* | 256 {times} 256 {times} 1 | 64 {times} 32 {times} 32 425| *16-Bit* | 256 {times} 128 {times} 1 | 32 {times} 32 {times} 32 426| *32-Bit* | 128 {times} 128 {times} 1 | 32 {times} 32 {times} 16 427| *64-Bit* | 128 {times} 64 {times} 1 | 32 {times} 16 {times} 16 428| *128-Bit* | 64 {times} 64 {times} 1 | 16 {times} 16 {times} 16 429|==== 430 431[[sparsememory-sparseblockshapesmsaa]] 432.Standard Sparse Image Block Shapes (MSAA) 433[options="header"] 434|==== 435| TEXEL SIZE (bits)| Block Shape (2X) | Block Shape (4X) | Block Shape (8X) | Block Shape (16X) 436| *8-Bit* | 128 {times} 256 {times} 1 | 128 {times} 128 {times} 1 | 64 {times} 128 {times} 1 | 64 {times} 64 {times} 1 437| *16-Bit* | 128 {times} 128 {times} 1 | 128 {times} 64 {times} 1 | 64 {times} 64 {times} 1 | 64 {times} 32 {times} 1 438| *32-Bit* | 64 {times} 128 {times} 1 | 64 {times} 64 {times} 1 | 32 {times} 64 {times} 1 | 32 {times} 32 {times} 1 439| *64-Bit* | 64 {times} 64 {times} 1 | 64 {times} 32 {times} 1 | 32 {times} 32 {times} 1 | 32 {times} 16 {times} 1 440| *128-Bit* | 32 {times} 64 {times} 1 | 32 {times} 32 {times} 1 | 16 {times} 32 {times} 1 | 16 {times} 16 {times} 1 441|==== 442 443 444Implementations that support the standard sparse image block shape for all 445formats listed in the <<sparsememory-sparseblockshapessingle>> and 446<<sparsememory-sparseblockshapesmsaa>> tables may: advertise the following 447sname:VkPhysicalDeviceSparseProperties: 448 449 * pname:residencyStandard2DBlockShape 450 * pname:residencyStandard2DMultisampleBlockShape 451 * pname:residencyStandard3DBlockShape 452 453Reporting each of these features does _not_ imply that all possible image 454types are supported as sparse. 455Instead, this indicates that no supported sparse image of the corresponding 456type will use custom sparse image block dimensions for any formats that have 457a corresponding standard sparse image block shape. 458 459 460[[sparsememory-custom-shapes]] 461=== Custom Sparse Image Block Shapes 462 463An implementation that does not support a standard image block shape for a 464particular sparse partially-resident image may: choose to support a custom 465sparse image block shape for it instead. 466The dimensions of such a custom sparse image block shape are reported in 467sname:VkSparseImageFormatProperties::pname:imageGranularity. 468As with standard sparse image block shapes, the size in bytes of the custom 469sparse image block shape will be reported in 470sname:VkMemoryRequirements::pname:alignment. 471 472Custom sparse image block dimensions are reported through 473fname:vkGetPhysicalDeviceSparseImageFormatProperties and 474fname:vkGetImageSparseMemoryRequirements. 475 476An implementation must: not support both the standard sparse image block 477shape and a custom sparse image block shape for the same image. 478The standard sparse image block shape must: be used if it is supported. 479 480 481[[sparsememory-multiaspect]] 482=== Multiple Aspects 483 484Partially resident images are allowed to report separate sparse properties 485for different aspects of the image. 486One example is for depth/stencil images where the implementation separates 487the depth and stencil data into separate planes. 488Another reason for multiple aspects is to allow the application to manage 489memory allocation for implementation-private _metadata_ associated with the 490image. 491See the figure below: 492 493image::{images}/sparseimage_multiaspect.svg[align="center",title="Multiple Aspect Sparse Image",opts="{imageopts}"] 494 495[NOTE] 496.Note 497==== 498The mip tail regions are presented here in 2D arrays simply for figure size 499reasons. 500Each mip tail is logically a single array of sparse blocks with an 501implementation-dependent mapping of texels or compressed texel blocks to 502sparse blocks. 503==== 504 505In the figure above the depth, stencil, and metadata aspects all have unique 506sparse properties. 507The per-texel stencil data is [eq]#{onequarter}# the size of the depth data, 508hence the stencil sparse blocks include [eq]#4 {times}# the number of 509texels. 510The sparse block size in bytes for all of the aspects is identical and 511defined by sname:VkMemoryRequirements::pname:alignment. 512 513 514==== Metadata 515 516The metadata aspect of an image has the following constraints: 517 518 * All metadata is reported in the mip tail region of the metadata aspect. 519 * All metadata must: be bound prior to device use of the sparse image. 520 521 522[[sparsememory-sparse-memory-aliasing]] 523== Sparse Memory Aliasing 524 525By default sparse resources have the same aliasing rules as non-sparse 526resources. 527See <<resources-memory-aliasing,Memory Aliasing>> for more information. 528 529sname:VkDevice objects that have the <<features-sparseResidencyAliased, 530pname:sparseResidencyAliased>> feature enabled are able to use the 531ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT and 532ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT flags for resource creation. 533These flags allow resources to access physical memory bound into multiple 534locations within one or more sparse resources in a _data consistent_ 535fashion. 536This means that reading physical memory from multiple aliased locations will 537return the same value. 538 539Care must: be taken when performing a write operation to aliased physical 540memory. 541Memory dependencies must: be used to separate writes to one alias from reads 542or writes to another alias. 543Writes to aliased memory that are not properly guarded against accesses to 544different aliases will have undefined: results for all accesses to the 545aliased memory. 546 547Applications that wish to make use of data consistent sparse memory aliasing 548must: abide by the following guidelines: 549 550 * All sparse resources that are bound to aliased physical memory must: be 551 created with the ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT / 552 ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT flag. 553 * All resources that access aliased physical memory must: interpret the 554 memory in the same way. 555 This implies the following: 556 ** Buffers and images cannot: alias the same physical memory in a data 557 consistent fashion. 558 The physical memory ranges must: be used exclusively by buffers or used 559 exclusively by images for data consistency to be guaranteed. 560 ** Memory in sparse image mip tail regions cannot: access aliased memory 561 in a data consistent fashion. 562 ** Sparse images that alias the same physical memory must: have compatible 563 formats and be using the same sparse image block shape in order to 564 access aliased memory in a data consistent fashion. 565 566Failure to follow any of the above guidelines will require the application 567to abide by the normal, non-sparse resource <<resources-memory-aliasing, 568aliasing rules>>. 569In this case memory cannot: be accessed in a data consistent fashion. 570 571[NOTE] 572.Note 573==== 574Enabling sparse resource memory aliasing can: be a way to lower physical 575memory use, but it may: reduce performance on some implementations. 576An application developer can: test on their target HW and balance the memory 577/ performance trade-offs measured. 578==== 579 580 581ifdef::implementation-guide[] 582== Sparse Resource Implementation Guidelines (Informative) 583 584**** 585This section is Informative. 586It is included to aid in implementors`' understanding of sparse resources. 587 588.Device Virtual Address 589 590The basic pname:sparseBinding feature allows the resource to reserve its own 591device virtual address range at resource creation time rather than relying 592on a bind operation to set this. 593Without any other creation flags, no other constraints are relaxed compared 594to normal resources. 595All pages must: be bound to physical memory before the device accesses the 596resource. 597 598The <<features-sparseResidency, pname:sparseResidency>> features allow 599sparse resources to be used even when not all pages are bound to memory. 600Implementations that support access to unbound pages without causing a fault 601may: support pname:residencyNonResidentStrict. 602 603Not faulting on access to unbound pages is not enough to support 604pname:residencyNonResidentStrict. 605An implementation must: also guarantee that reads after writes to unbound 606regions of the resource always return data for the read as if the memory 607contains zeros. 608Depending on any caching hierarchy of the implementation this may: not 609always be possible. 610 611Any implementation that does not fault, but does not guarantee correct read 612values must: not support pname:residencyNonResidentStrict. 613 614Any implementation that cannot: access unbound pages without causing a fault 615will require the implementation to bind the entire device virtual address 616range to physical memory. 617Any pages that the application does not bind to memory may: be bound to one 618(or more) "`placeholder" physical page(s) allocated by the implementation. 619Given the following properties: 620 621 * A process must: not access memory from another process 622 * Reads return undefined: values 623 624It is sufficient for each host process to allocate these placeholder pages 625and use them for all resources in that process. 626Implementations may: allocate more often (per instance, per device, or per 627resource). 628 629 630.Binding Memory 631 632The byte size reported in sname:VkMemoryRequirements::pname:size must: be 633greater than or equal to the amount of physical memory required: to fully 634populate the resource. 635Some implementations require "`holes`" in the device virtual address range 636that are never accessed. 637These holes may: be included in the pname:size reported for the resource. 638 639Including or not including the device virtual address holes in the resource 640size will alter how the implementation provides support for 641sname:VkSparseImageOpaqueMemoryBindInfo. 642This operation must: be supported for all sparse images, even ones created 643with ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. 644 645ifdef::editing-notes[] 646[NOTE] 647.editing-note 648==== 649@ntrevett suggested expanding the NOTE tag below to encompass everything 650from "`The cost is...`" in the first bullet point through the current note. 651TBD. 652==== 653endif::editing-notes[] 654 655 * If the holes are included in the size, this bind function becomes very 656 easy. 657 In most cases the pname:resourceOffset is simply a device virtual 658 address offset and the implementation can easily determine what device 659 virtual address to bind. 660 The cost is that the application may: allocate more physical memory for 661 the resource than it needs. 662 * If the holes are not included in the size, the application can: allocate 663 less physical memory than otherwise for the resource. 664 However, in this case the implementation must: account for the holes 665 when mapping pname:resourceOffset to the actual device virtual address 666 intended to be mapped. 667 668[NOTE] 669.Note 670==== 671If the application always uses sname:VkSparseImageMemoryBindInfo to bind 672memory for the non-tail mip levels, any holes that are present in the 673resource size may: never be bound. 674 675Since sname:VkSparseImageMemoryBindInfo uses texel locations to determine 676which device virtual addresses to bind, it is impossible to bind device 677virtual address holes with this operation. 678==== 679 680.Binding Metadata Memory 681 682All metadata for sparse images have their own sparse properties and are 683embedded in the mip tail region for said properties. 684See the <<sparsememory-multiaspect,Multiaspect>> section for details. 685 686Given that metadata is in a mip tail region, and the mip tail region must: 687be reported as contiguous (either globally or per-array-layer), some 688implementations will have to resort to complicated offset -> device virtual 689address mapping for handling sname:VkSparseImageOpaqueMemoryBindInfo. 690 691To make this easier on the implementation, the 692ename:VK_SPARSE_MEMORY_BIND_METADATA_BIT explicitly specifies when metadata 693is bound with sname:VkSparseImageOpaqueMemoryBindInfo. 694When this flag is not present, the pname:resourceOffset may: be treated as a 695strict device virtual address offset. 696 697When ename:VK_SPARSE_MEMORY_BIND_METADATA_BIT is present, the 698pname:resourceOffset must: have been derived explicitly from the 699pname:imageMipTailOffset in the sparse resource properties returned for the 700metadata aspect. 701By manipulating the value returned for pname:imageMipTailOffset, the 702pname:resourceOffset does not have to correlate directly to a device virtual 703address offset, and may: instead be whatever value makes it easiest for the 704implementation to derive the correct device virtual address. 705 706**** 707endif::implementation-guide[] 708endif::VKSC_VERSION_1_0[] 709 710[[sparsememory-resourceapi]] 711== Sparse Resource API 712 713The APIs related to sparse resources are grouped into the following 714categories: 715 716 * <<sparsememory-physicalfeatures,Physical Device Features>> 717 * <<sparsememory-physicalprops,Physical Device Sparse Properties>> 718ifndef::VKSC_VERSION_1_0[] 719 * <<sparsememory-format-props,Sparse Image Format Properties>> 720 * <<sparsememory-resource-creation,Sparse Resource Creation>> 721 * <<sparsememory-memory-requirements,Sparse Resource Memory Requirements>> 722 * <<sparsememory-resource-binding,Binding Resource Memory>> 723endif::VKSC_VERSION_1_0[] 724 725 726[[sparsememory-physicalfeatures]] 727=== Physical Device Features 728 729Some sparse-resource related features are reported and enabled in 730sname:VkPhysicalDeviceFeatures. 731These features must: be supported and enabled on the sname:VkDevice object 732before applications can: use them. 733See <<features, Physical Device Features>> for information on how to get and 734set enabled device features, and for more detailed explanations of these 735features. 736 737 738==== Sparse Physical Device Features 739 740 * pname:sparseBinding: Support for creating slink:VkBuffer and 741 sname:VkImage objects with the ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT 742 and ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT flags, respectively. 743 * pname:sparseResidencyBuffer: Support for creating slink:VkBuffer objects 744 with the ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT flag. 745 * pname:sparseResidencyImage2D: Support for creating 2D single-sampled 746 sname:VkImage objects with ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. 747 * pname:sparseResidencyImage3D: Support for creating 3D slink:VkImage 748 objects with ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. 749 * pname:sparseResidency2Samples: Support for creating 2D slink:VkImage 750 objects with 2 samples and ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. 751 * pname:sparseResidency4Samples: Support for creating 2D slink:VkImage 752 objects with 4 samples and ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. 753 * pname:sparseResidency8Samples: Support for creating 2D slink:VkImage 754 objects with 8 samples and ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. 755 * pname:sparseResidency16Samples: Support for creating 2D slink:VkImage 756 objects with 16 samples and ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT. 757 * pname:sparseResidencyAliased: Support for creating slink:VkBuffer and 758 sname:VkImage objects with the ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT 759 and ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT flags, respectively. 760 761 762[[sparsememory-physicalprops]] 763=== Physical Device Sparse Properties 764 765Some features of the implementation are not possible to disable, and are 766reported to allow applications to alter their sparse resource usage 767accordingly. 768These read-only capabilities are reported in the 769slink:VkPhysicalDeviceProperties::pname:sparseProperties member, which is a 770sname:VkPhysicalDeviceSparseProperties structure. 771 772[open,refpage='VkPhysicalDeviceSparseProperties',desc='Structure specifying physical device sparse memory properties',type='structs'] 773-- 774The sname:VkPhysicalDeviceSparseProperties structure is defined as: 775 776include::{generated}/api/structs/VkPhysicalDeviceSparseProperties.adoc[] 777 778 * pname:residencyStandard2DBlockShape 779ifndef::VKSC_VERSION_1_0[] 780 is ename:VK_TRUE if the physical device will access all single-sample 2D 781 sparse resources using the standard sparse image block shapes (based on 782 image format), as described in the 783 <<sparsememory-sparseblockshapessingle, Standard Sparse Image Block 784 Shapes (Single Sample)>> table. 785 If this property is not supported the value returned in the 786 pname:imageGranularity member of the sname:VkSparseImageFormatProperties 787 structure for single-sample 2D images is not required: to match the 788 standard sparse image block dimensions listed in the table. 789endif::VKSC_VERSION_1_0[] 790ifdef::VKSC_VERSION_1_0[must: be ename:VK_FALSE in Vulkan SC <<SCID-8>>.] 791 * pname:residencyStandard2DMultisampleBlockShape 792ifndef::VKSC_VERSION_1_0[] 793 is ename:VK_TRUE if the physical device will access all multisample 2D 794 sparse resources using the standard sparse image block shapes (based on 795 image format), as described in the 796 <<sparsememory-sparseblockshapesmsaa,Standard Sparse Image Block Shapes 797 (MSAA)>> table. 798 If this property is not supported, the value returned in the 799 pname:imageGranularity member of the sname:VkSparseImageFormatProperties 800 structure for multisample 2D images is not required: to match the 801 standard sparse image block dimensions listed in the table. 802endif::VKSC_VERSION_1_0[] 803ifdef::VKSC_VERSION_1_0[must: be ename:VK_FALSE in Vulkan SC <<SCID-8>>.] 804 * pname:residencyStandard3DBlockShape 805ifndef::VKSC_VERSION_1_0[] 806 is ename:VK_TRUE if the physical device will access all 3D sparse 807 resources using the standard sparse image block shapes (based on image 808 format), as described in the 809 <<sparsememory-sparseblockshapessingle,Standard Sparse Image Block 810 Shapes (Single Sample)>> table. 811 If this property is not supported, the value returned in the 812 pname:imageGranularity member of the sname:VkSparseImageFormatProperties 813 structure for 3D images is not required: to match the standard sparse 814 image block dimensions listed in the table. 815endif::VKSC_VERSION_1_0[] 816ifdef::VKSC_VERSION_1_0[must: be ename:VK_FALSE in Vulkan SC <<SCID-8>>.] 817 * pname:residencyAlignedMipSize 818ifndef::VKSC_VERSION_1_0[] 819 is ename:VK_TRUE if images with mip level dimensions that are not 820 integer multiples of the corresponding dimensions of the sparse image 821 block may: be placed in the mip tail. 822 If this property is not reported, only mip levels with dimensions 823 smaller than the pname:imageGranularity member of the 824 sname:VkSparseImageFormatProperties structure will be placed in the mip 825 tail. 826 If this property is reported the implementation is allowed to return 827 ename:VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT in the pname:flags 828 member of sname:VkSparseImageFormatProperties, indicating that mip level 829 dimensions that are not integer multiples of the corresponding 830 dimensions of the sparse image block will be placed in the mip tail. 831endif::VKSC_VERSION_1_0[] 832ifdef::VKSC_VERSION_1_0[must: be ename:VK_FALSE in Vulkan SC <<SCID-8>>.] 833 * pname:residencyNonResidentStrict 834ifndef::VKSC_VERSION_1_0[] 835 specifies whether the physical device can: consistently access 836 non-resident regions of a resource. 837 If this property is ename:VK_TRUE, access to non-resident regions of 838 resources will be guaranteed to return values as if the resource was 839 populated with 0; writes to non-resident regions will be discarded. 840endif::VKSC_VERSION_1_0[] 841ifdef::VKSC_VERSION_1_0[] 842 must: be ename:VK_FALSE in Vulkan SC <<SCID-8>>. 843ifdef::hidden[] 844// tag::scdeviation[] 845 * slink:VkPhysicalDeviceSparseProperties::pname:residencyStandard2DBlockShape 846 must: be reported as ename:VK_FALSE <<SCID-8>>. 847 * slink:VkPhysicalDeviceSparseProperties::pname:residencyStandard2DMultisampleBlockShape 848 must: be reported as ename:VK_FALSE <<SCID-8>>. 849 * slink:VkPhysicalDeviceSparseProperties::pname:residencyStandard3DBlockShape 850 must: be reported as ename:VK_FALSE <<SCID-8>>. 851 * slink:VkPhysicalDeviceSparseProperties::pname:residencyAlignedMipSize 852 must: be reported as ename:VK_FALSE <<SCID-8>>. 853 * slink:VkPhysicalDeviceSparseProperties::pname:residencyNonResidentStrict 854 must: be reported as ename:VK_FALSE <<SCID-8>>. 855// end::scdeviation[] 856endif::hidden[] 857endif::VKSC_VERSION_1_0[] 858 859 860include::{generated}/validity/structs/VkPhysicalDeviceSparseProperties.adoc[] 861-- 862 863ifndef::VKSC_VERSION_1_0[] 864 865[[sparsememory-format-props]] 866=== Sparse Image Format Properties 867 868Given that certain aspects of sparse image support, including the sparse 869image block dimensions, may: be implementation-dependent, 870flink:vkGetPhysicalDeviceSparseImageFormatProperties can: be used to query 871for sparse image format properties prior to resource creation. 872This command is used to check whether a given set of sparse image parameters 873is supported and what the sparse image block shape will be. 874 875 876==== Sparse Image Format Properties API 877 878[open,refpage='VkSparseImageFormatProperties',desc='Structure specifying sparse image format properties',type='structs'] 879-- 880The sname:VkSparseImageFormatProperties structure is defined as: 881 882include::{generated}/api/structs/VkSparseImageFormatProperties.adoc[] 883 884 * pname:aspectMask is a bitmask elink:VkImageAspectFlagBits specifying 885 which aspects of the image the properties apply to. 886 * pname:imageGranularity is the width, height, and depth of the sparse 887 image block in texels or compressed texel blocks. 888 * pname:flags is a bitmask of elink:VkSparseImageFormatFlagBits specifying 889 additional information about the sparse resource. 890 891include::{generated}/validity/structs/VkSparseImageFormatProperties.adoc[] 892-- 893 894[open,refpage='VkSparseImageFormatFlagBits',desc='Bitmask specifying additional information about a sparse image resource',type='enums'] 895-- 896Bits which may: be set in slink:VkSparseImageFormatProperties::pname:flags, 897specifying additional information about the sparse resource, are: 898 899include::{generated}/api/enums/VkSparseImageFormatFlagBits.adoc[] 900 901 * ename:VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT specifies that the image 902 uses a single mip tail region for all array layers. 903 * ename:VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT specifies that the 904 first mip level whose dimensions are not integer multiples of the 905 corresponding dimensions of the sparse image block begins the mip tail 906 region. 907 * ename:VK_SPARSE_IMAGE_FORMAT_NONSTANDARD_BLOCK_SIZE_BIT specifies that 908 the image uses non-standard sparse image block dimensions, and the 909 pname:imageGranularity values do not match the standard sparse image 910 block dimensions for the given format. 911-- 912 913[open,refpage='VkSparseImageFormatFlags',desc='Bitmask of VkSparseImageFormatFlagBits',type='flags'] 914-- 915include::{generated}/api/flags/VkSparseImageFormatFlags.adoc[] 916 917tname:VkSparseImageFormatFlags is a bitmask type for setting a mask of zero 918or more elink:VkSparseImageFormatFlagBits. 919-- 920 921[open,refpage='vkGetPhysicalDeviceSparseImageFormatProperties',desc='Retrieve properties of an image format applied to sparse images',type='protos'] 922-- 923fname:vkGetPhysicalDeviceSparseImageFormatProperties returns an array of 924slink:VkSparseImageFormatProperties. 925Each element will describe properties for one set of image aspects that are 926bound simultaneously in the image. 927This is usually one element for each aspect in the image, but for 928interleaved depth/stencil images there is only one element describing the 929combined aspects. 930 931include::{generated}/api/protos/vkGetPhysicalDeviceSparseImageFormatProperties.adoc[] 932 933 * pname:physicalDevice is the physical device from which to query the 934 sparse image format properties. 935 * pname:format is the image format. 936 * pname:type is the dimensionality of image. 937 * pname:samples is a elink:VkSampleCountFlagBits value specifying the 938 number of samples per texel. 939 * pname:usage is a bitmask describing the intended usage of the image. 940 * pname:tiling is the tiling arrangement of the texel blocks in memory. 941 * pname:pPropertyCount is a pointer to an integer related to the number of 942 sparse format properties available or queried, as described below. 943 * pname:pProperties is either `NULL` or a pointer to an array of 944 slink:VkSparseImageFormatProperties structures. 945 946If pname:pProperties is `NULL`, then the number of sparse format properties 947available is returned in pname:pPropertyCount. 948Otherwise, pname:pPropertyCount must: point to a variable set by the user to 949the number of elements in the pname:pProperties array, and on return the 950variable is overwritten with the number of structures actually written to 951pname:pProperties. 952If pname:pPropertyCount is less than the number of sparse format properties 953available, at most pname:pPropertyCount structures will be written. 954 955If ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT is not supported for the given 956arguments, pname:pPropertyCount will be set to zero upon return, and no data 957will be written to pname:pProperties. 958 959Multiple aspects are returned for depth/stencil images that are implemented 960as separate planes by the implementation. 961The depth and stencil data planes each have unique 962sname:VkSparseImageFormatProperties data. 963 964Depth/stencil images with depth and stencil data interleaved into a single 965plane will return a single sname:VkSparseImageFormatProperties structure 966with the pname:aspectMask set to ename:VK_IMAGE_ASPECT_DEPTH_BIT | 967ename:VK_IMAGE_ASPECT_STENCIL_BIT. 968 969.Valid Usage 970**** 971 * [[VUID-vkGetPhysicalDeviceSparseImageFormatProperties-samples-01094]] 972 pname:samples must: be a bit value that is set in 973 sname:VkImageFormatProperties::pname:sampleCounts returned by 974 fname:vkGetPhysicalDeviceImageFormatProperties with pname:format, 975 pname:type, pname:tiling, and pname:usage equal to those in this command 976 and pname:flags equal to the value that is set in 977 slink:VkImageCreateInfo::pname:flags when the image is created 978**** 979 980include::{generated}/validity/protos/vkGetPhysicalDeviceSparseImageFormatProperties.adoc[] 981-- 982 983ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 984[open,refpage='vkGetPhysicalDeviceSparseImageFormatProperties2',desc='Retrieve properties of an image format applied to sparse images',type='protos'] 985-- 986fname:vkGetPhysicalDeviceSparseImageFormatProperties2 returns an array of 987slink:VkSparseImageFormatProperties2. 988Each element will describe properties for one set of image aspects that are 989bound simultaneously in the image. 990This is usually one element for each aspect in the image, but for 991interleaved depth/stencil images there is only one element describing the 992combined aspects. 993 994ifdef::VK_VERSION_1_1[] 995include::{generated}/api/protos/vkGetPhysicalDeviceSparseImageFormatProperties2.adoc[] 996endif::VK_VERSION_1_1[] 997 998ifdef::VK_VERSION_1_1+VK_KHR_get_physical_device_properties2[or the equivalent command] 999 1000ifdef::VK_KHR_get_physical_device_properties2[] 1001include::{generated}/api/protos/vkGetPhysicalDeviceSparseImageFormatProperties2KHR.adoc[] 1002endif::VK_KHR_get_physical_device_properties2[] 1003 1004 * pname:physicalDevice is the physical device from which to query the 1005 sparse image format properties. 1006 * pname:pFormatInfo is a pointer to a 1007 slink:VkPhysicalDeviceSparseImageFormatInfo2 structure containing input 1008 parameters to the command. 1009 * pname:pPropertyCount is a pointer to an integer related to the number of 1010 sparse format properties available or queried, as described below. 1011 * pname:pProperties is either `NULL` or a pointer to an array of 1012 slink:VkSparseImageFormatProperties2 structures. 1013 1014fname:vkGetPhysicalDeviceSparseImageFormatProperties2 behaves identically to 1015flink:vkGetPhysicalDeviceSparseImageFormatProperties, with the ability to 1016return extended information by adding extending structures to the 1017pname:pNext chain of its pname:pProperties parameter. 1018 1019include::{generated}/validity/protos/vkGetPhysicalDeviceSparseImageFormatProperties2.adoc[] 1020-- 1021 1022[open,refpage='VkPhysicalDeviceSparseImageFormatInfo2',desc='Structure specifying sparse image format inputs',type='structs'] 1023-- 1024The sname:VkPhysicalDeviceSparseImageFormatInfo2 structure is defined as: 1025 1026include::{generated}/api/structs/VkPhysicalDeviceSparseImageFormatInfo2.adoc[] 1027 1028ifdef::VK_KHR_get_physical_device_properties2[] 1029or the equivalent 1030 1031include::{generated}/api/structs/VkPhysicalDeviceSparseImageFormatInfo2KHR.adoc[] 1032endif::VK_KHR_get_physical_device_properties2[] 1033 1034 * pname:sType is a elink:VkStructureType value identifying this structure. 1035 * pname:pNext is `NULL` or a pointer to a structure extending this 1036 structure. 1037 * pname:format is the image format. 1038 * pname:type is the dimensionality of image. 1039 * pname:samples is a elink:VkSampleCountFlagBits value specifying the 1040 number of samples per texel. 1041 * pname:usage is a bitmask describing the intended usage of the image. 1042 * pname:tiling is the tiling arrangement of the texel blocks in memory. 1043 1044.Valid Usage 1045**** 1046 * [[VUID-VkPhysicalDeviceSparseImageFormatInfo2-samples-01095]] 1047 pname:samples must: be a bit value that is set in 1048 sname:VkImageFormatProperties::pname:sampleCounts returned by 1049 fname:vkGetPhysicalDeviceImageFormatProperties with pname:format, 1050 pname:type, pname:tiling, and pname:usage equal to those in this command 1051 and pname:flags equal to the value that is set in 1052 slink:VkImageCreateInfo::pname:flags when the image is created 1053**** 1054 1055include::{generated}/validity/structs/VkPhysicalDeviceSparseImageFormatInfo2.adoc[] 1056-- 1057 1058[open,refpage='VkSparseImageFormatProperties2',desc='Structure specifying sparse image format properties',type='structs'] 1059-- 1060The sname:VkSparseImageFormatProperties2 structure is defined as: 1061 1062include::{generated}/api/structs/VkSparseImageFormatProperties2.adoc[] 1063 1064ifdef::VK_KHR_get_physical_device_properties2[] 1065or the equivalent 1066 1067include::{generated}/api/structs/VkSparseImageFormatProperties2KHR.adoc[] 1068endif::VK_KHR_get_physical_device_properties2[] 1069 1070 * pname:sType is a elink:VkStructureType value identifying this structure. 1071 * pname:pNext is `NULL` or a pointer to a structure extending this 1072 structure. 1073 * pname:properties is a slink:VkSparseImageFormatProperties structure 1074 which is populated with the same values as in 1075 flink:vkGetPhysicalDeviceSparseImageFormatProperties. 1076 1077include::{generated}/validity/structs/VkSparseImageFormatProperties2.adoc[] 1078-- 1079endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 1080 1081 1082[[sparsememory-resource-creation]] 1083=== Sparse Resource Creation 1084 1085Sparse resources require that one or more sparse feature flags be specified 1086(as part of the sname:VkPhysicalDeviceFeatures structure described 1087previously in the <<sparsememory-physicalfeatures,Physical Device Features>> 1088section) when calling flink:vkCreateDevice. 1089When the appropriate device features are enabled, the 1090etext:VK_BUFFER_CREATE_SPARSE_* and etext:VK_IMAGE_CREATE_SPARSE_* flags 1091can: be used. 1092See flink:vkCreateBuffer and flink:vkCreateImage for details of the resource 1093creation APIs. 1094 1095[NOTE] 1096.Note 1097==== 1098Specifying ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT or 1099ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT requires specifying 1100ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT or 1101ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, respectively, as well. 1102This means that resources must: be created with the appropriate 1103etext:*_SPARSE_BINDING_BIT to be used with the sparse binding command 1104(fname:vkQueueBindSparse). 1105==== 1106 1107 1108[[sparsememory-memory-requirements]] 1109=== Sparse Resource Memory Requirements 1110 1111Sparse resources have specific memory requirements related to binding sparse 1112memory. 1113These memory requirements are reported differently for sname:VkBuffer 1114objects and sname:VkImage objects. 1115 1116 1117[[sparsememory-memory-buffer-fully-resident]] 1118==== Buffer and Fully-Resident Images 1119 1120Buffers (both fully and partially resident) and fully-resident images can: 1121be bound to memory using only the data from sname:VkMemoryRequirements. 1122For all sparse resources the sname:VkMemoryRequirements::pname:alignment 1123member specifies both the bindable sparse block size in bytes and required: 1124alignment of sname:VkDeviceMemory. 1125 1126 1127[[sparsememory-memory-partially-resident]] 1128==== Partially Resident Images 1129 1130Partially resident images have a different method for binding memory. 1131As with buffers and fully resident images, the 1132sname:VkMemoryRequirements::pname:alignment field specifies the bindable 1133sparse block size in bytes for the image. 1134 1135Requesting sparse memory requirements for sname:VkImage objects using 1136fname:vkGetImageSparseMemoryRequirements will return an array of one or more 1137sname:VkSparseImageMemoryRequirements structures. 1138Each structure describes the sparse memory requirements for a group of 1139aspects of the image. 1140 1141The sparse image must: have been created using the 1142ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT flag to retrieve valid sparse 1143image memory requirements. 1144 1145 1146==== Sparse Image Memory Requirements 1147 1148[open,refpage='VkSparseImageMemoryRequirements',desc='Structure specifying sparse image memory requirements',type='structs'] 1149-- 1150The sname:VkSparseImageMemoryRequirements structure is defined as: 1151 1152include::{generated}/api/structs/VkSparseImageMemoryRequirements.adoc[] 1153 1154 * pname:formatProperties is a slink:VkSparseImageFormatProperties 1155 structure specifying properties of the image format. 1156 * pname:imageMipTailFirstLod is the first mip level at which image 1157 subresources are included in the mip tail region. 1158 * pname:imageMipTailSize is the memory size (in bytes) of the mip tail 1159 region. 1160 If pname:formatProperties.flags contains 1161 ename:VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT, this is the size of the 1162 whole mip tail, otherwise this is the size of the mip tail of a single 1163 array layer. 1164 This value is guaranteed to be a multiple of the sparse block size in 1165 bytes. 1166 * pname:imageMipTailOffset is the opaque memory offset used with 1167 slink:VkSparseImageOpaqueMemoryBindInfo to bind the mip tail region(s). 1168 * pname:imageMipTailStride is the offset stride between each array-layer's 1169 mip tail, if pname:formatProperties.flags does not contain 1170 ename:VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT (otherwise the value is 1171 undefined:). 1172 1173include::{generated}/validity/structs/VkSparseImageMemoryRequirements.adoc[] 1174-- 1175 1176[open,refpage='vkGetImageSparseMemoryRequirements',desc='Query the memory requirements for a sparse image',type='protos'] 1177-- 1178To query sparse memory requirements for an image, call: 1179 1180include::{generated}/api/protos/vkGetImageSparseMemoryRequirements.adoc[] 1181 1182 * pname:device is the logical device that owns the image. 1183 * pname:image is the slink:VkImage object to get the memory requirements 1184 for. 1185 * pname:pSparseMemoryRequirementCount is a pointer to an integer related 1186 to the number of sparse memory requirements available or queried, as 1187 described below. 1188 * pname:pSparseMemoryRequirements is either `NULL` or a pointer to an 1189 array of sname:VkSparseImageMemoryRequirements structures. 1190 1191If pname:pSparseMemoryRequirements is `NULL`, then the number of sparse 1192memory requirements available is returned in 1193pname:pSparseMemoryRequirementCount. 1194Otherwise, pname:pSparseMemoryRequirementCount must: point to a variable set 1195by the user to the number of elements in the pname:pSparseMemoryRequirements 1196array, and on return the variable is overwritten with the number of 1197structures actually written to pname:pSparseMemoryRequirements. 1198If pname:pSparseMemoryRequirementCount is less than the number of sparse 1199memory requirements available, at most pname:pSparseMemoryRequirementCount 1200structures will be written. 1201 1202If the image was not created with ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT 1203then pname:pSparseMemoryRequirementCount will be set to zero and 1204pname:pSparseMemoryRequirements will not be written to. 1205 1206[NOTE] 1207.Note 1208==== 1209It is legal for an implementation to report a larger value in 1210sname:VkMemoryRequirements::pname:size than would be obtained by adding 1211together memory sizes for all sname:VkSparseImageMemoryRequirements returned 1212by fname:vkGetImageSparseMemoryRequirements. 1213This may: occur when the implementation requires unused padding in the 1214address range describing the resource. 1215==== 1216 1217include::{generated}/validity/protos/vkGetImageSparseMemoryRequirements.adoc[] 1218-- 1219 1220ifdef::VK_VERSION_1_1,VK_KHR_get_memory_requirements2[] 1221[open,refpage='vkGetImageSparseMemoryRequirements2',desc='Query the memory requirements for a sparse image',type='protos'] 1222-- 1223To query sparse memory requirements for an image, call: 1224 1225ifdef::VK_VERSION_1_1[] 1226include::{generated}/api/protos/vkGetImageSparseMemoryRequirements2.adoc[] 1227endif::VK_VERSION_1_1[] 1228 1229ifdef::VK_VERSION_1_1+VK_KHR_get_memory_requirements2[or the equivalent command] 1230 1231ifdef::VK_KHR_get_memory_requirements2[] 1232include::{generated}/api/protos/vkGetImageSparseMemoryRequirements2KHR.adoc[] 1233endif::VK_KHR_get_memory_requirements2[] 1234 1235 * pname:device is the logical device that owns the image. 1236 * pname:pInfo is a pointer to a sname:VkImageSparseMemoryRequirementsInfo2 1237 structure containing parameters required for the memory requirements 1238 query. 1239 * pname:pSparseMemoryRequirementCount is a pointer to an integer related 1240 to the number of sparse memory requirements available or queried, as 1241 described below. 1242 * pname:pSparseMemoryRequirements is either `NULL` or a pointer to an 1243 array of sname:VkSparseImageMemoryRequirements2 structures. 1244 1245include::{generated}/validity/protos/vkGetImageSparseMemoryRequirements2.adoc[] 1246-- 1247 1248ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[] 1249[open,refpage='vkGetDeviceImageSparseMemoryRequirements',desc='Query the memory requirements for a sparse image',type='protos',alias='vkGetDeviceImageSparseMemoryRequirementsKHR'] 1250-- 1251To determine the sparse memory requirements for an image resource without 1252creating an object, call: 1253 1254ifdef::VK_VERSION_1_3[] 1255include::{generated}/api/protos/vkGetDeviceImageSparseMemoryRequirements.adoc[] 1256endif::VK_VERSION_1_3[] 1257 1258ifdef::VK_VERSION_1_3+VK_KHR_maintenance4[or the equivalent command] 1259 1260ifdef::VK_KHR_maintenance4[] 1261include::{generated}/api/protos/vkGetDeviceImageSparseMemoryRequirementsKHR.adoc[] 1262endif::VK_KHR_maintenance4[] 1263 1264 * pname:device is the logical device intended to own the image. 1265 * pname:pInfo is a pointer to a slink:VkDeviceImageMemoryRequirements 1266 structure containing parameters required for the memory requirements 1267 query. 1268 * pname:pSparseMemoryRequirementCount is a pointer to an integer related 1269 to the number of sparse memory requirements available or queried, as 1270 described below. 1271 * pname:pSparseMemoryRequirements is either `NULL` or a pointer to an 1272 array of sname:VkSparseImageMemoryRequirements2 structures. 1273 1274include::{generated}/validity/protos/vkGetDeviceImageSparseMemoryRequirements.adoc[] 1275-- 1276endif::VK_VERSION_1_3,VK_KHR_maintenance4[] 1277 1278[open,refpage='VkImageSparseMemoryRequirementsInfo2',desc='(None)',type='structs'] 1279-- 1280The sname:VkImageSparseMemoryRequirementsInfo2 structure is defined as: 1281 1282include::{generated}/api/structs/VkImageSparseMemoryRequirementsInfo2.adoc[] 1283 1284ifdef::VK_KHR_get_memory_requirements2[] 1285or the equivalent 1286 1287include::{generated}/api/structs/VkImageSparseMemoryRequirementsInfo2KHR.adoc[] 1288endif::VK_KHR_get_memory_requirements2[] 1289 1290 * pname:sType is a elink:VkStructureType value identifying this structure. 1291 * pname:pNext is `NULL` or a pointer to a structure extending this 1292 structure. 1293 * pname:image is the image to query. 1294 1295include::{generated}/validity/structs/VkImageSparseMemoryRequirementsInfo2.adoc[] 1296-- 1297 1298[open,refpage='VkSparseImageMemoryRequirements2',desc='(None)',type='structs'] 1299-- 1300The sname:VkSparseImageMemoryRequirements2 structure is defined as: 1301 1302include::{generated}/api/structs/VkSparseImageMemoryRequirements2.adoc[] 1303 1304ifdef::VK_KHR_get_memory_requirements2[] 1305or the equivalent 1306 1307include::{generated}/api/structs/VkSparseImageMemoryRequirements2KHR.adoc[] 1308endif::VK_KHR_get_memory_requirements2[] 1309 1310 * pname:sType is a elink:VkStructureType value identifying this structure. 1311 * pname:pNext is `NULL` or a pointer to a structure extending this 1312 structure. 1313 * pname:memoryRequirements is a slink:VkSparseImageMemoryRequirements 1314 structure describing the memory requirements of the sparse image. 1315 1316include::{generated}/validity/structs/VkSparseImageMemoryRequirements2.adoc[] 1317-- 1318endif::VK_VERSION_1_1,VK_KHR_get_memory_requirements2[] 1319 1320 1321[[sparsememory-resource-binding]] 1322=== Binding Resource Memory 1323 1324Non-sparse resources are backed by a single physical allocation prior to 1325device use (via fname:vkBindImageMemory or fname:vkBindBufferMemory), and 1326their backing must: not be changed. 1327On the other hand, sparse resources can: be bound to memory non-contiguously 1328and these bindings can: be altered during the lifetime of the resource. 1329 1330ifndef::VKSC_VERSION_1_0[] 1331 1332[NOTE] 1333.Note 1334==== 1335It is important to note that freeing a sname:VkDeviceMemory object with 1336fname:vkFreeMemory will not cause resources (or resource regions) bound to 1337the memory object to become unbound. 1338Applications must: not access resources bound to memory that has been freed. 1339==== 1340 1341endif::VKSC_VERSION_1_0[] 1342 1343Sparse memory bindings execute on a queue that includes the 1344ename:VK_QUEUE_SPARSE_BINDING_BIT bit. 1345Applications must: use <<synchronization,synchronization primitives>> to 1346guarantee that other queues do not access ranges of memory concurrently with 1347a binding change. 1348Applications can: access other ranges of the same resource while a bind 1349operation is executing. 1350 1351[NOTE] 1352.Note 1353==== 1354Implementations must: provide a guarantee that simultaneously binding sparse 1355blocks while another queue accesses those same sparse blocks via a sparse 1356resource must: not access memory owned by another process or otherwise 1357corrupt the system. 1358==== 1359 1360While some implementations may: include ename:VK_QUEUE_SPARSE_BINDING_BIT 1361support in queue families that also include graphics and compute support, 1362other implementations may: only expose a 1363ename:VK_QUEUE_SPARSE_BINDING_BIT-only queue family. 1364In either case, applications must: use <<synchronization,synchronization 1365primitives>> to explicitly request any ordering dependencies between sparse 1366memory binding operations and other graphics/compute/transfer operations, as 1367sparse binding operations are not automatically ordered against command 1368buffer execution, even within a single queue. 1369 1370When binding memory explicitly for the ename:VK_IMAGE_ASPECT_METADATA_BIT 1371the application must: use the ename:VK_SPARSE_MEMORY_BIND_METADATA_BIT in 1372the sname:VkSparseMemoryBind::pname:flags field when binding memory. 1373Binding memory for metadata is done the same way as binding memory for the 1374mip tail, with the addition of the ename:VK_SPARSE_MEMORY_BIND_METADATA_BIT 1375flag. 1376 1377Binding the mip tail for any aspect must: only be performed using 1378slink:VkSparseImageOpaqueMemoryBindInfo. 1379If pname:formatProperties.flags contains 1380ename:VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT, then it can: be bound with 1381a single slink:VkSparseMemoryBind structure, with pname:resourceOffset = 1382pname:imageMipTailOffset and pname:size = pname:imageMipTailSize. 1383 1384If pname:formatProperties.flags does not contain 1385ename:VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT then the offset for the mip 1386tail in each array layer is given as: 1387 1388[source,c++] 1389---- 1390arrayMipTailOffset = imageMipTailOffset + arrayLayer * imageMipTailStride; 1391---- 1392 1393and the mip tail can: be bound with code:layerCount slink:VkSparseMemoryBind 1394structures, each using pname:size = pname:imageMipTailSize and 1395pname:resourceOffset = ptext:arrayMipTailOffset as defined above. 1396 1397Sparse memory binding is handled by the following APIs and related data 1398structures. 1399 1400 1401[[sparsemem-memory-binding]] 1402==== Sparse Memory Binding Functions 1403 1404[open,refpage='VkSparseMemoryBind',desc='Structure specifying a sparse memory bind operation',type='structs'] 1405-- 1406The sname:VkSparseMemoryBind structure is defined as: 1407 1408include::{generated}/api/structs/VkSparseMemoryBind.adoc[] 1409 1410 * pname:resourceOffset is the offset into the resource. 1411 * pname:size is the size of the memory region to be bound. 1412 * pname:memory is the slink:VkDeviceMemory object that the range of the 1413 resource is bound to. 1414 If pname:memory is dlink:VK_NULL_HANDLE, the range is unbound. 1415 * pname:memoryOffset is the offset into the slink:VkDeviceMemory object to 1416 bind the resource range to. 1417 If pname:memory is dlink:VK_NULL_HANDLE, this value is ignored. 1418 * pname:flags is a bitmask of elink:VkSparseMemoryBindFlagBits specifying 1419 usage of the binding operation. 1420 1421The _binding range_ [eq]#[pname:resourceOffset, pname:resourceOffset {plus} 1422pname:size)# has different constraints based on pname:flags. 1423If pname:flags contains ename:VK_SPARSE_MEMORY_BIND_METADATA_BIT, the 1424binding range must: be within the mip tail region of the metadata aspect. 1425This metadata region is defined by: 1426 1427 {empty}:: [eq]#metadataRegion = [base, base {plus} 1428 pname:imageMipTailSize)# 1429 {empty}:: [eq]#base = pname:imageMipTailOffset {plus} 1430 pname:imageMipTailStride {times} n# 1431 1432and pname:imageMipTailOffset, pname:imageMipTailSize, and 1433pname:imageMipTailStride values are from the 1434slink:VkSparseImageMemoryRequirements corresponding to the metadata aspect 1435of the image, and [eq]#n# is a valid array layer index for the image, 1436 1437pname:imageMipTailStride is considered to be zero for aspects where 1438sname:VkSparseImageMemoryRequirements::pname:formatProperties.flags contains 1439ename:VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT. 1440 1441If pname:flags does not contain ename:VK_SPARSE_MEMORY_BIND_METADATA_BIT, 1442the binding range must: be within the range 1443[eq]#[0,slink:VkMemoryRequirements::pname:size)#. 1444 1445.Valid Usage 1446**** 1447 * [[VUID-VkSparseMemoryBind-memory-01096]] 1448 If pname:memory is not dlink:VK_NULL_HANDLE, pname:memory and 1449 pname:memoryOffset must: match the memory requirements of the resource, 1450 as described in section <<resources-association>> 1451 * [[VUID-VkSparseMemoryBind-memory-01097]] 1452 If pname:memory is not dlink:VK_NULL_HANDLE, pname:memory must: not have 1453 been created with a memory type that reports 1454 ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit set 1455 * [[VUID-VkSparseMemoryBind-size-01098]] 1456 pname:size must: be greater than `0` 1457 * [[VUID-VkSparseMemoryBind-resourceOffset-01099]] 1458 pname:resourceOffset must: be less than the size of the resource 1459 * [[VUID-VkSparseMemoryBind-size-01100]] 1460 pname:size must: be less than or equal to the size of the resource minus 1461 pname:resourceOffset 1462 * [[VUID-VkSparseMemoryBind-memoryOffset-01101]] 1463 pname:memoryOffset must: be less than the size of pname:memory 1464 * [[VUID-VkSparseMemoryBind-size-01102]] 1465 pname:size must: be less than or equal to the size of pname:memory minus 1466 pname:memoryOffset 1467ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 1468 * [[VUID-VkSparseMemoryBind-memory-02730]] 1469 If pname:memory was created with 1470 slink:VkExportMemoryAllocateInfo::pname:handleTypes not equal to `0`, at 1471 least one handle type it contained must: also have been set in 1472 slink:VkExternalMemoryBufferCreateInfo::pname:handleTypes or 1473 slink:VkExternalMemoryImageCreateInfo::pname:handleTypes when the 1474 resource was created 1475 * [[VUID-VkSparseMemoryBind-memory-02731]] 1476 If pname:memory was created by a memory import operation, the external 1477 handle type of the imported memory must: also have been set in 1478 slink:VkExternalMemoryBufferCreateInfo::pname:handleTypes or 1479 slink:VkExternalMemoryImageCreateInfo::pname:handleTypes when the 1480 resource was created 1481endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1482**** 1483 1484include::{generated}/validity/structs/VkSparseMemoryBind.adoc[] 1485-- 1486 1487[open,refpage='VkSparseMemoryBindFlagBits',desc='Bitmask specifying usage of a sparse memory binding operation',type='enums'] 1488-- 1489Bits which can: be set in slink:VkSparseMemoryBind::pname:flags, specifying 1490usage of a sparse memory binding operation, are: 1491 1492include::{generated}/api/enums/VkSparseMemoryBindFlagBits.adoc[] 1493 1494 * ename:VK_SPARSE_MEMORY_BIND_METADATA_BIT specifies that the memory being 1495 bound is only for the metadata aspect. 1496-- 1497 1498[open,refpage='VkSparseMemoryBindFlags',desc='Bitmask of VkSparseMemoryBindFlagBits',type='flags'] 1499-- 1500include::{generated}/api/flags/VkSparseMemoryBindFlags.adoc[] 1501 1502tname:VkSparseMemoryBindFlags is a bitmask type for setting a mask of zero 1503or more elink:VkSparseMemoryBindFlagBits. 1504-- 1505 1506[open,refpage='VkSparseBufferMemoryBindInfo',desc='Structure specifying a sparse buffer memory bind operation',type='structs'] 1507-- 1508Memory is bound to sname:VkBuffer objects created with the 1509ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT flag using the following 1510structure: 1511 1512include::{generated}/api/structs/VkSparseBufferMemoryBindInfo.adoc[] 1513 1514 * pname:buffer is the slink:VkBuffer object to be bound. 1515 * pname:bindCount is the number of slink:VkSparseMemoryBind structures in 1516 the pname:pBinds array. 1517 * pname:pBinds is a pointer to an array of slink:VkSparseMemoryBind 1518 structures. 1519 1520include::{generated}/validity/structs/VkSparseBufferMemoryBindInfo.adoc[] 1521-- 1522 1523[open,refpage='VkSparseImageOpaqueMemoryBindInfo',desc='Structure specifying sparse image opaque memory bind information',type='structs'] 1524-- 1525Memory is bound to opaque regions of sname:VkImage objects created with the 1526ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT flag using the following structure: 1527 1528include::{generated}/api/structs/VkSparseImageOpaqueMemoryBindInfo.adoc[] 1529 1530 * pname:image is the slink:VkImage object to be bound. 1531 * pname:bindCount is the number of slink:VkSparseMemoryBind structures in 1532 the pname:pBinds array. 1533 * pname:pBinds is a pointer to an array of slink:VkSparseMemoryBind 1534 structures. 1535 1536.Valid Usage 1537**** 1538 * [[VUID-VkSparseImageOpaqueMemoryBindInfo-pBinds-01103]] 1539 If the pname:flags member of any element of pname:pBinds contains 1540 ename:VK_SPARSE_MEMORY_BIND_METADATA_BIT, the binding range defined 1541 must: be within the mip tail region of the metadata aspect of 1542 pname:image 1543**** 1544 1545include::{generated}/validity/structs/VkSparseImageOpaqueMemoryBindInfo.adoc[] 1546-- 1547 1548[NOTE] 1549.Note 1550==== 1551This operation is normally used to bind memory to fully-resident sparse 1552images or for mip tail regions of partially resident images. 1553However, it can: also be used to bind memory for the entire binding range of 1554partially resident images. 1555 1556In case pname:flags does not contain 1557ename:VK_SPARSE_MEMORY_BIND_METADATA_BIT, the pname:resourceOffset is in the 1558range [eq]#[0, slink:VkMemoryRequirements::pname:size)#, This range includes 1559data from all aspects of the image, including metadata. 1560For most implementations this will probably mean that the 1561pname:resourceOffset is a simple device address offset within the resource. 1562It is possible for an application to bind a range of memory that includes 1563both resource data and metadata. 1564However, the application would not know what part of the image the memory is 1565used for, or if any range is being used for metadata. 1566 1567When pname:flags contains ename:VK_SPARSE_MEMORY_BIND_METADATA_BIT, the 1568binding range specified must: be within the mip tail region of the metadata 1569aspect. 1570In this case the pname:resourceOffset is not required: to be a simple device 1571address offset within the resource. 1572However, it _is_ defined to be within [eq]#[pname:imageMipTailOffset, 1573pname:imageMipTailOffset {plus} pname:imageMipTailSize)# for the metadata 1574aspect. 1575See slink:VkSparseMemoryBind for the full constraints on binding region with 1576this flag present. 1577==== 1578 1579ifdef::editing-notes[] 1580[NOTE] 1581.editing-note 1582==== 1583(Jon) The preceding NOTE refers to pname:flags, which is presumably a 1584reference to slink:VkSparseMemoryBind above, even though that is not 1585contextually clear. 1586==== 1587endif::editing-notes[] 1588 1589[open,refpage='VkSparseImageMemoryBindInfo',desc='Structure specifying sparse image memory bind information',type='structs'] 1590-- 1591Memory can: be bound to sparse image blocks of sname:VkImage objects created 1592with the ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT flag using the following 1593structure: 1594 1595include::{generated}/api/structs/VkSparseImageMemoryBindInfo.adoc[] 1596 1597 * pname:image is the slink:VkImage object to be bound 1598 * pname:bindCount is the number of slink:VkSparseImageMemoryBind 1599 structures in pname:pBinds array 1600 * pname:pBinds is a pointer to an array of slink:VkSparseImageMemoryBind 1601 structures 1602 1603.Valid Usage 1604**** 1605 * [[VUID-VkSparseImageMemoryBindInfo-subresource-01722]] 1606 The pname:subresource.mipLevel member of each element of pname:pBinds 1607 must: be less than the pname:mipLevels specified in 1608 slink:VkImageCreateInfo when pname:image was created 1609 * [[VUID-VkSparseImageMemoryBindInfo-subresource-01723]] 1610 The pname:subresource.arrayLayer member of each element of pname:pBinds 1611 must: be less than the pname:arrayLayers specified in 1612 slink:VkImageCreateInfo when pname:image was created 1613 * [[VUID-VkSparseImageMemoryBindInfo-image-02901]] 1614 pname:image must: have been created with 1615 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT set 1616**** 1617 1618include::{generated}/validity/structs/VkSparseImageMemoryBindInfo.adoc[] 1619-- 1620 1621[open,refpage='VkSparseImageMemoryBind',desc='Structure specifying sparse image memory bind',type='structs'] 1622-- 1623The sname:VkSparseImageMemoryBind structure is defined as: 1624 1625include::{generated}/api/structs/VkSparseImageMemoryBind.adoc[] 1626 1627 * pname:subresource is the image _aspect_ and region of interest in the 1628 image. 1629 * pname:offset are the coordinates of the first texel within the image 1630 subresource to bind. 1631 * pname:extent is the size in texels of the region within the image 1632 subresource to bind. 1633 The extent must: be a multiple of the sparse image block dimensions, 1634 except when binding sparse image blocks along the edge of an image 1635 subresource it can: instead be such that any coordinate of 1636 [eq]#pname:offset {plus} pname:extent# equals the corresponding 1637 dimensions of the image subresource. 1638 * pname:memory is the slink:VkDeviceMemory object that the sparse image 1639 blocks of the image are bound to. 1640 If pname:memory is dlink:VK_NULL_HANDLE, the sparse image blocks are 1641 unbound. 1642 * pname:memoryOffset is an offset into slink:VkDeviceMemory object. 1643 If pname:memory is dlink:VK_NULL_HANDLE, this value is ignored. 1644 * pname:flags are sparse memory binding flags. 1645 1646.Valid Usage 1647**** 1648 * [[VUID-VkSparseImageMemoryBind-memory-01104]] 1649 If the <<features-sparseResidencyAliased, pname:sparseResidencyAliased>> 1650 feature is not enabled, and if any other resources are bound to ranges 1651 of pname:memory, the range of pname:memory being bound must: not overlap 1652 with those bound ranges 1653 * [[VUID-VkSparseImageMemoryBind-memory-01105]] 1654 pname:memory and pname:memoryOffset must: match the memory requirements 1655 of the calling command's pname:image, as described in section 1656 <<resources-association>> 1657 * [[VUID-VkSparseImageMemoryBind-subresource-01106]] 1658 pname:subresource must: be a valid image subresource for pname:image 1659 (see <<resources-image-views>>) 1660 * [[VUID-VkSparseImageMemoryBind-offset-01107]] 1661 pname:offset.x must: be a multiple of the sparse image block width 1662 (sname:VkSparseImageFormatProperties::pname:imageGranularity.width) of 1663 the image 1664 * [[VUID-VkSparseImageMemoryBind-extent-09388]] 1665 pname:extent.width must: be greater than `0` 1666 * [[VUID-VkSparseImageMemoryBind-extent-01108]] 1667 pname:extent.width must: either be a multiple of the sparse image block 1668 width of the image, or else [eq]#(pname:extent.width {plus} 1669 pname:offset.x)# must: equal the width of the image subresource 1670 * [[VUID-VkSparseImageMemoryBind-offset-01109]] 1671 pname:offset.y must: be a multiple of the sparse image block height 1672 (sname:VkSparseImageFormatProperties::pname:imageGranularity.height) of 1673 the image 1674 * [[VUID-VkSparseImageMemoryBind-extent-09389]] 1675 pname:extent.height must: be greater than `0` 1676 * [[VUID-VkSparseImageMemoryBind-extent-01110]] 1677 pname:extent.height must: either be a multiple of the sparse image block 1678 height of the image, or else [eq]#(pname:extent.height {plus} 1679 pname:offset.y)# must: equal the height of the image subresource 1680 * [[VUID-VkSparseImageMemoryBind-offset-01111]] 1681 pname:offset.z must: be a multiple of the sparse image block depth 1682 (sname:VkSparseImageFormatProperties::pname:imageGranularity.depth) of 1683 the image 1684 * [[VUID-VkSparseImageMemoryBind-extent-09390]] 1685 pname:extent.depth must: be greater than `0` 1686 * [[VUID-VkSparseImageMemoryBind-extent-01112]] 1687 pname:extent.depth must: either be a multiple of the sparse image block 1688 depth of the image, or else [eq]#(pname:extent.depth {plus} 1689 pname:offset.z)# must: equal the depth of the image subresource 1690ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 1691 * [[VUID-VkSparseImageMemoryBind-memory-02732]] 1692 If pname:memory was created with 1693 slink:VkExportMemoryAllocateInfo::pname:handleTypes not equal to `0`, at 1694 least one handle type it contained must: also have been set in 1695 slink:VkExternalMemoryImageCreateInfo::pname:handleTypes when the image 1696 was created 1697 * [[VUID-VkSparseImageMemoryBind-memory-02733]] 1698 If pname:memory was created by a memory import operation, the external 1699 handle type of the imported memory must: also have been set in 1700 slink:VkExternalMemoryImageCreateInfo::pname:handleTypes when 1701 pname:image was created 1702endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1703**** 1704 1705include::{generated}/validity/structs/VkSparseImageMemoryBind.adoc[] 1706-- 1707 1708[open,refpage='vkQueueBindSparse',desc='Bind device memory to a sparse resource object',type='protos'] 1709-- 1710To submit sparse binding operations to a queue, call: 1711 1712include::{generated}/api/protos/vkQueueBindSparse.adoc[] 1713 1714 * pname:queue is the queue that the sparse binding operations will be 1715 submitted to. 1716 * pname:bindInfoCount is the number of elements in the pname:pBindInfo 1717 array. 1718 * pname:pBindInfo is a pointer to an array of slink:VkBindSparseInfo 1719 structures, each specifying a sparse binding submission batch. 1720 * pname:fence is an optional: handle to a fence to be signaled. 1721 If pname:fence is not dlink:VK_NULL_HANDLE, it defines a 1722 <<synchronization-fences-signaling, fence signal operation>>. 1723 1724fname:vkQueueBindSparse is a <<devsandqueues-submission,queue submission 1725command>>, with each batch defined by an element of pname:pBindInfo as a 1726slink:VkBindSparseInfo structure. 1727Batches begin execution in the order they appear in pname:pBindInfo, but 1728may: complete out of order. 1729 1730Within a batch, a given range of a resource must: not be bound more than 1731once. 1732Across batches, if a range is to be bound to one allocation and offset and 1733then to another allocation and offset, then the application must: guarantee 1734(usually using semaphores) that the binding operations are executed in the 1735correct order, as well as to order binding operations against the execution 1736of command buffer submissions. 1737 1738As no operation to flink:vkQueueBindSparse causes any pipeline stage to 1739access memory, synchronization primitives used in this command effectively 1740only define execution dependencies. 1741 1742Additional information about fence and semaphore operation is described in 1743<<synchronization, the synchronization chapter>>. 1744 1745.Valid Usage 1746**** 1747 * [[VUID-vkQueueBindSparse-fence-01113]] 1748 If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: be 1749 unsignaled 1750 * [[VUID-vkQueueBindSparse-fence-01114]] 1751 If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: not be 1752 associated with any other queue command that has not yet completed 1753 execution on that queue 1754 * [[VUID-vkQueueBindSparse-pSignalSemaphores-01115]] 1755 Each element of the pname:pSignalSemaphores member of each element of 1756 pname:pBindInfo must: be unsignaled when the semaphore signal operation 1757 it defines is executed on the device 1758 * [[VUID-vkQueueBindSparse-pWaitSemaphores-01116]] 1759 When a semaphore wait operation referring to a binary semaphore defined 1760 by any element of the pname:pWaitSemaphores member of any element of 1761 pname:pBindInfo executes on pname:queue, there must: be no other queues 1762 waiting on the same semaphore 1763ifndef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1764 * [[VUID-vkQueueBindSparse-pWaitSemaphores-01117]] 1765 All elements of the pname:pWaitSemaphores member of all elements of the 1766 pname:pBindInfo parameter referring to a binary semaphore must: be 1767 semaphores that are signaled, or have 1768 <<synchronization-semaphores-signaling, semaphore signal operations>> 1769 previously submitted for execution 1770endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1771ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1772 * [[VUID-vkQueueBindSparse-pWaitSemaphores-03245]] 1773 All elements of the pname:pWaitSemaphores member of all elements of 1774 pname:pBindInfo created with a elink:VkSemaphoreType of 1775 ename:VK_SEMAPHORE_TYPE_BINARY must: reference a semaphore signal 1776 operation that has been submitted for execution and any 1777 <<synchronization-semaphores-signaling, semaphore signal operations>> on 1778 which it depends (if any) must: have also been submitted for execution 1779endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1780**** 1781 1782include::{generated}/validity/protos/vkQueueBindSparse.adoc[] 1783-- 1784 1785[open,refpage='VkBindSparseInfo',desc='Structure specifying a sparse binding operation',type='structs'] 1786-- 1787The sname:VkBindSparseInfo structure is defined as: 1788 1789include::{generated}/api/structs/VkBindSparseInfo.adoc[] 1790 1791 * pname:sType is a elink:VkStructureType value identifying this structure. 1792 * pname:pNext is `NULL` or a pointer to a structure extending this 1793 structure. 1794 * pname:waitSemaphoreCount is the number of semaphores upon which to wait 1795 before executing the sparse binding operations for the batch. 1796 * pname:pWaitSemaphores is a pointer to an array of semaphores upon which 1797 to wait on before the sparse binding operations for this batch begin 1798 execution. 1799 If semaphores to wait on are provided, they define a 1800 <<synchronization-semaphores-waiting, semaphore wait operation>>. 1801 * pname:bufferBindCount is the number of sparse buffer bindings to perform 1802 in the batch. 1803 * pname:pBufferBinds is a pointer to an array of 1804 slink:VkSparseBufferMemoryBindInfo structures. 1805 * pname:imageOpaqueBindCount is the number of opaque sparse image bindings 1806 to perform. 1807 * pname:pImageOpaqueBinds is a pointer to an array of 1808 slink:VkSparseImageOpaqueMemoryBindInfo structures, indicating opaque 1809 sparse image bindings to perform. 1810 * pname:imageBindCount is the number of sparse image bindings to perform. 1811 * pname:pImageBinds is a pointer to an array of 1812 slink:VkSparseImageMemoryBindInfo structures, indicating sparse image 1813 bindings to perform. 1814 * pname:signalSemaphoreCount is the number of semaphores to be signaled 1815 once the sparse binding operations specified by the structure have 1816 completed execution. 1817 * pname:pSignalSemaphores is a pointer to an array of semaphores which 1818 will be signaled when the sparse binding operations for this batch have 1819 completed execution. 1820 If semaphores to be signaled are provided, they define a 1821 <<synchronization-semaphores-signaling, semaphore signal operation>>. 1822 1823ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1824.Valid Usage 1825**** 1826 * [[VUID-VkBindSparseInfo-pWaitSemaphores-03246]] 1827 If any element of pname:pWaitSemaphores or pname:pSignalSemaphores was 1828 created with a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE 1829 then the pname:pNext chain must: include a 1830 slink:VkTimelineSemaphoreSubmitInfo structure 1831 * [[VUID-VkBindSparseInfo-pNext-03247]] 1832 If the pname:pNext chain of this structure includes a 1833 slink:VkTimelineSemaphoreSubmitInfo structure and any element of 1834 pname:pWaitSemaphores was created with a elink:VkSemaphoreType of 1835 ename:VK_SEMAPHORE_TYPE_TIMELINE then its pname:waitSemaphoreValueCount 1836 member must: equal pname:waitSemaphoreCount 1837 * [[VUID-VkBindSparseInfo-pNext-03248]] 1838 If the pname:pNext chain of this structure includes a 1839 slink:VkTimelineSemaphoreSubmitInfo structure and any element of 1840 pname:pSignalSemaphores was created with a elink:VkSemaphoreType of 1841 ename:VK_SEMAPHORE_TYPE_TIMELINE then its 1842 pname:signalSemaphoreValueCount member must: equal 1843 pname:signalSemaphoreCount 1844 * [[VUID-VkBindSparseInfo-pSignalSemaphores-03249]] 1845 For each element of pname:pSignalSemaphores created with a 1846 elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE the 1847 corresponding element of 1848 slink:VkTimelineSemaphoreSubmitInfo::pname:pSignalSemaphoreValues must: 1849 have a value greater than the current value of the semaphore when the 1850 <<synchronization-semaphores-signaling,semaphore signal operation>> is 1851 executed 1852 * [[VUID-VkBindSparseInfo-pWaitSemaphores-03250]] 1853 For each element of pname:pWaitSemaphores created with a 1854 elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE the 1855 corresponding element of 1856 slink:VkTimelineSemaphoreSubmitInfo::pname:pWaitSemaphoreValues must: 1857 have a value which does not differ from the current value of the 1858 semaphore or from the value of any outstanding semaphore wait or signal 1859 operation on that semaphore by more than 1860 <<limits-maxTimelineSemaphoreValueDifference, 1861 pname:maxTimelineSemaphoreValueDifference>> 1862 * [[VUID-VkBindSparseInfo-pSignalSemaphores-03251]] 1863 For each element of pname:pSignalSemaphores created with a 1864 elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE the 1865 corresponding element of 1866 slink:VkTimelineSemaphoreSubmitInfo::pname:pSignalSemaphoreValues must: 1867 have a value which does not differ from the current value of the 1868 semaphore or from the value of any outstanding semaphore wait or signal 1869 operation on that semaphore by more than 1870 <<limits-maxTimelineSemaphoreValueDifference, 1871 pname:maxTimelineSemaphoreValueDifference>> 1872**** 1873endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1874 1875include::{generated}/validity/structs/VkBindSparseInfo.adoc[] 1876-- 1877 1878ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1879To specify the values to use when waiting for and signaling semaphores 1880created with a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE, 1881add a slink:VkTimelineSemaphoreSubmitInfo structure to the pname:pNext chain 1882of the slink:VkBindSparseInfo structure. 1883endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1884 1885ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 1886[open,refpage='VkDeviceGroupBindSparseInfo',desc='Structure indicating which instances are bound',type='structs'] 1887-- 1888If the pname:pNext chain of slink:VkBindSparseInfo includes a 1889sname:VkDeviceGroupBindSparseInfo structure, then that structure includes 1890device indices specifying which instance of the resources and memory are 1891bound. 1892 1893The sname:VkDeviceGroupBindSparseInfo structure is defined as: 1894 1895include::{generated}/api/structs/VkDeviceGroupBindSparseInfo.adoc[] 1896 1897ifdef::VK_KHR_device_group[] 1898or the equivalent 1899 1900include::{generated}/api/structs/VkDeviceGroupBindSparseInfoKHR.adoc[] 1901endif::VK_KHR_device_group[] 1902 1903 * pname:sType is a elink:VkStructureType value identifying this structure. 1904 * pname:pNext is `NULL` or a pointer to a structure extending this 1905 structure. 1906 * pname:resourceDeviceIndex is a device index indicating which instance of 1907 the resource is bound. 1908 * pname:memoryDeviceIndex is a device index indicating which instance of 1909 the memory the resource instance is bound to. 1910 1911These device indices apply to all buffer and image memory binds included in 1912the batch pointing to this structure. 1913The semaphore waits and signals for the batch are executed only by the 1914physical device specified by the pname:resourceDeviceIndex. 1915 1916If this structure is not present, pname:resourceDeviceIndex and 1917pname:memoryDeviceIndex are assumed to be zero. 1918 1919.Valid Usage 1920**** 1921 * [[VUID-VkDeviceGroupBindSparseInfo-resourceDeviceIndex-01118]] 1922 pname:resourceDeviceIndex and pname:memoryDeviceIndex must: both be 1923 valid device indices 1924 * [[VUID-VkDeviceGroupBindSparseInfo-memoryDeviceIndex-01119]] 1925 Each memory allocation bound in this batch must: have allocated an 1926 instance for pname:memoryDeviceIndex 1927**** 1928 1929include::{generated}/validity/structs/VkDeviceGroupBindSparseInfo.adoc[] 1930-- 1931endif::VK_VERSION_1_1,VK_KHR_device_group[] 1932endif::VKSC_VERSION_1_0[] 1933
