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