Skip to content

fix(volume): VolumeRaycaster hardening pass — release 0.5.2 - #2

Merged
physwkim merged 15 commits into
mainfrom
fix/volume-hardening
Jul 8, 2026
Merged

physwkim merged 15 commits into
mainfrom
fix/volume-hardening

Conversation

@physwkim

@physwkim physwkim commented Jul 7, 2026

Copy link
Copy Markdown
Owner

Summary

Post-release correctness/robustness pass over the VolumeRaycaster shipped in
0.5.1 (9 commits), plus the 0.5.2 version bump. rsplot only.

Fixed

  • Dark fringe around opaque regions — premultiply the volume on upload and
    composite in premultiplied space (straight-alpha bled rgb=0 at boundaries).
  • Opacity independent of set_steps — Beer-Lambert–correct per-sample
    coverage to a 256-step baseline.
  • set_steps clamped to [1, 4096] — a huge value could trip the GPU
    timeout watchdog and reset the device.
  • Volume validation — reject zero extents / mismatched RGBA length up front
    instead of a wgpu panic in the backend.
  • Ctrl/Cmd-pan anchored at box-centre depth so the volume tracks the pointer.
  • Per-callback camera — same VolumeId in two panels no longer shares one
    uniform buffer.

Changed

  • VolumeRaycaster::remove / remove_volume_raycaster(id) to free VRAM.
  • Dropped the unused cam_pos uniform.

Test plan

  • cargo fmt --all --check, cargo clippy --workspace --all-targets -D warnings — clean
  • cargo test --workspace --all-targets — pass (incl. new premultiply_* unit tests + volume render tests)
  • 3-OS CI (Linux/macOS/Windows) runs on this PR.

physwkim added 15 commits July 7, 2026 18:22
The 3D texture stored straight-alpha RGBA and the linear sampler
interpolated colour and alpha independently, so at a colour/transparent
boundary a transparent voxel's rgb=0 bled into the neighbouring colour
and darkened it — a black fringe around every opaque region.

Premultiply on upload (rgb *= a/255) so a transparent voxel is (0,0,0,0)
and the filter interpolates premultiplied colour, which keeps the hue.
The shader now composites in premultiplied space: it scales coverage by
the opacity knob and rescales the premultiplied colour to match
(gain = sa/s.a) rather than re-multiplying straight rgb by alpha.
premultiply_rgba is unit-tested; the render tests stay green.
Per-sample coverage was composited as-is, so raising `set_steps` sampled
each voxel more often and made the whole volume more opaque — the step
knob doubled as a brightness knob. Correct each sample's coverage by
REF_STEPS/steps (Beer-Lambert) so transmittance (1-sa)^steps is held to a
256-step baseline. Opacity now depends only on the data and alpha_scale,
not the sample count. The baseline equals the widget's default steps, so
the default view is unchanged.
Shared resources kept one VolumeGpu (3D texture + bind group + uniform
buffer) per id forever — a view that came and went, or a caller cycling
ids, leaked that VRAM for the app's lifetime with no way to release it.
Add remove_volume_raycaster(id) and VolumeRaycaster::remove to drop the
entry and its GPU handles; both are no-ops if nothing was uploaded.
PanDrag began on the far plane (ndc_z = 1.0), so a Ctrl/Cmd-drag pan
moved the volume faster than the cursor — the pan plane sat far behind
the geometry. Anchor the pan at the box-centre depth, the same NDC-z the
wheel zoom already uses, so the volume tracks the pointer one-to-one.
set_volume_raycaster fed its arguments straight to wgpu, so a zero extent
or an rgba slice that did not match depth*height*width*4 surfaced as a
wgpu validation error (a hard panic deep in the render backend). Check
the texture invariants up front: an invalid call is a no-op that keeps
any prior upload, and a debug_assert flags the caller bug in dev builds.
set_steps only enforced a floor of 1, so a large value marched every ray
that many times in one frame and could outrun the OS GPU-timeout
watchdog, resetting the device. Clamp to [1, 4096]; the default 256 and
any reasonable quality setting are unaffected.
The shader builds each ray by un-projecting near/far NDC through inv_mvp,
so cam_pos was written to the uniform buffer every frame and never read.
Remove it from the WGSL and Rust uniform structs, VolumeFrame, and the
widget that filled it — shrinking the uniform buffer and dropping a dead
per-frame camera-position computation.
The per-id uniform buffer is shared between prepare and paint, so two
callbacks with the same id in one frame both read the last-prepared
camera. A full fix needs per-callback GPU buffers (disproportionate — the
widget already binds one id per instance and never triggers this).
Document the invariant on paint_volume_raycaster and VolumeRaycaster::new
so callers assigning ids by hand keep them distinct.
…amera

F13 root-cause fix (was documented-only). VolumeGpu held one uniform
buffer + bind group per VolumeId, written in prepare and read in paint.
egui_wgpu runs prepare for ALL callbacks, then paint for ALL, so two
callbacks sharing a VolumeId in one frame both wrote that single buffer
and both painted whichever prepared last — same volume in two panels
would render both from one camera.

Move the dynamic state out of the shared per-id slot: VolumeGpu now
holds only the 3D texture + world box; each VolumeCallback builds its
own uniform buffer + bind group in prepare (VolumeGpu::frame_bind_group)
and stashes it in a Mutex, which paint reads. The Mutex only satisfies
CallbackTrait: Send + Sync — prepare/paint run in sequence on the render
thread. The bind group holds strong refs to the fresh uniform buffer and
texture view, so both live for the frame; the guard is held through the
draw. Illegal state (two views, one camera) is now unrepresentable by
construction, not avoided by a "paint each id once per frame" invariant.

Drops the now-moot invariant docs on paint_volume_raycaster and the
widget's new(). GPU render tests + 1619 lib tests pass; clippy clean.
Bump rsplot, rsdm, adl2rsdm to 0.5.2 in lockstep and cut the CHANGELOG [0.5.2]
section: a post-release correctness/robustness pass over VolumeRaycaster
(premultiplied-alpha dark-fringe fix, step-independent opacity, step clamp,
input validation, pointer-tracking pan, per-callback camera, remove API,
dropped cam_pos uniform). rsplot only; rsdm/adl2rsdm lockstep no-op.
calc_update_list_restricts_which_child_triggers_recompute intermittently
timed out on the macOS CI runner (3 of 5 runs): the calc:// pipeline
(child connect -> value poll -> expr eval -> republish) occasionally took
longer than the 2 s wait_for deadline under load. wait_for returns as soon as
the condition holds, so a larger deadline only bounds the failure path and
never slows a passing run. Centralize the file's deadline into one WAIT
constant (30 s) instead of scattered 2 s literals. The negative-assertion
settle sleep is unchanged.
…can't leak a duplicate sample

`on_connect` posted the connect-time value unconditionally. It can run
more than once per connection (a native-type-change / reconnect event
re-enters it, and it races the value monitor), so the second post
re-emitted a value already delivered on this connection. When a value
subscriber (`subscribe_values`, used by the strip chart / event plot) was
created between the two posts, the duplicate leaked to it as a spurious
sample.

Invariant: a value event is emitted only when the decoded value differs
from `last_value`, at every value-arrival site. The monitor branch
already enforced it; `on_connect` was the one unconditional emitter.
Gate its post on the same `last_value` check — emit on an actual change,
else refresh the CTRL metadata via `update` with no sample. Reconnect
still re-emits because the Disconnected arm clears `last_value` (PyDM
clear_cache parity).

Reproduced ca_ioc::ca_property_event_refreshes_metadata_live at 3/100
(unfixed, under CPU load) with an instrumented trace showing a second
on_connect post delivered to the live subscription; 0/350 after the fix.

pva_plugin does not share the family: its initial value arrives exactly
once via the first monitor Data event (marked=None), with no separate
connect-time value post.
…ren connect

The poll loop advanced `prev_stamps[i]` for every changed child stamp
unconditionally, then gated the recompute on `all_connected && trigger`
in the same tick. A child's initial value routinely lands a tick or more
before the last child connects, so that change was folded into
`prev_stamps` while `!all_connected` and its trigger was dropped. If the
child that finally completes the connection is not itself a triggering
variable (an `update` list that excludes it), the first all-connected
tick saw no change and never ran the initial evaluation: the calc stayed
connected but valueless until the next child write.

This is child-connect-order dependent, so it flaked on CI: with
`update=a`, whether the initial value published depended on whether `a`
connected before or after `b`.

Fix: fold stamp changes into `prev_stamps` only while `all_connected`.
`prev_stamps` stays at `u64::MAX` until the first all-connected tick,
which therefore always observes every child as changed and runs the
initial evaluation — with no dependence on the child-connect vs poll-tick
interleaving. This also makes the default-update case's initial eval hold
by construction, not by the last-connecting child happening to be a
trigger.

Adds calc_publishes_initial_value_when_update_var_connects_before_others:
connects the update variable first, lets the poll loop observe it while
the other child is still disconnected, then connects the other
(non-update) child. Times out on the pre-fix code (30 s), passes after.
The 0.5.2 section covered only the VolumeRaycaster hardening; the two
rsdm data-engine race fixes (ca:// duplicate initial sample, calc://
lost initial evaluation) landed on the release branch after it. Add them
under a Fixed — rsdm subsection and correct the release date to 2026-07-08.
…ARP crash

The two tests each create and tear down their own wgpu device; `cargo
test` runs them on parallel threads, so on the Windows CI runner's DX12
software adapter (WARP) the concurrent device create/destroy faulted with
STATUS_ACCESS_VIOLATION (0xc0000005) — a native crash in the adapter, not
in rsplot, and intermittent (the same code passed the full matrix on the
prior run). Serialize them through a process-wide lock so exactly one
device is alive at a time; poison is recovered so a failed assertion in
one test cannot wedge the other.

This removes the concurrency that triggers the crash; the underlying
WARP-adapter fault under concurrent device lifecycle is environmental and
outside rsplot.
@physwkim
physwkim merged commit ceca5de into main Jul 8, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant