ComputeBVHSampler
new ComputeBVHSampler(sdfGenerator : ComputeSDFGenerator, renderer : THREE.WebGPURenderer, count : number, options : Object)GPU-accelerated point sampler for SDF volumes.
Architecture
- Uses a pre-computed SDF (Signed Distance Field) to efficiently test volume containment.
- Employs Blue Noise Sampling for temporally stable, low-discrepancy point distribution.
- Supports Rejection Sampling on the GPU to conform to complex shapes.
- Outputs transformation matrices directly compatible with
THREE.InstancedMesh.
Sampling Strategies
- Uniform: Distributes points uniformly within the volume.
- Surface: (Planned) Distributes points near the surface.
- Custom: (Planned) Uses a custom density function.
Usage
This class is typically used in conjunction with ComputeSDFGenerator.
Constructor Parameters
The SDF generator containing the volume data.
rendererTHREE.WebGPURendererWebGPU renderer instance.
countnumberTotal number of samples to generate.
optionsoptionalObjectConfiguration options.
strategyoptionalstringDistribution strategy:'uniform','surface', or'custom'.
Default is'uniform'.sdfThresholdoptionalnumberSDF value threshold. Points with distance < threshold are accepted.
- Negative values are inside the mesh.
- Positive values are outside (for shells).
Default is0.0.seedoptionalnumberRandom seed for stable sampling.
Default is1337.maxAttemptsoptionalnumberMaximum rejection sampling attempts per instance per frame.
Default is32.surfaceWeightoptionalnumberWeight for surface-weighted sampling (when strategy='surface').
Default is1.0.alignToNormaloptionalbooleanIf true, aligns the Y-axis of instances to the SDF gradient (surface normal).
Default isfalse.scaleoptionalTHREE.Vector3Scale factor applied to each generated instance.
Default isVector3(1,1,1).
See also
- {@link ComputeSDFGenerator}
Example
import { ComputeSDFGenerator, ComputeBVHSampler } from '@three-blocks/core';
import * as THREE from 'three/webgpu';
// 1. Generate SDF from geometry
const sdfGen = new ComputeSDFGenerator({ resolution: 64 });
await sdfGen.generate(geometry, bvh, renderer);
// 2. Sample points inside the volume
const sampler = new ComputeBVHSampler(sdfGen, renderer, 10000, {
strategy: 'uniform',
sdfThreshold: 0.0, // < 0 is inside
samplingBounds: sdfGen.geometryBounds, // Tight bounds for efficiency
maxAttempts: 32, // Retry limit for rejection sampling
alignToNormal: true // Align instances to SDF gradient
});
// 3. Run compute shader
await sampler.compute();
// 4. Use output with InstancedMesh
const instancedMesh = new THREE.InstancedMesh(geometry, material, 10000);
instancedMesh.instanceMatrix = sampler.output;Properties
# .sdfGenerator : ComputeSDFGenerator
# .renderer : THREE.WebGPURenderer
# .count : number
# .strategy : string
# .alignToNormal : boolean
# .samplingBounds : THREE.Box3|null
# .outMatrixSSBO : THREE.StorageInstancedBufferAttribute
# .outPositionsSSBO : THREE.StorageInstancedBufferAttribute
# .output :
Gets the output transformation matrices.
# .positionsBuffer :
Gets the output positions buffer (vec3 per sample). Useful for particle systems like SPH that only need positions.
Methods
compute#
compute(options : Object) : Promise<void>Computes the volume sampling.
Parameters
optionsoptionalObjectCompute options
sdfThresholdoptionalnumberOverride SDF thresholddebugoptionalbooleanEnable debug logging
Default isfalse.
Returns
Promise<void>updateSDF#
updateSDF(sdfGenerator : ComputeSDFGenerator)Updates the SDF generator reference (useful when SDF is regenerated).
Parameters
New SDF generator
readback#
readback() : Promise<Float32Array>Performs CPU readback of transformation matrices.
Returns
Promise<Float32Array>calculateValidRate#
calculateValidRate(positions : Float32Array) : numberCalculates the valid sample rate (non-zero positions). Accounts for potential vec4 padding in GPU buffers.
Parameters
positionsFloat32ArrayPositions array from readbackPositions()
Returns
number — Valid sample percentage (0-100)dispose#
dispose()Disposes GPU resources.