访问官网
Github
文档
Table of Contents
Installation
# 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 API with some helpers targeted for different platforms:
react-dom
This example uses create-react-app for the sake of simplicity, but you can use your own environment or create a codesandbox.
Show full example
# 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.
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 (
<mesh
{...props}
ref={mesh}
scale={active ? 1.5 : 1}
onClick={() => setActive((value) => !value)}
onPointerOver={() => setHover(true)}
onPointerOut={() => setHover(false)}
>
<box />
<program
vertex={`
attribute vec3 position;
attribute vec3 normal;
uniform mat4 modelViewMatrix;
uniform mat4 projectionMatrix;
uniform mat3 normalMatrix;
varying vec3 vNormal;
void main() {
vNormal = normalize(normalMatrix * normal);
gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
}
`}
fragment={`
precision highp float;
uniform vec3 uColor;
varying vec3 vNormal;
void main() {
vec3 normal = normalize(vNormal);
float lighting = dot(normal, normalize(vec3(10)));
gl_FragColor.rgb = uColor + lighting * 0.1;
gl_FragColor.a = 1.0;
}
`}
uniforms={{ uColor: hovered ? 'hotpink' : 'orange' }}
/>
</mesh>
)
}
createRoot(document.getElementById('root')).render(
<Canvas camera={{ position: [0, 0, 8] }}>
<Box position={[-1.2, 0, 0]} />
<Box position={[1.2, 0, 0]} />
</Canvas>,
)
react-native
This example uses expo-cli but you can create a bare app with react-native CLI as well.
Show full example
# 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.
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.
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 (
<mesh
{...props}
ref={mesh}
scale={active ? 1.5 : 1}
onClick={() => setActive((value) => !value)}
onPointerOver={() => setHover(true)}
onPointerOut={() => setHover(false)}
>
<box />
<program
vertex={`
attribute vec3 position;
attribute vec3 normal;
uniform mat4 modelViewMatrix;
uniform mat4 projectionMatrix;
uniform mat3 normalMatrix;
varying vec3 vNormal;
void main() {
vNormal = normalize(normalMatrix * normal);
gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
}
`}
fragment={`
precision highp float;
uniform vec3 uColor;
varying vec3 vNormal;
void main() {
vec3 normal = normalize(vNormal);
float lighting = dot(normal, normalize(vec3(10)));
gl_FragColor.rgb = uColor + lighting * 0.1;
gl_FragColor.a = 1.0;
}
`}
uniforms={{ uColor: hovered ? 'hotpink' : 'orange' }}
/>
</mesh>
)
}
export default () => (
<Canvas camera={{ position: [0, 0, 8] }}>
<Box position={[-1.2, 0, 0]} />
<Box position={[1.2, 0, 0]} />
</Canvas>
)
Canvas
react-ogl provides an x-platform <Canvas /> 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).
Canvas Props
In addition to its platform props, <Canvas /> accepts a set of RenderProps to configure react-ogl and its rendering behavior.
<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>
Custom Canvas
A react 18 style createRoot API creates an imperative Root with the same options as <Canvas />, but you're responsible for updating it and configuring things like events (see 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).
import { createRoot, events } from 'react-ogl'
const canvas = document.querySelector('canvas')
const root = createRoot(canvas, { events })
root.render(
<mesh>
<box />
<normalProgram />
</mesh>,
)
root.unmount()
createRoot can also be used to create a custom <Canvas />. The following constructs a custom canvas that renders its children into react-ogl.
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 <canvas ref={setCanvas} />
}
Creating elements
react-ogl renders React components into an OGL scene-graph, and can be used on top of other renderers like react-dom and 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).
function Component(props) {
return (
<mesh {...props}>
<box />
<normalProgram />
</mesh>
)
}
;<transform>
<Component position={[1, 2, 3]} />
</transform>
These elements are not exported or implemented internally, but merely expressed as JSX — <mesh /> 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.
<transform
// Set non-atomic properties with literals
// transform.visible = false
visible={false}
// Copy atomic properties with a stable reference (e.g. useMemo)
// transform.rotation.copy(rotation)
rotation={rotation}
// Set atomic properties with declarative array syntax
// transform.position.set(1, 2, 3)
position={[1, 2, 3]}
// Set scalars with shorthand for vector properties
// transform.scale.set(1, 1, 1)
scale={1}
// Set CSS names or hex values as shorthand for color properties
// transform.color.set('red')
color="red"
// Set sub properties with prop piercing or dash-case
// transform.rotation.x = Math.PI / 2
rotation-x={Math.PI / 2}
/>
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.
// new OGL.Text({ font, text: 'Text' })
<text args={[{ font, text: 'Text' }]} />
Built-in elements that require a gl context such as <mesh />, <geometry />, or <program /> are marked as effectful (see extend) and do not require an OGLRenderingContext to be passed via args. They can be constructed mutably and manipulated via props:
<mesh>
<box />
<normalProgram />
</mesh>
<geometry /> and <program /> 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.
<mesh>
<geometry
position={{ size: 3, data: new Float32Array([-0.5, 0.5, 0, -0.5, -0.5, 0, 0.5, 0.5, 0, 0.5, -0.5, 0]) }}
uv={{ size: 2, data: new Float32Array([0, 1, 1, 1, 0, 0, 1, 0]) }}
index={{ data: new Uint16Array([0, 1, 2, 1, 3, 2]) }}
/>
{/* prettier-ignore */}
<program
vertex={/* glsl */ `...`}
fragment={/* glsl */ `...`}
uniforms={{ uniform: value }}
/>
</mesh>
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.
// Attaches into parent.property, parent.sub.property, and parent.array[0]
<parent>
<element attach="property" />
<element attach="sub-property" />
<element attach="array-0" />
</parent>
// Attaches via parent#setProperty and parent#removeProperty
<parent>
<element
attach={(parent, self) => {
parent.setProperty(self)
return () => parent.removeProperty(self)
}}
// lambda version
