molgfx_gpu/descriptors/
ray_query.rs

1//! Backend-neutral acceleration-structure descriptors.
2
3use crate::Device;
4
5bitflags::bitflags! {
6    /// Construction preferences for a BLAS or TLAS.
7    #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
8    pub struct AccelerationStructureFlags: u8 {
9        /// Permit topology-preserving updates.
10        const ALLOW_UPDATE = 1;
11        /// Prefer traversal speed over build speed.
12        const PREFER_FAST_TRACE = 1 << 1;
13        /// Prefer build speed over traversal speed.
14        const PREFER_FAST_BUILD = 1 << 2;
15        /// Prefer a smaller device-memory footprint.
16        const LOW_MEMORY = 1 << 3;
17    }
18}
19
20bitflags::bitflags! {
21    /// Per-geometry ray-query behavior.
22    #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
23    pub struct AccelerationGeometryFlags: u8 {
24        /// Geometry has no any-hit rejection step.
25        const OPAQUE = 1;
26    }
27}
28
29/// Whether a build may update an existing acceleration structure.
30#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
31pub enum AccelerationStructureUpdateMode {
32    /// Always perform a complete build.
33    #[default]
34    Build,
35    /// Prefer a topology-preserving update when supported.
36    PreferUpdate,
37}
38
39/// Index encoding for triangle BLAS geometry.
40#[derive(Clone, Copy, Debug, PartialEq, Eq)]
41pub enum AccelerationIndexFormat {
42    /// Unsigned 16-bit indices.
43    Uint16,
44    /// Unsigned 32-bit indices.
45    Uint32,
46}
47
48/// Size ceiling for one triangle geometry in a BLAS.
49#[derive(Clone, Copy, Debug, PartialEq, Eq)]
50pub struct TriangleGeometrySize {
51    /// Maximum vertex count.
52    pub vertex_count: u32,
53    /// Optional index format and maximum index count.
54    pub indices: Option<(AccelerationIndexFormat, u32)>,
55    /// Geometry behavior.
56    pub flags: AccelerationGeometryFlags,
57}
58
59/// Size ceiling for one procedural AABB geometry in a BLAS.
60#[derive(Clone, Copy, Debug, PartialEq, Eq)]
61pub struct AabbGeometrySize {
62    /// Maximum primitive count.
63    pub primitive_count: u32,
64    /// Geometry behavior.
65    pub flags: AccelerationGeometryFlags,
66}
67
68/// Geometry family and size ceilings used to allocate a BLAS.
69#[derive(Clone, Copy, Debug)]
70pub enum BlasGeometrySizes<'a> {
71    /// Triangle geometries with `Float32x3` positions.
72    Triangles(&'a [TriangleGeometrySize]),
73    /// Procedural AABB geometries.
74    Aabbs(&'a [AabbGeometrySize]),
75}
76
77/// Descriptor for allocating a BLAS.
78#[derive(Clone, Copy, Debug)]
79pub struct BlasDesc<'a> {
80    /// Diagnostic label.
81    pub label: &'static str,
82    /// Construction preferences.
83    pub flags: AccelerationStructureFlags,
84    /// Build/update policy.
85    pub update_mode: AccelerationStructureUpdateMode,
86    /// Geometry family and allocation ceilings.
87    pub geometries: BlasGeometrySizes<'a>,
88}
89
90/// Descriptor for allocating a TLAS.
91#[derive(Clone, Copy, Debug)]
92pub struct TlasDesc {
93    /// Diagnostic label.
94    pub label: &'static str,
95    /// Maximum number of instances.
96    pub max_instances: u32,
97    /// Construction preferences.
98    pub flags: AccelerationStructureFlags,
99    /// Build/update policy.
100    pub update_mode: AccelerationStructureUpdateMode,
101}
102
103/// Triangle geometry supplied to one BLAS build.
104#[derive(Clone, Copy, Debug)]
105pub struct TriangleGeometry<'a, D: Device> {
106    /// Size descriptor used when the BLAS was allocated.
107    pub size: &'a TriangleGeometrySize,
108    /// Packed vertex storage.
109    pub vertex_buffer: &'a D::Buffer,
110    /// First vertex in the buffer.
111    pub first_vertex: u32,
112    /// Byte stride between vertices.
113    pub vertex_stride: u64,
114    /// Optional index buffer, first index and format.
115    pub indices: Option<(&'a D::Buffer, u32, AccelerationIndexFormat)>,
116}
117
118/// Procedural AABB geometry supplied to one BLAS build.
119#[derive(Clone, Copy, Debug)]
120pub struct AabbGeometry<'a, D: Device> {
121    /// Size descriptor used when the BLAS was allocated.
122    pub size: &'a AabbGeometrySize,
123    /// Packed min/max AABB storage.
124    pub buffer: &'a D::Buffer,
125    /// Byte offset to the first primitive.
126    pub offset: u32,
127    /// Byte stride between primitives; at least 24 and divisible by 8.
128    pub stride: u64,
129}
130
131/// Geometry family supplied to one BLAS build.
132#[derive(Clone, Copy, Debug)]
133pub enum BlasGeometries<'a, D: Device> {
134    /// Triangle geometries.
135    Triangles(&'a [TriangleGeometry<'a, D>]),
136    /// Procedural AABB geometries.
137    Aabbs(&'a [AabbGeometry<'a, D>]),
138}
139
140/// One BLAS build operation.
141#[derive(Clone, Copy, Debug)]
142pub struct BlasBuildDesc<'a, D: Device> {
143    /// Destination BLAS.
144    pub blas: &'a D::Blas,
145    /// Geometry buffers and ranges.
146    pub geometries: BlasGeometries<'a, D>,
147}
148
149/// One instance stored in a TLAS.
150#[derive(Clone, Copy, Debug)]
151pub struct TlasInstance<'a, D: Device> {
152    /// Referenced BLAS.
153    pub blas: &'a D::Blas,
154    /// Row-major affine 3x4 transform.
155    pub transform: [f32; 12],
156    /// Shader-visible 24-bit application value.
157    pub custom_data: u32,
158    /// Eight-bit ray mask.
159    pub mask: u8,
160}
molgfx_gpu/descriptors/ray_query.rs

molgfx_gpu/descriptors/
ray_query.rs
