dymokomi/luce-gpu
Source of release 0.5.7
0.5.7 / src / gpu / accel.lucb
#==============================================================================================
#
# accel - Acceleration structures for ray queries
#
# DESCRIPTION:
# A Blas (bottom-level acceleration structure) holds one triangle mesh's BVH, or one set
# of axis-aligned boxes around procedural primitives (splats, spheres, curves) whose
# intersections the tracing kernel computes itself; a Tlas
# (top-level) holds instances of Blases, each with a transform, a custom id and a mask.
# Kernels trace rays against a Tlas with GL_EXT_ray_query (Metal's intersection_query,
# Vulkan's VK_KHR_ray_query), where `limits().ray_query`. Both are manual Base resources
# whose storage is sized when they are created; builds, refits and updates are recorded
# on a Compute pass, ordered with its dispatches like every other command.
#
#==============================================================================================
## A mesh's triangles for a Blas: `vertex_count` world-space float3 positions,
## `stride` bytes apart from `vertex_offset` in `vertices`, and three u32
## indices per triangle from `index_offset` in `indices`. Offsets and the
## stride are multiples of four. `opaque` triangles never run any-hit logic
## (ray queries then need no candidate loop for them).
pub struct Triangles:
pub var vertices: Buffer
pub var vertex_offset: usize = 0
pub var stride: u32 = 12
pub var vertex_count: u32
pub var indices: Buffer
pub var index_offset: usize = 0
pub var triangle_count: u32
pub var opaque: bool = true
## Axis-aligned boxes for a Blas: procedural primitives. A ray query reports
## each box the ray enters as a candidate (`gl_RayQueryCandidateIntersectionAABBEXT`,
## its primitive index the box's), and the kernel decides whether and where it
## is hit, committing a distance with `rayQueryGenerateIntersectionEXT`.
## `count` boxes of six f32 (low x, y, z, then high x, y, z), `stride` bytes
## apart from `offset` in `buffer`; offset and stride are multiples of eight
## (Vulkan's rule), the stride at least 24.
pub struct Boxes:
pub var buffer: Buffer
pub var offset: usize = 0
pub var stride: u32 = 24
pub var count: u32
## One instance of a Blas in a Tlas. `transform` is the object-to-world matrix,
## 3 rows of 4 (row-major, the Vulkan and DXR layout: x' = row 0 ยท (x, y, z, 1));
## `id` is the custom index a ray query reports (24 bits); a ray's cull mask
## must share a bit with `mask` for the instance to be hit.
pub struct Instance:
pub var blas: Blas
pub var transform: f32[12] = [1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0]
pub var id: u32 = 0
pub var mask: u8 = 0xff
## The largest instance id: 24 bits, as Vulkan stores it.
pub let instance_id_limit: u32 = 0xffffff
## A bottom-level acceleration structure: one mesh, or one set of boxes. The zero value is closed;
## copies alias ownership; one owner destroys it on the main thread, and
## recorded builds, Tlases built from it and submitted work keep it alive.
pub struct Blas:
var state: AccelState*?
## Storage for a mesh of `triangles`' counts (its buffers are not read
## yet: build it on a pass). `refit` lets later passes refit it after its
## vertices move.
pub static func create(device: Device, triangles: Triangles, refit: bool = true) -> Blas!:
let owner = try device.checked()
if not owner.limits.ray_query:
error(unsupported, "the device has no ray queries")
if triangles.vertex_count == 0 or triangles.triangle_count == 0:
error(invalid_geometry, "a Blas holds at least one triangle")
let native = try backend_accel_blas(owner, triangles.vertex_count, triangles.triangle_count, triangles.opaque, false, refit)
errdefer backend_accel_destroy(owner, native)
let state = try new AccelState(device = owner, native = native, vertex_count = triangles.vertex_count,
triangle_count = triangles.triangle_count, refit = refit) in memory.heap
owner.references += 1
return Blas(state = state)
## Storage for `boxes`' count of procedural boxes (the buffer is not read
## yet: build it on a pass with `build_boxes`). `refit` lets later passes
## refit it after the boxes move or resize.
pub static func create_boxes(device: Device, boxes: Boxes, refit: bool = true) -> Blas!:
let owner = try device.checked()
if not owner.limits.ray_query:
error(unsupported, "the device has no ray queries")
if boxes.count == 0:
error(invalid_geometry, "a Blas holds at least one box")
let native = try backend_accel_blas(owner, 0, boxes.count, false, true, refit)
errdefer backend_accel_destroy(owner, native)
let state = try new AccelState(device = owner, native = native, triangle_count = boxes.count, boxes = true, refit = refit) in memory.heap
owner.references += 1
return Blas(state = state)
pub func is_open() -> bool:
return self.state != none
pub func destroy():
let state = self.state else return
require_thread()
self.state = none
release_accel(state)
func checked() -> AccelState*!:
try check_thread()
return self.state else error(closed, "the Blas is closed")
## A top-level acceleration structure: instances of Blases. The zero value is
## closed; copies alias ownership; one owner destroys it on the main thread,
## and recorded builds and submitted work keep it alive.
pub struct Tlas:
var state: AccelState*?
## Storage for up to `capacity` instances; build it on a pass.
pub static func create(device: Device, capacity: u32) -> Tlas!:
let owner = try device.checked()
if not owner.limits.ray_query:
error(unsupported, "the device has no ray queries")
if capacity == 0:
error(invalid_geometry, "a Tlas holds at least one instance")
let native = try backend_accel_tlas(owner, capacity)
errdefer backend_accel_destroy(owner, native)
let state = try new AccelState(device = owner, native = native, top = true, capacity = capacity, refit = true) in memory.heap
owner.references += 1
return Tlas(state = state)
pub func is_open() -> bool:
return self.state != none
pub func destroy():
let state = self.state else return
require_thread()
self.state = none
release_accel(state)
func checked() -> AccelState*!:
try check_thread()
return self.state else error(closed, "the Tlas is closed")
struct AccelState:
var device: DeviceState*
var native: void*
var references: usize = 1
var top: bool
## A Blas of boxes rather than triangles.
var boxes: bool
## A Blas's counts (its triangles, or its boxes), or a Tlas's capacity.
var vertex_count: u32
var triangle_count: u32
var capacity: u32
var refit: bool
## Whether a build was recorded (refits and updates need one).
var built: bool
## A Tlas: the Blases its last recorded build instanced, in instance order;
## it holds a reference to each until it is built again or released.
var instanced: AccelState*[]
var instanced_count: usize
## Hold `blases` as the instances of this Tlas, replacing the last build's.
func keep_instanced(blases: AccelState*[]) -> !:
if self.instanced.length < blases.length:
let grown = try new AccelState*[blases.length] --- in memory.heap
memory.copy(grown, self.instanced, self.instanced_count)
if self.instanced.length > 0: free(self.instanced) in memory.heap
self.instanced = grown
# New references first: a Blas in both builds must not reach zero.
for blas in blases:
blas.references += 1
self.release_instanced()
memory.copy(self.instanced, blases, blases.length)
self.instanced_count = blases.length
func release_instanced():
for index in 0..<self.instanced_count:
release_accel(self.instanced[index])
self.instanced_count = 0
func release_accel(state: AccelState*):
state.references -= 1
if state.references == 0:
state.release_instanced()
if state.instanced.length > 0: free(state.instanced) in memory.heap
backend_accel_destroy(state.device, state.native)
release_device(state.device)
free(state) in memory.heap
## A recorded Blas build's geometry, its buffers referenced by the command:
## triangles (vertices from `offset`, indices from `index_offset`) or `boxes`
## (from `offset`), `count` of them.
struct GeometryRecord:
var boxes: bool
var offset: usize
var stride: u32
var vertex_count: u32
var index_offset: usize
var count: u32
var opaque: bool
## A recorded instance: its Blas is the command's `instanced[index]`.
struct InstanceRecord:
var transform: f32[12]
var id: u32
var mask: u8
## Check `triangles` against `blas` and the pass's device.
func check_triangles(device: DeviceState*, blas: AccelState*, triangles: const Triangles*) -> !:
if blas.top or blas.boxes:
error(invalid_geometry, "a Tlas is built from instances, a Blas of boxes from boxes, not triangles")
if triangles.vertex_count != blas.vertex_count or triangles.triangle_count != blas.triangle_count:
error(invalid_geometry, "a Blas is built from the counts it was created for")
let vertices = triangles.vertices.state else error(closed, "a Blas build was given a closed vertex buffer")
let indices = triangles.indices.state else error(closed, "a Blas build was given a closed index buffer")
if vertices.device != device or indices.device != device:
error(wrong_device, "a Blas build reads buffers of its own device")
if triangles.stride < 12 or triangles.stride % 4 != 0 or triangles.vertex_offset % 4 != 0 or triangles.index_offset % 4 != 0:
error(invalid_geometry, "vertex strides and offsets are multiples of four, strides at least 12")
let vertex_end = (u64)triangles.vertex_offset + ((u64)triangles.vertex_count - 1) * (u64)triangles.stride + 12
let index_end = (u64)triangles.index_offset + (u64)triangles.triangle_count * 12
if vertex_end > (u64)vertices.bytes or index_end > (u64)indices.bytes:
error(invalid_geometry, "a Blas's vertices and indices lie inside their buffers")
## Check `boxes` against `blas` and the pass's device.
func check_boxes(device: DeviceState*, blas: AccelState*, boxes: const Boxes*) -> !:
if not blas.boxes:
error(invalid_geometry, "a Blas of triangles is built from triangles, not boxes")
if boxes.count != blas.triangle_count:
error(invalid_geometry, "a Blas is built from the count it was created for")
let buffer = boxes.buffer.state else error(closed, "a Blas build was given a closed box buffer")
if buffer.device != device:
error(wrong_device, "a Blas build reads buffers of its own device")
if boxes.stride < 24 or boxes.stride % 8 != 0 or boxes.offset % 8 != 0:
error(invalid_geometry, "box strides and offsets are multiples of eight, strides at least 24")
let end = (u64)boxes.offset + ((u64)boxes.count - 1) * (u64)boxes.stride + 24
if end > (u64)buffer.bytes:
error(invalid_geometry, "a Blas's boxes lie inside their buffer")
# mark: Dispatch ==============================================================================
## A Blas's storage: `count` triangles over `vertex_count` vertices, or `count` boxes.
func backend_accel_blas(device: DeviceState*, vertex_count: u32, count: u32, opaque: bool, boxes: bool, refit: bool) -> void*!:
if (platform.windows or platform.linux) and device.backend == Backend.vulkan:
return (void*)try vulkan_accel_blas((VulkanDevice*)device.native, vertex_count, count, opaque, boxes, refit)
if platform.macos and platform.arm64:
if device.backend == Backend.metal:
return (void*)try metal_accel_blas((MetalDevice*)device.native, vertex_count, count, opaque, boxes, refit)
error(unsupported, "ray queries are unavailable on this backend")
func backend_accel_tlas(device: DeviceState*, capacity: u32) -> void*!:
if (platform.windows or platform.linux) and device.backend == Backend.vulkan:
return (void*)try vulkan_accel_tlas((VulkanDevice*)device.native, capacity)
if platform.macos and platform.arm64:
if device.backend == Backend.metal:
return (void*)try metal_accel_tlas((MetalDevice*)device.native, capacity)
error(unsupported, "ray queries are unavailable on this backend")
## Released by the backend once no submitted work uses it.
func backend_accel_destroy(device: DeviceState*, native: void*):
if (platform.windows or platform.linux) and device.backend == Backend.vulkan:
vulkan_accel_destroy((VulkanDevice*)device.native, (VulkanAccel*)native)
return
if platform.macos and platform.arm64:
if device.backend == Backend.metal:
metal_accel_destroy((MetalAccel*)native)