Skip to content

refactor(raytracing): group long parameter lists and bump to 0.31.2 - #318

Merged
vshengbro merged 2 commits into
masterfrom
refactor/raytrace-parameter-objects
Oct 18, 2026
Merged

vshengbro merged 2 commits into
masterfrom
refactor/raytrace-parameter-objects

Conversation

@vshengbro

@vshengbro vshengbro commented Oct 18, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Groups the raytracing/lighting parameter lists that grew past four ordinary
parameters into parameter structs, and bumps the workspace to 0.31.2 as a
patch release. This is the follow-up delivery of the parameter-object refactor:
the renderer work itself already reached master through the earlier PR; this
PR carries the remaining parameter grouping plus the version bump on top of the
current master.

Scope: 26 functions with >= 5 ordinary parameters

All 26 functions added by PR #317 that carried five or more ordinary
parameters now have four or fewer, or have been removed. Measured with a
scratch syn AST scanner over 148 source files: the original renderer scope's
147 files plus this PR's new source file:

before after
functions with >= 5 ordinary params added by the renderer work 26 0
functions with >= 5 ordinary params inherited and unchanged 19 19 (untouched)

The 26 changed signatures resolve three ways:

  • Grouped into a struct — the new RayTraceFrame collects camera, lights,
    settings and dimensions so pack_raytrace_frame and render_raytrace_rgba
    shrink from 6 to 2 and from 7 to 3 ordinary parameters, respectively.
    New stack-based BVH, light, upload and lifecycle parameter structs group
    the other related inputs without adding long positional constructors.
  • Reused existing types — intersection helpers pass Ray without
    normalizing its direction, and the WebGPU draw helper uses the existing
    DrawArgs descriptor while preserving four separate JavaScript arguments.
  • Removed or replaced helpers — the thin push_vec4 helper is replaced
    with direct extend_from_slice calls. grow_texture is consolidated into
    ensure_packed_texture, while the generic call4 helper becomes the
    draw-specific draw_vertices.

The only new source file is engine/src/raytracing/pipeline/render/struct.rs,
which holds PixelSample — a Copy struct of four scalars used by
pixel_direction; constructing this parameter object adds no per-sample
heap allocation.

Public API migration

Callers move from positional arguments to the frame struct:

RayTraceFrame<'a> is a Copy struct of public fields — the camera, lights and
settings are borrowed, the two dimensions are copied — so constructing one
allocates nothing and clones nothing:

// before
pack_raytrace_frame(&mut out, &camera, &lights, &settings, width, height);
render_raytrace_rgba(&scene, &camera, &lights, &settings, width, height, &mut out);

// after
let frame: RayTraceFrame<'_> = RayTraceFrame {
    camera: &camera,
    lights: &lights,
    settings: &settings,
    width,
    height,
};
pack_raytrace_frame(&mut out, &frame);
render_raytrace_rgba(&scene, &frame, &mut out);

Triangle intersection keeps both entry points, with their existing range
semantics untouched:

// free function — does NOT filter by the ray's t_min/t_max range
intersect_triangle(&ray, [v0, v1, v2])

// inherent method — same maths, then applies the ray's range clamp
Ray::intersect_triangle(&ray, [v0, v1, v2])

The free function's lack of range filtering and the inherent method's range
clamp are preserved and covered by regression tests.

The 19 inherited long-parameter renderer methods are outside this refactor's
scope and remain unchanged, as do the public WebGL and WebGPU backend entry
points. The public frame and triangle signatures above are breaking source
changes: downstream callers must migrate them.

Tests

8 new regression tests cover the shapes the parameter grouping has to preserve:

  • frame_struct_carries_its_own_inputs
  • frame_packs_the_camera_lights_and_settings_it_was_given
  • frame_packs_a_non_square_dimensions_pair_into_its_own_slots
  • frame_rejects_invalid_dimensions_without_touching_the_buffer
  • render_reuses_its_output_buffer_across_frame_shapes
  • soft_shadow_treats_a_coincident_light_as_visible
  • soft_shadow_ignores_a_sphere_the_segment_only_touches_at_an_endpoint
  • soft_shadow_tests_both_ray_sphere_roots_so_a_segment_starting_inside_an_occluder_is_shadowed

Verification performed on this branch

All gates were run against the final tree of this branch, including upstream
CI-generated derive ordering in backend/canvas/struct.rs and
backend/data/struct.rs:

  • AST parameter scan: 26 → 0 remaining, 148 files, no parse failures
  • cargo fmt --all -- --check and two idempotent cargo fmt --all runs
  • crate fmt --check — clean
  • full rust-standards audit: 54/54
  • cargo check --workspace --all-targets --all-features
  • cargo clippy --workspace --all-targets --all-features -- -D warnings
  • cargo test --workspace --all-features: 2877 passed, 0 failed, 286 ignored
  • WASM: strict clippy for euv-engine + euv-example, and a release check of
    the workspace (excluding euv-cli)
  • test-layout strictification, dependency order and CI-no-bump verifiers
  • cargo metadata: 8 workspace members, all at a single version 0.31.2

The three-backend browser run (189/189) was executed on the same 0.31.2 business
logic in the previous round and is not re-run here; the only upstream delta in
this branch is derive attribute ordering.

Versioning

Patch release 0.31.1 → 0.31.2. The root [workspace.package].version and
all 7 path-dependency entries in the root Cargo.toml carry 0.31.2, and
cargo metadata confirms all 8 members resolve to that single version.

Note for reviewers: this repo's publish and release jobs are gated on
push to master, so this PR runs check/tests/clippy/build only. No
publication happens from a pull request.

vshengbro added 2 commits October 18, 2026 13:45
Functions in the raytracing and lighting paths that had grown to five or more
ordinary parameters now take a struct instead, so call sites read as one
conceptual argument rather than a positional run of scalars.

The new RayTraceFrame collects the borrowed camera, lights and settings plus
the two copied dimensions, which brings pack_raytrace_frame and
render_raytrace_rgba down to three parameters each. BVH build and traversal,
shading and cleanup paths reuse the Ray, RayTraceSettings, LightingUniforms and
Camera3D types that already exist. push_vec4 was a thin extend_from_slice
wrapper and is removed; grow_texture and call4 fold into ensure_packed_texture
and draw_vertices.

The new PixelSample in pipeline/render/struct.rs holds the four scalars
pixel_direction needs per supersample, so that path keeps allocating nothing.

Triangle intersection keeps both entry points and their existing semantics: the
free function intersect_triangle(ray, vertices) deliberately does not filter by
the ray's t_min/t_max range, and Ray::intersect_triangle keeps the range clamp.

The 19 pre-existing renderer entry points and the WebGL/WebGPU backend APIs are
unchanged.

Adds 8 regression tests covering the frame struct's inputs, packing across a
non-square dimension pair, rejection without touching the buffer, output buffer
reuse across frame shapes, and three soft-shadow edge cases.
@ghfind-review ghfind-review Bot added the review: high ghfind author score; see https://ghfind.com label Oct 18, 2026
@vshengbro
vshengbro merged commit 13a5129 into master Oct 18, 2026
8 checks passed
@vshengbro
vshengbro deleted the refactor/raytrace-parameter-objects branch October 18, 2026 06:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review: high ghfind author score; see https://ghfind.com

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant