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