react-three-gpu-pathtracer

When using camera controls (like OrbitControls from @react-three/drei) with path tracing, ensure you use the makeDefault prop to ensure the controls are correctly integrated with the scene.

<OrbitControls makeDefault />

To enable path tracing in a react-three-fiber scene, wrap your scene content with the <Pathtracer /> component. This component intercepts the scene and renders it using the path tracing algorithm instead of standard rasterization.

import { Pathtracer } from "@react-three/gpu-pathtracer";

function GradientSphere() {
  return (
    <Canvas>
      <Pathtracer>{/* Your scene */}</Pathtracer>
    </Canvas>
  );
}

You can add environment maps to your path-traced scene using the <Environment /> component from @react-three/drei. Place the <Environment /> component inside the <Pathtracer /> wrapper.

<Pathtracer>
  <Environment
    preset="..."
    background // Optional, set as scene background
    backgroundBlurriness={0.5}
    backgroundIntensity={1}
  />
</Pathtracer>

The <Pathtracer /> component accepts several props to control the quality, performance, and lifecycle of the path tracing process:

The usePathtracer hook provides access to the internal renderer and lifecycle controls. Note: This hook must be used within a component that is a child of the <Pathtracer /> component.

const { pathtracer, update, reset } = usePathtracer();

The FullScreenQuad class is a helper designed for post-processing passes that need to fill the entire viewport with a single quad (a plane covering the screen). It manages an OrthographicCamera and a PlaneGeometry internally.

Usage:

• Initialize it with a Material (e.g., a shader material).
• Use the .render(renderer) method to draw the quad using the provided WebGL renderer.
• Access or update the material via the .material property.
• Call .dispose() to clean up the underlying geometry and prevent memory leaks.

import { FullScreenQuad } from "@react-three/gpu-pathtracer";
import { ShaderMaterial } from "three";

const material = new ShaderMaterial({ /* ... */ });
const quad = new FullScreenQuad(material);

// In your render loop:
quad.render(renderer);

// Cleanup:
quad.dispose();

The FogVolumeMaterial component allows you to render volumetric fog within a scene using the GPU pathtracer. It is a React wrapper around the FogVolumeMaterial implementation from three-gpu-pathtracer.

To use it, ensure you have a Pathtracer context provider active in your component tree, as the material automatically calls pathtracer.updateMaterials() whenever it mounts to ensure the GPU state is synchronized.

import { FogVolumeMaterial } from '@react-three/gpu-pathtracer';

// Inside your Canvas/Pathtracer context
<fogVolumeMaterial 
  args={[{ color: 'white', density: 0.1 }]} 
  // ... other FogVolumeMaterialImpl props
/>

The ShapedAreaLight component allows you to create area lights with custom shapes for use with the GPU Pathtracer. It is a wrapper around the three-gpu-pathtracer implementation that automatically triggers a pathtracer.updateLights() call whenever the component is mounted, ensuring the light is registered with the pathtracer instance.

To use it, ensure you have a Pathtracer context provider in your scene tree, as the component relies on the usePathtracer hook to access the pathtracer instance.

<Pathtracer>
  <ShapedAreaLight 
    args={["path/to/geometry/or/shape"]}
    /* other ShapedAreaLightImpl props */ 
  />
</Pathtracer>

The PhysicalCamera component provides a Three.js PhysicalCamera implementation integrated with @react-three/fiber and the GPU Pathtracer. It automatically handles aspect ratio calculations (unless manual mode is enabled), updates the projection matrix, and sets itself as the active camera in the R3F state. Crucially, it automatically triggers pathtracer.updateCamera() whenever the camera changes, ensuring the path tracer stays in sync with the camera's properties.

To use it, simply include the <physicalCamera /> element within your R3F scene. It accepts all standard PhysicalCamera properties from three-gpu-pathtracer.

<PhysicalCamera 
  fov={50} 
  near={0.1} 
  far={1000} 
  // manual={true} // Set to true if you want to manage aspect ratio yourself
/>

The Pathtracer component supports a ref that exposes the underlying WebGLPathTracer instance. This allows you to access the low-level engine directly for advanced configurations or manual control.

const pathtracerRef = useRef<WebGLPathTracer>(null);

<Pathtracer ref={pathtracerRef} />

// Later in code:
// pathtracerRef.current.someMethod();