wgpu Graphics API

Ray queries (inline raytracing) allow you to perform ray-scene intersections directly within a shader. The process follows a specific lifecycle:

1. Initialize: Call rayQueryInitialize with a RayDesc and an acceleration structure. This sets up the query state.
2. Traverse: Call rayQueryProceed to step through the scene. This function returns true if it finds a Candidate intersection (a hit in a non-opaque Blas) and false if it finds a Committed intersection or no more hits.
3. Handle Intersections:
   • Candidate Intersections: These are non-guaranteed closest hits. Use rayQueryGetCandidateIntersection to inspect them. They are useful for custom intersection logic.
   • Committed Intersections: These are the closest valid hits found so far. Use rayQueryGetCommittedIntersection to retrieve details.
4. Terminate: Use rayQueryTerminate to abort the query. The next rayQueryProceed will return false, and subsequent calls to rayQueryGetCommittedIntersection will return the closest committed result found up to that point.

Note on Candidate vs Committed:

• A Candidate intersection interrupts traversal but might not be the closest hit.
• A Committed intersection is a confirmed hit that the user has decided is valid (or the closest one found).

// Example lifecycle sketch
rayQueryInitialize(rq, accel_struct, ray_desc);
while (rayQueryProceed(rq)) {
    // Handle candidate intersections if needed
}
let hit = rayQueryGetCommittedIntersection(rq);
if (hit.kind != RAY_QUERY_INTERSECTION_NONE) {
    // Use hit data
}

A cooperative matrix is a value type parameterized by tile size (M×N), scalar element type T, and a role R. The role determines how the matrix participates in a multiply-accumulate operation (A * B + C):

• A: Left operand. Shape is M×K.
• B: Right operand. Shape is K×N.
• C: Accumulator/result. Shape is M×N.

Important: Roles are part of the type and are not interchangeable. You must use combinations of (M, N, T, R) that are explicitly supported by the hardware, which can be queried via Adapter::cooperative_matrix_properties.

// Example: 8x8 single-precision tiles
alias CoopMatA = coop_mat8x8<f32, A>;
alias CoopMatB = coop_mat8x8<f32, B>;
alias CoopMatC = coop_mat8x8<f32, C>;

// Example: 16x16 mixed precision (f16 inputs, f32 accumulator)
alias CoopMat16x16A = coop_mat16x16<f16, A>;
alias CoopMat16x16B = coop_mat16x16<f16, B>;
alias CoopMat16x16C = coop_mat16x16<f32, C>;

Mesh shaders are the primary stage for generating geometry. They are invoked in a grid of workgroups.

Key Requirements:

• Attribute: Must use the @mesh(VAR) attribute, where VAR is a workgroup variable storing the output information.
• Payload: If a task shader is present in the pipeline, the mesh shader must also have a @payload(G) attribute with matching variable sizes. Mesh shaders can read from this payload but cannot write to it.
• Output Structure: The workgroup variable VAR must be a struct with exactly 4 fields:
  1. @builtin(vertex_count): u32 (number of vertices to draw).
  2. @builtin(primitive_count): u32 (number of primitives to draw).
  3. @builtin(vertices): An array of vertex output types V.
  4. @builtin(primitives): An array of primitive output types P.

Primitive Output (P) Details:

• Must be a struct.
• Must contain exactly one member with one of these attributes:
  • @builtin(triangle_indices), @builtin(line_indices), or @builtin(point_index): Type vec3<u32>, vec2<u32>, or u32. These act as indices into the generated vertex array.
  • @builtin(cull_primitive): Type bool. If true, the primitive is skipped.
• All members decorated with @location must also be decorated with @per_primitive.

Capabilities:

• Can use compute and mesh shader builtin inputs.
• Can use view_index and (if no task shader is present) draw_id.

struct MeshOutput {
    @builtin(vertices) vertices: array<VertexOutput, 64>,
    @builtin(primitives) primitives: array<PrimitiveOutput, 128>,
    @builtin(vertex_count) vertex_count: u32,
    @builtin(primitive_count) primitive_count: u32,
}

var<workgroup> mesh_output: MeshOutput;

@mesh(mesh_output)
@workgroup_size(64)
fn my_mesh_main() {
    // ... populate mesh_output ...
}