@react-three/offscreen

react-three-offscreen

npm install three @react-three/fiber @react-three/offscreen

This is an experimental package that allows you to render your react-three-fiber scene with an offscreen canvas in a web worker. This is mostly useful for self-contained webgl apps, and un-blocking the main thread.

The package will forward DOM events to the worker so you can expect mostly everything to run fine. It will even shim a basic document/window interface so that camera controls and various threejs classes that must interact with the DOM have something to work with.

For better interop all non-passive events (click, contextmenu, dlbclick) will preventDefault, pointerdown will capture, pointerup will release capture.

Usage

Instead of importing <Canvas> from @react-three/fiber you can import it from @react-three/offscreen and pass a worker prop. The fallback prop is optional, your scene will be rendered on the main thread, in a regular canvas, where OffscreenCanvas is not supported (Safari).

It takes all other props that <Canvas> takes (dpr, shadows, etc), you can use it as a drop-in replacement.

// App.js (main thread)
import { Canvas } from '@react-three/offscreen'

// This is the fallback component that will be rendered on the main thread
// This will happen on systems where OffscreenCanvas is not supported
const Scene = React.lazy(() => import('./Scene'))
// This is the worker thread that will render the scene
const worker = new Worker(new URL('./worker.js', import.meta.url))

export default function App() {
  return <Canvas shadows camera={{ position: [0, 5, 10], fov: 25 }} worker={worker} fallback={<Scene />} />
}

Your worker thread will be responsible for rendering the scene. The render function takes a single argument, a ReactNode.

// worker.js (worker thread)
import { render } from '@react-three/offscreen'

render(<Scene />)

Your app or scene should be self contained, meaning it shouldn't interact with the DOM. This is because offscreen canvas + webgl is still not supported in Safari. If you must communicate with the DOM, you can use the web broadcast API.

// Scene.js (a self contained webgl app)
import React, { useRef, useState } from 'react'
import { useFrame } from '@react-three/fiber'
import { ContactShadows, Environment, CameraControls } from '@react-three/drei'

function Cube(props) {
  const mesh = useRef()
  const [hovered, setHover] = useState(false)
  const [active, setActive] = useState(false)
  useFrame((state, delta) => {
    mesh.current.rotation.x += delta
    mesh.current.rotation.y += delta
  })
  return (
    <>
      <mesh
        {...props}
        ref={mesh}
        scale={active ? 1.25 : 1}
        onClick={(e) => (e.stopPropagation(), setActive(!active))}
        onPointerOver={(e) => (e.stopPropagation(), setHover(true))}
        onPointerOut={(e) => setHover(false)}
      >
        <boxGeometry args={[1, 1, 1]} />
        <meshStandardMaterial color={hovered ? 'hotpink' : 'orange'} />
      </mesh>
      <ContactShadows color={hovered ? 'hotpink' : 'orange'} position={[0, -1.5, 0]} blur={3} opacity={0.75} />
    </>
  )
}

export default function App() {
  return (
    <>
      <ambientLight />
      <pointLight position={[10, 10, 10]} />
      <Cube />
      <Environment preset="city" />
      <CameraControls />
    </>
  )
}

How to contribute

If you like this project, please consider helping out. All contributions are welcome as well as donations to Opencollective, or in crypto BTC: 36fuguTPxGCNnYZSRdgdh6Ea94brCAjMbH, ETH: 0x6E3f79Ea1d0dcedeb33D3fC6c34d2B1f156F2682.

Backers

Thank you to all our backers! 🙏

Contributors

This project exists thanks to all the people who contribute.