molgfx_gpu/descriptors/
ray_query.rs

1//! Backend-neutral acceleration-structure descriptors.
2
3use crate::{Device, IndexFormat};
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/// Size ceiling for one triangle geometry in a BLAS.
40#[derive(Clone, Copy, Debug, PartialEq, Eq)]
41pub struct TriangleGeometrySize {
42    /// Maximum vertex count.
43    pub vertex_count: u32,
44    /// Optional index format and maximum index count.
45    pub indices: Option<(IndexFormat, u32)>,
46    /// Geometry behavior.
47    pub flags: AccelerationGeometryFlags,
48}
49
50/// Size ceiling for one procedural AABB geometry in a BLAS.
51#[derive(Clone, Copy, Debug, PartialEq, Eq)]
52pub struct AabbGeometrySize {
53    /// Maximum primitive count.
54    pub primitive_count: u32,
55    /// Geometry behavior.
56    pub flags: AccelerationGeometryFlags,
57}
58
59/// Geometry family and size ceilings used to allocate a BLAS.
60#[derive(Clone, Copy, Debug)]
61pub enum BlasGeometrySizes<'a> {
62    /// Triangle geometries with `Float32x3` positions.
63    Triangles(&'a [TriangleGeometrySize]),
64    /// Procedural AABB geometries.
65    Aabbs(&'a [AabbGeometrySize]),
66}
67
68/// Descriptor for allocating a BLAS.
69#[derive(Clone, Copy, Debug)]
70pub struct BlasDesc<'a> {
71    /// Diagnostic label.
72    pub label: &'static str,
73    /// Construction preferences.
74    pub flags: AccelerationStructureFlags,
75    /// Build/update policy.
76    pub update_mode: AccelerationStructureUpdateMode,
77    /// Geometry family and allocation ceilings.
78    pub geometries: BlasGeometrySizes<'a>,
79}
80
81/// Descriptor for allocating a TLAS.
82#[derive(Clone, Copy, Debug)]
83pub struct TlasDesc {
84    /// Diagnostic label.
85    pub label: &'static str,
86    /// Maximum number of instances.
87    pub max_instances: u32,
88    /// Construction preferences.
89    pub flags: AccelerationStructureFlags,
90    /// Build/update policy.
91    pub update_mode: AccelerationStructureUpdateMode,
92}
93
94/// Triangle geometry supplied to one BLAS build.
95#[derive(Clone, Copy, Debug)]
96pub struct TriangleGeometry<'a, D: Device> {
97    /// Size descriptor used when the BLAS was allocated.
98    pub size: &'a TriangleGeometrySize,
99    /// Packed vertex storage.
100    pub vertex_buffer: &'a D::Buffer,
101    /// First vertex in the buffer.
102    pub first_vertex: u32,
103    /// Byte stride between vertices.
104    pub vertex_stride: u64,
105    /// Optional index buffer, first index and format.
106    pub indices: Option<(&'a D::Buffer, u32, IndexFormat)>,
107}
108
109/// Procedural AABB geometry supplied to one BLAS build.
110#[derive(Clone, Copy, Debug)]
111pub struct AabbGeometry<'a, D: Device> {
112    /// Size descriptor used when the BLAS was allocated.
113    pub size: &'a AabbGeometrySize,
114    /// Packed min/max AABB storage.
115    pub buffer: &'a D::Buffer,
116    /// Byte offset to the first primitive.
117    pub offset: u32,
118    /// Byte stride between primitives; at least 24 and divisible by 8.
119    pub stride: u64,
120}
121
122/// Geometry family supplied to one BLAS build.
123#[derive(Clone, Copy, Debug)]
124pub enum BlasGeometries<'a, D: Device> {
125    /// Triangle geometries.
126    Triangles(&'a [TriangleGeometry<'a, D>]),
127    /// Procedural AABB geometries.
128    Aabbs(&'a [AabbGeometry<'a, D>]),
129}
130
131/// One BLAS build operation.
132#[derive(Clone, Copy, Debug)]
133pub struct BlasBuildDesc<'a, D: Device> {
134    /// Destination BLAS.
135    pub blas: &'a D::Blas,
136    /// Geometry buffers and ranges.
137    pub geometries: BlasGeometries<'a, D>,
138}
139
140/// One instance stored in a TLAS.
141#[derive(Clone, Copy, Debug)]
142pub struct TlasInstance<'a, D: Device> {
143    /// Referenced BLAS.
144    pub blas: &'a D::Blas,
145    /// Row-major affine 3x4 transform.
146    pub transform: [f32; 12],
147    /// Shader-visible 24-bit application value.
148    pub custom_data: u32,
149    /// Eight-bit ray mask.
150    pub mask: u8,
151}
molgfx_gpu/descriptors/ray_query.rs

molgfx_gpu/descriptors/
ray_query.rs
