1// Copyright 2021-2023 The Khronos Group Inc.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5= Proposal Template
6:toc: left
7:refpage: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/
8:sectnums:
9
10VK_EXT_opacity_micromap adds a micromap object to associate micro-geometry information with geometry in an acceleration
11structure as well as a specific application of an opacity micromap to acceleration sub-triangle opacity without
12having to call a user any hit shader.
13
14== Problem Statement
15
16Geometry in an acceleration structure in the basic ray tracing extensions contains either geometric information or
17bounds for custom geometry. There are some applications where having a more compact representation of sub-triangle
18level information can be useful. One specific application is handling opacity information more efficiently at traversal
19time than having to return to an application-provided any hit shader.
20
21== Solution Space
22
23The mapping of the data onto the mesh is one design choice. Traditionally, texturing onto geometry is accomplished by
24application-provided texture coordinates, but in this case that would add significant extra metadata and require
25potentially more complicated sampling. A quad domain is natural for some interpretations of map data, but that may
26require more information from the application on at least adjacency information, even if not full UV coordinates. A
27triangular mapping is very amenable to performant implementations both in hardware and in software while not requiring
28extra information from the application outside of a given triangle.
29
30Relatedly, the mapping from triangle to index is another design choice. With raster images, pitch ordering is the de facto
31standard for interoperating images. There is no direct analogy to a triangular domain, though, and the most similar mapping
32is significantly less trivial than raster images. Moving to a mapping with more locality gives gains in terms of locality
33of processing, ease of downsampling, and similar operations.
34
35== Proposal
36
37The extension defines a VkMicromapEXT object and functions to manipulate it which parallel the functions that operate on
38acceleration structures. The micromap information is defined on the domain of subdivided triangles on a given acceleration
39structure geometry triangle. The build information contains usage information to compute the size including the number of triangles
40with a given subdivision level and format. For an opacity micromap, the micromap contains either 1-bit or 2-bit information
41which controls how the traversal is performed when combined with a set of flags.
42
43Once the micromap is built an extension structure can attach it to
44link:{refpage}VkAccelerationStructureGeometryKHR.html[VkAccelerationStructureGeometryKHR] along with
45mapping information from each triangle in the geometry to a specified triangle index in the micromap.
46
47== Examples
48
49    VkMicromapBuildInfoEXT mmBuildInfo = { VK_STRUCTURE_TYPE_MICROMAP_BUILD_INFO_EXT };
50
51    mmBuildInfo... = ;
52
53    vkGetMicromapBuildSizesEXT(..., &mmBuildInfo, &sizeInfo)
54
55    CreateBuffer(sizeInfo)
56
57    VkMicromapCreateInfoEXT mmCreateInfo = { VK_STRUCTURE_TYPE_MICROMAP_CREATE_INFO_EXT };
58
59    mmCreateInfo... = ;
60
61    vkCreateMicromapEXT(device, mmCreateInfo, null, &micromap)
62
63    mmBuildInfo = ...;
64
65    vkCmdBuildMicromapsEXT(cmd, 1, &mmBuildInfo);
66
67    VkAccelerationStructureTrianglesOpacityMicromapEXT opacityGeometryMicromap = { VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_TRIANGLES_OPACITY_MICROMAP_EXT };
68
69    opacityGeometryMicromap... = ;
70
71    VkAccelerationStructureGeometryKHR bottomASGeometry = { VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_KHR };
72
73    bottomASGeometry... = ;
74    bottomASGEometry.pNext = &opacityGeometryMicromap;
75
76    vkGetAccelerationStructureBuildSizesKHR()
77    vkCreateAccelerationStructureKHR()
78    vkCmdBuildAccelerationStructureKHR()
79
80== Issues
81
82=== RESOLVED: Are there any issues that belong here?
83
84All of the issues are in the spec documents.
85
86== Further Functionality
87
88 . A flag to give an implementation more flexibility in conservatively calling any hit shaders may be interesting. During EXT discussion,
89   it was decided that it was not ready and postponed for a possible extension to the extension.
90