tracer

Ray-traced render orchestration: renderer dispatch and the deterministic wavefront’s host-side tile / iteration loop.

render_batch_raytraced() is the entry point called by the render loop for a batch of frames. It obtains the merged per-geometry-type arrays + STBVHs (scene_builder), prepares camera / light / environment tensors in the render arena, and dispatches on the sample count:

• samples_per_pixel == 1 (default) – the deterministic wavefront tracer (raytrace_render_wavefront()): bounded ray tiles run generate -> traverse -> shade -> composite kernel stages (wavefront_kernels_taichi.py), with per-ray state pool-allocated from ManualMemory, Taichi-side compaction of the still-active rays between host iterations, and a shared continuation pool for reflective / refractive splits (an overflowing tile is discarded and retried with fewer primaries, never approximated).

• samples_per_pixel > 1 – the path tracer (path_tracer.py + path_tracer_taichi.py): the same wavefront shape, sharing this renderer’s traversal kernel outright, run in sample waves of one path per pixel at output resolution (jittered samples are the anti-aliasing) into a float32 per-pixel buffer that finalize_samples averages.

Reflections and refraction are inferred from the mob’s Three.js-style material properties. Use MeshStandardMaterial(metalness=..., roughness=...) or MeshPhysicalMaterial before spawning; rays bounce up to max_bounces times.

On out-of-memory the frame window is halved and retried (OutOfRenderMemory); see render_batch_raytraced.

Classes

RenderPlan

Resolved renderer route and capability assessment for one batch.

Functions

analytic_raster_route_active(merged, *, light_sources=(), environment_map=None, near_clip=0.0, far_clip=0.0, transparent_background=False)

Whether this batch can use analytic coverage at output resolution.

This is the single host-side route decision shared by allocation planning and rendering. A requested supersample level is therefore retained for every route that the raster frontend cannot honor; only a batch whose complete primary geometry has analytic coverage selects AA=1.

Analytic coverage is resolved by the sheet route and nothing else (DESIGN_sheet_resolve.md; the fragment walk that once served it is deleted), so the sheet resolve’s own preconditions are route vetoes here: with any of them off the batch falls back to the classic wavefront at the requested supersample level. A transparent background composites fine from sheet leftover weight, but not together with an environment map (the env prefill would fill the alpha the background owes), so that one combination also falls back.

effective_anti_alias_level(merged, requested, *, light_sources=(), environment_map=None, near_clip=0.0, far_clip=0.0, transparent_background=False)

Return 1 for analytic raster or the path tracer, otherwise the requested AA setting.

is_ray_tracing_enabled()

Vestigial: always False. The ray-traced primitive classes are now the engine’s only renderer (RENDERER_REGISTRY binds them by default), and the enable_ray_tracing toggle that used to populate _originals was removed with the rasterizer. Kept only because post_processing.bloom probes for it defensively.

raytrace_render_wavefront(tri_bvh, bez_bvh, merged, cam_origin, screen_point, pixel_basis_x, pixel_basis_y, pixel_world_scale, time_start, time_end, width, height, half_screen_w, half_screen_h, layer_offset_triangles, has_tri, has_bez, max_bounces, light_pos, light_col, num_lights, frag_flag, frag_pipelines, frag_scatters, shadow_flag, refraction_flag, ior_stack_flag, transparent, memory, out, aa_level=1, lights_extended=False, env_meta=None, near_clip=0.0, far_clip=0.0, analytic_raster=False)

Wavefront orchestration for the general triangle/PN/bezier path.

Persistent continuation state is stage-split in global memory and PyTorch compacts ray indices between host iterations. Hit records are different: traversal writes one exact-size [num_active, kbuf] transient event batch, shade consumes it immediately, and the arena range is then reused. No pool-wide K-buffer is attached to secondary radiance ray slots. The persistent scalar state carries base_dist for Bezier border widths across bounces.

frag_flag/shadow_flag select the deterministic per-fragment shading and opacity-weighted hard-shadow paths (compile-time templates of the shade kernel); light_pos/light_col feed both.

frag_scatters is the per-pipeline custom ray-continuation (scatter) tuple (empty when no scene pipeline overrides bouncing); a non-empty tuple switches the monolithic shade kernel’s bounce block from the built-in opacity/reflectivity/Fresnel logic to per-material scatter dispatch (_run_frag_scatter), so users can customise reflection / refraction / pass-through. Empty keeps the built-in bounce block byte-identical.

refraction_flag enables simultaneous reflection + refraction (glass): the shade kernel SPLITS such a ray, continuing the reflected branch in place and spawning the refracted branch into a free pool slot. The pool is therefore over-allocated by pool_ratio (only when refraction / custom scatter is on) – it holds primary_per_tile one-per-pixel rays plus spare slots for split branches, at fixed total memory (fewer pixels per tile instead of bigger per-ray state). Each ray commits into a shared per-pixel accumulator (pix_accum) on termination, so a pixel’s reflected and refracted branches sum.

When fragment shading is active, the monolithic wavefront_shade kernel below is the shade architecture: it handles custom scatter and normal-mapped lighting, and on the built-in materials it drains up to kbuf hits per launch. (A Cycles-style sorted alternative – rays suspended at their material events and shaded by one kernel per material bucket – was measured slower for exactly that reason and has been removed.) The vertex-shaded path below is unaffected.

render_batch_raytraced(primitives, scene, screen_width, screen_height, time_start, time_end, background, transparent_background, ray_origin, screen_point, screen_basis, anti_alias_level=1, light_sources=(), memory=None, post_processes=(), **kwargs)

Render a primitive batch through the selected hybrid or path tracer.

Consume the batch’s immutable scene/camera/light data, validate renderer capabilities, reserve scene and transient arena storage, and render frame chunks into the output buffer. Memory includes geometry, acceleration structures, hit events, path/continuation state and post-processing scratch; it is not independent of scene complexity. The enclosing render loop owns frame-window retries, while renderer-specific tiling bounds transient work.