1// Copyright 2020-2023 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[micromap]] 6= Micromap 7 8 9[[micromap-def]] 10== Micromaps 11 12_Acceleration structures_ store and organize geometry for ray tracing, but 13in some cases it is beneficial to include some information within the 14geometry, particularly for triangles. 15A _micromap_ organizes this data around a map of values corresponding to 16subdivided microtriangles which can be added to a triangle geometry when 17building a _bottom level acceleration structure_. 18 19An _opacity micromap_ is a type of micromap which stores information to 20control intersection opacity as described in <<ray-opacity-micromap,Ray 21Opacity Micromap>>. 22 23ifdef::VK_NV_displacement_micromap[] 24A _displacement micromap_ is a type of micromap which stores information to 25displace sub-triangle vertices as described in <<displacement-micromap, 26Displacement Micromap>>. 27endif::VK_NV_displacement_micromap[] 28 29A micromap is considered to be constructed if a <<micromap-building,micromap 30build command>> or <<micromap-copying,copy command>> has been executed with 31the given acceleration structure as the destination. 32 33 34[[micromap-building]] 35=== Building Micromaps 36 37[open,refpage='vkCmdBuildMicromapsEXT',desc='Build a micromap',type='protos'] 38-- 39:refpage: vkCmdBuildMicromapsEXT 40 41To build micromaps call: 42 43include::{generated}/api/protos/vkCmdBuildMicromapsEXT.adoc[] 44 45 * pname:commandBuffer is the command buffer into which the command will be 46 recorded. 47 * pname:infoCount is the number of micromaps to build. 48 It specifies the number of the pname:pInfos structures that must: be 49 provided. 50 * pname:pInfos is a pointer to an array of pname:infoCount 51 slink:VkMicromapBuildInfoEXT structures defining the data used to build 52 each micromap. 53 54The fname:vkCmdBuildMicromapsEXT command provides the ability to initiate 55multiple micromaps builds, however there is no ordering or synchronization 56implied between any of the individual micromap builds. 57 58[NOTE] 59.Note 60==== 61This means that there cannot: be any memory aliasing between any micromap 62memories or scratch memories being used by any of the builds. 63==== 64 65[[micromap-scratch]] 66Accesses to the micromap scratch buffers as identified by the 67slink:VkMicromapBuildInfoEXT::pname:scratchData buffer device addresses 68must: be <<synchronization-dependencies,synchronized>> with the 69ename:VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT 70<<synchronization-pipeline-stages, pipeline stage>> and an 71<<synchronization-access-types, access type>> of 72(ename:VK_ACCESS_2_MICROMAP_READ_BIT_EXT | 73ename:VK_ACCESS_2_MICROMAP_WRITE_BIT_EXT). 74Accesses to slink:VkMicromapBuildInfoEXT::pname:dstMicromap must: be 75<<synchronization-dependencies,synchronized>> with the 76ename:VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT 77<<synchronization-pipeline-stages, pipeline stage>> and an 78<<synchronization-access-types, access type>> of 79ename:VK_ACCESS_2_MICROMAP_WRITE_BIT_EXT. 80 81Accesses to other input buffers as identified by any used values of 82slink:VkMicromapBuildInfoEXT::pname:data or 83slink:VkMicromapBuildInfoEXT::pname:triangleArray must: be 84<<synchronization-dependencies,synchronized>> with the 85ename:VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT 86<<synchronization-pipeline-stages, pipeline stage>> and an 87<<synchronization-access-types, access type>> of 88ename:VK_ACCESS_SHADER_READ_BIT. 89 90 91.Valid Usage 92**** 93include::{chapters}/commonvalidity/build_micromap_common.adoc[] 94 * [[VUID-vkCmdBuildMicromapsEXT-pInfos-07508]] 95 For each element of pname:pInfos, the pname:buffer used to create its 96 pname:dstMicromap member must: be bound to device memory 97 * [[VUID-vkCmdBuildMicromapsEXT-pInfos-07509]] 98 If pname:pInfos[i].pname:mode is ename:VK_BUILD_MICROMAP_MODE_BUILD_EXT, 99 all addresses between pname:pInfos[i].pname:scratchData.deviceAddress 100 and pname:pInfos[i].pname:scratchData.deviceAddress {plus} N - 1 must: 101 be in the buffer device address range of the same buffer, where N is 102 given by the pname:buildScratchSize member of the 103 slink:VkMicromapBuildSizesInfoEXT structure returned from a call to 104 flink:vkGetMicromapBuildSizesEXT with an identical 105 slink:VkMicromapBuildInfoEXT structure and primitive count 106 * [[VUID-vkCmdBuildMicromapsEXT-data-07510]] 107 The buffers from which the buffer device addresses for all of the 108 pname:data and pname:triangleArray members of all pname:pInfos[i] are 109 queried must: have been created with the 110 ename:VK_BUFFER_USAGE_MICROMAP_BUILD_INPUT_READ_ONLY_BIT_EXT usage flag 111 * [[VUID-vkCmdBuildMicromapsEXT-pInfos-07511]] 112 For each element of pname:pInfos[i] the buffer from which the buffer 113 device address pname:pInfos[i].pname:scratchData.deviceAddress is 114 queried must: have been created with 115 ename:VK_BUFFER_USAGE_STORAGE_BUFFER_BIT usage flag 116 * [[VUID-vkCmdBuildMicromapsEXT-pInfos-07512]] 117 For each element of pname:pInfos, its pname:scratchData.deviceAddress, 118 pname:data.deviceAddress, and pname:triangleArray.deviceAddress members 119 must: be valid device addresses obtained from 120 flink:vkGetBufferDeviceAddress 121 * [[VUID-vkCmdBuildMicromapsEXT-pInfos-07513]] 122 For each element of pname:pInfos, if pname:scratchData.deviceAddress, 123 pname:data.deviceAddress, or pname:triangleArray.deviceAddress is the 124 address of a non-sparse buffer then it must: be bound completely and 125 contiguously to a single slink:VkDeviceMemory object 126 * [[VUID-vkCmdBuildMicromapsEXT-pInfos-07514]] 127 For each element of pname:pInfos, its pname:scratchData.deviceAddress 128 member must: be a multiple of 129 slink:VkPhysicalDeviceAccelerationStructurePropertiesKHR::pname:minAccelerationStructureScratchOffsetAlignment 130 * [[VUID-vkCmdBuildMicromapsEXT-pInfos-07515]] 131 For each element of pname:pInfos, its pname:triangleArray.deviceAddress 132 and pname:data.deviceAddress members must: be a multiple of `256` 133**** 134 135include::{generated}/validity/protos/vkCmdBuildMicromapsEXT.adoc[] 136-- 137 138[open,refpage='VkOpacityMicromapFormatEXT',desc='Format enum for opacity micromaps',type='enums'] 139-- 140:refpage: VkOpacityMicromapFormatEXT 141 142Formats which can: be set in slink:VkMicromapUsageEXT::pname:format and 143slink:VkMicromapTriangleEXT::pname:format for micromap builds, are: 144 145include::{generated}/api/enums/VkOpacityMicromapFormatEXT.adoc[] 146 147 * ename:VK_OPACITY_MICROMAP_FORMAT_2_STATE_EXT indicates that the given 148 micromap format has one bit per subtriangle encoding either fully opaque 149 or fully transparent. 150 * ename:VK_OPACITY_MICROMAP_FORMAT_4_STATE_EXT indicates that the given 151 micromap format has two bits per subtriangle encoding four modes which 152 can be interpreted as described in <<ray-opacity-micromap,ray 153 traversal>>. 154 155[NOTE] 156.Note 157==== 158For compactness, these values are stored as 16-bit in some structures. 159==== 160-- 161 162ifdef::VK_NV_displacement_micromap[] 163[open,refpage='VkDisplacementMicromapFormatNV',desc='Format enum for displacement micromaps',type='enums'] 164-- 165:refpage: VkDisplacementMicromapFormatNV 166 167Formats which can: be set in slink:VkMicromapUsageEXT::pname:format and 168slink:VkMicromapTriangleEXT::pname:format for micromap builds, are: 169 170include::{generated}/api/enums/VkDisplacementMicromapFormatNV.adoc[] 171 172 * ename:VK_DISPLACEMENT_MICROMAP_FORMAT_64_TRIANGLES_64_BYTES_NV indicates 173 that the given micromap format encodes 64 micro-triangles worth of 174 displacements in 64 bytes as described in 175 <<displacement-micromap-encoding, Displacement Micromap Encoding>>. 176 * ename:VK_DISPLACEMENT_MICROMAP_FORMAT_256_TRIANGLES_128_BYTES_NV 177 indicates that the given micromap format encodes 256 micro-triangles 178 worth of displacements in 128 bytes as described in 179 <<displacement-micromap-encoding, Displacement Micromap Encoding>>. 180 * ename:VK_DISPLACEMENT_MICROMAP_FORMAT_1024_TRIANGLES_128_BYTES_NV 181 indicates that the given micromap format encodes 1024 micro-triangles 182 worth of displacements in 128 bytes as described in 183 <<displacement-micromap-encoding, Displacement Micromap Encoding>>. 184 185[NOTE] 186.Note 187==== 188For compactness, these values are stored as 16-bit in some structures. 189==== 190-- 191endif::VK_NV_displacement_micromap[] 192 193[open,refpage='VkMicromapBuildInfoEXT',desc='Structure specifying the data used to build a micromap',type='structs'] 194-- 195:refpage: VkMicromapBuildInfoEXT 196 197The sname:VkMicromapBuildInfoEXT structure is defined as: 198 199include::{generated}/api/structs/VkMicromapBuildInfoEXT.adoc[] 200 201 * pname:sType is a elink:VkStructureType value identifying this structure. 202 * pname:pNext is `NULL` or a pointer to a structure extending this 203 structure. 204 * pname:type is a elink:VkMicromapTypeEXT value specifying the type of 205 micromap being built. 206 * pname:flags is a bitmask of elink:VkBuildMicromapFlagBitsEXT specifying 207 additional parameters of the micromap. 208 * pname:mode is a elink:VkBuildMicromapModeEXT value specifying the type 209 of operation to perform. 210 * pname:dstMicromap is a pointer to the target micromap for the build. 211 * pname:usageCountsCount specifies the number of usage counts structures 212 that will be used to determine the size of this micromap. 213 * pname:pUsageCounts is a pointer to an array of slink:VkMicromapUsageEXT 214 structures. 215 * pname:ppUsageCounts is a pointer to an array of pointers to 216 slink:VkMicromapUsageEXT structures. 217 * pname:data is the device or host address to memory which contains the 218 data for the micromap. 219 * pname:scratchData is the device or host address to memory that will be 220 used as scratch memory for the build. 221 * pname:triangleArray is the device or host address to memory containing 222 the slink:VkMicromapTriangleEXT data 223 * pname:triangleArrayStride is the stride in bytes between each element of 224 pname:triangleArray 225 226Only one of pname:pUsageCounts or pname:ppUsageCounts can: be a valid 227pointer, the other must: be `NULL`. 228The elements of the non-`NULL` array describe the total counts used to build 229each micromap. 230Each element contains a pname:count which is the number of micromap 231triangles of that pname:format and pname:subdivisionLevel contained in the 232micromap. 233Multiple elements with the same pname:format and pname:subdivisionLevel are 234allowed and the total count for that pname:format and pname:subdivisionLevel 235is the sum of the pname:count for each element. 236 237 238 239Each micromap triangle refers to one element in pname:triangleArray which 240contains the pname:format and pname:subdivisionLevel for that particular 241triangle as well as a pname:dataOffset in bytes which is the location 242relative to pname:data where that triangle's micromap data begins. 243The data at pname:triangleArray is laid out as a 4 byte unsigned integer for 244the pname:dataOffset followed by a 2 byte unsigned integer for the 245subdivision level then a 2 byte unsigned integer for the format. 246In practice, compilers compile slink:VkMicromapTriangleEXT to match this 247pattern. 248 249For opacity micromaps, the data at pname:data is packed as either one bit 250per element for ename:VK_OPACITY_MICROMAP_FORMAT_2_STATE_EXT or two bits per 251element for ename:VK_OPACITY_MICROMAP_FORMAT_4_STATE_EXT and is packed from 252LSB to MSB in each byte. 253The data at each index in those bytes is interpreted as discussed in 254<<ray-opacity-micromap, Ray Opacity Micromap>>. 255 256ifdef::VK_NV_displacement_micromap[] 257For displacement micromaps, the data at pname:data is interpreted as 258discussed in <<displacement-micromap-encoding, Displacement Micromap 259Encoding>>. 260endif::VK_NV_displacement_micromap[] 261 262.Valid Usage 263**** 264 * [[VUID-VkMicromapBuildInfoEXT-pUsageCounts-07516]] 265 Only one of pname:pUsageCounts or pname:ppUsageCounts can: be a valid 266 pointer, the other must: be `NULL` 267 * [[VUID-VkMicromapBuildInfoEXT-type-07517]] 268 If pname:type is ename:VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT the 269 pname:format member of slink:VkMicromapUsageEXT must: be a valid value 270 from ename:VkOpacityMicromapFormatEXT 271 * [[VUID-VkMicromapBuildInfoEXT-type-07518]] 272 If pname:type is ename:VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT the 273 pname:format member of slink:VkMicromapTriangleEXT must: be a valid 274 value from ename:VkOpacityMicromapFormatEXT 275ifdef::VK_NV_displacement_micromap[] 276 * [[VUID-VkMicromapBuildInfoEXT-type-08704]] 277 If pname:type is ename:VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV the 278 pname:format member of slink:VkMicromapUsageEXT must: be a valid value 279 from ename:VkDisplacementMicromapFormatNV 280 * [[VUID-VkMicromapBuildInfoEXT-type-08705]] 281 If pname:type is ename:VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV the 282 pname:format member of slink:VkMicromapTriangleEXT must: be a valid 283 value from ename:VkDisplacementMicromapFormatNV 284endif::VK_NV_displacement_micromap[] 285**** 286include::{generated}/validity/structs/VkMicromapBuildInfoEXT.adoc[] 287-- 288 289[open,refpage='VkBuildMicromapModeEXT',desc='Enum specifying the type of build operation to perform',type='enums'] 290-- 291:refpage: VkBuildMicromapModeEXT 292 293The ename:VkBuildMicromapModeEXT enumeration is defined as: 294 295include::{generated}/api/enums/VkBuildMicromapModeEXT.adoc[] 296 297 * ename:VK_BUILD_MICROMAP_MODE_BUILD_EXT specifies that the destination 298 micromap will be built using the specified data. 299-- 300 301[open,refpage='VkMicromapUsageEXT',desc='Structure specifying the usage information used to build a micromap',type='structs'] 302-- 303:refpage: VkMicromapUsageEXT 304 305The sname:VkMicromapUsageEXT structure is defined as: 306 307include::{generated}/api/structs/VkMicromapUsageEXT.adoc[] 308 309 * pname:count is the number of triangles in the usage format defined by 310 the pname:subdivisionLevel and pname:format below in the micromap 311 * pname:subdivisionLevel is the subdivision level of this usage format 312 * pname:format is the format of this usage format 313 314.Valid Usage 315**** 316 * [[VUID-VkMicromapUsageEXT-format-07519]] 317 If the elink:VkMicromapTypeEXT of the micromap is 318 ename:VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT then pname:format must: be 319 ename:VK_OPACITY_MICROMAP_FORMAT_2_STATE_EXT or 320 ename:VK_OPACITY_MICROMAP_FORMAT_4_STATE_EXT 321 * [[VUID-VkMicromapUsageEXT-format-07520]] 322 If the elink:VkMicromapTypeEXT of the micromap is 323 ename:VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT and pname:format is 324 ename:VK_OPACITY_MICROMAP_FORMAT_2_STATE_EXT then pname:subdivisionLevel 325 must: be less than or equal to 326 slink:VkPhysicalDeviceOpacityMicromapPropertiesEXT::pname:maxOpacity2StateSubdivisionLevel 327 * [[VUID-VkMicromapUsageEXT-format-07521]] 328 If the elink:VkMicromapTypeEXT of the micromap is 329 ename:VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT and pname:format is 330 ename:VK_OPACITY_MICROMAP_FORMAT_4_STATE_EXT then pname:subdivisionLevel 331 must: be less than or equal to 332 slink:VkPhysicalDeviceOpacityMicromapPropertiesEXT::pname:maxOpacity4StateSubdivisionLevel 333ifdef::VK_NV_displacement_micromap[] 334 * [[VUID-VkMicromapUsageEXT-format-08706]] 335 If the elink:VkMicromapTypeEXT of the micromap is 336 ename:VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV then pname:format must: 337 be ename:VK_DISPLACEMENT_MICROMAP_FORMAT_64_TRIANGLES_64_BYTES_NV, 338 ename:VK_DISPLACEMENT_MICROMAP_FORMAT_256_TRIANGLES_128_BYTES_NV or 339 ename:VK_DISPLACEMENT_MICROMAP_FORMAT_1024_TRIANGLES_128_BYTES_NV 340 * [[VUID-VkMicromapUsageEXT-subdivisionLevel-08707]] 341 If the elink:VkMicromapTypeEXT of the micromap is 342 ename:VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV then 343 pname:subdivisionLevel must: be less than or equal to 344 slink:VkPhysicalDeviceDisplacementMicromapPropertiesNV::pname:maxDisplacementMicromapSubdivisionLevel 345endif::VK_NV_displacement_micromap[] 346**** 347 348The pname:format is interpreted based on the pname:type of the micromap 349using it. 350 351include::{generated}/validity/structs/VkMicromapUsageEXT.adoc[] 352-- 353 354[open,refpage='VkMicromapTriangleEXT',desc='Structure specifying the micromap format and data for a triangle',type='structs'] 355-- 356:refpage: VkMicromapTriangleEXT 357 358The sname:VkMicromapTriangleEXT structure is defined as: 359 360include::{generated}/api/structs/VkMicromapTriangleEXT.adoc[] 361 362 * pname:dataOffset is the offset in bytes of the start of the data for 363 this triangle. 364 This is a byte aligned value. 365 * pname:subdivisionLevel is the subdivision level of this triangle 366 * pname:format is the format of this triangle 367 368.Valid Usage 369**** 370 * [[VUID-VkMicromapTriangleEXT-format-07522]] 371 If the elink:VkMicromapTypeEXT of the micromap is 372 ename:VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT then pname:format must: be 373 ename:VK_OPACITY_MICROMAP_FORMAT_2_STATE_EXT or 374 ename:VK_OPACITY_MICROMAP_FORMAT_4_STATE_EXT 375 * [[VUID-VkMicromapTriangleEXT-format-07523]] 376 If the elink:VkMicromapTypeEXT of the micromap is 377 ename:VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT and pname:format is 378 ename:VK_OPACITY_MICROMAP_FORMAT_2_STATE_EXT then pname:subdivisionLevel 379 must: be less than or equal to 380 slink:VkPhysicalDeviceOpacityMicromapPropertiesEXT::pname:maxOpacity2StateSubdivisionLevel 381 * [[VUID-VkMicromapTriangleEXT-format-07524]] 382 If the elink:VkMicromapTypeEXT of the micromap is 383 ename:VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT and pname:format is 384 ename:VK_OPACITY_MICROMAP_FORMAT_4_STATE_EXT then pname:subdivisionLevel 385 must: be less than or equal to 386 slink:VkPhysicalDeviceOpacityMicromapPropertiesEXT::pname:maxOpacity4StateSubdivisionLevel 387ifdef::VK_NV_displacement_micromap[] 388 * [[VUID-VkMicromapTriangleEXT-format-08708]] 389 If the elink:VkMicromapTypeEXT of the micromap is 390 ename:VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV then pname:format must: 391 be ename:VK_DISPLACEMENT_MICROMAP_FORMAT_64_TRIANGLES_64_BYTES_NV, 392 ename:VK_DISPLACEMENT_MICROMAP_FORMAT_256_TRIANGLES_128_BYTES_NV or 393 ename:VK_DISPLACEMENT_MICROMAP_FORMAT_1024_TRIANGLES_128_BYTES_NV 394 * [[VUID-VkMicromapTriangleEXT-subdivisionLevel-08709]] 395 If the elink:VkMicromapTypeEXT of the micromap is 396 ename:VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV then 397 pname:subdivisionLevel must: be less than or equal to 398 slink:VkPhysicalDeviceDisplacementMicromapPropertiesNV::pname:maxDisplacementMicromapSubdivisionLevel 399endif::VK_NV_displacement_micromap[] 400**** 401 402The pname:format is interpreted based on the pname:type of the micromap 403using it. 404 405include::{generated}/validity/structs/VkMicromapTriangleEXT.adoc[] 406-- 407 408 409[[micromap-copying]] 410=== Copying Micromaps 411 412An additional command exists for copying micromaps without updating their 413contents. 414Before copying, an application must: query the size of the resulting 415micromap. 416 417[open,refpage='vkCmdWriteMicromapsPropertiesEXT',desc='Write micromap result parameters to query results.',type='protos'] 418-- 419:refpage: vkCmdWriteMicromapsPropertiesEXT 420 421To query micromap size parameters call: 422 423include::{generated}/api/protos/vkCmdWriteMicromapsPropertiesEXT.adoc[] 424 425 * pname:commandBuffer is the command buffer into which the command will be 426 recorded. 427 * pname:micromapCount is the count of micromaps for which to query the 428 property. 429 * pname:pMicromaps is a pointer to an array of existing previously built 430 micromaps. 431 * pname:queryType is a elink:VkQueryType value specifying the type of 432 queries managed by the pool. 433 * pname:queryPool is the query pool that will manage the results of the 434 query. 435 * pname:firstQuery is the first query index within the query pool that 436 will contain the pname:micromapCount number of results. 437 438Accesses to any of the micromaps listed in pname:pMicromaps must: be 439<<synchronization-dependencies, synchronized>> with the 440ename:VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT 441<<synchronization-pipeline-stages, pipeline stage>> and an 442<<synchronization-access-types, access type>> of 443ename:VK_ACCESS_2_MICROMAP_READ_BIT_EXT. 444 445 * If pname:queryType is 446 ename:VK_QUERY_TYPE_MICROMAP_SERIALIZATION_SIZE_EXT, then the value 447 written out is the number of bytes required by a serialized micromap. 448 * If pname:queryType is ename:VK_QUERY_TYPE_MICROMAP_COMPACTED_SIZE_EXT, 449 then the value written out is the number of bytes required by a 450 compacted micromap. 451 452.Valid Usage 453**** 454 * [[VUID-vkCmdWriteMicromapsPropertiesEXT-queryPool-07525]] 455 pname:queryPool must: have been created with a pname:queryType matching 456 pname:queryType 457 * [[VUID-vkCmdWriteMicromapsPropertiesEXT-queryPool-07526]] 458 The queries identified by pname:queryPool and pname:firstQuery must: be 459 _unavailable_ 460 * [[VUID-vkCmdWriteMicromapsPropertiesEXT-buffer-07527]] 461 The pname:buffer used to create each micromap in pname:pMicrmaps must: 462 be bound to device memory 463 * [[VUID-vkCmdWriteMicromapsPropertiesEXT-query-07528]] 464 The sum of pname:query plus pname:micromapCount must: be less than or 465 equal to the number of queries in pname:queryPool 466include::{chapters}/commonvalidity/write_micromap_properties_common.adoc[] 467**** 468 469include::{generated}/validity/protos/vkCmdWriteMicromapsPropertiesEXT.adoc[] 470-- 471 472[open,refpage='vkCmdCopyMicromapEXT',desc='Copy a micromap',type='protos'] 473-- 474:refpage: vkCmdCopyMicromapEXT 475 476To copy a micromap call: 477 478include::{generated}/api/protos/vkCmdCopyMicromapEXT.adoc[] 479 480 * pname:commandBuffer is the command buffer into which the command will be 481 recorded. 482 * pname:pInfo is a pointer to a slink:VkCopyMicromapInfoEXT structure 483 defining the copy operation. 484 485This command copies the pname:pInfo->src micromap to the pname:pInfo->dst 486micromap in the manner specified by pname:pInfo->mode. 487 488Accesses to pname:pInfo->src and pname:pInfo->dst must: be 489<<synchronization-dependencies, synchronized>> with the 490ename:VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT 491<<synchronization-pipeline-stages, pipeline stage>> and an 492<<synchronization-access-types, access type>> of 493ename:VK_ACCESS_2_MICROMAP_READ_BIT_EXT or 494ename:VK_ACCESS_2_MICROMAP_WRITE_BIT_EXT as appropriate. 495 496.Valid Usage 497**** 498 * [[VUID-vkCmdCopyMicromapEXT-buffer-07529]] 499 The pname:buffer used to create pname:pInfo->src must: be bound to 500 device memory 501 * [[VUID-vkCmdCopyMicromapEXT-buffer-07530]] 502 The pname:buffer used to create pname:pInfo->dst must: be bound to 503 device memory 504**** 505 506include::{generated}/validity/protos/vkCmdCopyMicromapEXT.adoc[] 507-- 508 509[open,refpage='VkCopyMicromapInfoEXT',desc='Parameters for copying a micromap',type='structs'] 510-- 511:refpage: VkCopyMicromapInfoEXT 512 513The sname:VkCopyMicromapInfoEXT structure is defined as: 514 515include::{generated}/api/structs/VkCopyMicromapInfoEXT.adoc[] 516 517 * pname:sType is a elink:VkStructureType value identifying this structure. 518 * pname:pNext is `NULL` or a pointer to a structure extending this 519 structure. 520 * pname:src is the source micromap for the copy. 521 * pname:dst is the target micromap for the copy. 522 * pname:mode is a elink:VkCopyMicromapModeEXT value specifying additional 523 operations to perform during the copy. 524 525.Valid Usage 526**** 527 * [[VUID-VkCopyMicromapInfoEXT-mode-07531]] 528 pname:mode must: be ename:VK_COPY_MICROMAP_MODE_COMPACT_EXT or 529 ename:VK_COPY_MICROMAP_MODE_CLONE_EXT 530 * [[VUID-VkCopyMicromapInfoEXT-src-07532]] 531 The source acceleration structure pname:src must: have been constructed 532 prior to the execution of this command 533 * [[VUID-VkCopyMicromapInfoEXT-mode-07533]] 534 If pname:mode is ename:VK_COPY_MICROMAP_MODE_COMPACT_EXT, pname:src 535 must: have been constructed with 536 ename:VK_BUILD_MICROMAP_ALLOW_COMPACTION_BIT_EXT in the build 537 * [[VUID-VkCopyMicromapInfoEXT-buffer-07534]] 538 The pname:buffer used to create pname:src must: be bound to device 539 memory 540 * [[VUID-VkCopyMicromapInfoEXT-buffer-07535]] 541 The pname:buffer used to create pname:dst must: be bound to device 542 memory 543**** 544 545include::{generated}/validity/structs/VkCopyMicromapInfoEXT.adoc[] 546-- 547 548[open,refpage='VkCopyMicromapModeEXT',desc='Micromap copy mode',type='enums'] 549-- 550:refpage: VkCopyMicromapModeEXT 551 552Possible values of pname:mode specifying additional operations to perform 553during the copy, are: 554 555include::{generated}/api/enums/VkCopyMicromapModeEXT.adoc[] 556 557 * ename:VK_COPY_MICROMAP_MODE_CLONE_EXT creates a direct copy of the 558 micromap specified in pname:src into the one specified by pname:dst. 559 The pname:dst micromap must: have been created with the same parameters 560 as pname:src. 561 * ename:VK_COPY_MICROMAP_MODE_SERIALIZE_EXT serializes the micromap to a 562 semi-opaque format which can be reloaded on a compatible implementation. 563 * ename:VK_COPY_MICROMAP_MODE_DESERIALIZE_EXT deserializes the semi-opaque 564 serialization format in the buffer to the micromap. 565 * ename:VK_COPY_MICROMAP_MODE_COMPACT_EXT creates a more compact version 566 of a micromap pname:src into pname:dst. 567 The micromap pname:dst must: have been created with a size at least as 568 large as that returned by flink:vkCmdWriteMicromapsPropertiesEXT after 569 the build of the micromap specified by pname:src. 570-- 571 572[open,refpage='vkCmdCopyMicromapToMemoryEXT',desc='Copy a micromap to device memory',type='protos'] 573-- 574:refpage: vkCmdCopyMicromapToMemoryEXT 575 576To copy a micromap to device memory call: 577 578include::{generated}/api/protos/vkCmdCopyMicromapToMemoryEXT.adoc[] 579 580 * pname:commandBuffer is the command buffer into which the command will be 581 recorded. 582 * pname:pInfo is an a pointer to a slink:VkCopyMicromapToMemoryInfoEXT 583 structure defining the copy operation. 584 585Accesses to pname:pInfo->src must: be <<synchronization-dependencies, 586synchronized>> with the ename:VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT 587<<synchronization-pipeline-stages, pipeline stage>> and an 588<<synchronization-access-types, access type>> of 589ename:VK_ACCESS_2_MICROMAP_READ_BIT_EXT. 590Accesses to the buffer indicated by pname:pInfo->dst.deviceAddress must: be 591synchronized with the ename:VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT 592pipeline stage and an access type of ename:VK_ACCESS_TRANSFER_WRITE_BIT. 593 594This command produces the same results as flink:vkCopyMicromapToMemoryEXT, 595but writes its result to a device address, and is executed on the device 596rather than the host. 597The output may: not necessarily be bit-for-bit identical, but it can be 598equally used by either flink:vkCmdCopyMemoryToMicromapEXT or 599flink:vkCopyMemoryToMicromapEXT. 600 601[[serialized-micromap-header]] 602The defined header structure for the serialized data consists of: 603 604 * ename:VK_UUID_SIZE bytes of data matching 605 sname:VkPhysicalDeviceIDProperties::pname:driverUUID 606 * ename:VK_UUID_SIZE bytes of data identifying the compatibility for 607 comparison using flink:vkGetDeviceMicromapCompatibilityEXT 608The serialized data is written to the buffer (or read from the buffer) 609according to the host endianness. 610 611.Valid Usage 612**** 613 * [[VUID-vkCmdCopyMicromapToMemoryEXT-pInfo-07536]] 614 pname:pInfo->dst.deviceAddress must: be a valid device address for a 615 buffer bound to device memory 616 * [[VUID-vkCmdCopyMicromapToMemoryEXT-pInfo-07537]] 617 pname:pInfo->dst.deviceAddress must: be aligned to `256` bytes 618 * [[VUID-vkCmdCopyMicromapToMemoryEXT-pInfo-07538]] 619 If the buffer pointed to by pname:pInfo->dst.deviceAddress is non-sparse 620 then it must: be bound completely and contiguously to a single 621 slink:VkDeviceMemory object 622 * [[VUID-vkCmdCopyMicromapToMemoryEXT-buffer-07539]] 623 The pname:buffer used to create pname:pInfo->src must: be bound to 624 device memory 625**** 626 627include::{generated}/validity/protos/vkCmdCopyMicromapToMemoryEXT.adoc[] 628-- 629 630[open,refpage='VkCopyMicromapToMemoryInfoEXT',desc='Parameters for serializing a micromap',type='structs'] 631-- 632:refpage: VkCopyMicromapToMemoryInfoEXT 633 634include::{generated}/api/structs/VkCopyMicromapToMemoryInfoEXT.adoc[] 635 636 * pname:sType is a elink:VkStructureType value identifying this structure. 637 * pname:pNext is `NULL` or a pointer to a structure extending this 638 structure. 639 * pname:src is the source micromap for the copy 640 * pname:dst is the device or host address to memory which is the target 641 for the copy 642 * pname:mode is a elink:VkCopyMicromapModeEXT value specifying additional 643 operations to perform during the copy. 644 645.Valid Usage 646**** 647 * [[VUID-VkCopyMicromapToMemoryInfoEXT-src-07540]] 648 The source micromap pname:src must: have been constructed prior to the 649 execution of this command 650 * [[VUID-VkCopyMicromapToMemoryInfoEXT-dst-07541]] 651 The memory pointed to by pname:dst must: be at least as large as the 652 serialization size of pname:src, as reported by 653 flink:vkWriteMicromapsPropertiesEXT or 654 flink:vkCmdWriteMicromapsPropertiesEXT with a query type of 655 ename:VK_QUERY_TYPE_MICROMAP_SERIALIZATION_SIZE_EXT 656 * [[VUID-VkCopyMicromapToMemoryInfoEXT-mode-07542]] 657 pname:mode must: be ename:VK_COPY_MICROMAP_MODE_SERIALIZE_EXT 658**** 659 660include::{generated}/validity/structs/VkCopyMicromapToMemoryInfoEXT.adoc[] 661-- 662 663[open,refpage='vkCmdCopyMemoryToMicromapEXT',desc='Copy device memory to a micromap',type='protos'] 664-- 665:refpage: vkCmdCopyMemoryToMicromapEXT 666 667To copy device memory to a micromap call: 668 669include::{generated}/api/protos/vkCmdCopyMemoryToMicromapEXT.adoc[] 670 671 * pname:commandBuffer is the command buffer into which the command will be 672 recorded. 673 * pname:pInfo is a pointer to a slink:VkCopyMicromapToMemoryInfoEXT 674 structure defining the copy operation. 675 676Accesses to pname:pInfo->dst must: be <<synchronization-dependencies, 677synchronized>> with the ename:VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT 678<<synchronization-pipeline-stages, pipeline stage>> and an 679<<synchronization-access-types, access type>> of 680ename:VK_ACCESS_2_MICROMAP_READ_BIT_EXT. 681Accesses to the buffer indicated by pname:pInfo->src.deviceAddress must: be 682synchronized with the ename:VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT 683pipeline stage and an access type of ename:VK_ACCESS_TRANSFER_READ_BIT. 684 685This command can accept micromaps produced by either 686flink:vkCmdCopyMicromapToMemoryEXT or flink:vkCopyMicromapToMemoryEXT. 687 688.Valid Usage 689**** 690 * [[VUID-vkCmdCopyMemoryToMicromapEXT-pInfo-07543]] 691 pname:pInfo->src.deviceAddress must: be a valid device address for a 692 buffer bound to device memory 693 * [[VUID-vkCmdCopyMemoryToMicromapEXT-pInfo-07544]] 694 pname:pInfo->src.deviceAddress must: be aligned to `256` bytes 695 * [[VUID-vkCmdCopyMemoryToMicromapEXT-pInfo-07545]] 696 If the buffer pointed to by pname:pInfo->src.deviceAddress is non-sparse 697 then it must: be bound completely and contiguously to a single 698 slink:VkDeviceMemory object 699 * [[VUID-vkCmdCopyMemoryToMicromapEXT-buffer-07546]] 700 The pname:buffer used to create pname:pInfo->dst must: be bound to 701 device memory 702**** 703 704include::{generated}/validity/protos/vkCmdCopyMemoryToMicromapEXT.adoc[] 705-- 706 707[open,refpage='VkCopyMemoryToMicromapInfoEXT',desc='Parameters for deserializing a micromap',type='structs'] 708-- 709:refpage: VkCopyMemoryToMicromapInfoEXT 710 711The sname:VkCopyMemoryToMicromapInfoEXT structure is defined as: 712 713include::{generated}/api/structs/VkCopyMemoryToMicromapInfoEXT.adoc[] 714 715 * pname:sType is a elink:VkStructureType value identifying this structure. 716 * pname:pNext is `NULL` or a pointer to a structure extending this 717 structure. 718 * pname:src is the device or host address to memory containing the source 719 data for the copy. 720 * pname:dst is the target micromap for the copy. 721 * pname:mode is a elink:VkCopyMicromapModeEXT value specifying additional 722 operations to perform during the copy. 723 724.Valid Usage 725**** 726 * [[VUID-VkCopyMemoryToMicromapInfoEXT-src-07547]] 727 The source memory pointed to by pname:src must: contain data previously 728 serialized using flink:vkCmdCopyMicromapToMemoryEXT 729 * [[VUID-VkCopyMemoryToMicromapInfoEXT-mode-07548]] 730 pname:mode must: be ename:VK_COPY_MICROMAP_MODE_DESERIALIZE_EXT 731 * [[VUID-VkCopyMemoryToMicromapInfoEXT-src-07549]] 732 The data in pname:src must: have a format compatible with the 733 destination physical device as returned by 734 flink:vkGetDeviceMicromapCompatibilityEXT 735 * [[VUID-VkCopyMemoryToMicromapInfoEXT-dst-07550]] 736 pname:dst must: have been created with a pname:size greater than or 737 equal to that used to serialize the data in pname:src 738**** 739 740include::{generated}/validity/structs/VkCopyMemoryToMicromapInfoEXT.adoc[] 741-- 742 743[open,refpage='vkGetDeviceMicromapCompatibilityEXT',desc='Check if a serialized micromap is compatible with the current device',type='protos'] 744-- 745:refpage: vkGetDeviceMicromapCompatibilityEXT 746 747To check if a serialized micromap is compatible with the current device 748call: 749 750include::{generated}/api/protos/vkGetDeviceMicromapCompatibilityEXT.adoc[] 751 752 * pname:device is the device to check the version against. 753 * pname:pVersionInfo is a pointer to a slink:VkMicromapVersionInfoEXT 754 structure specifying version information to check against the device. 755 * pname:pCompatibility is a pointer to a 756 elink:VkAccelerationStructureCompatibilityKHR value in which 757 compatibility information is returned. 758 759.Valid Usage 760**** 761 * [[VUID-vkGetDeviceMicromapCompatibilityEXT-micromap-07551]] 762 The <<features-micromap, pname:micromap>> feature must: be enabled 763**** 764 765include::{generated}/validity/protos/vkGetDeviceMicromapCompatibilityEXT.adoc[] 766-- 767 768[open,refpage='VkMicromapVersionInfoEXT',desc='Micromap version information',type='structs'] 769-- 770:refpage: VkMicromapVersionInfoEXT 771 772The sname:VkMicromapVersionInfoEXT structure is defined as: 773 774include::{generated}/api/structs/VkMicromapVersionInfoEXT.adoc[] 775 776 * pname:sType is a elink:VkStructureType value identifying this structure. 777 * pname:pNext is `NULL` or a pointer to a structure extending this 778 structure. 779 * pname:pVersionData is a pointer to the version header of a micromap as 780 defined in flink:vkCmdCopyMicromapToMemoryEXT 781 782[NOTE] 783.Note 784==== 785pname:pVersionData is a _pointer_ to an array of 2{times}ename:VK_UUID_SIZE 786code:uint8_t values instead of two ename:VK_UUID_SIZE arrays as the expected 787use case for this member is to be pointed at the header of a previously 788serialized micromap (via flink:vkCmdCopyMicromapToMemoryEXT or 789flink:vkCopyMicromapToMemoryEXT) that is loaded in memory. 790Using arrays would necessitate extra memory copies of the UUIDs. 791==== 792 793include::{generated}/validity/structs/VkMicromapVersionInfoEXT.adoc[] 794-- 795 796 797[[host-micromap]] 798== Host Micromap Operations 799 800Implementations are also required to provide host implementations of the 801micromap operations if the <<features-micromapHostCommands, 802pname:micromapHostCommands>> feature is enabled: 803 804 * flink:vkBuildMicromapsEXT corresponding to flink:vkCmdBuildMicromapsEXT 805 * flink:vkCopyMicromapEXT corresponding to flink:vkCmdCopyMicromapEXT 806 * flink:vkCopyMicromapToMemoryEXT corresponding to 807 flink:vkCmdCopyMicromapToMemoryEXT 808 * flink:vkCopyMemoryToMicromapEXT corresponding to 809 flink:vkCmdCopyMemoryToMicromapEXT 810 * flink:vkWriteMicromapsPropertiesEXT corresponding to 811 flink:vkCmdWriteMicromapsPropertiesEXT 812 813These commands are functionally equivalent to their device counterparts, 814except that they are executed on the host timeline, rather than being 815enqueued into command buffers. 816 817All micromaps used by the host commands must: be bound to host-visible 818memory, and all input data for micromap builds must: be referenced using 819host addresses instead of device addresses. 820Applications are not required to map micromap memory when using the host 821commands. 822 823 824[NOTE] 825.Note 826==== 827The flink:vkBuildMicromapsEXT and flink:vkCmdBuildMicromapsEXT may: use 828different algorithms, and thus are not required to produce identical 829structures. 830 831Apart from these details, the host and device operations are 832interchangeable. 833==== 834 835[NOTE] 836.Note 837==== 838For efficient execution, micromaps manipulated using these commands should 839always be bound to host cached memory, as the implementation may need to 840repeatedly read and write this memory during the execution of the command. 841==== 842 843[open,refpage='vkBuildMicromapsEXT',desc='Build a micromap on the host',type='protos'] 844-- 845:refpage: vkBuildMicromapsEXT 846 847To build micromaps on the host, call: 848 849include::{generated}/api/protos/vkBuildMicromapsEXT.adoc[] 850 851 * pname:device is the sname:VkDevice for which the micromaps are being 852 built. 853 * pname:deferredOperation is an optional slink:VkDeferredOperationKHR to 854 <<deferred-host-operations-requesting, request deferral>> for this 855 command. 856 * pname:infoCount is the number of micromaps to build. 857 It specifies the number of the pname:pInfos that must: be provided. 858 * pname:pInfos is a pointer to an array of pname:infoCount 859 slink:VkMicromapBuildInfoEXT structures defining the geometry used to 860 build each micromap. 861 862This command fulfills the same task as flink:vkCmdBuildMicromapsEXT but is 863executed by the host. 864 865The fname:vkBuildMicromapsEXT command provides the ability to initiate 866multiple micromaps builds, however there is no ordering or synchronization 867implied between any of the individual micromap builds. 868 869[NOTE] 870.Note 871==== 872This means that there cannot: be any memory aliasing between any micromap 873memories or scratch memories being used by any of the builds. 874==== 875 876.Valid Usage 877**** 878include::{chapters}/commonvalidity/build_micromap_common.adoc[] 879 * [[VUID-vkBuildMicromapsEXT-pInfos-07552]] 880 For each element of pname:pInfos, the pname:buffer used to create its 881 pname:dstMicromap member must: be bound to host-visible device memory 882 * [[VUID-vkBuildMicromapsEXT-pInfos-07553]] 883 For each element of pname:pInfos, all referenced addresses of 884 pname:pInfos[i].pname:data.hostAddress must: be valid host memory 885 * [[VUID-vkBuildMicromapsEXT-pInfos-07554]] 886 For each element of pname:pInfos, all referenced addresses of 887 pname:pInfos[i].pname:triangleArray.hostAddress must: be valid host 888 memory 889 * [[VUID-vkBuildMicromapsEXT-micromapHostCommands-07555]] 890 The <<features-micromapHostCommands, 891 sname:VkPhysicalDeviceOpacityMicromapFeaturesEXT::pname:micromapHostCommands>> 892 feature must: be enabled 893 * [[VUID-vkBuildMicromapsEXT-pInfos-07556]] 894 If pname:pInfos[i].pname:mode is ename:VK_BUILD_MICROMAP_MODE_BUILD_EXT, 895 all addresses between pname:pInfos[i].pname:scratchData.hostAddress and 896 pname:pInfos[i].pname:scratchData.hostAddress + N - 1 must: be valid 897 host memory, where N is given by the pname:buildScratchSize member of 898 the slink:VkMicromapBuildSizesInfoEXT structure returned from a call to 899 flink:vkGetMicromapBuildSizesEXT with an identical 900 slink:VkMicromapBuildInfoEXT structure and primitive count 901ifdef::VK_KHR_device_group,VK_VERSION_1_1[] 902 * [[VUID-vkBuildMicromapsEXT-pInfos-07557]] 903 For each element of pname:pInfos, the pname:buffer used to create its 904 pname:dstMicromap member must: be bound to memory that was not allocated 905 with multiple instances 906endif::VK_KHR_device_group,VK_VERSION_1_1[] 907**** 908 909include::{generated}/validity/protos/vkBuildMicromapsEXT.adoc[] 910-- 911 912[open,refpage='vkCopyMicromapEXT',desc='Copy a micromap on the host',type='protos'] 913-- 914:refpage: vkCopyMicromapEXT 915 916To copy or compact a micromap on the host, call: 917 918include::{generated}/api/protos/vkCopyMicromapEXT.adoc[] 919 920 * pname:device is the device which owns the micromaps. 921 * pname:deferredOperation is an optional slink:VkDeferredOperationKHR to 922 <<deferred-host-operations-requesting, request deferral>> for this 923 command. 924 * pname:pInfo is a pointer to a slink:VkCopyMicromapInfoEXT structure 925 defining the copy operation. 926 927This command fulfills the same task as flink:vkCmdCopyMicromapEXT but is 928executed by the host. 929 930.Valid Usage 931**** 932include::{chapters}/commonvalidity/deferred_operations_common.adoc[] 933 * [[VUID-vkCopyMicromapEXT-buffer-07558]] 934 The pname:buffer used to create pname:pInfo->src must: be bound to 935 host-visible device memory 936 * [[VUID-vkCopyMicromapEXT-buffer-07559]] 937 The pname:buffer used to create pname:pInfo->dst must: be bound to 938 host-visible device memory 939 * [[VUID-vkCopyMicromapEXT-micromapHostCommands-07560]] 940 The <<features-micromapHostCommands, 941 sname:VkPhysicalDeviceOpacityMicromapFeaturesEXT::pname:micromapHostCommands>> 942 feature must: be enabled 943ifdef::VK_KHR_device_group,VK_VERSION_1_1[] 944 * [[VUID-vkCopyMicromapEXT-buffer-07561]] 945 The pname:buffer used to create pname:pInfo->src must: be bound to 946 memory that was not allocated with multiple instances 947 * [[VUID-vkCopyMicromapEXT-buffer-07562]] 948 The pname:buffer used to create pname:pInfo->dst must: be bound to 949 memory that was not allocated with multiple instances 950endif::VK_KHR_device_group,VK_VERSION_1_1[] 951**** 952 953include::{generated}/validity/protos/vkCopyMicromapEXT.adoc[] 954-- 955 956[open,refpage='vkCopyMemoryToMicromapEXT',desc='Deserialize a micromap on the host',type='protos'] 957-- 958:refpage: vkCopyMemoryToMicromapEXT 959 960To copy host accessible memory to a micromap, call: 961 962include::{generated}/api/protos/vkCopyMemoryToMicromapEXT.adoc[] 963 964 * pname:device is the device which owns pname:pInfo->dst. 965 * pname:deferredOperation is an optional slink:VkDeferredOperationKHR to 966 <<deferred-host-operations-requesting, request deferral>> for this 967 command. 968 * pname:pInfo is a pointer to a slink:VkCopyMemoryToMicromapInfoEXT 969 structure defining the copy operation. 970 971This command fulfills the same task as flink:vkCmdCopyMemoryToMicromapEXT 972but is executed by the host. 973 974This command can accept micromaps produced by either 975flink:vkCmdCopyMicromapToMemoryEXT or flink:vkCopyMicromapToMemoryEXT. 976 977.Valid Usage 978**** 979include::{chapters}/commonvalidity/deferred_operations_common.adoc[] 980 * [[VUID-vkCopyMemoryToMicromapEXT-pInfo-07563]] 981 pname:pInfo->src.hostAddress must: be a valid host pointer 982 * [[VUID-vkCopyMemoryToMicromapEXT-pInfo-07564]] 983 pname:pInfo->src.hostAddress must: be aligned to 16 bytes 984 * [[VUID-vkCopyMemoryToMicromapEXT-buffer-07565]] 985 The pname:buffer used to create pname:pInfo->dst must: be bound to 986 host-visible device memory 987 * [[VUID-vkCopyMemoryToMicromapEXT-micromapHostCommands-07566]] 988 The <<features-micromapHostCommands, 989 sname:VkPhysicalDeviceOpacityMicromapFeaturesEXT::pname:micromapHostCommands>> 990 feature must: be enabled 991ifdef::VK_KHR_device_group,VK_VERSION_1_1[] 992 * [[VUID-vkCopyMemoryToMicromapEXT-buffer-07567]] 993 The pname:buffer used to create pname:pInfo->dst must: be bound to 994 memory that was not allocated with multiple instances 995endif::VK_KHR_device_group,VK_VERSION_1_1[] 996**** 997 998include::{generated}/validity/protos/vkCopyMemoryToMicromapEXT.adoc[] 999-- 1000 1001[open,refpage='vkCopyMicromapToMemoryEXT',desc='Serialize a micromap on the host',type='protos'] 1002-- 1003:refpage: vkCopyMicromapToMemoryEXT 1004 1005To copy a micromap to host accessible memory, call: 1006 1007include::{generated}/api/protos/vkCopyMicromapToMemoryEXT.adoc[] 1008 1009 * pname:device is the device which owns pname:pInfo->src. 1010 * pname:deferredOperation is an optional slink:VkDeferredOperationKHR to 1011 <<deferred-host-operations-requesting, request deferral>> for this 1012 command. 1013 * pname:pInfo is a pointer to a slink:VkCopyMicromapToMemoryInfoEXT 1014 structure defining the copy operation. 1015 1016This command fulfills the same task as flink:vkCmdCopyMicromapToMemoryEXT 1017but is executed by the host. 1018 1019This command produces the same results as 1020flink:vkCmdCopyMicromapToMemoryEXT, but writes its result directly to a host 1021pointer, and is executed on the host rather than the device. 1022The output may: not necessarily be bit-for-bit identical, but it can be 1023equally used by either flink:vkCmdCopyMemoryToMicromapEXT or 1024flink:vkCopyMemoryToMicromapEXT. 1025 1026.Valid Usage 1027**** 1028include::{chapters}/commonvalidity/deferred_operations_common.adoc[] 1029 * [[VUID-vkCopyMicromapToMemoryEXT-buffer-07568]] 1030 The pname:buffer used to create pname:pInfo->src must: be bound to 1031 host-visible device memory 1032 * [[VUID-vkCopyMicromapToMemoryEXT-pInfo-07569]] 1033 pname:pInfo->dst.hostAddress must: be a valid host pointer 1034 * [[VUID-vkCopyMicromapToMemoryEXT-pInfo-07570]] 1035 pname:pInfo->dst.hostAddress must: be aligned to 16 bytes 1036 * [[VUID-vkCopyMicromapToMemoryEXT-micromapHostCommands-07571]] 1037 The <<features-micromapHostCommands, 1038 sname:VkPhysicalDeviceOpacityMicromapFeaturesEXT::pname:micromapHostCommands>> 1039 feature must: be enabled 1040ifdef::VK_KHR_device_group,VK_VERSION_1_1[] 1041 * [[VUID-vkCopyMicromapToMemoryEXT-buffer-07572]] 1042 The pname:buffer used to create pname:pInfo->src must: be bound to 1043 memory that was not allocated with multiple instances 1044endif::VK_KHR_device_group,VK_VERSION_1_1[] 1045**** 1046 1047include::{generated}/validity/protos/vkCopyMicromapToMemoryEXT.adoc[] 1048-- 1049 1050[open,refpage='vkWriteMicromapsPropertiesEXT',desc='Query micromap meta-data on the host',type='protos'] 1051-- 1052:refpage: vkWriteMicromapsPropertiesEXT 1053 1054To query micromap size parameters on the host, call: 1055 1056include::{generated}/api/protos/vkWriteMicromapsPropertiesEXT.adoc[] 1057 1058 * pname:device is the device which owns the micromaps in pname:pMicromaps. 1059 * pname:micromapCount is the count of micromaps for which to query the 1060 property. 1061 * pname:pMicromaps is a pointer to an array of existing previously built 1062 micromaps. 1063 * pname:queryType is a elink:VkQueryType value specifying the property to 1064 be queried. 1065 * pname:dataSize is the size in bytes of the buffer pointed to by 1066 pname:pData. 1067 * pname:pData is a pointer to a user-allocated buffer where the results 1068 will be written. 1069 * pname:stride is the stride in bytes between results for individual 1070 queries within pname:pData. 1071 1072This command fulfills the same task as 1073flink:vkCmdWriteMicromapsPropertiesEXT but is executed by the host. 1074 1075.Valid Usage 1076**** 1077include::{chapters}/commonvalidity/write_micromap_properties_common.adoc[] 1078 * [[VUID-vkWriteMicromapsPropertiesEXT-queryType-07573]] 1079 If pname:queryType is 1080 ename:VK_QUERY_TYPE_MICROMAP_SERIALIZATION_SIZE_EXT, then pname:stride 1081 must: be a multiple of the size of basetype:VkDeviceSize 1082 * [[VUID-vkWriteMicromapsPropertiesEXT-queryType-07574]] 1083 If pname:queryType is 1084 ename:VK_QUERY_TYPE_MICROMAP_SERIALIZATION_SIZE_EXT, then pname:pData 1085 must: point to a basetype:VkDeviceSize 1086 * [[VUID-vkWriteMicromapsPropertiesEXT-queryType-07575]] 1087 If pname:queryType is 1088 * [[VUID-vkWriteMicromapsPropertiesEXT-dataSize-07576]] 1089 pname:dataSize must: be greater than or equal to 1090 [eq]#pname:micromapCount*pname:stride# 1091 * [[VUID-vkWriteMicromapsPropertiesEXT-buffer-07577]] 1092 The pname:buffer used to create each micromap in pname:pMicromaps must: 1093 be bound to host-visible device memory 1094 * [[VUID-vkWriteMicromapsPropertiesEXT-micromapHostCommands-07578]] 1095 The <<features-micromapHostCommands, 1096 sname:VkPhysicalDeviceOpacityMicromapFeaturesEXT::pname:micromapHostCommands>> 1097 feature must: be enabled 1098ifdef::VK_KHR_device_group,VK_VERSION_1_1[] 1099 * [[VUID-vkWriteMicromapsPropertiesEXT-buffer-07579]] 1100 The pname:buffer used to create each micromap in pname:pMicromaps must: 1101 be bound to memory that was not allocated with multiple instances 1102endif::VK_KHR_device_group,VK_VERSION_1_1[] 1103**** 1104 1105include::{generated}/validity/protos/vkWriteMicromapsPropertiesEXT.adoc[] 1106-- 1107 1108ifdef::VK_NV_displacement_micromap[] 1109[[displacement-micromap]] 1110=== Displacement Micromap 1111 1112A displacement micromap in an acceleration structure includes information in 1113the slink:VkAccelerationStructureTrianglesDisplacementMicromapNV to define a 1114base triangle and displacement directions then uses displacement information 1115encoded in the micromap to apply to those values to generate the final 1116position. 1117 1118==== Displacement Base Triangle 1119 1120If pname:displacementBiasAndScaleBuffer is provided the bias and scale are 1121fetched from that buffer. 1122If pname:displacementBiasAndScaleBuffer is zero the bias and scale are 1123assumed to be 0.0 and 1.0, respectively. 1124 1125Given an input position from the geometry, the base position and 1126displacement vector used by the displacement are computed by: 1127 1128[eq]#basePosition = inputPosition {plus} displacementVector {times} bias# 1129 1130[eq]#baseDisplacementVector = displacementVector {times} scale# 1131 1132The parameters of each micro-vertex are derived from a combination of the 1133base triangle parameters extracted from the bottom-level acceleration 1134structure, the barycentrics of that micro-vertex, and the displacement value 1135fetched from the displacement micromap corresponding to that micro-vertex. 1136 1137[eq]#microVertexBasePosition = lerp(basePositions, microVertexBarycentrics)# 1138 1139[eq]#microVertexDisplacementVector = lerp(displacementVectors, 1140microVertexBarycentrics)# 1141 1142[eq]#microVertexDisplacedPosition = microVertexBasePosition {plus} 1143microVertexDisplacementVector {times} micromapDisplacementValue# 1144 1145==== Displacement Micromap Encoding 1146 1147[[displacement-micromap-encoding]] 1148 1149// XXX Needs a lot of diagrams and pseudocode 1150 1151Displacement amounts are stored in displacement blocks, each covering a 1152triangular region of microvertices. 1153Depending on the subdivision level and encoding format, one or more 1154displacement blocks combine to store all displacement values for a given 1155displacement micromap. 1156 1157Displacement blocks are organized along a space filling curve within a 1158displacement micromap if more than one block is required, then 1159micro-vertices are organized along the same space filling curve within a 1160displacement micromap. 1161 1162The space-filling curve is purely hierarchical with recursive splitting, 1163similar to that for opacity micromaps but operating on vertices instead of 1164triangles. 1165To maintain that the hierarchical ordering is contiguous while keeping 1166continuous winding, some triangles are flipped and wound differently. 1167 1168The ename:VK_DISPLACEMENT_MICROMAP_FORMAT_64_TRIANGLES_64_BYTES_NV format is 1169an uncompressed, packed format which covers 64 microtriangles (subdivision 1170level 3) in a block. 1171The block contains 45 displacement values encoded as 11 bit unorm values and 1172stored tightly packed in the vertex order described above, occupying 495 1173bits. 1174This is followed by 15 unused bits then 2 reserved bits which must: be 0. 1175If this block is used to store displacement for a subdivision level below 3 1176the later unused values are ignored. 1177 1178[options="header"] 1179|==== 1180| Section | Field | Entries | Bits per entry | Starting bit offset 1181| Displacement amounts | Vertex 0 - 44 | 45 | 11 | 0 1182| Unused | | 1 | 15 | 495 1183| Reserved | Must be 0 | 1 | 2 | 510 1184|==== 1185 1186The ename:VK_DISPLACEMENT_MICROMAP_FORMAT_256_TRIANGLES_128_BYTES_NV and 1187ename:VK_DISPLACEMENT_MICROMAP_FORMAT_1024_TRIANGLES_128_BYTES_NV formats 1188store displacements in a compressed form to save space. 1189Both formats use the same compression algorithm, differing in the number of 1190bits used in the different fields. 1191 1192The compression algorithm works by starting with fully specified anchor 1193vertices, then for each level, predicting the value for the displacement and 1194encoding the correction for that value, using fewer bits for each level of 1195subdivision. 1196 1197When adding a vertex in the recursive subdivision process between two 1198adjacent displacement values, the predicted value is given by the rounded 1199average of the two adjacent values as integers: 1200 1201[eq]#prediction = (A {plus} B {plus} 1) / 2# 1202 1203The decoded value after applying the correction is given by: 1204 1205[eq]#decoded = prediction {plus} ( SignExtend(correction) << shift )# 1206 1207where [eq]#correction# is given by the corrections field for a given level 1208and micro vertex and [eq]#shift# is given by the shifts field indexed from 1209the level then by 4 values, selected from interior or the 3 edges in vertex 1210order in that order. 1211 1212The bit encoding for 1213ename:VK_DISPLACEMENT_MICROMAP_FORMAT_256_TRIANGLES_128_BYTES_NV 1214 1215[options="header"] 1216|==== 1217| Section | Field | Entries | Bits per entry | Starting bit offset 1218| Anchors | Vertex 0 - 2 | 3 | 11 | 0 1219| Corrections | Level 1 | 3 | 11 | 33 1220| | Level 2 | 9 | 11 | 66 1221| | Level 3 | 30 | 10 | 165 1222| | Level 4 | 108 | 5 | 465 1223| Unused | | 1 | 1 | 1005 1224| Shifts | Level 4 | 4 | 3 | 1006 1225| | Level 3 | 4 | 1 | 1018 1226| Reserved | Must be 0 | 1 | 2 | 1022 1227|==== 1228 1229The bit encoding for 1230ename:VK_DISPLACEMENT_MICROMAP_FORMAT_1024_TRIANGLES_128_BYTES_NV 1231 1232[options="header"] 1233|==== 1234| Section | Field | Entries | Bits per entry | Starting bit offset 1235| Anchors | Vertex 0 - 2 | 3 | 11 | 0 1236| Corrections | Level 1 | 3 | 11 | 33 1237| | Level 2 | 9 | 8 | 66 1238| | Level 3 | 30 | 4 | 138 1239| | Level 4 | 108 | 2 | 258 1240| | Level 5 | 408 | 1 | 474 1241| Unused | | 1 | 88 | 882 1242| Shifts | Level 5 | 4 | 4 | 970 1243| | Level 4 | 4 | 4 | 986 1244| | Level 3 | 4 | 3 | 1002 1245| | Level 2 | 4 | 2 | 1014 1246| Reserved | Must be 0 | 1 | 2 | 1022 1247|==== 1248 1249endif::VK_NV_displacement_micromap[] 1250