GPU field visualization — engine19

Show scalar and vector data on the GPU. These tools display existing regular-grid
buffers; they do not simulate a plasma, smoke, temperature or Maxwell equations.
getGPUCapabilities must report gpuVolumeFields/gpuVectorFields/gpuFieldProbes.

Data layout
createGPUProgram("field", [{name:"density",count:nx*ny*nz,components:1,
 nx:nx,ny:ny,nz:nz,spacing:{x:dx,y:dy,z:dz},spatialOffset:{x:x0,y:y0,z:z0},values:data}])
Scalar index=x+nx*(y+ny*z). Vectors use components:3 with contiguous xyz per node.
Node coordinates=spatialOffset+index*spacing. Bounds run from the first node to
last node (dimensions-1). All dimensions2..128, exact grid count<=1048576.
Trilinear sampling is shared by rendering, streamlines and point probes.
Values are f32; keep units in the buffer metadata. Runtime WGSL may update them.

Show a density volume
showGPUVolume("field","density",{min:0,max:1,density:1,samples:64})
Front-to-back Beer-Lambert absorption/emission, with opaque-scene depth clipping.
This is not multiple scattering, physical smoke lighting, or a fluid solver.
Transfer alpha is extinction per world unit before the density multiplier.
Changing samples controls integration quality; it should not scale opacity.
Unsorted overlapping transparent objects/volumes remain approximate.

Give the same field a movable slice
showGPUFieldSlice("field","density",{min:0,max:1,slicePoint:{x:0,y:0,z:0},sliceNormal:{x:1,y:0,z:1}})
One field view per program. Switching modes preserves the underlying field.
styleGPUField("field",{slicePoint:{x:0,y:0,z:1}})
clipGPUField("field",{x:0,y:0,z:0},{x:1,y:0,z:0})

Select colors and build a legend from the exact mapping
styleGPUField("field",{min:0,max:10,stops:[
 {at:0,color:{r:0,g:0,b:.2,a:0}},
 {at:.5,color:{r:0,g:.8,b:1,a:.3}},
 {at:1,color:{r:1,g:.8,b:.1,a:1}}]})
At values are normalized0..1; map to min+at*(max-min). Use getGPUFieldState
fieldView.settings to draw the same legend, with the fieldView.units label.
Slice/arrow/line alpha uses stop alpha*density, clamped0..1.
RGB0..16 allows HDR emission; alpha0..1. At least2 and at most8 ordered stops.

Draw a vector field or its integral curves
showGPUVectorField("field","electric",{min:0,max:5,stride:4,glyphLength:.6,glyphWidth:.08})
showGPUStreamlines("field","electric",[{x:0,y:1,z:0}],{steps:128,stepLength:.05,lineWidth:.025,min:0,max:5})
Vector buffers require components3. Arrows scale with mapped magnitude and point
along the vector. Streamlines use normalized-vector RK2 with fixed spatial steps,
stop on invalid/zero fields or exit, and update with the field each frame. They
have no time meaning and are not particles following a time-varying trajectory.
Direction may be1 or-1. Seed inside bounds. Choose small enough spatial steps for
curvature, compare step sizes for convergence; fixed-step RK2 is not adaptive.
Limits:32768 arrows,256 seeds,256 steps,65536 segments. Changing allocated steps
requires showGPUStreamlines again. This batch does not add time-history trails.

Sample and inspect
var sample=await probeGPUField("field",{x:0,y:0,z:0})
if(sample.hit) console.log(sample.values,sample.sum)
Asynchronous16-byte GPU readback; <=4 pending. Outside/nonfinite neighbors give
hit=false and no values. Probes read the current queued field, not a full snapshot.
getGPUFieldState("field") returns bounds, grid, configured counts, field/visual bytes
and display settings. Counts are not actual GPU timings. Keep probes sparse.
Display counts/quality in a compact UI. Include pause/reset for the underlying
solver when it runs; changing display settings does not pause or change physics.

Lifecycle
hideGPUField("field")
styleGPUField("field",{visible:true})
removeGPUProgram("field")
Program removal/clearRun release field visuals. At most4 programs and128MiB typed
program budget remain. MainCamera is reused; depth texture enabled for occlusion.

Separate demos: GPU Fields01 Density Volume,02 Oblique Slice,03 Vector Field,
04 Streamlines. Their fields are analytical visualization test data; do not call
them full scientific solvers. See roadmap-batch8/RESULTS.txt for acceptance status.