1// Copyright 2015-2024 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 the 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 valid elink:VkSampleCountFlagBits value that is 973 set in 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 the 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 valid elink:VkSampleCountFlagBits value that is 1048 set in 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-resourceOffset-09491]] 1452 If the resource being bound is a sname:VkBuffer, pname:resourceOffset 1453 and pname:memoryOffset must: be an integer multiple of the 1454 pname:alignment of the slink:VkMemoryRequirements structure returned 1455 from a call to flink:vkGetBufferMemoryRequirements with the buffer 1456 resource 1457 * [[VUID-VkSparseMemoryBind-resourceOffset-09492]] 1458 If the resource being bound is a sname:VkImage, pname:resourceOffset and 1459 pname:memoryOffset must: be an integer multiple of the pname:alignment 1460 of the slink:VkMemoryRequirements structure returned from a call to 1461 flink:vkGetImageMemoryRequirements with the image resource 1462 * [[VUID-VkSparseMemoryBind-memory-01097]] 1463 If pname:memory is not dlink:VK_NULL_HANDLE, pname:memory must: not have 1464 been created with a memory type that reports 1465 ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit set 1466 * [[VUID-VkSparseMemoryBind-size-01098]] 1467 pname:size must: be greater than `0` 1468 * [[VUID-VkSparseMemoryBind-resourceOffset-01099]] 1469 pname:resourceOffset must: be less than the size of the resource 1470 * [[VUID-VkSparseMemoryBind-size-01100]] 1471 pname:size must: be less than or equal to the size of the resource minus 1472 pname:resourceOffset 1473 * [[VUID-VkSparseMemoryBind-memoryOffset-01101]] 1474 pname:memoryOffset must: be less than the size of pname:memory 1475 * [[VUID-VkSparseMemoryBind-size-01102]] 1476 pname:size must: be less than or equal to the size of pname:memory minus 1477 pname:memoryOffset 1478ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 1479 * [[VUID-VkSparseMemoryBind-memory-02730]] 1480 If pname:memory was created with 1481 slink:VkExportMemoryAllocateInfo::pname:handleTypes not equal to `0`, at 1482 least one handle type it contained must: also have been set in 1483 slink:VkExternalMemoryBufferCreateInfo::pname:handleTypes or 1484 slink:VkExternalMemoryImageCreateInfo::pname:handleTypes when the 1485 resource was created 1486 * [[VUID-VkSparseMemoryBind-memory-02731]] 1487 If pname:memory was created by a memory import operation, the external 1488 handle type of the imported memory must: also have been set in 1489 slink:VkExternalMemoryBufferCreateInfo::pname:handleTypes or 1490 slink:VkExternalMemoryImageCreateInfo::pname:handleTypes when the 1491 resource was created 1492endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1493**** 1494 1495include::{generated}/validity/structs/VkSparseMemoryBind.adoc[] 1496-- 1497 1498[open,refpage='VkSparseMemoryBindFlagBits',desc='Bitmask specifying usage of a sparse memory binding operation',type='enums'] 1499-- 1500Bits which can: be set in slink:VkSparseMemoryBind::pname:flags, specifying 1501usage of a sparse memory binding operation, are: 1502 1503include::{generated}/api/enums/VkSparseMemoryBindFlagBits.adoc[] 1504 1505 * ename:VK_SPARSE_MEMORY_BIND_METADATA_BIT specifies that the memory being 1506 bound is only for the metadata aspect. 1507-- 1508 1509[open,refpage='VkSparseMemoryBindFlags',desc='Bitmask of VkSparseMemoryBindFlagBits',type='flags'] 1510-- 1511include::{generated}/api/flags/VkSparseMemoryBindFlags.adoc[] 1512 1513tname:VkSparseMemoryBindFlags is a bitmask type for setting a mask of zero 1514or more elink:VkSparseMemoryBindFlagBits. 1515-- 1516 1517[open,refpage='VkSparseBufferMemoryBindInfo',desc='Structure specifying a sparse buffer memory bind operation',type='structs'] 1518-- 1519Memory is bound to sname:VkBuffer objects created with the 1520ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT flag using the following 1521structure: 1522 1523include::{generated}/api/structs/VkSparseBufferMemoryBindInfo.adoc[] 1524 1525 * pname:buffer is the slink:VkBuffer object to be bound. 1526 * pname:bindCount is the number of slink:VkSparseMemoryBind structures in 1527 the pname:pBinds array. 1528 * pname:pBinds is a pointer to an array of slink:VkSparseMemoryBind 1529 structures. 1530 1531include::{generated}/validity/structs/VkSparseBufferMemoryBindInfo.adoc[] 1532-- 1533 1534[open,refpage='VkSparseImageOpaqueMemoryBindInfo',desc='Structure specifying sparse image opaque memory bind information',type='structs'] 1535-- 1536Memory is bound to opaque regions of sname:VkImage objects created with the 1537ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT flag using the following structure: 1538 1539include::{generated}/api/structs/VkSparseImageOpaqueMemoryBindInfo.adoc[] 1540 1541 * pname:image is the slink:VkImage object to be bound. 1542 * pname:bindCount is the number of slink:VkSparseMemoryBind structures in 1543 the pname:pBinds array. 1544 * pname:pBinds is a pointer to an array of slink:VkSparseMemoryBind 1545 structures. 1546 1547.Valid Usage 1548**** 1549 * [[VUID-VkSparseImageOpaqueMemoryBindInfo-pBinds-01103]] 1550 If the pname:flags member of any element of pname:pBinds contains 1551 ename:VK_SPARSE_MEMORY_BIND_METADATA_BIT, the binding range defined 1552 must: be within the mip tail region of the metadata aspect of 1553 pname:image 1554**** 1555 1556include::{generated}/validity/structs/VkSparseImageOpaqueMemoryBindInfo.adoc[] 1557-- 1558 1559[NOTE] 1560.Note 1561==== 1562This operation is normally used to bind memory to fully-resident sparse 1563images or for mip tail regions of partially resident images. 1564However, it can: also be used to bind memory for the entire binding range of 1565partially resident images. 1566 1567In case pname:flags does not contain 1568ename:VK_SPARSE_MEMORY_BIND_METADATA_BIT, the pname:resourceOffset is in the 1569range [eq]#[0, slink:VkMemoryRequirements::pname:size)#, This range includes 1570data from all aspects of the image, including metadata. 1571For most implementations this will probably mean that the 1572pname:resourceOffset is a simple device address offset within the resource. 1573It is possible for an application to bind a range of memory that includes 1574both resource data and metadata. 1575However, the application would not know what part of the image the memory is 1576used for, or if any range is being used for metadata. 1577 1578When pname:flags contains ename:VK_SPARSE_MEMORY_BIND_METADATA_BIT, the 1579binding range specified must: be within the mip tail region of the metadata 1580aspect. 1581In this case the pname:resourceOffset is not required: to be a simple device 1582address offset within the resource. 1583However, it _is_ defined to be within [eq]#[pname:imageMipTailOffset, 1584pname:imageMipTailOffset {plus} pname:imageMipTailSize)# for the metadata 1585aspect. 1586See slink:VkSparseMemoryBind for the full constraints on binding region with 1587this flag present. 1588==== 1589 1590ifdef::editing-notes[] 1591[NOTE] 1592.editing-note 1593==== 1594(Jon) The preceding NOTE refers to pname:flags, which is presumably a 1595reference to slink:VkSparseMemoryBind above, even though that is not 1596contextually clear. 1597==== 1598endif::editing-notes[] 1599 1600[open,refpage='VkSparseImageMemoryBindInfo',desc='Structure specifying sparse image memory bind information',type='structs'] 1601-- 1602Memory can: be bound to sparse image blocks of sname:VkImage objects created 1603with the ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT flag using the following 1604structure: 1605 1606include::{generated}/api/structs/VkSparseImageMemoryBindInfo.adoc[] 1607 1608 * pname:image is the slink:VkImage object to be bound 1609 * pname:bindCount is the number of slink:VkSparseImageMemoryBind 1610 structures in pname:pBinds array 1611 * pname:pBinds is a pointer to an array of slink:VkSparseImageMemoryBind 1612 structures 1613 1614.Valid Usage 1615**** 1616 * [[VUID-VkSparseImageMemoryBindInfo-subresource-01722]] 1617 The pname:subresource.mipLevel member of each element of pname:pBinds 1618 must: be less than the pname:mipLevels specified in 1619 slink:VkImageCreateInfo when pname:image was created 1620 * [[VUID-VkSparseImageMemoryBindInfo-subresource-01723]] 1621 The pname:subresource.arrayLayer member of each element of pname:pBinds 1622 must: be less than the pname:arrayLayers specified in 1623 slink:VkImageCreateInfo when pname:image was created 1624 * [[VUID-VkSparseImageMemoryBindInfo-image-02901]] 1625 pname:image must: have been created with 1626 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT set 1627**** 1628 1629include::{generated}/validity/structs/VkSparseImageMemoryBindInfo.adoc[] 1630-- 1631 1632[open,refpage='VkSparseImageMemoryBind',desc='Structure specifying sparse image memory bind',type='structs'] 1633-- 1634The sname:VkSparseImageMemoryBind structure is defined as: 1635 1636include::{generated}/api/structs/VkSparseImageMemoryBind.adoc[] 1637 1638 * pname:subresource is the image _aspect_ and region of interest in the 1639 image. 1640 * pname:offset are the coordinates of the first texel within the image 1641 subresource to bind. 1642 * pname:extent is the size in texels of the region within the image 1643 subresource to bind. 1644 The extent must: be a multiple of the sparse image block dimensions, 1645 except when binding sparse image blocks along the edge of an image 1646 subresource it can: instead be such that any coordinate of 1647 [eq]#pname:offset {plus} pname:extent# equals the corresponding 1648 dimensions of the image subresource. 1649 * pname:memory is the slink:VkDeviceMemory object that the sparse image 1650 blocks of the image are bound to. 1651 If pname:memory is dlink:VK_NULL_HANDLE, the sparse image blocks are 1652 unbound. 1653 * pname:memoryOffset is an offset into slink:VkDeviceMemory object. 1654 If pname:memory is dlink:VK_NULL_HANDLE, this value is ignored. 1655 * pname:flags are sparse memory binding flags. 1656 1657.Valid Usage 1658**** 1659 * [[VUID-VkSparseImageMemoryBind-memory-01104]] 1660 If the <<features-sparseResidencyAliased, pname:sparseResidencyAliased>> 1661 feature is not enabled, and if any other resources are bound to ranges 1662 of pname:memory, the range of pname:memory being bound must: not overlap 1663 with those bound ranges 1664 * [[VUID-VkSparseImageMemoryBind-memory-01105]] 1665 pname:memory and pname:memoryOffset must: match the memory requirements 1666 of the calling command's pname:image, as described in section 1667 <<resources-association>> 1668 * [[VUID-VkSparseImageMemoryBind-subresource-01106]] 1669 pname:subresource must: be a valid image subresource for pname:image 1670 (see <<resources-image-views>>) 1671 * [[VUID-VkSparseImageMemoryBind-offset-01107]] 1672 pname:offset.x must: be a multiple of the sparse image block width 1673 (sname:VkSparseImageFormatProperties::pname:imageGranularity.width) of 1674 the image 1675 * [[VUID-VkSparseImageMemoryBind-extent-09388]] 1676 pname:extent.width must: be greater than `0` 1677 * [[VUID-VkSparseImageMemoryBind-extent-01108]] 1678 pname:extent.width must: either be a multiple of the sparse image block 1679 width of the image, or else [eq]#(pname:extent.width {plus} 1680 pname:offset.x)# must: equal the width of the image subresource 1681 * [[VUID-VkSparseImageMemoryBind-offset-01109]] 1682 pname:offset.y must: be a multiple of the sparse image block height 1683 (sname:VkSparseImageFormatProperties::pname:imageGranularity.height) of 1684 the image 1685 * [[VUID-VkSparseImageMemoryBind-extent-09389]] 1686 pname:extent.height must: be greater than `0` 1687 * [[VUID-VkSparseImageMemoryBind-extent-01110]] 1688 pname:extent.height must: either be a multiple of the sparse image block 1689 height of the image, or else [eq]#(pname:extent.height {plus} 1690 pname:offset.y)# must: equal the height of the image subresource 1691 * [[VUID-VkSparseImageMemoryBind-offset-01111]] 1692 pname:offset.z must: be a multiple of the sparse image block depth 1693 (sname:VkSparseImageFormatProperties::pname:imageGranularity.depth) of 1694 the image 1695 * [[VUID-VkSparseImageMemoryBind-extent-09390]] 1696 pname:extent.depth must: be greater than `0` 1697 * [[VUID-VkSparseImageMemoryBind-extent-01112]] 1698 pname:extent.depth must: either be a multiple of the sparse image block 1699 depth of the image, or else [eq]#(pname:extent.depth {plus} 1700 pname:offset.z)# must: equal the depth of the image subresource 1701ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 1702 * [[VUID-VkSparseImageMemoryBind-memory-02732]] 1703 If pname:memory was created with 1704 slink:VkExportMemoryAllocateInfo::pname:handleTypes not equal to `0`, at 1705 least one handle type it contained must: also have been set in 1706 slink:VkExternalMemoryImageCreateInfo::pname:handleTypes when the image 1707 was created 1708 * [[VUID-VkSparseImageMemoryBind-memory-02733]] 1709 If pname:memory was created by a memory import operation, the external 1710 handle type of the imported memory must: also have been set in 1711 slink:VkExternalMemoryImageCreateInfo::pname:handleTypes when 1712 pname:image was created 1713endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1714**** 1715 1716include::{generated}/validity/structs/VkSparseImageMemoryBind.adoc[] 1717-- 1718 1719[open,refpage='vkQueueBindSparse',desc='Bind device memory to a sparse resource object',type='protos'] 1720-- 1721To submit sparse binding operations to a queue, call: 1722 1723include::{generated}/api/protos/vkQueueBindSparse.adoc[] 1724 1725 * pname:queue is the queue that the sparse binding operations will be 1726 submitted to. 1727 * pname:bindInfoCount is the number of elements in the pname:pBindInfo 1728 array. 1729 * pname:pBindInfo is a pointer to an array of slink:VkBindSparseInfo 1730 structures, each specifying a sparse binding submission batch. 1731 * pname:fence is an optional: handle to a fence to be signaled. 1732 If pname:fence is not dlink:VK_NULL_HANDLE, it defines a 1733 <<synchronization-fences-signaling, fence signal operation>>. 1734 1735fname:vkQueueBindSparse is a <<devsandqueues-submission,queue submission 1736command>>, with each batch defined by an element of pname:pBindInfo as a 1737slink:VkBindSparseInfo structure. 1738Batches begin execution in the order they appear in pname:pBindInfo, but 1739may: complete out of order. 1740 1741Within a batch, a given range of a resource must: not be bound more than 1742once. 1743Across batches, if a range is to be bound to one allocation and offset and 1744then to another allocation and offset, then the application must: guarantee 1745(usually using semaphores) that the binding operations are executed in the 1746correct order, as well as to order binding operations against the execution 1747of command buffer submissions. 1748 1749As no operation to flink:vkQueueBindSparse causes any pipeline stage to 1750access memory, synchronization primitives used in this command effectively 1751only define execution dependencies. 1752 1753Additional information about fence and semaphore operation is described in 1754<<synchronization, the synchronization chapter>>. 1755 1756.Valid Usage 1757**** 1758 * [[VUID-vkQueueBindSparse-fence-01113]] 1759 If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: be 1760 unsignaled 1761 * [[VUID-vkQueueBindSparse-fence-01114]] 1762 If pname:fence is not dlink:VK_NULL_HANDLE, pname:fence must: not be 1763 associated with any other queue command that has not yet completed 1764 execution on that queue 1765 * [[VUID-vkQueueBindSparse-pSignalSemaphores-01115]] 1766 Each element of the pname:pSignalSemaphores member of each element of 1767 pname:pBindInfo must: be unsignaled when the semaphore signal operation 1768 it defines is executed on the device 1769 * [[VUID-vkQueueBindSparse-pWaitSemaphores-01116]] 1770 When a semaphore wait operation referring to a binary semaphore defined 1771 by any element of the pname:pWaitSemaphores member of any element of 1772 pname:pBindInfo executes on pname:queue, there must: be no other queues 1773 waiting on the same semaphore 1774 * [[VUID-vkQueueBindSparse-pWaitSemaphores-03245]] 1775 All elements of the pname:pWaitSemaphores member of all elements of 1776 pname:pBindInfo referring to a semaphore 1777ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1778 created with a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_BINARY 1779endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1780 must: reference a semaphore signal operation that has been submitted for 1781 execution and any <<synchronization-semaphores-signaling, semaphore 1782 signal operations>> on which it depends must: have also been submitted 1783 for execution 1784**** 1785 1786include::{generated}/validity/protos/vkQueueBindSparse.adoc[] 1787-- 1788 1789[open,refpage='VkBindSparseInfo',desc='Structure specifying a sparse binding operation',type='structs'] 1790-- 1791The sname:VkBindSparseInfo structure is defined as: 1792 1793include::{generated}/api/structs/VkBindSparseInfo.adoc[] 1794 1795 * pname:sType is a elink:VkStructureType value identifying this structure. 1796 * pname:pNext is `NULL` or a pointer to a structure extending this 1797 structure. 1798 * pname:waitSemaphoreCount is the number of semaphores upon which to wait 1799 before executing the sparse binding operations for the batch. 1800 * pname:pWaitSemaphores is a pointer to an array of semaphores upon which 1801 to wait on before the sparse binding operations for this batch begin 1802 execution. 1803 If semaphores to wait on are provided, they define a 1804 <<synchronization-semaphores-waiting, semaphore wait operation>>. 1805 * pname:bufferBindCount is the number of sparse buffer bindings to perform 1806 in the batch. 1807 * pname:pBufferBinds is a pointer to an array of 1808 slink:VkSparseBufferMemoryBindInfo structures. 1809 * pname:imageOpaqueBindCount is the number of opaque sparse image bindings 1810 to perform. 1811 * pname:pImageOpaqueBinds is a pointer to an array of 1812 slink:VkSparseImageOpaqueMemoryBindInfo structures, indicating opaque 1813 sparse image bindings to perform. 1814 * pname:imageBindCount is the number of sparse image bindings to perform. 1815 * pname:pImageBinds is a pointer to an array of 1816 slink:VkSparseImageMemoryBindInfo structures, indicating sparse image 1817 bindings to perform. 1818 * pname:signalSemaphoreCount is the number of semaphores to be signaled 1819 once the sparse binding operations specified by the structure have 1820 completed execution. 1821 * pname:pSignalSemaphores is a pointer to an array of semaphores which 1822 will be signaled when the sparse binding operations for this batch have 1823 completed execution. 1824 If semaphores to be signaled are provided, they define a 1825 <<synchronization-semaphores-signaling, semaphore signal operation>>. 1826 1827ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1828.Valid Usage 1829**** 1830 * [[VUID-VkBindSparseInfo-pWaitSemaphores-03246]] 1831 If any element of pname:pWaitSemaphores or pname:pSignalSemaphores was 1832 created with a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE 1833 then the pname:pNext chain must: include a 1834 slink:VkTimelineSemaphoreSubmitInfo structure 1835 * [[VUID-VkBindSparseInfo-pNext-03247]] 1836 If the pname:pNext chain of this structure includes a 1837 slink:VkTimelineSemaphoreSubmitInfo structure and any element of 1838 pname:pWaitSemaphores was created with a elink:VkSemaphoreType of 1839 ename:VK_SEMAPHORE_TYPE_TIMELINE then its pname:waitSemaphoreValueCount 1840 member must: equal pname:waitSemaphoreCount 1841 * [[VUID-VkBindSparseInfo-pNext-03248]] 1842 If the pname:pNext chain of this structure includes a 1843 slink:VkTimelineSemaphoreSubmitInfo structure and any element of 1844 pname:pSignalSemaphores was created with a elink:VkSemaphoreType of 1845 ename:VK_SEMAPHORE_TYPE_TIMELINE then its 1846 pname:signalSemaphoreValueCount member must: equal 1847 pname:signalSemaphoreCount 1848 * [[VUID-VkBindSparseInfo-pSignalSemaphores-03249]] 1849 For each element of pname:pSignalSemaphores created with a 1850 elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE the 1851 corresponding element of 1852 slink:VkTimelineSemaphoreSubmitInfo::pname:pSignalSemaphoreValues must: 1853 have a value greater than the current value of the semaphore when the 1854 <<synchronization-semaphores-signaling,semaphore signal operation>> is 1855 executed 1856 * [[VUID-VkBindSparseInfo-pWaitSemaphores-03250]] 1857 For each element of pname:pWaitSemaphores created with a 1858 elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE the 1859 corresponding element of 1860 slink:VkTimelineSemaphoreSubmitInfo::pname:pWaitSemaphoreValues must: 1861 have a value which does not differ from the current value of the 1862 semaphore or from the value of any outstanding semaphore wait or signal 1863 operation on that semaphore by more than 1864 <<limits-maxTimelineSemaphoreValueDifference, 1865 pname:maxTimelineSemaphoreValueDifference>> 1866 * [[VUID-VkBindSparseInfo-pSignalSemaphores-03251]] 1867 For each element of pname:pSignalSemaphores created with a 1868 elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE the 1869 corresponding element of 1870 slink:VkTimelineSemaphoreSubmitInfo::pname:pSignalSemaphoreValues must: 1871 have a value which does not differ from the current value of the 1872 semaphore or from the value of any outstanding semaphore wait or signal 1873 operation on that semaphore by more than 1874 <<limits-maxTimelineSemaphoreValueDifference, 1875 pname:maxTimelineSemaphoreValueDifference>> 1876**** 1877endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1878 1879include::{generated}/validity/structs/VkBindSparseInfo.adoc[] 1880-- 1881 1882ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1883To specify the values to use when waiting for and signaling semaphores 1884created with a elink:VkSemaphoreType of ename:VK_SEMAPHORE_TYPE_TIMELINE, 1885add a slink:VkTimelineSemaphoreSubmitInfo structure to the pname:pNext chain 1886of the slink:VkBindSparseInfo structure. 1887endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1888 1889ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 1890[open,refpage='VkDeviceGroupBindSparseInfo',desc='Structure indicating which instances are bound',type='structs'] 1891-- 1892If the pname:pNext chain of slink:VkBindSparseInfo includes a 1893sname:VkDeviceGroupBindSparseInfo structure, then that structure includes 1894device indices specifying which instance of the resources and memory are 1895bound. 1896 1897The sname:VkDeviceGroupBindSparseInfo structure is defined as: 1898 1899include::{generated}/api/structs/VkDeviceGroupBindSparseInfo.adoc[] 1900 1901ifdef::VK_KHR_device_group[] 1902or the equivalent 1903 1904include::{generated}/api/structs/VkDeviceGroupBindSparseInfoKHR.adoc[] 1905endif::VK_KHR_device_group[] 1906 1907 * pname:sType is a elink:VkStructureType value identifying this structure. 1908 * pname:pNext is `NULL` or a pointer to a structure extending this 1909 structure. 1910 * pname:resourceDeviceIndex is a device index indicating which instance of 1911 the resource is bound. 1912 * pname:memoryDeviceIndex is a device index indicating which instance of 1913 the memory the resource instance is bound to. 1914 1915These device indices apply to all buffer and image memory binds included in 1916the batch pointing to this structure. 1917The semaphore waits and signals for the batch are executed only by the 1918physical device specified by the pname:resourceDeviceIndex. 1919 1920If this structure is not present, pname:resourceDeviceIndex and 1921pname:memoryDeviceIndex are assumed to be zero. 1922 1923.Valid Usage 1924**** 1925 * [[VUID-VkDeviceGroupBindSparseInfo-resourceDeviceIndex-01118]] 1926 pname:resourceDeviceIndex and pname:memoryDeviceIndex must: both be 1927 valid device indices 1928 * [[VUID-VkDeviceGroupBindSparseInfo-memoryDeviceIndex-01119]] 1929 Each memory allocation bound in this batch must: have allocated an 1930 instance for pname:memoryDeviceIndex 1931**** 1932 1933include::{generated}/validity/structs/VkDeviceGroupBindSparseInfo.adoc[] 1934-- 1935endif::VK_VERSION_1_1,VK_KHR_device_group[] 1936endif::VKSC_VERSION_1_0[] 1937
