drei Documentation

npm install @react-three/drei

import { PerspectiveCamera, PositionalAudio, ... } from '@react-three/drei'

import { PerspectiveCamera, PositionalAudio, ... } from '@react-three/drei/native'

type DragControlsProps = {
  /** If autoTransform is true, automatically apply the local transform on drag, true */
  autoTransform?: boolean
  /** The matrix to control */
  matrix?: THREE.Matrix4
  /** Lock the drag to a specific axis */
  axisLock?: 'x' | 'y' | 'z'
  /** Limits */
  dragLimits?: [[number, number] | undefined, [number, number] | undefined, [number, number] | undefined]
  /** Hover event */
  onHover?: (hovering: boolean) => void
  /** Drag start event */
  onDragStart?: (origin: THREE.Vector3) => void
  /** Drag event */
  onDrag?: (
    localMatrix: THREE.Matrix4,
    deltaLocalMatrix: THREE.Matrix4,
    worldMatrix: THREE.Matrix4,
    deltaWorldMatrix: THREE.Matrix4
  ) => void
  /** Drag end event */
  onDragEnd?: () => void
  children: React.ReactNode
}

<DragControls>
  <mesh />
</DragControls>

const matrix = new THREE.Matrix4()
return (
  <DragControls
    ref={ref}
    matrix={matrix}
    autoTransform={false}
    onDrag={(localMatrix) => matrix.copy(localMatrix)}

<GizmoHelper
  alignment="bottom-right" // widget alignment within scene
  margin={[80, 80]} // widget margins (X, Y)
  onUpdate={/* called during camera animation  */}
  onTarget={/* return current camera target (e.g. from orbit controls) to center animation */}
  renderPriority={/* use renderPriority to prevent the helper from disappearing if there is another useFrame(..., 1)*/}
>
  <GizmoViewport axisColors={['red', 'green', 'blue']} labelColor="black" />
  {/* alternative: <GizmoViewcube /> */}
</GizmoHelper>

export type GridMaterialType = {
  /** Cell size, default: 0.5 */
  cellSize?: number
  /** Cell thickness, default: 0.5 */
  cellThickness?: number
  /** Cell color, default: black */
  cellColor?: THREE.ColorRepresentation
  /** Section size, default: 1 */
  sectionSize?: number
  /** Section thickness, default: 1 */
  sectionThickness?: number
  /** Section color, default: #2080ff */
  sectionColor?: THREE.ColorRepresentation
  /** Follow camera, default: false */
  followCamera?: boolean
  /** Display the grid infinitely, default: false */
  infiniteGrid?: boolean
  /** Fade distance, default: 100 */
  fadeDistance?: number
  /** Fade strength, default: 1 */
  fadeStrength?: number
  /** Fade from camera (1) or origin (0), or somewhere in between, default: camera */
  fadeFrom?: number
}

export type GridProps = GridMaterialType & {
  /** Default plane-geometry arguments */
  args?: ConstructorParameters<typeof THREE.PlaneGeometry>
}

<Grid />

const mesh = useRef()
useHelper(mesh, BoxHelper, 'cyan')
useHelper(condition && mesh, BoxHelper, 'red') // you can pass false instead of the object ref to hide the helper

<mesh ref={mesh} ... />

<mesh>
  <boxGeometry />
  <meshBasicMaterial />

  <Helper type={BoxHelper} args={['royalblue']} />
  <Helper type={VertexNormalsHelper} args={[1, 0xff0000]} />
</mesh>

/* Detailed source-code truncated for AI context efficiency. */

<PivotControls>
  <mesh />
</PivotControls>

const matrix = new THREE.Matrix4()
return (
  <PivotControls
    ref={ref}
    matrix={matrix}
    autoTransform={false}
    onDrag={({ matrix: matrix_ }) => matrix.copy(matrix_)}

<TransformControls mode="translate">
  <mesh />
</TransformControls>

<TransformControls object={mesh} mode="translate" />
<mesh ref={mesh} />

<TransformControls mode="translate" />
<OrbitControls makeDefault />

const envMap = useCubeTexture(['px.png', 'nx.png', 'py.png', 'ny.png', 'pz.png', 'nz.png'], { path: 'cube/' })

useFBX(url)

function SuzanneFBX() {
  let fbx = useFBX('suzanne/suzanne.fbx')
  return <primitive object={fbx} />
}

useGLTF<T extends string | string[]>(
  path: T,
  useDraco?: boolean | string = true,
  useMeshOpt: boolean = true,
  extendLoader?: (loader: GLTFLoader) => void
): T extends any[] ? (GLTF & ObjectMap)[] : GLTF & ObjectMap

const gltf = useGLTF(url)

useGLTF.preload(url)

useGLTF(url, '/draco-gltf')

useGLTF.setDecoderPath(path)

import { KTX2Loader } from 'three-stdlib'
const ktx2Loader = new KTX2Loader()
ktx2Loader.setTranscoderPath('https://unpkg.com/[email protected]/examples/jsm/libs/basis/')

// ...

const { gl } = useThree()
useGLTF('facecap.glb', true, true, (loader) => {
  loader.setKTX2Loader(ktx2Loader.detectSupport(gl))
})

<Gltf src={url} />
<Gltf src={url} useDraco='/draco-gltf' ... />

const texture = useKTX2(url)
const [texture1, texture2] = useKTX2([texture1, texture2])

return <meshStandardMaterial map={texture} />

<Canvas>
  <Suspense fallback={null}>
    <AsyncModels />
  </Suspense>
</Canvas>
<Loader />

<Loader
  containerStyles={...container} // Flex layout styles
  innerStyles={...inner} // Inner container styles
  barStyles={...bar} // Loading-bar styles
  dataStyles={...data} // Text styles
  dataInterpolation={(p) => `Loading ${p.toFixed(2)}%`} // Text
  initialState={(active) => active} // Initial black out state
>

function Loader() {
  const { active, progress, errors, item, loaded, total } = useProgress()
  return <Html center>{progress} % loaded</Html>
}

return (
  <Suspense fallback={<Loader />}>
    <AsyncModels />
  </Suspense>
)

const errors = useProgress((state) => state.errors)

export type ScreenVideoTextureProps = Omit<VideoTextureProps, 'src'> & {
  options?: DisplayMediaStreamOptions
}

<ScreenVideoTexture>
  {(texture) => <meshBasicMaterial map={texture} />}

const textureRef = useRef()
<ScreenVideoTexture ref={textureRef} />

const texture = useTexture(url)
const [texture1, texture2] = useTexture([texture1, texture2])

const props = useTexture({
  metalnessMap: url1,
  map: url2,
})
return <meshStandardMaterial {...props} />

type TrailConfig = {
  /** texture size (default: 256x256) */
  size?: number
  /** Max age (ms) of trail points (default: 750) */
  maxAge?: number
  /** Trail radius (default: 0.3) */
  radius?: number
  /** Canvas trail opacity (default: 0.2) */
  intensity?: number
  /** Add points in between slow pointer events (default: 0) */
  interpolate?: number
  /** Moving average of pointer force (default: 0) */
  smoothing?: number
  /** Minimum pointer force (default: 0.3) */
  minForce?: number
  /** Blend mode (default: 'screen') */
  blend?: CanvasRenderingContext2D['globalCompositeOperation']
  /** Easing (default: easeCircOut) */
  ease?: (t: number) => number
}

const [texture, onMove] = useTrailTexture(config)
return (
  <mesh onPointerMove={onMove}>
    <meshStandardMaterial displacementMap={texture} />

const font = useFont('/fonts/helvetiker_regular.typeface.json')
return <Text3D font={font} />

useFont.preload('/fonts/helvetiker_regular.typeface.json')

type Props = {
  /** The texture url to load the sprite frames from */
  input?: Url | null
  /** The JSON data describing the position of the frames within the texture (optional) */
  json?: string | null
  /** The animation names into which the frames will be divided into (optional) */
  animationNames?: string[] | null
  /** The number of frames on a standalone (no JSON data) spritesheet (optional)*/
  numberOfFrames?: number | null
  /** The callback to call when all textures and data have been loaded and parsed */
  onLoad?: (texture: Texture, textureData?: any) => void
  /** Allows the configuration of the canvas options */
  canvasRenderingContext2DSettings?: CanvasRenderingContext2DSettings
}

const { spriteObj } = useSpriteLoader(
  'multiasset.png',
  'multiasset.json',

  ['orange', 'Idle Blinking', '_Bat'],
  null
)

<SpriteAnimator
  position={[4.5, 0.5, 0.1]}
  autoPlay={true}
  loop={true}
  scale={5}
  frameName={'_Bat'}
  animationNames={['_Bat']}
  spriteDataset={spriteObj}
  alphaTest={0.01}
  asSprite={false}
/>

<SpriteAnimator
  position={[5.5, 0.5, 5.8]}
  autoPlay={true}
  loop={true}
  scale={5}
  frameName={'Idle Blinking'}
  animationNames={['Idle Blinking']}
  spriteDataset={spriteObj}
  alphaTest={0.01}
  asSprite={false}
/>

export function useVideoTexture(
  srcOrSrcObject: HTMLVideoElement['src' | 'srcObject'],
  {
    unsuspend = 'loadedmetadata',
    start = true,
    hls = {},
    crossOrigin = 'anonymous',
    muted = true,
    loop = true,
    playsInline = true,
    onVideoFrame,
    ...videoProps
  }: {
    unsuspend?: keyof HTMLVideoElementEventMap
    start?: boolean
    hls?: Parameters<typeof getHls>[0]
    onVideoFrame: VideoFrameRequestCallback
  } & Partial<Omit<HTMLVideoElement, 'children' | 'src' | 'srcObject'>> = {}
)

const texture = useVideoTexture("/video.mp4")
return (
  <mesh>
    <meshBasicMaterial map={texture} toneMapped={false} />

const [stream, setStream] = useState<MediaStream | null>(null)

return (
  <mesh onClick={async () => setStream(await navigator.mediaDevices.getDisplayMedia({ video: true }))}>
    <React.Suspense fallback={<meshBasicMaterial wireframe />}>
      <VideoMaterial src={stream} />
    </React.Suspense>

function VideoMaterial({ src }) {
  const texture = useVideoTexture(src)

  return <meshBasicMaterial map={texture} toneMapped={false} />
}

const texture = useVideoTexture('https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8')

const texture = useVideoTexture('https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8', {
  hls: { abrEwmaFastLive: 1.0, abrEwmaSlowLive: 3.0, enableWorker: true },
})

useVideoTexture(src, {
  onVideoFrame: (now, metadata) => {}
})

export type VideoTextureProps = {
  children?: (texture: THREE.VideoTexture) => React.ReactNode
  src: UseVideoTextureParams[0]
} & UseVideoTextureParams[1]

<VideoTexture src="/video.mp4">
  {(texture) => <meshBasicMaterial map={texture} />}

const textureRef = useRef()
<VideoTexture ref={textureRef} src="/video.mp4" />

const texture = useVideoTexture(src, { start: false });

async function warmup(texture: THREE.VideoTexture) {
  const video = texture.image as HTMLVideoElement;

  await video.play();
  setTimeout(() => {
    video.pause();
    video.currentTime = 0;
  }, 0);
}

useEffect(() => {
  warmup(texture).catch((err) => console.log("warmup failed", err));
}, [texture]);

export type WebcamVideoTextureProps = Omit<VideoTextureProps, 'src'> & {
  constraints?: MediaStreamConstraints
}

<WebcamVideoTexture>
  {(texture) => <meshBasicMaterial map={texture} />}

const textureRef = useRef()
<WebcamVideoTexture ref={textureRef} />

export function useCubeCamera({
  /** Resolution of the FBO, 256 */
  resolution?: number
  /** Camera near, 0.1 */
  near?: number
  /** Camera far, 1000 */
  far?: number
  /** Custom environment map that is temporarily set as the scenes background */
  envMap?: THREE.Texture
  /** Custom fog that is temporarily set as the scenes fog */
  fog?: Fog | FogExp2
})

const { fbo, camera, update } = useCubeCamera()

<CycleRaycast
  preventDefault={true} // Call event.preventDefault() (default: true)
  scroll={true} // Wheel events (default: true)
  keyCode={9} // Keyboard events (default: 9 [Tab])
  onChanged={(objects, cycle) => console.log(objects, cycle)} // Optional onChanged event
/>

function App() {
  const GPUTier = useDetectGPU()
  // show a fallback for mobile or lowest tier GPUs
  return (
    {(GPUTier.tier === 0 || GPUTier.isMobile) ? <Fallback /> : <Canvas>...</Canvas>

<Suspense fallback={null}>
  <App />

<Example font="/Inter_Bold.json" />

type ExampleProps = {
  font: string
  color?: Color
  debug?: boolean
  bevelSize?: number
}

const api = useRef<ExampleApi>()

<Example ref={api} font="/Inter_Bold.json" />

type ExampleApi = {
  incr: (x?: number) => void
  decr: (x?: number) => void
}

<FaceLandmarker>{/* ... */}</FaceLandmarker>

{
  basePath: "https://cdn.jsdelivr.net/npm/@mediapipe/[email protected]/wasm", // x.y.z will value the @mediapipe/tasks-vision version, eg: 0.10.2
  options: {
    baseOptions: {
      modelAssetPath: "https://storage.googleapis.com/mediapipe-models/face_landmarker/face_landmarker/float16/1/face_landmarker.task",
      delegate: "GPU",
    },
    runningMode: "VIDEO",
    outputFaceBlendshapes: true,
    outputFacialTransformationMatrixes: true,
  }
}

$ ln -s ../node_modules/@mediapipe/tasks-vision/wasm/ public/tasks-vision-wasm
$ curl https://storage.googleapis.com/mediapipe-models/face_landmarker/face_landmarker/float16/1/face_landmarker.task -o public/face_landmarker.task

import { FaceLandmarkerDefaults } from '@react-three/drei'

const visionBasePath = new URL("/tasks-vision-wasm", import.meta.url).toString()
const modelAssetPath = new URL("/face_landmarker.task", import.meta.url).toString()

const faceLandmarkerOptions = { ...FaceLandmarkerDefaults.options };
faceLandmarkerOptions.baseOptions.modelAssetPath = modelAssetPath;

<FaceLandmarker basePath={visionBasePath} options={faceLandmarkerOptions}>

const faceLandmarkerRef = useRef<ComponentRef<typeof FaceLandmarker>>(null)

<FaceLandmarker ref={faceLandmarkerRef}>
  {/* ... */}
</FaceLandmarker>

const faceLandmarker = useFaceLandmarker()

type FBOSettings = Omit<FboProps, 'width' | 'height' | 'children'>

export function useFBO(
  /** Width in pixels, or settings (will render fullscreen by default) */
  width?: number | FBOSettings,
  /** Height in pixels */
  height?: number,
  /** Settings, see constructor's `options`: https://threejs.org/docs/#api/en/renderers/WebGLRenderTarget */
  settings?: FBOSettings
): THREE.WebGLRenderTarget {

const target = useFBO({ stencilBuffer: false })

export type FboProps = {
  children?: (renderTarget: Fbo) => React.ReactNode
  width?: UseFBOParams[0]
  height?: UseFBOParams[1]
} & FBOSettings

<Fbo width={1024} height={1024} stencilBuffer={false}>
  {(renderTarget) => (
    <mesh>
      <planeGeometry />
      <meshBasicMaterial map={renderTarget.texture} />
    </mesh>
  )}

const renderTargetRef = useRef()
<Fbo ref={renderTargetRef} />

<Html
  as='div' // Wrapping element (default: 'div')
  wrapperClass // The className of the wrapping element (default: undefined)
  prepend // Project content behind the canvas (default: false)
  center // Adds a -50%/-50% css transform (default: false) [ignored in transform mode]
  fullscreen // Aligns to the upper-left corner, fills the screen (default:false) [ignored in transform mode]
  distanceFactor={10} // If set (default: undefined), children will be scaled by this factor, and also by distance to a PerspectiveCamera / zoom by a OrthographicCamera.
  zIndexRange={[100, 0]} // Z-order range (default=[16777271, 0])
  portal={domnodeRef} // Reference to target container (default=undefined)
  transform // If true, applies matrix3d transformations (default=false)
  sprite // Renders as sprite, but only in transform mode (default=false)
  calculatePosition={(el: Object3D, camera: Camera, size: { width: number; height: number }) => number[]} // Override default positioning function. (default=undefined) [ignored in transform mode]
  occlude={[ref]} // Can be true or a Ref<Object3D>[], true occludes the entire scene (default: undefined)
  onOcclude={(hidden) => null} // Callback when the visibility changes (default: undefined)
  {...groupProps} // All THREE.Group props are valid
  {...divProps} // All HTMLDivElement props are valid
>
  <h1>hello</h1>
  <Grid cols={4}>world</Grid>
</Html>

<Html occlude />

const [hidden, set] = useState()

<Html
  occlude
  onOcclude={set}
  style={{
    transition: 'all 0.5s',
    opacity: hidden ? 0 : 1,
    transform: `scale(${hidden ? 0.5 : 1})`
  }}
/>

// Enable real occlusion
<Html occlude="blending" />

<Html
  occlude
  material={
    <meshPhysicalMaterial
      side={DoubleSide} // Required
      opacity={0.1} // Degree of influence of lighting on the HTML
      ... // Any other material properties
    />
  }
/>

<Html
  occlude
  castShadow // Make HTML cast a shadow
  receiveShadow // Make HTML receive shadows
  material={<meshPhysicalMaterial side={DoubleSide} opacity={0.1} />}
/>

<Html transform scale={0.5}>
  <div style={{ transform: 'scale(2)' }}>Some text</div>
</Html>

type Props = {
  /** Allow multi select, default: false */
  multiple?: boolean
  /** Allow box select, default: false */
  box?: boolean
  /** Custom CSS border: default: '1px solid #55aaff' */
  border?: string
  /** Curom CSS color, default: 'rgba(75, 160, 255, 0.1)' */
  backgroundColor?: string
  /** Callback for selection changes */
  onChange?: (selected: THREE.Object3D[]) => void
  /** Callback for selection changes once the pointer is up */
  onChangePointerUp?: (selected: THREE.Object3D[]) => void
  /** Optional filter for filtering the selection */
  filter?: (selected: THREE.Object3D[]) => THREE.Object3D[]
}

<Select box multiple onChange={console.log} filter={items => items}>
  <Foo />
  <Bar />
</Select>

function Foo() {
  const selected = useSelect()

/* Detailed source-code truncated for AI context efficiency. */

<SpriteAnimator
  position={[-3.5, -2.0, 2.5]}
  startFrame={0}
  meshProps={{ frustumCulled: false, scale: 2.5 }}
  autoPlay={true}
  loop={true}
  numberOfFrames={16}
  textureImageURL={'./alien.png'}
/>

const { spriteObj: statics } = useSpriteLoader('/statics.png', '/statics.json', ['heart', 'skull', 'sword'], null)

<SpriteAnimator
  position={[2, 2.8, 0.01]}
  fps={0}
  meshProps={{ frustumCulled: false, scale: 2.5 }}
  autoPlay={true}
  loop={true}
  flipX={false}
  startFrame={0}
  frameName={'sword'}
  spriteDataset={statics}
  asSprite={false}
  alphaTest={0.01}
/>

;<ScrollControls damping={0.2} maxSpeed={0.5} pages={2}>
  <SpriteAnimator
    position={[0.0, -1.5, -1.5]}
    startFrame={0}
    onEnd={doSomethingOnEnd}
    onStart={doSomethingOnStart}
    autoPlay={true}
    textureImageURL={'sprite.png'}
    textureDataURL={'sprite.json'}
  >
    <FireScroll />
  </SpriteAnimator>
</ScrollControls>

function FireScroll() {
  const sprite = useSpriteAnimator()
  const scroll = useScroll()
  const ref = React.useRef()
  useFrame(() => {
    if (sprite && scroll) {
      sprite.current = scroll.offset
    }
  })

  return null
}

<StatsGl className="stats" {...props} />

<Stats showPanel={0} className="stats" {...props} />

const node = useRef(document.createElement('div'))

useEffect(() => {
  node.current.id = 'test'
  document.body.appendChild(node.current)

  return () => document.body.removeChild(node.current)
}, [])

return <Stats parent={parent} />

const points = useTrail(
  target, // Required target object. This object will produce the trail.
  {
    length, // Length of the line
    decay, // How fast the line fades away
    local, // Wether to use the target's world or local positions
    stride, // Min distance between previous and current point
    interval, // Number of frames to wait before next calculation
  }
)

// To use...
useFrame(() => {
  meshLineRef.current.position.setPoints(points.current)
})

const scale = useAspect(
  1024,                     // Pixel-width
  512,                      // Pixel-height
  1                         // Optional scaling factor
)
return (
  <mesh scale={scale}>
    <planeGeometry />
    <meshBasicMaterial map={imageTexture} />

const projection = useBoxProjectedEnv(
  [0, 0, 0], // Position
  [1, 1, 1] // Scale
)

<CubeCamera frames={1}>
  {(texture) => (
    <mesh>
      <planeGeometry />
      <meshStandardMaterial envMap={texture} {...projection} />
    </mesh>
  )}
</CubeCamera>

<mesh raycast={useCamera(customCamera)} />

function SceneWrapper() {
  // bridge any number of contexts
  // Note: These contexts must be provided by something above this SceneWrapper component
  //       You cannot render the providers for these contexts inside this component
  const ContextBridge = useContextBridge(ThemeContext, GreetingContext)
  return (
    <Canvas>
      <ContextBridge>
        <Scene />
      </ContextBridge>
    </Canvas>
  )
}

function Scene() {
  // we can now consume a context within the Canvas
  const theme = React.useContext(ThemeContext)
  const greeting = React.useContext(GreetingContext)
  return (
    //...
  )
}

const [hovered, set] = useState()
useCursor(hovered, /*'pointer', 'auto', document.body*/)
return (
  <mesh onPointerOver={() => set(true)} onPointerOut={() => set(false)}>

const depthBuffer = useDepthBuffer({
  size: 256, // Size of the FBO, 256 by default
  frames: Infinity, // How many frames it renders, Infinity by default
})
return <SomethingThatNeedsADepthBuffer depthBuffer={depthBuffer} />

const ref = useIntersect((visible) => console.log('object is visible', visible))
return <mesh ref={ref} />

const buffer = useSurfaceSampler(
  mesh, // Mesh to sample
  count, // [Optional] Number of samples (default: 16)
  transform, // [Optional] Transformation function. Same as in `<Sampler />`
  weight, // [Optional] Same as in `<Sampler />`
  instancedMesh // [Optional] Instanced mesh to scatter
)

<mesh>
  <geometry />
  <material />

  <Wireframe /> // Will apply wireframe on top of existing material on this mesh
</mesh>

// OR
<Wireframe
  geometry={geometry | geometryRef} // Will create the wireframe based on input geometry.

  // Other props
  simplify={false} // Remove some edges from wireframes
  fill={"#00ff00"} // Color of the inside of the wireframe
  fillMix={0} // Mix between the base color and the Wireframe 'fill'. 0 = base; 1 = wireframe
  fillOpacity={0.25} // Opacity of the inner fill
  stroke={"#ff0000"} // Color of the stroke
  strokeOpacity={1} // Opacity of the stroke
  thickness={0.05} // Thinkness of the lines
  colorBackfaces={false} // Whether to draw lines that are facing away from the camera
  backfaceStroke={"#0000ff"} // Color of the lines that are facing away from the camera
  dashInvert={true} // Invert the dashes
  dash={false} // Whether to draw lines as dashes
  dashRepeats={4} // Number of dashes in one seqment
  dashLength={0.5} // Length of each dash
  squeeze={false} // Narrow the centers of each line segment
  squeezeMin={0.2} // Smallest width to squueze to
  squeezeMax={1} // Largest width to squeeze from
/>

const curveRef = useRef<CurveModifierRef>()
const scroll = useScroll()

const curve = React.useMemo(() => new THREE.CatmullRomCurve3([...handlePos], true, 'centripetal'), [handlePos])

useFrame(() => {
  if (curveRef.current) {
    // Move continuously along the curve
    curveRef.current.moveAlongCurve(0.001)
    
    // Move along the curve using the scrollbar
    curveRef.current.uniforms.pathOffset.value = scroll.offset
  }
})

return (
  <CurveModifier ref={curveRef} curve={curve}>
    <mesh>
      <boxGeometry args={[10, 10]} />
    </mesh>
  </CurveModifier>
)

type CurveModifierRef = {
  curveArray: Curve<any>[];
  curveLengthArray: number[];
  object3D: TMesh;
  splineTexure: DataTexture;
  uniforms: CurveModifierUniforms;
  updateCurve<TCurve extends Curve<any>>(index: number, curve: TCurve): void;
  moveAlongCurve(amount: number): void;
}

type CurveModifierUniforms = {
  spineTexture: IUniform<DataTexture>;
  pathOffset: INumericUniform;
  pathSegment: INumericUniform;
  spineOffset: INumericUniform;
  spineLength: INumericUniform;
  flow: INumericUniform;
}

<AdaptiveDpr pixelated />

<AdaptiveEvents />

<Canvas>
  <Suspense fallback={null}>
    <Model />
    <BakeShadows />

export interface BVHOptions {
  /** Split strategy, default: SAH (slowest to construct, fastest runtime, least memory) */
  splitStrategy?: 'CENTER' | 'AVERAGE' | 'SAH'
  /** Print out warnings encountered during tree construction, default: false */
  verbose?: boolean
  /** If true then the bounding box for the geometry is set once the BVH has been constructed, default: true */
  setBoundingBox?: boolean
  /** The maximum depth to allow the tree to build to, default: 40 */
  maxDepth?: number
  /** The number of triangles to aim for in a leaf node, default: 10 */
  maxLeafTris?: number
  /** If false then an index buffer is created if it does not exist and is rearranged */
  /** to hold the bvh structure. If false then a separate buffer is created to store the */
  /** structure and the index buffer (or lack thereof) is retained. This can be used */
  /** when the existing index layout is important or groups are being used so a */
  /** single BVH hierarchy can be created to improve performance. */
  /** default: false */
  /** Note: This setting is experimental */
  indirect?: boolean
}

export type BvhProps = BVHOptions &
  ThreeElements['group'] & {
    /**Enabled, default: true */
    enabled?: boolean
    /** Use .raycastFirst to retrieve hits which is generally faster, default: false */
    firstHitOnly?: boolean
  }

<Canvas>
  <Bvh firstHitOnly>
    <Scene />
  </Bvh>
</Canvas>

<Detailed distances={[0, 10, 20]} {...props}>
  <mesh geometry={highDetail} />
  <mesh geometry={mediumDetail} />
  <mesh geometry={lowDetail} />
</Detailed>

<Instances
  limit={1000} // Optional: max amount of items (for calculating buffer size)
  range={1000} // Optional: draw-range
>
  <boxGeometry />
  <meshStandardMaterial />
  <Instance
    color="red"
    scale={2}
    position={[1, 2, 3]}
    rotation={[Math.PI / 3, 0, 0]}
    onClick={onClick} ... />
  // As many as you want, make them conditional, mount/unmount them, lazy load them, etc ...
</Instances>

<group position={[1, 2, 3]} rotation={[Math.PI / 2, 0, 0]}>
  <Instance />
</group>

<Instance>
  <Html>hello from the dom</Html>
</Instance>

<Instance onClick={...} onPointerOver={...} />

const [CubeInstances, Cube] = createInstances()
const [SphereInstances, Sphere] = createInstances()

function App() {
  return (
    <>
      <CubeInstances>
        <boxGeometry />
        <meshStandardMaterial />
        <SphereInstances>
          <sphereGeometry />
          <meshLambertMaterial />
          <Cube position={[1, 2, 3]} />
          <Sphere position={[4, 5, 6]} />
        </SphereInstances>
      </CubeInstances>
    </>
  )
}

<Instances ref={ref} limit={20}>
  <boxGeometry />
  <someSpecialMaterial />
  <InstancedAttribute name="foo" defaultValue={1} />
  <Instance position={[-1.2, 0, 0]} foo={10} />
</Instances>

# vertex
attribute float foo;
varying float vFoo;
void main() {
  ...
  vFoo = foo;

# fragment
varying float vFoo;
void main() {
  ...

interface SphereAttributes {
  myCustomAttribute: number
}

const [SphereInstances, Sphere] = createInstances<SphereAttributes>()

function App() {
  return (
    <>
      <SphereInstances>
        <InstancedAttribute name="myCustomAttribute" defaultValue={1} />
        <sphereGeometry />
        <shaderMaterial
          // will recienve myCustomAttribute as an attribute
          vertexShader={`
              attribute float myCustomAttribute;
              void main() {
                ...
              }
            `}
        />
        <Sphere
          position={[4, 5, 6]}
          myCustomAttribute={1} // typed
        />
      </SphereInstances>
    </>
  )
}

<Merged meshes={[box, sphere]}>
  {(Box, Sphere) => (
    <>
      <Box position={[-2, -2, 0]} color="red" />
      <Box position={[-3, -3, 0]} color="tomato" />
      <Sphere scale={0.7} position={[2, 1, 0]} color="green" />
      <Sphere scale={0.7} position={[3, 2, 0]} color="teal" />
    </>
  )}
</Merged>

function Model({ url }) {
  const { nodes } = useGLTF(url)
  return (
    <Merged meshes={nodes}>
      {({ Screw, Filter, Pipe }) => (
        <>
          <Screw />
          <Filter position={[1, 2, 3]} />
          <Pipe position={[4, 5, 6]} />
        </>
      )}
    </Merged>
  )
}

<mesh raycast={meshBounds} />

/* Detailed source-code truncated for AI context efficiency. */

type PerformanceMonitorApi = {
  /** Current fps */
  fps: number
  /** Current performance factor, between 0 and 1 */
  factor: number
  /** Current highest fps, you can use this to determine device refresh rate */
  refreshrate: number
  /** Fps samples taken over time  */
  frames: number[]
  /** Averages of frames taken over n iterations   */
  averages: number[]
}

function App() {
  const [dpr, setDpr] = useState(1.5)
  return (
    <Canvas dpr={dpr}>
      <PerformanceMonitor onIncline={() => setDpr(2)} onDecline={() => setDpr(1)} />

const [dpr, setDpr] = useState(2)
return (
 <Canvas dpr={dpr}>
  <PerformanceMonitor factor={1} onChange={({ factor }) => setDpr(Math.floor(0.5 + 1.5 * factor, 1))} />

<PerformanceMonitor flipflops={3} onFallback={() => setDpr(1)} />

;<PerformanceMonitor>
  <Effects />
</PerformanceMonitor>

function Effects() {
  usePerformanceMonitor({ onIncline, onDecline, onFallback, onChange })
  // ...
}

<Points
  limit={1000} // Optional: max amount of items (for calculating buffer size)
  range={1000} // Optional: draw-range
>
  <pointsMaterial vertexColors />
  <Point position={[1, 2, 3]} color="red" onClick={onClick} onPointerOver={onPointerOver} ... />
  // As many as you want, make them conditional, mount/unmount them, lazy load them, etc ...
</Points>

<Points positions={positionsBuffer} colors={colorsBuffer} sizes={sizesBuffer}>
  <pointsMaterial />
</Points>

<Canvas>
  <Suspense fallback={null}>
    <Model />
    <Preload all />

<Segments
  limit={1000}
  lineWidth={1.0}
  // All THREE.LineMaterial props are valid
  {...materialProps}
>
  <Segment start={[0, 0, 0]} end={[0, 10, 0]} color="red" />
  <Segment start={[0, 0, 0]} end={[0, 10, 10]} color={[1, 0, 1]} />
</Segments>

const ref = useRef()

// E.g. to change segment position each frame.
useFrame(() => {
  ref.current.start.set(0,0,0)
  ref.current.end.set(10,10,0)
  ref.current.color.setRGB(0,0,0)
})
// ...
<Segments
  limit={1000}
  lineWidth={1.0}
>
  <Segment ref={ref} />
</Segments>

export type FisheyeProps = ThreeElements['mesh'] & {
  /** Zoom factor, 0..1, 0 */
  zoom?: number
  /** Number of segments, 64 */
  segments?: number
  /** Cubemap resolution (for each of the 6 takes), null === full screen resolution, default: 896 */
  resolution?: number
  /** Children will be projected into the fisheye */
  children: React.ReactNode
  /** Optional render priority, defaults to 1 */
  renderPriority?: number
}

<Canvas camera={{ position: [0, 0, 5] }}>
  <Fisheye>
    <YourScene />
  </Fisheye>
  <OrbitControls />

type HudProps = {
  /** Any React node */
  children: React.ReactNode
  /** Render priority, default: 1 */
  renderPriority?: number
}

{
  /* Renders on top of the default scene with a perspective camera */
}
;<Hud>
  <PerspectiveCamera makeDefault position={[0, 0, 10]} />
  <mesh>
    <ringGeometry />
  </mesh>
</Hud>

{
  /* Renders on top of the previous HUD with an orthographic camera */
}
;<Hud renderPriority={2}>
  <OrthographicCamera makeDefault position={[0, 0, 10]} />
  <mesh>
    <boxGeometry />
  </mesh>
</Hud>

<Mask
  /** Each mask must have an id, you can have compound masks referring to the same id */
  id: number
  /** If colors of the masks own material will leak through, default: false */
  colorWrite?: boolean
  /** If depth  of the masks own material will leak through, default: false */
  depthWrite?: boolean
/>

<Mask id={1}>
  <planeGeometry />
  <meshBasicMaterial />
</Mask>

const stencil = useMask(1)
return (
  <mesh>
    <torusKnotGeometry />
    <meshStandardMaterial {...stencil} />

<Mask position={[-1, 0, 0]} id={1}>
  <planeGeometry />
  <meshBasicMaterial />
</Mask>
<Mask colorWrite depthWrite position={[1, 0, 0]} id={1}>
  <circleGeometry />
  <meshBasicMaterial />
</Mask>

const stencil = useMask(1, true)

export type PortalProps = ThreeElements['shaderMaterial'] & {
  /** Mix the portals own scene with the world scene, 0 = world scene render,
   *  0.5 = both scenes render, 1 = portal scene renders, defaults to 0 */
  blend?: number
  /** Edge fade blur, 0 = no blur (default) */
  blur?: number
  /** SDF resolution, the smaller the faster is the start-up time (default: 512) */
  resolution?: number
  /** By default portals use relative coordinates, contents are affects by the local matrix transform */
  worldUnits?: boolean
  /** Optional event priority, defaults to 0 */
  eventPriority?: number
  /** Optional render priority, defaults to 0 */
  renderPriority?: number
  /** Optionally diable events inside the portal, defaults to false */
  events?: boolean
}

<mesh {...props}>
  <planeGeometry />
  <MeshPortalMaterial>
    <mesh>
      <sphereGeometry />
    </mesh>
  </MeshPortalMaterial>
</mesh>

<MeshPortalMaterial transparent blur={0.5}>

<MeshPortalMaterial blend={1}>

export type RenderCubeTextureProps = Omit<ThreeElements['texture'], 'rotation'> & {
  /** Optional stencil buffer, defaults to false */
  stencilBuffer?: boolean
  /** Optional depth buffer, defaults to true */
  depthBuffer?: boolean
  /** Optional generate mipmaps, defaults to false */
  generateMipmaps?: boolean
  /** Optional render priority, defaults to 0 */
  renderPriority?: number
  /** Optional event priority, defaults to 0 */
  eventPriority?: number
  /** Optional frame count, defaults to Infinity. If you set it to 1, it would only render a single frame, etc */
  frames?: number
  /** Optional event compute, defaults to undefined */
  compute?: ComputeFunction
  /** Flip cubemap, see https://github.com/mrdoob/three.js/blob/master/src/renderers/WebGLCubeRenderTarget.js */
  flip?: boolean
  /** Cubemap resolution (for each of the 6 takes), null === full screen resolution, default: 896 */
  resolution?: number
  /** Children will be rendered into a portal */
  children: React.ReactNode
  near?: number
  far?: number
  position?: ReactThreeFiber.Vector3
  rotation?: ReactThreeFiber.Euler
  scale?: ReactThreeFiber.Vector3
  quaternion?: ReactThreeFiber.Quaternion
  matrix?: ReactThreeFiber.Matrix4
  matrixAutoUpdate?: boolean
}

export type RenderCubeTextureApi = {
  scene: THREE.Scene
  fbo: THREE.WebGLCubeRenderTarget
  camera: THREE.CubeCamera
}

const api = useRef<RenderCubeTextureApi>(null!)
// ...
<mesh ref={api}>
  <sphereGeometry args={[1, 64, 64]} />
    <meshBasicMaterial>
      <RenderCubeTexture attach="envMap" flip>
        <mesh />

type Props = ThreeElements['texture'] & {
  /** Optional width of the texture, defaults to viewport bounds */
  width?: number
  /** Optional height of the texture, defaults to viewport bounds */
  height?: number
  /** Optional fbo samples */
  samples?: number
  /** Optional stencil buffer, defaults to false */
  stencilBuffer?: boolean
  /** Optional depth buffer, defaults to true */
  depthBuffer?: boolean
  /** Optional generate mipmaps, defaults to false */
  generateMipmaps?: boolean
  /** Optional render priority, defaults to 0 */
  renderPriority?: number
  /** Optional event priority, defaults to 0 */
  eventPriority?: number
  /** Optional frame count, defaults to Infinity. If you set it to 1, it would only render a single frame, etc */
  frames?: number
  /** Optional event compute, defaults to undefined */
  compute?: (event: any, state: any, previous: any) => false | undefined
  /** Children will be rendered into a portal */
  children: React.ReactNode
}

<mesh>
  <planeGeometry />
  <meshStandardMaterial>
    <RenderTexture attach="map">
      <mesh />

export type ViewProps = {
  /** Root element type, default: div */
  as?: string
  /** CSS id prop */
  id?: string
  /** CSS classname prop */
  className?: string
  /** CSS style prop */
  style?: React.CSSProperties
  /** If the view is visible or not, default: true */
  visible?: boolean
  /** Views take over the render loop, optional render index (1 by default) */
  index?: number
  /** If you know your view is always at the same place set this to 1 to avoid needless getBoundingClientRect overhead */
  frames?: number
  /** The scene to render, if you leave this undefined it will render the default scene */
  children?: React.ReactNode
  /** The tracking element, the view will be cut according to its whereabouts
   * @deprecated You can use inline Views now, see: https://github.com/pmndrs/drei/pull/1784
   */
  track?: React.RefObject<HTMLElement>
}

export type ViewportProps = { Port: () => React.ReactNode } & React.ForwardRefExoticComponent<
  ViewProps & React.RefAttributes<HTMLElement | THREE.Group>
>

return (
  <main ref={container}>
    <h1>Html content here</h1>
    <View style={{ width: 200, height: 200 }}>
      <mesh geometry={foo} />
      <OrbitControls />
    </View>
    <View className="canvas-view">
      <mesh geometry={bar} />
      <CameraControls />
    </View>
    <Canvas eventSource={container}>
      <View.Port />
    </Canvas>
  </main>
)

<mesh castShadow>
  <torusKnotGeonetry />
  <MeshDiscardMaterial />
  {/* Shadows and edges will show, but the model itself won't */}
  <Edges />

<mesh>
  <boxGeometry />
  <MeshDistortMaterial distort={1} speed={10} />
</mesh>

<mesh>
  <planeGeometry />
  <MeshReflectorMaterial
    blur={[0, 0]} // Blur ground reflections (width, height), 0 skips blur
    mixBlur={0} // How much blur mixes with surface roughness (default = 1)
    mixStrength={1} // Strength of the reflections
    mixContrast={1} // Contrast of the reflections
    resolution={256} // Off-buffer resolution, lower=faster, higher=better quality, slower
    mirror={0} // Mirror environment, 0 = texture colors, 1 = pick up env colors
    depthScale={0} // Scale the depth factor (0 = no depth, default = 0)
    minDepthThreshold={0.9} // Lower edge for the depthTexture interpolation (default = 0)
    maxDepthThreshold={1} // Upper edge for the depthTexture interpolation (default = 0)
    depthToBlurRatioBias={0.25} // Adds a bias factor to the depthTexture before calculating the blur amount [blurFactor = blurTexture * (depthTexture + bias)]. It accepts values between 0 and 1, default is 0.25. An amount > 0 of bias makes sure that the blurTexture is not too sharp because of the multiplication with the depthTexture
    distortion={1} // Amount of distortion based on the distortionMap texture
    distortionMap={distortionTexture} // The red channel of this texture is used as the distortion map. Default is null
    reflectorOffset={0.2} // Offsets the virtual camera that projects the reflection. Useful when the reflective surface is some distance from the object's origin (default = 0)
  />
</mesh>

type MeshRefractionMaterialProps = ThreeElements['shaderMaterial'] & {
  /** Environment map */
  envMap: THREE.CubeTexture | THREE.Texture
  /** Number of ray-cast bounces, it can be expensive to have too many, 2 */
  bounces?: number
  /** Refraction index, 2.4 */
  ior?: number
  /** Fresnel (strip light), 0 */
  fresnel?: number
  /** RGB shift intensity, can be expensive, 0 */
  aberrationStrength?: number
  /** Color, white */
  color?: ReactThreeFiber.Color
  /** If this is on it uses fewer ray casts for the RGB shift sacrificing physical accuracy, true */
  fastChroma?: boolean
}

<CubeCamera>
  {(texture) => (
    <mesh geometry={diamondGeometry} {...props}>
      <MeshRefractionMaterial envMap={texture} />
    </mesh>
  )}
</CubeCamera>

const texture = useLoader(RGBELoader, "/textures/royal_esplanade_1k.hdr")
return (
  <mesh geometry={diamondGeometry} {...props}>
    <MeshRefractionMaterial envMap={texture} />

/* Detailed source-code truncated for AI context efficiency. */

return (
  <mesh geometry={geometry} {...props}>
    <MeshTransmissionMaterial />

<mesh geometry={torus}>
  <MeshTransmissionMaterial transmissionSampler />
</mesh>
<mesh geometry={sphere}>
  <MeshTransmissionMaterial transmissionSampler />
</mesh>

const buffer = useFBO()
useFrame((state) => {
  state.gl.setRenderTarget(buffer)
  state.gl.render(state.scene, state.camera)
  state.gl.setRenderTarget(null)
})
return (
  <>
    <mesh geometry={torus}>
      <MeshTransmissionMaterial buffer={buffer.texture} />
    </mesh>
    <mesh geometry={sphere}>
      <MeshTransmissionMaterial buffer={buffer.texture} />
    </mesh>

<PerspectiveCamera makeDefault fov={75} position={[10, 0, 15]} resolution={1024}>
  {(texture) => (
    <>
      <mesh geometry={torus}>
        <MeshTransmissionMaterial buffer={texture} />
      </mesh>
      <mesh geometry={sphere}>
        <MeshTransmissionMaterial buffer={texture} />
      </mesh>
    </>
  )}

<mesh>
  <boxGeometry />
  <MeshWobbleMaterial factor={1} speed={10} />
</mesh>

<points>
  <PointMaterial transparent vertexColors size={15} sizeAttenuation={false} depthWrite={false} />
</points>

import { extend } from '@react-three/fiber'

const ColorShiftMaterial = shaderMaterial(
  { time: 0, color: new THREE.Color(0.2, 0.0, 0.1) },
  // vertex shader
  /*glsl*/`
    varying vec2 vUv;
    void main() {
      vUv = uv;
      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
    }
  `,
  // fragment shader
  /*glsl*/`
    uniform float time;
    uniform vec3 color;
    varying vec2 vUv;
    void main() {
      gl_FragColor.rgba = vec4(0.5 + 0.3 * sin(vUv.yxx + time) + color, 1.0);
    }
  `
)

// declaratively
extend({ ColorShiftMaterial })
...
<mesh>
  <colorShiftMaterial color="hotpink" time={1} />
</mesh>

// imperatively, all uniforms are available as setter/getters and constructor args
const material = new ColorShiftMaterial({ color: new THREE.Color("hotpink") })
material.time = 1

import { ColorShiftMaterial } from './ColorShiftMaterial'

extend({ ColorShiftMaterial })

// in your component
<colorShiftMaterial key={ColorShiftMaterial.key} color="hotpink" time={1} />

type SoftShadowsProps = {
  /** Size of the light source (the larger the softer the light), default: 25 */
  size?: number
  /** Number of samples (more samples less noise but more expensive), default: 10 */
  samples?: number
  /** Depth focus, use it to shift the focal point (where the shadow is the sharpest), default: 0 (the beginning) */
  focus?: number
}

<SoftShadows />

<CatmullRomLine
  points={[[0, 0, 0], ...]}       // Array of Points
  closed={false}                  // Default
  curveType="centripetal"         // One of "centripetal" (default), "chordal", or "catmullrom"
  tension={0.5}                   // Default (only applies to "catmullrom" curveType)
  color="black"                   // Default
  lineWidth={1}                   // In pixels (default)
  dashed={false}                  // Default
  vertexColors={[[0, 0, 0], ...]} // Optional array of RGB values for each point
  {...lineProps}                  // All THREE.Line2 props are valid
  {...materialProps}              // All THREE.LineMaterial props are valid
/>

<CubicBezierLine
  start={[0, 0, 0]}               // Starting point
  end={[10, 0, 10]}               // Ending point
  midA={[5, 0, 0]}                // First control point
  midB={[0, 0, 5]}                // Second control point
  color="black"                   // Default
  lineWidth={1}                   // In pixels (default)
  dashed={false}                  // Default
  vertexColors={[[0, 0, 0], ...]} // Optional array of RGB values for each point
  {...lineProps}                  // All THREE.Line2 props are valid
  {...materialProps}              // All THREE.LineMaterial props are valid
/>

const faceLandmarkerResult = {
    "faceLandmarks": [
      [
        { "x": 0.5760777592658997, "y": 0.8639070391654968, "z": -0.030997956171631813 },
        { "x": 0.572094738483429, "y": 0.7886289358139038, "z": -0.07189624011516571 },
        // ...
      ],
      // ...
    ],
    "faceBlendshapes": [
      // ...
    ],
    "facialTransformationMatrixes": [
      // ...
    ]
  },
}
const points = faceLandmarkerResult.faceLandmarks[0]

<Facemesh points={points} />

/* Detailed source-code truncated for AI context efficiency. */

const api = useRef<FacemeshApi>()

<Facemesh ref={api} points={points} />

type FacemeshApi = {
  meshRef: React.RefObject<THREE.Mesh>
  outerRef: React.RefObject<THREE.Group>
  eyeRightRef: React.RefObject<FacemeshEyeApi>
  eyeLeftRef: React.RefObject<FacemeshEyeApi>
}

api.meshRef.current.localToWorld(new THREE.Vector3(0, 0, -1))

api.eyeRightRef.current.irisDirRef.current.localToWorld(new THREE.Vector3(0, 0, -1))

<Line
  points={[[0, 0, 0], ...]}       // Array of points, Array<Vector3 | Vector2 | [number, number, number] | [number, number] | number>
  color="black"                   // Default
  lineWidth={1}                   // In pixels (default)
  segments                        // If true, renders a THREE.LineSegments2. Otherwise, renders a THREE.Line2
  dashed={false}                  // Default
  vertexColors={[[0, 0, 0], ...]} // Optional array of RGB values for each point
  {...lineProps}                  // All THREE.Line2 props are valid
  {...materialProps}              // All THREE.LineMaterial props are valid
/>

<Box
  args={[1, 1, 1]}                // Args for the buffer geometry
  {...meshProps}                  // All THREE.Mesh props are valid
/>

// Plane with buffer geometry args
<Plane args={[2, 2]} />

// Box with color set on the default MeshBasicMaterial
<Box material-color="hotpink" />

// Sphere with a MeshStandardMaterial
<Sphere>
  <meshStandardMaterial color="hotpink" />
</Sphere>

<QuadraticBezierLine
  start={[0, 0, 0]}               // Starting point, can be an array or a vec3
  end={[10, 0, 10]}               // Ending point, can be an array or a vec3
  mid={[5, 0, 5]}                 // Optional control point, can be an array or a vec3
  color="black"                   // Default
  lineWidth={1}                   // In pixels (default)
  dashed={false}                  // Default
  vertexColors={[[0, 0, 0], ...]} // Optional array of RGB values for each point
  {...lineProps}                  // All THREE.Line2 props are valid
  {...materialProps}              // All THREE.LineMaterial props are valid
/>

const ref = useRef()
useFrame((state) => {
  ref.current.setPoints(
    [0, 0, 0],
    [10, 0, 0],
    // [5, 0, 0] // Optional: mid-point
  )
}, [])
return <QuadraticBezierLine ref={ref} />
}

<RoundedBox
  args={[1, 1, 1]} // Width, height, depth. Default is [1, 1, 1]
  radius={0.05} // Radius of the rounded corners. Default is 0.05
  steps={1} // Extrusion steps. Default is 1
  smoothness={4} // The number of curve segments. Default is 4
  bevelSegments={4} // The number of bevel segments. Default is 4, setting it to 0 removes the bevel, as a result the texture is applied to the whole geometry.
  creaseAngle={0.4} // Smooth normals everywhere except faces that meet at an angle greater than the crease angle
  {...meshProps} // All THREE.Mesh props are valid
>
  <meshPhongMaterial color="#f3f3f3" wireframe />
</RoundedBox>

<mesh>
  <RoundedBoxGeometry
    args={[1, 1, 1]}
    radius={0.05}
    steps={1}
    smoothness={4}
    bevelSegments={4}
    creaseAngle={0.4}
  />
  <meshPhongMaterial color="#f3f3f3" wireframe />
</mesh>

<ScreenQuad>
  <myMaterial />
</ScreenQuad>

type AccumulativeShadowsProps = ThreeElements['group'] & {
  /** How many frames it can render, more yields cleaner results but takes more time, 40 */
  frames?: number
  /** If frames === Infinity blend controls the refresh ratio, 100 */
  blend?: number
  /** Can limit the amount of frames rendered if frames === Infinity, usually to get some performance back once a movable scene has settled, Infinity */
  limit?: number
  /** Scale of the plane,  */
  scale?: number
  /** Temporal accumulates shadows over time which is more performant but has a visual regression over instant results, false  */
  temporal?: false
  /** Opacity of the plane, 1 */
  opacity?: number
  /** Discards alpha pixels, 0.65 */
  alphaTest?: number
  /** Shadow color, black */
  color?: string
  /** Colorblend, how much colors turn to black, 0 is black, 2 */
  colorBlend?: number
  /** Buffer resolution, 1024 */
  resolution?: number
  /** Children should be randomized lights shining from different angles to emulate raycasting */
  children?: React.ReactNode
}

<AccumulativeShadows temporal frames={100} scale={10}>
  <RandomizedLight amount={8} position={[5, 5, -10]} />
</AccumulativeShadows>

interface AccumulativeContext {
  /** Returns the plane geometry onto which the shadow is cast */
  getMesh: () => THREE.Mesh<THREE.PlaneGeometry, SoftShadowMaterialProps & THREE.ShaderMaterial>
  /** Resets the buffers, starting from scratch */
  reset: () => void
  /** Updates the lightmap for a number of frames accumulartively */
  update: (frames?: number) => void
  /** Allows children to subscribe. AccumulativeShadows will call child.update() in its own update function */
  setLights: React.Dispatch<React.SetStateAction<AccumulativeLightContext[]>>
}

<Backdrop
  floor={0.25} // Stretches the floor segment, 0.25 by default
  segments={20} // Mesh-resolution, 20 by default
>
  <meshStandardMaterial color="#353540" />
</Backdrop>

childrenAnchor = boundingBoxPosition + (boundingBoxSize * anchor / 2)

<BBAnchor
  anchor // THREE.Vector3 or [number, number, number]
  {...groupProps} // All THREE.Group props are valid
>
  {children}
</BBAnchor>

<Box>
  <BBAnchor anchor={[1, 1, 1]}>
    <Html center>
      <span>Hello world!</span>
    </Html>
  </BBAnchor>
</Box>

const interpolateFunc = (t: number) => 1 - Math.exp(-5 * t) + 0.007 * t // Matches the default Bounds behavior
const interpolateFunc1 = (t: number) => -t * t * t + 2 * t * t          // Start smoothly, finish linearly
const interpolateFunc2 = (t: number) => -t * t * t + t * t + t          // Start linearly, finish smoothly

<Bounds fit clip observe margin={1.2} maxDuration={1} interpolateFunc={interpolateFunc}>
  <mesh />
</Bounds>

function Foo() {
  const bounds = useBounds()
  useEffect(() => {
    // Calculate scene bounds
    bounds.refresh().clip().fit()

    // Or, focus a specific object or box3
    // bounds.refresh(ref.current).clip().fit()
    // bounds.refresh(new THREE.Box3()).clip().fit()

    // Or, move the camera to a specific position, and change its orientation
    // bounds.moveTo([0, 10, 10]).lookAt({ target: [5, 5, 0], up: [0, -1, 0] })

    // For orthographic cameras, reset has to be used to center the view (fit would only change its zoom to match the bounding box)
    // bounds.refresh().reset().clip().fit()
  }, [...])
}

<Bounds>
  <Foo />
</Bounds>

const config = {
  maxYaw: 0.1, // Max amount camera can yaw in either direction
  maxPitch: 0.1, // Max amount camera can pitch in either direction
  maxRoll: 0.1, // Max amount camera can roll in either direction
  yawFrequency: 0.1, // Frequency of the yaw rotation
  pitchFrequency: 0.1, // Frequency of the pitch rotation
  rollFrequency: 0.1, // Frequency of the roll rotation
  intensity: 1, // initial intensity of the shake
  decay: false, // should the intensity decay over time
  decayRate: 0.65, // if decay = true this is the rate at which intensity will reduce at
  controls: undefined, // if using orbit controls, pass a ref here so we can update the rotation
}

<CameraShake {...config} />

interface ShakeController {
  getIntensity: () => number
  setIntensity: (val: number) => void
}

type CausticsProps = ThreeElements['group'] & {
  /** How many frames it will render, set it to Infinity for runtime, default: 1 */
  frames?: number
  /** Enables visual cues to help you stage your scene, default: false */
  debug?: boolean
  /** Will display caustics only and skip the models, default: false */
  causticsOnly: boolean
  /** Will include back faces and enable the backsideIOR prop, default: false */
  backside: boolean
  /** The IOR refraction index, default: 1.1 */
  ior?: number
  /** The IOR refraction index for back faces (only available when backside is enabled), default: 1.1 */
  backsideIOR?: number
  /** The texel size, default: 0.3125 */
  worldRadius?: number
  /** Intensity of the prjected caustics, default: 0.05 */
  intensity?: number
  /** Caustics color, default: white */
  color?: ReactThreeFiber.Color
  /** Buffer resolution, default: 2048 */
  resolution?: number
  /** Camera position, it will point towards the contents bounds center, default: [5, 5, 5] */
  lightSource?: [x: number, y: number, z: number] | React.RefObject<THREE.Object3D>
}

<Caustics debug backside lightSource={[2.5, 5, -2.5]}>
  <Bottle />
  <WineGlass>
</Caustics>

<Caustics backside lightSource={[2.5, 5, -2.5]} >
  <WineGlass />
</Caustics>
<Caustics causticsOnly backside lightSource={[-2.5, 5, 2.5]} ior={0.79} worldRadius={0.0124}>
  <WineGlass />
</Caustics>

const lightSource = useRef()

<Caustics frames={Infinity} resolution={256} lightSource={lightSource} >
  <WineGlass />
</Caustics>
<object3d ref={lightSource} position={[2.5, 5, -2.5]} />

export type Props = ThreeElements['group'] & {
  top?: boolean
  right?: boolean
  bottom?: boolean
  left?: boolean
  front?: boolean
  back?: boolean
  /** Disable all axes */
  disable?: boolean
  /** Disable x-axis centering */
  disableX?: boolean
  /** Disable y-axis centering */
  disableY?: boolean
  /** Disable z-axis centering */
  disableZ?: boolean
  /** object to compute box3 from */
  object?: THREE.Object3D | null
  /** Precision, defaults to true, see https://threejs.org/docs/index.html?q=box3#api/en/math/Box3.setFromObject */
  precise?: boolean
  /** Callback, fires in the useLayoutEffect phase, after measurement */
  onCentered?: (props: OnCenterCallbackProps) => void
}

type OnCenterCallbackProps = {
  /** The next parent above <Center> */
  parent: THREE.Object3D
  /** The outmost container group of the <Center> component */
  container: THREE.Object3D
  width: number
  height: number
  depth: number
  boundingBox: THREE.Box3
  boundingSphere: THREE.Sphere
  center: THREE.Vector3
  verticalAlignment: number
  horizontalAlignment: number
  depthAlignment: number
}

<Center top left>
  <mesh />
</Center>

function ScaledModel() {
  const viewport = useThree((state) => state.viewport)
  return (
    <Center onCentered={({ container, height }) => container.scale.setScalar(viewport.height / height)}>
      <Model />
    </Center>

/* Detailed source-code truncated for AI context efficiency. */

<Clouds material={THREE.MeshBasicMaterial}>
  <Cloud segments={40} bounds={[10, 2, 2]} volume={10} color="orange" />
  <Cloud seed={1} scale={2} volume={5} color="hotpink" fade={100} />
</Clouds>

<ContactShadows opacity={1} scale={10} blur={1} far={10} resolution={256} color="#000000" />

<ContactShadows frames={1} />

<Environment
  background={false} // can be true, false or "only" (which only sets the background) (default: false)
  backgroundBlurriness={0} // optional blur factor between 0 and 1 (default: 0, only works with three 0.146 and up)
  backgroundIntensity={1} // optional intensity factor (default: 1, only works with three 0.163 and up)
  backgroundRotation={[0, Math.PI / 2, 0]} // optional rotation (default: 0, only works with three 0.163 and up)
  environmentIntensity={1} // optional intensity factor (default: 1, only works with three 0.163 and up)
  environmentRotation={[0, Math.PI / 2, 0]} // optional rotation (default: 0, only works with three 0.163 and up)
  files={['px.png', 'nx.png', 'py.png', 'ny.png', 'pz.png', 'nz.png']}
  path="/"
  preset={null}
  scene={undefined} // adds the ability to pass a custom THREE.Scene, can also be a ref
  encoding={undefined} // adds the ability to pass a custom THREE.TextureEncoding (default: THREE.sRGBEncoding for an array of files and THREE.LinearEncoding for a single texture)
/>

<Environment preset="city" />

<Environment files="file.hdr" />
<Environment files="file.exr" />
<Environment files="file.jpg" />
<Environment files={['file.webp', 'file-gainmap.webp', 'file.json']} />
<Environment files={['px.png', 'nx.png', 'py.png', 'ny.png', 'pz.png', 'nz.png']} />

import { suspend } from 'suspend-react'
const city = import('@pmndrs/assets/hdri/city.exr').then((module) => module.default)

<Environment files={suspend(city)} />

<CubeCamera>{(texture) => <Environment map={texture} />}</CubeCamera>

<Environment background near={1} far={1000} resolution={256}>
  <mesh scale={100}>
    <sphereGeometry args={[1, 64, 64]} />
    <meshBasicMaterial map={texture} side={THREE.BackSide} />
  </mesh>
</Environment>

return (
  <Environment background near={1} far={1000} resolution={256} preset="warehouse">
    <mesh />

return (
  <Environment frames={Infinity} resolution={256}>
    <Float>
      <mesh />
    </Float>

<Environment ground />

<Environment
  ground={{
    height: 15, // Height of the camera that was used to create the env map (Default: 15)
    radius: 60, // Radius of the world. (Default 60)
    scale: 1000, // Scale of the backside projected sphere that holds the env texture (Default: 1000)
  }}
/>

<Float
  speed={1} // Animation speed, defaults to 1
  rotationIntensity={1} // XYZ rotation intensity, defaults to 1
  floatIntensity={1} // Up/down float intensity, works like a multiplier with floatingRange,defaults to 1
  floatingRange={[1, 10]} // Range of y-axis values the object will float within, defaults to [-0.1,0.1]
>
  <mesh />
</Float>

<Canvas frameloop="demand">
  <Float autoInvalidate>
    <mesh />
  </Float>
</Canvas>

<Environment>
  <Lightformer
    form="rect" // circle | ring | rect (optional, default = rect)
    intensity={1} // power level (optional = 1)
    color="white" // (optional = white)
    scale={[10, 5]} // Scale it any way you prefer (optional = [1, 1])
    target={[0, 0, 0]} // Target position (optional = undefined)
  />

const [matcap, url] = useMatcapTexture(
 0, // index of the matcap texture https://github.com/emmelleppi/matcaps/blob/master/matcap-list.json
 1024 // size of the texture ( 64, 128, 256, 512, 1024 )
)

return (
 ...
 <meshMatcapMaterial matcap={matcap} />
 ...
)

const [matcap] = useMatcapTexture('3E2335_D36A1B_8E4A2E_2842A5')

const [normalMap, url] = useNormalTexture(
  1, // index of the normal texture - https://github.com/emmelleppi/normal-maps/blob/master/normals.json
  // second argument is texture attributes
  {
    offset: [0, 0],
    repeat: [normRepeat, normRepeat],
    anisotropy: 8
  }
)

return (
  ...
  <meshStandardMaterial normalMap={normalMap} />
  ...
)

type RandomizedLightProps = ThreeElements['group'] & {
  /** How many frames it will jiggle the lights, 1.
   *  Frames is context aware, if a provider like AccumulativeShadows exists, frames will be taken from there!  */
  frames?: number
  /** Light position, [0, 0, 0] */
  position?: [x: number, y: number, z: number]
  /** Radius of the jiggle, higher values make softer light, 5 */
  radius?: number
  /** Amount of lights, 8 */
  amount?: number
  /** Light intensity, 1 */
  intensity?: number
  /** Ambient occlusion, lower values mean less AO, hight more, you can mix AO and directional light, 0.5 */
  ambient?: number
  /** If the lights cast shadows, this is true by default */
  castShadow?: boolean
  /** Default shadow bias, 0 */
  bias?: number
  /** Default map size, 512 */
  mapSize?: number
  /** Default size of the shadow camera, 10 */
  size?: number
  /** Default shadow camera near, 0.5 */
  near?: number
  /** Default shadow camera far, 500 */
  far?: number
}

<RandomizedLight castShadow amount={8} frames={100} position={[5, 5, -10]} />

interface AccumulativeLightContext {
  /** Jiggles the lights */
  update: () => void;
}

export type ResizeProps = ThreeElements['group'] & {
  /** constrained by width dimension (x axis), undefined */
  width?: boolean
  /** constrained by height dimension (y axis), undefined */
  height?: boolean
  /** constrained by depth dimension (z axis), undefined */
  depth?: boolean
  /** You can optionally pass the Box3, otherwise will be computed, undefined */
  box3?: THREE.Box3
  /** See https://threejs.org/docs/index.html?q=box3#api/en/math/Box3.setFromObject */
  precise?: boolean
}

<Resize>
  <mesh />
</Resize>

<Resize height>
  <Box args={[70, 40, 20]}>
</Resize>

<mesh>
  <geometry />
  <material transparent opacity={0.5} />

  <ShadowAlpha
    opacity={undefined} // number. Override the opacity of the shadow.
    alphaMap={undefined} // THREE.Texture. Override the alphaMap of the shadow
  />
</mesh>

<Shadow
  color="black"
  colorStop={0}
  opacity={0.5}
  fog={false} // Reacts to fog (default=false)
/>

<Sky distance={450000} sunPosition={[0, 1, 0]} inclination={0} azimuth={0.25} {...props} />

<Sparkles
  /** Number of particles (default: 100) */
  count?: number
  /** Speed of particles (default: 1) */
  speed?: number | Float32Array
  /** Opacity of particles (default: 1) */
  opacity?: number | Float32Array
  /** Color of particles (default: 100) */
  color?: THREE.ColorRepresentation | Float32Array
  /** Size of particles (default: randomized between 0 and 1) */
  size?: number | Float32Array
  /** The space the particles occupy (default: 1) */
  scale?: number | [number, number, number] | THREE.Vector3
  /** Movement factor (default: 1) */
  noise?: number | [number, number, number] | THREE.Vector3 | Float32Array
/>

attribute float size;
attribute float speed;
attribute float opacity;
attribute vec3 noise;
attribute vec3 color;

{ "time": 0, "pixelRatio": 1 }

<SpotLight>
  <SpotLightShadow
    distance={0.4} // Distance between the shadow caster and light
    alphaTest={0.5} // Sets the alpha value to be used when running an alpha test. See Material.alphaTest
    scale={1} //  Scale of the shadow caster plane
    map={undefined} // Texture - Pattern of the shadow
    shader={undefined} // Optional shader to run. Lets you add effects to the shadow map. See bellow
    width={512} // Width of the shadow map. The higher the more expnsive
    height={512} // Height of the shadow map. The higher the more expnsive
  />
</SpotLight>

gl_FragColor = vec4(vec3(1.), 1.); // Opaque
gl_FragColor = vec4(vec3(0.), 1.); // Transparent

<SpotLight
  distance={5}
  angle={0.15}
  attenuation={5}
  anglePower={5} // Diffuse-cone anglePower (default: 5)
/>

function Foo() {
  const depthBuffer = useDepthBuffer()
  return <SpotLight depthBuffer={depthBuffer} />

type StageProps = {
  /** Lighting setup, default: "rembrandt" */
  preset?:
    | 'rembrandt'
    | 'portrait'
    | 'upfront'
    | 'soft'
    | { main: [x: number, y: number, z: number]; fill: [x: number, y: number, z: number] }
  /** Controls the ground shadows, default: "contact" */
  shadows?: boolean | 'contact' | 'accumulative' | StageShadows
  /** Optionally wraps and thereby centers the models using <Bounds>, can also be a margin, default: true */
  adjustCamera?: boolean | number
  /** The default environment, default: "city" */
  environment?: PresetsType | Partial<EnvironmentProps>
  /** The lighting intensity, default: 0.5 */
  intensity?: number
  /** To adjust centering, default: undefined */
  center?: Partial<CenterProps>
}

type StageShadows = Partial<AccumulativeShadowsProps> &
  Partial<RandomizedLightProps> &
  Partial<ContactShadowsProps> & {
    type: 'contact' | 'accumulative'
    /** Shadow plane offset, default: 0 */
    offset?: number
    /** Shadow bias, default: -0.0001 */
    bias?: number
    /** Shadow normal bias, default: 0 */
    normalBias?: number
    /** Shadow map size, default: 1024 */
    size?: number
  }

<Stage adjustCamera intensity={0.5} shadows="contact" environment="city">
  <mesh />
</Stage>

<Canvas shadows>
  <Stage shadows="accumulative">
    <mesh castShadow />
  </Stage>
</Canvas>

<Stars radius={100} depth={50} count={5000} factor={4} saturation={0} fade speed={1} />

export type EnvironmentLoaderProps = {
  files?: string | string[]
  path?: string
  preset?: PresetsType
  extensions?: (loader: Loader) => void
  encoding?: TextureEncoding

const cubeTexture = useEnvironment()

const presetTexture = useEnvironment({ preset: 'city' })
const rgbeTexture = useEnvironment({ files: 'model.hdr' })
const cubeTexture = useEnvironment({ files: ['px', 'nx', 'py', 'ny', 'pz', 'nz'].map((n) => `${n}.png`) })

useEnvironment.preload({ preset: 'city' })
useEnvironment.preload({ files: 'model.hdr' })
useEnvironment.preload({ files: ['px', 'nx', 'py', 'ny', 'pz', 'nz'].map((n) => `${n}.png`) })

useEnvironment.clear({ preset: 'city' })
useEnvironment.clear({ files: 'model.hdr' })
useEnvironment.clear({ files: ['px', 'nx', 'py', 'ny', 'pz', 'nz'].map((n) => `${n}.png`) })