pmndrs / react-ogl Goto Github PK

<Canvas
  // Configures the react rendering mode. Defaults to `blocking`
  mode={"legacy" | "blocking" | "concurrent"}
  // Creates, sets, or configures the default renderer.
  // Accepts a callback, an external renderer, or renderer constructor params/properties.
  // Defaults to `new OGL.Renderer({ alpha: true, antialias: true, powerPreference: 'high-performance' })
  renderer={(canvas: HTMLCanvasElement) => new Renderer(canvas) | renderer | { ...params, ...props }}
  // Sets the renderer pixel ratio from a clamped range or value. Default is `[1, 2]`
  dpr={[min, max] | value}
  // Sets or configures the default camera.
  // Accepts an external camera, or camera constructor params/properties.
  // Defaults to `new OGL.Camera(gl, { fov: 75, near: 1, far: 1000 })` with position-z `5`
  camera={camera | { ...params, ...props }}
  // Enables orthographic projection when using OGL's built-in camera. Default is `false`
  orthographic={true | false}
  // Defaults to `always`
  frameloop={'always' | 'never'}
  // An optional callback invoked after canvas creation and before commit.
  onCreated={(state: RootState) => void}
  // Optionally configures custom events. Defaults to built-in events exported as `events`
  events={EventManager | undefined}
>
  {/* Accepts OGL elements as children */}
  <transform />
</Canvas>

// e.g.

<Canvas
  renderer={{ alpha: true }}
  camera={{ fov: 45, position: [0, 1.3, 3] }}
  onCreated={(state) => void state.gl.clearColor(1, 1, 1, 0)}
>
  <transform />
</Canvas>

import { OGLElement, extend } from 'react-ogl'

class CustomElement {}

declare module 'react-ogl' {
  interface OGLElements {
    customElement: OGLElement<typeof CustomElement>
  }
}

extend({ CustomElement })

interface RootState {
  // Zustand setter and getter for live state manipulation.
  // See https://github.com/pmndrs/zustand
  get(): RootState
  set(fn: (previous: RootState) => (next: Partial<RootState>)): void
  // Canvas layout information
  size: { width: number; height: number }
  // OGL scene internals
  renderer: OGL.Renderer
  gl: OGL.OGLRenderingContext
  scene: OGL.Transform
  camera: OGL.Camera
  // OGL perspective and frameloop preferences
  orthographic: boolean
  frameloop: 'always' | 'never'
  // Internal XR manager to enable WebXR features
  xr: XRManager
  // Frameloop internals for custom render loops
  priority: number
  subscribed: React.MutableRefObject<Subscription>[]
  subscribe: (refCallback: React.MutableRefObject<Subscription>, renderPriority?: number) => void
  unsubscribe: (refCallback: React.MutableRefObject<Subscription>, renderPriority?: number) => void
  // Optional canvas event manager and its state
  events?: EventManager
  mouse: OGL.Vec2
  raycaster: OGL.Raycast
  hovered: Map<number, Instance<OGL.Mesh>['object']>
}

const { renderer, gl, scene, camera, ... } = useOGL()

const renderer = useOGL((state) => state.renderer)

const object = React.useRef<OGL.Transform>(null!)

useFrame((state: RootState, time: number, frame?: XRFrame) => {
  object.current.rotation.x = time / 2000
  object.current.rotation.y = time / 1000
})

return <transform ref={object} />

class CustomLoader {
  async load(gl: OGLRenderingContext, url: string): Promise<void> {}
}

const result = useLoader(CustomLoader, '/path/to/resource')

const { nodes, programs } = useGraph(object)

<mesh geometry={nodes['Foo'].geometry} program={programs['Bar']} />

const store = useStore()
React.useLayoutEffect(() => store.subscribe(state => ...), [store])

const ref = React.useRef<OGL.Transform>()
const instance = useInstanceHandle(ref)

React.useLayoutEffect(() => {
  instance.parent.object.foo()
}, [])

<transform ref={ref} />

<mesh
  // Fired when the mesh is clicked or tapped.
  onClick={(event: OGLEvent<MouseEvent>) => ...}
  // Fired when a pointer becomes inactive over the mesh.
  onPointerUp={(event: OGLEvent<PointerEvent>) => ...}
  // Fired when a pointer becomes active over the mesh.
  onPointerDown={(event: OGLEvent<PointerEvent>) => ...}
  // Fired when a pointer moves over the mesh.
  onPointerMove={(event: OGLEvent<PointerEvent>) => ...}
  // Fired when a pointer enters the mesh's bounds.
  onPointerOver={(event: OGLEvent<PointerEvent>) => ...}
  // Fired when a pointer leaves the mesh's bounds.
  onPointerOut={(event: OGLEvent<PointerEvent>) => ...}
/>

{
  nativeEvent: PointerEvent | MouseEvent,
  localPoint: Vec3,
  distance: number,
  point: Vec3,
  faceNormal: Vec3,
  localFaceNormal: Vec3,
  uv: Vec2,
  localNormal: Vec3,
  normal: Vec3,
}

const events: EventManager = {
  connected: false,
  connect(canvas: HTMLCanvasElement, state: RootState) {
    // Bind handlers
  },
  disconnect(canvas: HTMLCanvasElement, state: RootState) {
    // Cleanup
  },
}

<Canvas events={events}>
  <mesh onPointerMove={(event: OGLEvent<PointerEvent>) => console.log(event)}>
    <box />
    <normalProgram />
  </mesh>
</Canvas>

function Component {
  // scene & camera are inherited from portal parameters
  const { scene, camera, ... } = useOGL()
}

const scene = new OGL.Transform()
const camera = new OGL.Camera()

<transform>
  {createPortal(<Component />, scene, { camera })
</transform>

import * as React from 'react'
import * as OGL from 'ogl'
import { type Root, type RootStore, type RootState, createRoot, act } from 'react-ogl'

it('tests against a react-ogl component or scene', async () => {
  const transform = React.createRef<OGL.Transform>()

  const root: Root = createRoot(document.createElement('canvas'))
  const store: RootStore = await act(async () => root.render(<transform ref={transform} />))
  const state: RootState = store.getState()

  expect(transform.current).toBeInstanceOf(OGL.Transform)
  expect(state.scene.children).toStrictEqual([transform.current])
})