ray

Casts rays and segments against the triangles of a geometry through the hierarchy the bvh kernel builds (closest hit, or any hit for occlusion), and computes the generalized winding number of the geometry about each origin, which is the inside test a boolean or a distance field needs. A hit is the parametric t, the primitive index and the barycentric weights. The header of bindings.yaml states the ray and hit layouts: a ray is 8 words of rays (origin xyz, tmin, direction xyz, tmax); a miss writes t = -1 and hit_prim 0xffffffff. Exact: the same rays give the same hits, ties going to the lower index.

ray binds rays, the geometry's pts (xyz a point), vpt, vstart and vcount, and the accel node table the bvh kernel builds, with the np param the number of primitives; the STAGE specialization picks closest, any or winding. The winding stage sums over every primitive and reads only the origin of each ray. geometry.boolean and geometry.to_sdf run the winding stage for their inside test, and sim.particles runs ray_shapes for its collisions.

ray is a family of three kernels, since one dispatch binds at most 8 storage buffers a stage:

Kernel	Answers
ray	hit (t, u, v, fan) and hit_prim (the primitive, the shape index of a mesh hit) for the closest, any and winding stages
ray_surface	for the closest hits ray found: hit_normal (unit triangle normal facing the ray's origin side) and hit_end (the hit point pushed out along the normal by the skin param; a miss answers the ray's end)
ray_shapes	the analytic shape table, bound as a columns binding (shapeKind, center, extent, rotation, bounce, friction, index; a plane's extent is its unit normal, a sphere's extent.x its radius): hit, hit_prim (the row of the shape table), hit_normal, hit_end

Chain for a mesh: dispatch ray with STAGE = closest, then ray_surface with the same rays, geometry bindings and the hit and hit_prim that ray wrote.