Skip to content

Latest commit

 

History

History
362 lines (255 loc) · 13.6 KB

RT_SPEC.md

File metadata and controls

362 lines (255 loc) · 13.6 KB
Raw

WebGPU Ray-Tracing

Objects

GPURayTracingAccelerationContainer

Used to encapsulate geometries or geometry instances, based on the assigned level.

Methods:

destroy

Destroys the acceleration container.

updateInstance

Updates the state of an instance inside a Top-Level container.

Type Description
Number The instance id
GPURayTracingAccelerationInstanceDescriptor The instance data to update with

GPURayTracingShaderBindingTable

Used to group shaders together which later can be dynamically invoked.

Methods:

destroy

Destroys the shader binding table.

GPURayTracingPipeline

Ray Tracing Pipeline.

Methods:

None

GPUDevice

This object gets extended with the following methods:

Methods:

createRayTracingAccelerationContainer:

Returns a new GPURayTracingAccelerationContainer.

Type
GPURayTracingAccelerationContainerDescriptor
createRayTracingShaderBindingTable:

Returns a new GPURayTracingShaderBindingTable.

Type
GPURayTracingShaderBindingTableDescriptor
createRayTracingPipeline:

Returns a new GPURayTracingPipeline.

Type
GPURayTracingPipelineDescriptor

GPURayTracingPassEncoder

Used to record a Ray-Tracing pass.

Methods:

insertDebugMarker
Type Description
String Group label for the marker
popDebugGroup

No arguments

pushDebugGroup
Type Description
String Debug group to push
setPipeline
Type Description
GPURaytracingPipeline The pipeline to use in this pass
setBindGroup
Type Description
Number The bind group index
GPUBindGroup The bind group to use in this pass
[Number] Array of dynamic offsets
traceRays
Type Description
Number The SBT Ray-Generation Group offset
Number The SBT Ray-Hit Group offset
Number The SBT Ray-Hit Miss offset
Number The width of the ray trace query dimensions
Number The height of the ray trace query dimensions
Number The depth of the ray trace query dimensions. Defaults to 1
endPass

No arguments

GPUCommandEncoder

This object gets extended with the following methods:

Methods:

beginRayTracingPass:

Begin a new Ray-Tracing pass.

Type
GPURayTracingPassDescriptor
buildRayTracingAccelerationContainer:

Build a GPURayTracingAccelerationContainer. When building a top-level container, all linked bottom-level containers (referenced through GPURayTracingAccelerationInstanceDescriptor.geometryContainer) must have finished building in a former pass.

Type Description
GPURayTracingAccelerationContainer The acceleration container to build
copyRayTracingAccelerationContainer:

Copies a GPURayTracingAccelerationContainer into another GPURayTracingAccelerationContainer. The source and the destination containers must be built before.

Type Description
GPURayTracingAccelerationContainer The source acceleration container to copy from
GPURayTracingAccelerationContainer The destination acceleration container to copy into
updateRayTracingAccelerationContainer:

Updates an acceleration container. The container must be built and created with the GPURayTracingAccelerationContainerUsage ALLOW_UPDATE flag.

Type Description
GPURayTracingAccelerationContainer The acceleration container to update

Bitmasks

GPURayTracingAccelerationGeometryUsage

Name Description
NONE Invokes Any-Hit and Closest-Hit shaders. Any-Hit shaders may get invoked multiple times for the same triangle
OPAQUE No Any-Hit Shader will be invoked for this geometry
ALLOW_ANY_HIT Any-Hit Shader will be invoked only once when hitting a triangle

GPURayTracingAccelerationInstanceUsage

Name Description
NONE
TRIANGLE_CULL_DISABLE Disables face culling for this geometry instance
TRIANGLE_FRONT_COUNTERCLOCKWISE Indicates that the front face of the triangle for culling purposes is the face that is counter clockwise in object space relative to the ray origin
FORCE_OPAQUE Interprets the flags of all referenced geometry containers to be opaque. This behavior can be overridden with the traceRayEXT ray flag
FORCE_NO_OPAQUE Inverse behavior of FORCE_OPAQUE

GPURayTracingAccelerationContainerUsage

Name Description
NONE
ALLOW_UPDATE Allows updating the container's state with updateAccelerationContainer
PREFER_FAST_TRACE Hint to prefer fast ray tracing for this container
PREFER_FAST_BUILD Hint to prefer faster build times for this container
LOW_MEMORY Indicates that the container should use less memory, but might causes slower build times

GPUShaderStage

This bitmask gets extended with the following additional properties:

Name Description
RAY_GENERATION Ray Generation shader (.rgen, raygen), used to generate primary rays
RAY_CLOSEST_HIT Ray Closest-Hit shader (.rchit, closest), called for the closest surface relative to the ray
RAY_ANY_HIT Ray Any-Hit shader (.rahit, anyhit), called whenever a ray hit occurs
RAY_MISS Ray Miss shader (.rmiss, miss), called whenever a traced ray didn't hit a surface at all
RAY_INTERSECTION Ray Intersection shader (.rint) - Instead of the default triangle-based intersection, a custom ray-geometry intersection shader can be defined.

GPUBufferUsage

This bitmask gets extended with the following additional properties:

Name Description
RAY_TRACING Buffers used in acceleration containers must have been created with this flag

Enums

GPUIndexFormat

Name Description
none If index type is none, triangle acceleration geometry will not use indexing

GPURayTracingAccelerationGeometryType

Name Description
triangles Set of vertices and optionally indices, used for triangle based geometry
aabbs Set of axis-aligned bounding boxes, used for procedural geometry

GPURayTracingAccelerationContainerLevel

Name Description
bottom Bottom-Level Container, encapsulates geometry
top Top-Level Container, encapsulates geometry instances

GPURayTracingShaderBindingTableGroupType

Name Description
general .rgen, .rmiss
triangles-hit-group .rchit, rahit
procedural-hit-group .rint

Descriptors

GPUBindGroupEntry

This descriptor gets extended with the following properties:

Name Type Description
accelerationContainer GPURayTracingAccelerationContainer Acceleration container to bind

GPUTransform3DDescriptor

Name Type Description
x Number X coordinate
y Number Y coordinate
z Number Z coordinate

GPURayTracingAccelerationInstanceTransformDescriptor

Name Type Description
translation GPUTransform3DDescriptor Translation property
rotation GPUTransform3DDescriptor Rotation property
scale GPUTransform3DDescriptor Scale property

GPURayTracingAccelerationGeometryVertexDescriptor

Name Type Description
buffer GPUBuffer a GPUBuffer containing the vertices to be used
format GPUVertexFormat The format of the vertices
stride Number Byte stride between each vertex
offset Number Starting byte offset in the buffer
count Number Amount of vertices

GPURayTracingAccelerationGeometryIndexDescriptor

Name Type Description
buffer GPUBuffer a GPUBuffer containing the indices to be used
format GPUIndexFormat The format of the indices
offset Number Starting byte offset in the buffer
count Number Amount of indices

GPURayTracingAccelerationGeometryAABBDescriptor

Name Type Description
buffer GPUBuffer a GPUBuffer containing the AABBs to be used
stride Number The stride between each AABB
offset Number Starting byte offset in the buffer
count Number Amount of AABBs

GPURayTracingAccelerationGeometryDescriptor

Name Type Description
usage GPURayTracingAccelerationGeometryUsage Usage flags for this geometry
type GPURayTracingAccelerationGeometryType Type of this geometry
vertex GPURayTracingAccelerationGeometryVertexDescriptor Vertex descriptor
index GPURayTracingAccelerationGeometryIndexDescriptor Index descriptor
aabb GPURayTracingAccelerationGeometryAABBDescriptor AABB descriptor

GPURayTracingAccelerationInstanceDescriptor

Name Type Description
usage GPURayTracingAccelerationInstanceUsage Usage flags for this instance
mask Number (8 Bit) Ignore mask (see traceRayEXT)
instanceId Number (24 Bit) Used to identify an instance in a shader (see gl_InstanceCustomIndexEXT)instance
instanceOffset Number (24 Bit) Unused yet
transform GPURayTracingAccelerationInstanceTransformDescriptor Transform properties of this instance
transformMatrix Float32Array Low-Level alternative to transform - A 3x4 row-major transform matrix
geometryContainer GPURayTracingAccelerationContainer Geometry container to be used by this instance

GPURayTracingAccelerationContainerDescriptor

Name Type Description
usage GPURayTracingAccelerationContainerUsage Usage flags for the container
level GPURayTracingAccelerationContainerLevel Level of the container
geometries [GPURayTracingAccelerationGeometryDescriptor] Geometry to encapsulate by this container
instances [GPURayTracingAccelerationInstanceDescriptor] Geometry instances to encapsulate by this container

GPURayTracingShaderBindingTableStageDescriptor

Name Type Description
stage GPUShaderStage Ray-Tracing shader stage
module GPUShaderModule Shader module containing the shader

GPURayTracingShaderBindingTableGroupDescriptor

Name Type Description
type GPURayTracingShaderBindingTableGroupType Group type
generalIndex Number Index of a general group stage (.rgen, .rmiss)
closestHitIndex Number Index of a closest-hit stage (.rchit)
anyHitIndex Number Index of a any-hit stage (.rahit)
intersectionIndex Number Index of a intersection stage (.rint)

Each index defaults to -1, indicating that the group is unused. To enable a group, use the index of the respective shader defined in stages.

GPURayTracingShaderBindingTableDescriptor

Name Type Description
stages [GPURayTracingShaderBindingTableStageDescriptor] Ray-Tracing stages
groups [GPURayTracingShaderBindingTableGroupDescriptor] Ray-Tracing groups

GPURayTracingStateDescriptor

Name Type Description
shaderBindingTable GPURayTracingShaderBindingTable The shader binding table to use
maxRecursionDepth Number The maximum allowed Ray trace recursion in shaders. Defaults to 1
maxPayloadSize Number The maximum payload size (in bytes) used between shaders. A wrong number leads to undefined behaviour. This member is flux and might change in future.

GPURayTracingPipelineDescriptor

Name Type Description
layout GPUPipelineLayout Pipeline layout to use
rayTracingState GPURayTracingStateDescriptor Ray-Tracing state for this pipeline

GPURayTracingPassDescriptor

Name Type Description
label String Debug label