Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pmndrs/react-ogl
ðĶī A barebones react renderer for ogl.
https://github.com/pmndrs/react-ogl
ogl react renderer shaders webgl webxr
Last synced: 4 days ago
JSON representation
ðĶī A barebones react renderer for ogl.
- Host: GitHub
- URL: https://github.com/pmndrs/react-ogl
- Owner: pmndrs
- License: mit
- Created: 2021-11-04T12:15:09.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-07-02T07:57:24.000Z (6 months ago)
- Last Synced: 2024-10-29T15:32:07.586Z (2 months ago)
- Topics: ogl, react, renderer, shaders, webgl, webxr
- Language: TypeScript
- Homepage: https://npmjs.com/react-ogl
- Size: 2.28 MB
- Stars: 196
- Watchers: 10
- Forks: 8
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
[](https://bundlephobia.com/package/react-ogl)
[](https://npmjs.com/package/react-ogl)
[](https://npmjs.com/package/react-ogl)
[](https://twitter.com/pmndrs)
[](https://discord.gg/poimandres)
![Build OGL scenes declaratively with re-usable, self-contained components that react to state, are readily interactive and can participate in React's ecosystem.</p>
<p>react-ogl is a barebones react renderer for OGL with an emphasis on minimalism and modularity. Its reconciler simply expresses JSX as OGL elements â <mesh /> becomes new OGL.Mesh(). This happens dynamically; there's no wrapper involved.]()
## Table of Contents
- [Installation](#installation)
- [Getting Started](#getting-started)
- [react-dom](#react-dom)
- [react-native](#react-native)
- [Canvas](#canvas)
- [Canvas Props](#canvas-props)
- [Custom Canvas](#custom-canvas)
- [Creating Elements](#creating-elements)
- [JSX, properties, and shortcuts](#jsx-properties-and-shortcuts)
- [Setting constructor arguments via `args`](#setting-constructor-arguments-via-args)
- [Attaching into element properties via `attach`](#attaching-into-element-properties-via-attach)
- [Creating custom elements via `extend`](#creating-custom-elements-via-extend)
- [Adding third-party objects via ``](#adding-third-party-objects-via-primitive-)
- [Hooks](#hooks)
- [Root State](#root-state)
- [Accessing state via `useOGL`](#accessing-state-via-useogl)
- [Frameloop subscriptions via `useFrame`](#frameloop-subscriptions-via-useframe)
- [Loading assets via `useLoader`](#loading-assets-via-useloader)
- [Object traversal via `useGraph`](#object-traversal-via-usegraph)
- [Transient updates via `useStore`](#transient-updates-via-usestore)
- [Access internals via `useInstanceHandle`](#access-internals-via-useinstancehandle)
- [Events](#events)
- [Custom Events](#custom-events)
- [Portals](#portals)
- [Testing](#testing)
## Installation
```bash
# NPM
npm install ogl react-ogl
# Yarn
yarn add ogl react-ogl
# PNPM
pnpm add ogl react-ogl
```
## Getting Started
react-ogl itself is super minimal, but you can use the familiar [@react-three/fiber](https://github.com/pmndrs/react-three-fiber) API with some helpers targeted for different platforms:
### react-dom
This example uses [`create-react-app`](https://reactjs.org/docs/create-a-new-react-app.html#create-react-app) for the sake of simplicity, but you can use your own environment or [create a codesandbox](https://react.new).
Show full example
```bash
# Create app
npx create-react-app my-app
cd my-app
# Install dependencies
npm install ogl react-ogl
# Start
npm run start
```
The following creates a re-usable component that has its own state, reacts to events and participates a shared render-loop.
```jsx
import * as React from 'react'
import { useFrame, Canvas } from 'react-ogl'
import { createRoot } from 'react-dom/client'
function Box(props) {
// This reference will give us direct access to the mesh
const mesh = React.useRef()
// Set up state for the hovered and active state
const [hovered, setHover] = React.useState(false)
const [active, setActive] = React.useState(false)
// Subscribe this component to the render-loop, rotate the mesh every frame
useFrame(() => (mesh.current.rotation.x += 0.01))
// Return view, these are regular OGL elements expressed in JSX
return (
setActive((value) => !value)}
onPointerOver={() => setHover(true)}
onPointerOut={() => setHover(false)}
>
)
}
createRoot(document.getElementById('root')).render(
,
)
```
### react-native
This example uses [`expo-cli`](https://docs.expo.dev/get-started/create-a-new-app) but you can create a bare app with `react-native` CLI as well.
Show full example
```bash
# Create app and cd into it
npx expo init my-app # or npx react-native init my-app
cd my-app
# Automatically install & link expo modules
npx install-expo-modules@latest
expo install expo-gl
# Install NPM dependencies
npm install ogl react-ogl
# Start
npm run start
```
We'll also need to configure `metro.config.js` to look for the mjs file extension that OGL uses.
```js
module.exports = {
resolver: {
resolverMainFields: ['browser', 'exports', 'main'], // https://github.com/facebook/metro/issues/670
sourceExts: ['json', 'js', 'jsx', 'ts', 'tsx', 'cjs', 'mjs'],
assetExts: ['glb', 'gltf', 'png', 'jpg'],
},
}
```
Inside of our app, you can use the same API as web while running on native OpenGL ES â no webview needed.
```js
import * as React from 'react'
import { useFrame, Canvas } from 'react-ogl'
function Box(props) {
// This reference will give us direct access to the mesh
const mesh = React.useRef()
// Set up state for the hovered and active state
const [hovered, setHover] = React.useState(false)
const [active, setActive] = React.useState(false)
// Subscribe this component to the render-loop, rotate the mesh every frame
useFrame(() => (mesh.current.rotation.x += 0.01))
// Return view, these are regular OGL elements expressed in JSX
return (
setActive((value) => !value)}
onPointerOver={() => setHover(true)}
onPointerOut={() => setHover(false)}
>
)
}
export default () => (
)
```
## Canvas
react-ogl provides an x-platform `` component for web and native that serves as the entrypoint for your OGL scenes. It is a real DOM canvas or native view that accepts OGL elements as children (see [creating elements](#creating-elements)).
### Canvas Props
In addition to its platform props, `` accepts a set of `RenderProps` to configure react-ogl and its rendering behavior.
```tsx
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 */}
// e.g.
void state.gl.clearColor(1, 1, 1, 0)}
>
```
### Custom Canvas
A react 18 style `createRoot` API creates an imperative `Root` with the same options as ``, but you're responsible for updating it and configuring things like events (see [events](#events)). This root attaches to an `HTMLCanvasElement` and renders OGL elements into a scene. Useful for creating an entrypoint with react-ogl and for headless contexts like a server or testing (see [testing](#testing)).
```jsx
import { createRoot, events } from 'react-ogl'
const canvas = document.querySelector('canvas')
const root = createRoot(canvas, { events })
root.render(
,
)
root.unmount()
```
`createRoot` can also be used to create a custom ``. The following constructs a custom canvas that renders its children into react-ogl.
```jsx
import * as React from 'react'
import { createRoot, events } from 'react-ogl'
function CustomCanvas({ children }) {
// Init root from canvas
const [canvas, setCanvas] = React.useState()
const root = React.useMemo(() => canvas && createRoot(canvas, { events }), [canvas])
// Render children as a render-effect
root?.render(children)
// Cleanup on unmount
React.useEffect(() => () => root?.unmount(), [root])
// Use callback-style ref to access canvas in render
return
}
```
## Creating elements
react-ogl renders React components into an OGL scene-graph, and can be used on top of other renderers like [react-dom](https://npmjs.com/react-dom) and [react-native](https://npmjs.com/react-native) that render for web and native, respectively. react-ogl components are defined by primitives or lower-case elements native to the OGL namespace (for custom elements, see [extend](#creating-custom-elements-via-extend)).
```jsx
function Component(props) {
return (
)
}
;
```
These elements are not exported or implemented internally, but merely expressed as JSX â `` becomes `new OGL.Mesh()`. This happens dynamically; there's no wrapper involved.
### JSX, properties, and shortcuts
react-ogl elements can be modified with JSX attributes or props. These are native to their underlying OGL objects.
```jsx
```
### Setting constructor arguments via `args`
An array of constructor arguments (`args`) can be passed to instantiate elements' underlying OGL objects. Changing `args` will reconstruct the object and update any associated refs.
```jsx
// new OGL.Text({ font, text: 'Text' })
```
Built-in elements that require a `gl` context such as ``, ``, or `` are marked as effectful (see [extend](#creating-custom-elements-via-extend)) and do not require an `OGLRenderingContext` to be passed via `args`. They can be constructed mutably and manipulated via props:
```jsx
```
`` and `` also accept attributes and shader sources as props, which are passed to their respective constructors. This does not affect other properties like `drawRange` or `uniforms`.
```jsx
{/* prettier-ignore */}
```
### Attaching into element properties via `attach`
Some elements do not follow the traditional scene-graph and need to be added by other means. For this, the `attach` prop can describe where an element is added via a property or a callback to add & remove the element.
```jsx
// Attaches into parent.property, parent.sub.property, and parent.array[0]
// Attaches via parent#setProperty and parent#removeProperty
{
parent.setProperty(self)
return () => parent.removeProperty(self)
}}
// lambda version
attach={(parent, self) => (parent.setProperty(self), () => parent.removeProperty(self))}
/>
```
Elements who extend `OGL.Geometry` or `OGL.Program` will automatically attach via `attach="geometry"` and `attach="program"`, respectively.
```jsx
```
### Creating custom elements via `extend`
react-ogl tracks an internal catalog of constructable elements, defaulting to the OGL namespace. This catalog can be expanded via `extend` to declaratively use custom elements as native elements.
```jsx
import { extend } from 'react-ogl'
class CustomElement {}
extend({ CustomElement })
```
TypeScript users will need to extend the `OGLElements` interface to describe custom elements and their properties.
```tsx
import { OGLElement, extend } from 'react-ogl'
class CustomElement {}
declare module 'react-ogl' {
interface OGLElements {
customElement: OGLElement
}
}
extend({ CustomElement })
```
Effectful elements that require a `gl` context can mark themselves as effectful and receive a `OGLRenderingContext` when constructed, making args mutable and enabling the use of props. This is done for OGL built-in elements like ``, ``, and ``.
```jsx
import { extend } from 'react-ogl'
class CustomElement {
constructor(gl) {
this.gl = gl
}
}
extend({ CustomElement }, true)
```
### Adding third-party objects via ``
Objects created outside of React (e.g. globally or from a loader) can be added to the scene-graph with the `` element via its `object` prop. Primitives can be interacted with like any other element, but will modify `object` and cannot make use of `args`.
```jsx
import * as OGL from 'ogl'
const object = new OGL.Transform()
```
## Hooks
react-ogl ships with hooks that allow you to tie or request information to your components. These are called within the body of `` and contain imperative and possibly stateful code.
### Root State
Each `` or `Root` encapsulates its own OGL state via [React context](https://reactjs.org/docs/context.html) and a [Zustand](https://github.com/pmndrs/zustand) store, as defined by `RootState`. This can be accessed and modified with the `onCreated` canvas prop, and with hooks like `useOGL`.
```tsx
interface RootState {
// Zustand setter and getter for live state manipulation.
// See https://github.com/pmndrs/zustand
get(): RootState
set(fn: (previous: RootState) => (next: Partial)): 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[]
subscribe: (refCallback: React.MutableRefObject, renderPriority?: number) => void
unsubscribe: (refCallback: React.MutableRefObject, renderPriority?: number) => void
// Optional canvas event manager and its state
events?: EventManager
mouse: OGL.Vec2
raycaster: OGL.Raycast
hovered: Map['object']>
}
```
### Accessing state via `useOGL`
Returns the current canvas' `RootState`, describing react-ogl state and OGL rendering internals (see [root state](#root-state)).
```tsx
const { renderer, gl, scene, camera, ... } = useOGL()
```
To subscribe to a specific key, `useOGL` accepts a [Zustand](https://github.com/pmndrs/zustand) selector:
```tsx
const renderer = useOGL((state) => state.renderer)
```
### Frameloop subscriptions via `useFrame`
Subscribes an element into a shared render loop outside of React. `useFrame` subscriptions are provided a live `RootState`, the current RaF time in seconds, and a `XRFrame` when in a WebXR session. Note: `useFrame` subscriptions should never update React state but prefer external mechanisms like refs.
```tsx
const object = React.useRef(null!)
useFrame((state: RootState, time: number, frame?: XRFrame) => {
object.current.rotation.x = time / 2000
object.current.rotation.y = time / 1000
})
return
```
### Loading assets via `useLoader`
Synchronously loads and caches assets with a loader via suspense. Note: the caller component must be wrapped in `React.Suspense`.
```jsx
const texture = useLoader(OGL.TextureLoader, '/path/to/image.jpg')
```
Multiple assets can be requested in parallel by passing an array:
```jsx
const [texture1, texture2] = useLoader(OGL.TextureLoader, ['/path/to/image1.jpg', '/path/to/image2.jpg'])
```
Custom loaders can be implemented via the `LoaderRepresentation` signature:
```tsx
class CustomLoader {
async load(gl: OGLRenderingContext, url: string): Promise {}
}
const result = useLoader(CustomLoader, '/path/to/resource')
```
### Object traversal via `useGraph`
Traverses an `OGL.Transform` for unique meshes and programs, returning an `ObjectMap`.
```tsx
const { nodes, programs } = useGraph(object)
```
### Transient updates via `useStore`
Returns the internal [Zustand](https://github.com/pmndrs/zustand) store. Useful for transient updates outside of React (e.g. multiplayer/networking).
```tsx
const store = useStore()
React.useLayoutEffect(() => store.subscribe(state => ...), [store])
```
### Access internals via `useInstanceHandle`
Exposes an object's react-internal `Instance` state from a ref.
> **Note**: this is an escape hatch to react-internal fields. Expect this to change significantly between versions.
```tsx
const ref = React.useRef()
const instance = useInstanceHandle(ref)
React.useLayoutEffect(() => {
instance.parent.object.foo()
}, [])
```
## Events
react-ogl implements mesh pointer-events with `OGL.Raycast` that can be tapped into via the following props:
```tsx
) => ...}
// Fired when a pointer becomes inactive over the mesh.
onPointerUp={(event: OGLEvent) => ...}
// Fired when a pointer becomes active over the mesh.
onPointerDown={(event: OGLEvent) => ...}
// Fired when a pointer moves over the mesh.
onPointerMove={(event: OGLEvent) => ...}
// Fired when a pointer enters the mesh's bounds.
onPointerOver={(event: OGLEvent) => ...}
// Fired when a pointer leaves the mesh's bounds.
onPointerOut={(event: OGLEvent) => ...}
/>
```
Events contain the original event as `nativeEvent` and properties from `OGL.RaycastHit`.
```tsx
{
nativeEvent: PointerEvent | MouseEvent,
localPoint: Vec3,
distance: number,
point: Vec3,
faceNormal: Vec3,
localFaceNormal: Vec3,
uv: Vec2,
localNormal: Vec3,
normal: Vec3,
}
```
### Custom events
Custom events can be implemented per the `EventManager` interface and passed via the `events` Canvas prop.
```tsx
const events: EventManager = {
connected: false,
connect(canvas: HTMLCanvasElement, state: RootState) {
// Bind handlers
},
disconnect(canvas: HTMLCanvasElement, state: RootState) {
// Cleanup
},
}
) => console.log(event)}>
```
Full example
```tsx
const events = {
connected: false,
connect(canvas: HTMLCanvasElement, state: RootState) {
state.events.handlers = {
pointermove(event: PointerEvent) {
// Convert mouse coordinates
state.mouse.x = (event.offsetX / state.size.width) * 2 - 1
state.mouse.y = -(event.offsetY / state.size.height) * 2 + 1
// Filter to interactive meshes
const interactive: OGL.Mesh[] = []
state.scene.traverse((node: OGL.Transform) => {
// Mesh has registered events and a defined volume
if (
node instanceof OGL.Mesh &&
(node as Instance['object']).__handlers &&
node.geometry?.attributes?.position
)
interactive.push(node)
})
// Get elements that intersect with our pointer
state.raycaster!.castMouse(state.camera, state.mouse)
const intersects: OGL.Mesh[] = state.raycaster!.intersectMeshes(interactive)
// Call mesh handlers
for (const entry of intersects) {
if ((entry as unknown as any).__handlers) {
const object = entry as Instance['object']
const handlers = object.__handlers
const handlers = object.__handlers
handlers?.onPointerMove?.({ ...object.hit, nativeEvent: event })
}
}
},
}
// Bind
state.events.connected = true
for (const [name, handler] of Object.entries(state.events.handlers)) {
canvas.addEventListener(name, handler)
}
},
disconnect(canvas: HTMLCanvasElement, state: RootState) {
// Unbind
state.events.connected = false
for (const [name, handler] of Object.entries(state.events.handlers)) {
canvas.removeEventListener(name, handler)
}
},
}
) => console.log(event)}>
```
## Portals
Portal children into a foreign OGL element via `createPortal`, which can modify children's `RootState`. This is particularly useful for postprocessing and complex render effects.
```tsx
function Component {
// scene & camera are inherited from portal parameters
const { scene, camera, ... } = useOGL()
}
const scene = new OGL.Transform()
const camera = new OGL.Camera()
{createPortal(, scene, { camera })
```
## Testing
In addition to `createRoot` (see [custom canvas](#custom-canvas)), react-ogl exports an `act` method which can be used to safely flush async effects in tests. The following emulates a legacy root and asserts against `RootState` (see [root state](#root-state)).
```tsx
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()
const root: Root = createRoot(document.createElement('canvas'))
const store: RootStore = await act(async () => root.render())
const state: RootState = store.getState()
expect(transform.current).toBeInstanceOf(OGL.Transform)
expect(state.scene.children).toStrictEqual([transform.current])
})
```