Project Icon

react-ogl

React渲染器实现OGL场景的声明式构建

react-ogl是一个轻量级React渲染器,用于构建OGL场景。它支持以声明式方式创建可复用的场景组件,这些组件可响应状态变化并参与React生态系统。react-ogl能将JSX直接转换为OGL元素,无需额外包装,简化了3D图形开发流程。其简约设计和模块化架构为开发者提供了灵活高效的开发体验。

Size Version Downloads Twitter Discord

Build OGL scenes declaratively with re-usable, self-contained components that react to state, are readily interactive and can participate in React's ecosystem.

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

# 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
  
项目侧边栏1项目侧边栏2
推荐项目
Project Cover

豆包MarsCode

豆包 MarsCode 是一款革命性的编程助手,通过AI技术提供代码补全、单测生成、代码解释和智能问答等功能,支持100+编程语言,与主流编辑器无缝集成,显著提升开发效率和代码质量。

Project Cover

问小白

问小白是一个基于 DeepSeek R1 模型的智能对话平台,专为用户提供高效、贴心的对话体验。实时在线,支持深度思考和联网搜索。免费不限次数,帮用户写作、创作、分析和规划,各种任务随时完成!

Project Cover

白日梦AI

白日梦AI提供专注于AI视频生成的多样化功能,包括文生视频、动态画面和形象生成等,帮助用户快速上手,创造专业级内容。

Project Cover

有言AI

有言平台提供一站式AIGC视频创作解决方案,通过智能技术简化视频制作流程。无论是企业宣传还是个人分享,有言都能帮助用户快速、轻松地制作出专业级别的视频内容。

Project Cover

讯飞绘镜

讯飞绘镜是一个支持从创意到完整视频创作的智能平台,用户可以快速生成视频素材并创作独特的音乐视频和故事。平台提供多样化的主题和精选作品,帮助用户探索创意灵感。

Project Cover

讯飞文书

讯飞文书依托讯飞星火大模型,为文书写作者提供从素材筹备到稿件撰写及审稿的全程支持。通过录音智记和以稿写稿等功能,满足事务性工作的高频需求,帮助撰稿人节省精力,提高效率,优化工作与生活。

Project Cover

阿里绘蛙

绘蛙是阿里巴巴集团推出的革命性AI电商营销平台。利用尖端人工智能技术,为商家提供一键生成商品图和营销文案的服务,显著提升内容创作效率和营销效果。适用于淘宝、天猫等电商平台,让商品第一时间被种草。

Project Cover

Trae

Trae是一种自适应的集成开发环境(IDE),通过自动化和多元协作改变开发流程。利用Trae,团队能够更快速、精确地编写和部署代码,从而提高编程效率和项目交付速度。Trae具备上下文感知和代码自动完成功能,是提升开发效率的理想工具。

Project Cover

AIWritePaper论文写作

AIWritePaper论文写作是一站式AI论文写作辅助工具,简化了选题、文献检索至论文撰写的整个过程。通过简单设定,平台可快速生成高质量论文大纲和全文,配合图表、参考文献等一应俱全,同时提供开题报告和答辩PPT等增值服务,保障数据安全,有效提升写作效率和论文质量。

投诉举报邮箱: service@vectorlightyear.com
@2024 懂AI·鲁ICP备2024100362号-6·鲁公网安备37021002001498号