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