API reference

The public exports of @pmndrs/raytracer, grouped by area.

Every name below is exported from @pmndrs/raytracer. WGSL functions are listed on the page that covers them. The source is in packages/raytracer/src; each export has a doc comment there.

Items marked experimental work and are checked, but their API can still change.

Device and capabilities

See Capabilities.

NameKindWhat it does
detectCapsfunctionReads an adapter's features and limits into a Caps.
requestDeviceForCapsfunctionRequests a device with every useful feature and raised limits; returns { device, caps }.
buildCapsfunctionCaps from any adapter-like or device-like object (for example one with no features).
featuresToRequest, limitsToRequestfunctionWhat requestDeviceForCaps would request.
DEFAULT_LIMIT_CAPSconstantCeilings on requested limits.
capsHashfunctionStable hash of everything that changes generated code: a pipeline cache key.
deriveTierfunctionThe tier label of a set of caps. Report it, never branch on it.
Caps, RequestDeviceOptions, DeviceForCaps, Tiertype

Scene building

The input types are described in Scenes, Materials and Lights.

NameKindWhat it does
buildGpuScenefunctionBuilds the BVH and the scene copy from a SceneCopyInput and uploads both. Returns a GpuScene.
GpuScenetypetrace, buffers, copy, format, packing, destroy().
buildSceneCopyfunctionThe CPU half: material, light and surface tables, textures.
uploadSceneCopyfunctionUploads a SceneCopy to storage buffers and texture arrays.
writeSceneCopyfunctionRewrites a rebuilt copy into existing buffers when it fits.
createMaterial, defaultMaterialfunctionA full RtMaterial from a partial one; the OpenPBR defaults.
makeSun, makeEnvironmentfunctionLight records from SunInput and EnvironmentInput.
buildTriangleLightsfunctionThe emissive-triangle lights of meshes and instances.
lightSelectionWeights, parseLightSelectionfunctionLight-selection strategies ('pbrt', 'power', 'kind', capped).
buildAliasTable, sampleAliasfunctionVose alias table and its sampler (CPU).
buildEnvMapTable, envMapMeanfunctionSampling tables and mean radiance of an equirect environment map.
SceneCopyInput, SceneCopyMesh, SceneCopyInstance, SceneCopyOptions, RtMaterialInput, SunInput, EnvironmentInput, TextureInput, TextureOptionstypeInputs.
SceneCopy, SceneCopyBuffers, RtMaterial, RtLighttypeOutputs.

Scene copy in WGSL

See Scene copy.

NameKindWhat it does
rtSceneCopyLayoutEntriesfunctionBind group layout entries of the scene copy (buffers, then texture arrays and samplers).
rtSceneCopyBindGroupEntriesfunctionThe matching bind group entries for uploaded buffers.
rtPackSceneAccessfunctionRewrites WGSL written against the split buffers to read the packed one.
rtLightSampleWgslfunctionWGSL of light point sampling (rtSampleLightLi); envMap: true adds map importance sampling.
rtSceneWgslfunctionThe scene-copy WGSL on its own (what rtModuleWgsl adds with scene).
rtMipGeneratorfunctionThe default per-device @pmndrs/downsampler mip generator.
sceneCopyBindingLimitfunctionThe device's storage binding size cap.
DEFAULT_SCENE_PACKINGconstant'packed'.
RtMipGenerator, SceneCopyPacking, TextureLayouttype
rtSetResourceTable, rtUsesResourceTablefunctionExperimental. Bindless textures: bind a resource table; whether a texture layout needs one.

CPU twins, for tests and tools: readMaterial, unpackMaterial, readLight, readLightIndexOfHit, readLightPmfOfHit, readSurfaceFromTable, sampleSceneTexture, textureLod, coneUvFootprint, applyNormalMap, sampleLightLi, lightPdfLi, envMapLookup, envMapPdf, sampleEnvMap.

Tracing in WGSL

See Inline WGSL.

NameKindWhat it does
rtModuleWgslfunctionThe inline module: walk, rtVisible, rtClosest, and optionally rtSurface, the scene copy, rtShade, intervals.
RtModuleOptionstypeIts options.
sceneFormatOffunctionThe formats of bvh trace buffers, to spread into module and tracer options.
rtWalkEntriesfunctionLayout entries (without binding numbers) of the walk's buffers.
withBindingsfunctionNumbers module entries from a first binding.
rtSceneBindGroupEntriesfunctionBind group entries of the walk for bvh trace buffers.
rtModuleStorageBuffersfunctionStorage buffers a module adds to a kernel.
RT_MASK_ALL, RT_NO_MATERIALconstantAll ray-mask bits; the material id of a hit with none.
SURFACEconstantThe RT_SURF_* bit values.
rtIsWideNodeFormatfunctionExperimental. True for the wide formats bvh4 and cwbvh8.

Batch and interval tracers

See Batch tracer and Interval queries.

NameKindWhat it does
RtBatchTracerclassTraces a GPU ray buffer into hit records or visibility words.
RtBatchTracerOptions, RtBatch, RtIndirectCounttypeIts options, a batch, a GPU-side count.
packRays, packRaysSoa, aosToSoa, unpackRay, packConesfunctionRay and cone buffers from CPU data.
readHits, readVisibilityfunctionDecode read-back results.
resultBytes, dispatchGridfunctionBytes per result; the workgroup grid for a ray count.
rtBatchKernelWgsl, rtBatchArgsKernelWgsl, rtBatchEntries, resolveBatchOptionsfunctionThe batch kernel's parts, for your own pipeline.
Ray, Hit, RayConetypeThe CPU forms of rays, hits and cones.
RAY_BYTES, HIT_BYTES, HIT_COMPACT_BYTES, RAY_CONE_BYTES, HIT_WORD, MISS_TconstantRecord sizes, hit word offsets, the miss distance.
RtIntervalTracerclassExperimental. Batched interval queries from rays or probe bundles.
RtIntervalJob, IntervalKernelOptionstypeExperimental. A job; the tracer's options.
intervalResultBytes, intervalRayCountfunctionExperimental. Result stride; rays per job.
intervalBounds, inInterval, cascadeEnd, cascadeStart, cascadeIndexfunctionExperimental. CPU twins of the interval and cascade arithmetic.
octEqualAreaDecode, bundleDirectionfunctionExperimental. Equal-area square-to-sphere map; a probe cell's direction.
nextUpF32, nextDownF32, RT_T_INFfunction, constantExperimental. f32 stepping; the largest finite f32.

glTF

See Loading glTF.

NameKindWhat it does
loadGltffunctionReads a .glb or .gltf (URL or bytes) into a SceneCopyInput with cameras, sun and notes.
LoadGltfOptions, GltfSceneInputtypeIts options and result.
decodeImageWithCanvasfunctionThe default image decoder (browsers and workers).
gltfSceneFromJson, gltfSceneToInputfunctionThe two steps of loadGltf, for files you have already parsed.
parseGlb, isGlbfunctionGLB container parsing.
gltfMaterialToOpenPbr, openPbrToRtMaterialfunctionglTF material to OpenPBR parameters to a scene-copy material.
resolveOpenPbr, OPENPBR_DEFAULTSfunction, constantOpenPBR parameter defaults.

Shading

See Shading.

NameKindWhat it does
RtShadeOptionstypeOptions of the shade module option.
RT_SHADE_MODEconstant{ flat, lambert, full } values of the WGSL RT_SHADE_* constants.
rtShadeWgslfunctionThe shading WGSL on its own (what rtModuleWgsl adds with shade).
shadefunctionCPU twin of rtShade (f64).
makeShadePoint, builtinBsdf, shadeMiss, shadeTotal, shadeDiffuseFromIrradiancefunctionParts of the twin.

Noise and sampling

NameKindWhat it does
rtOwenSobolWgslfunctionWGSL of an Owen-scrambled Sobol sampler: rtOwenSobol2D(index, seed), rtHash32, rtUnit24, ...
owenSobol2D, hash32, nestedUniformScramble, shuffleIndexfunctionIts CPU twins, bit-identical to the GPU.
loadBlueNoisefunctionDecode a blue-noise texture shipped in the package (gf-vec2-64 default, gf-vec2-128).
fetchBlueNoise, decodeBlueNoisePng, parseBlueNoisefunctionLoad other blue-noise textures from a served folder (16-bit PNG or raw float32).
blueNoiseAtfunctionA texel with toroidal wrap.
BlueNoiseTexture, BlueNoiseMetatype

WGSL tooling

NameKindWhat it does
rtCreateComputePipelineAsyncfunctionCreates a pipeline; on failure throws the compiler messages mapped to source lines and names.
rtTransformWgslfunctionPrune, shorten and minify in one call, with a source map.
rtPruneWgsl, rtShortenWgsl, rtMinifyWgsl, stripWgslCommentsfunctionThe individual size transforms.
rtMapCompilationInfo, rtMapCompilationMessagefunctionTranslate compiler messages through a source map.
rtCheckShaderModulefunctionReads a module's compilation info and throws translated errors.
rtFormatCompilationMessages, rtFormatSourceContextfunctionHuman-readable messages with source context.
rtComposeSourceMaps, rtWgslIdentityMap, rtWgslSourceMapV3functionBuild and combine source maps; export one as Source Map v3.
RtWgslSourceMap, RtWgslBuildtype
buildWgsl, preprocessfunctionThe #if preprocessor, with or without the enable lines.
wgslEnableLines, capsDefinesfunctionThe enable lines and preprocessor defines for a set of caps.

Conventions

NameKindWhat it does
WORLD, NDC, VIEW_Z_SIGN, MOTION, JITTER, IMAGE, NORMAL_SPACEconstantThe shared conventions in code. See Conventions.
roughnessToAlphafunctionPerceptual roughness to GGX alpha (roughness^2).
FrameCamera, AOVtype, constantCamera and render-output names shared with real-time consumers.