This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 55).

For the complete documentation index, see llms.txt. Use this Use this file to discover all available pages.

expo-gl 提供了一个 View，它充当 OpenGL ES 渲染目标，适用于渲染 2D 和 3D 图形。挂载时，会创建一个 OpenGL ES 上下文。其绘图缓冲区会在每一帧作为 View 的内容呈现出来。

安装

If you are installing this in an existing React Native app, make sure to install expo in your project.

用法

import { View } from 'react-native';
import { GLView } from 'expo-gl';

export default function App() {
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <GLView style={{ width: 300, height: 300 }} onContextCreate={onContextCreate} />
    </View>
  );
}

function onContextCreate(gl) {
  gl.viewport(0, 0, gl.drawingBufferWidth, gl.drawingBufferHeight);
  gl.clearColor(0, 1, 1, 1);

  // 创建顶点着色器（形状和位置）
  const vert = gl.createShader(gl.VERTEX_SHADER);
  gl.shaderSource(
    vert,
    `
    void main(void) {
      gl_Position = vec4(0.0, 0.0, 0.0, 1.0);
      gl_PointSize = 150.0;
    }
  `
  );
  gl.compileShader(vert);

  // 创建片段着色器（颜色）
  const frag = gl.createShader(gl.FRAGMENT_SHADER);
  gl.shaderSource(
    frag,
    `
    void main(void) {
      gl_FragColor = vec4(0.0, 0.0, 0.0, 1.0);
    }
  `
  );
  gl.compileShader(frag);

  // 组合链接成一个程序
  const program = gl.createProgram();
  gl.attachShader(program, vert);
  gl.attachShader(program, frag);
  gl.linkProgram(program);
  gl.useProgram(program);

  gl.clear(gl.COLOR_BUFFER_BIT);
  gl.drawArrays(gl.POINTS, 0, 1);

  gl.flush();
  gl.endFrameEXP();
}

高级 API

由于 WebGL API 相当底层，使用底层的 GLView 来渲染时，借助更高级别的图形 API 会更方便。以下库集成了常见的图形 API：

• expo-three 用于 three.js
• expo-processing 用于 Processing

任何支持 WebGL、并且期望使用 WebGLRenderingContext 的库都可以使用。有时这类库会假设 Web 端的 JavaScript 环境（例如假设存在 document）。通常这只是用于资源加载或事件处理，而主要渲染逻辑仍然只使用纯 WebGL。因此，这些库通常仍可通过一些变通方法使用。上面这些 Expo 特定的集成已经为一些常见库提供了这些变通方法。

与 Reanimated worklet 集成

要在 Reanimated worklet 中使用此 API，你需要将 GL 上下文 ID 传递给 worklet，并像下面的示例一样重新创建 GL 对象。

import { View } from 'react-native';
import { runOnUI } from 'react-native-reanimated';
import { GLView } from 'expo-gl';

function render(gl) {
  'worklet';
  // 在这里添加你的 WebGL 代码
}

function onContextCreate(gl) {
  runOnUI((contextId: number) => {
    'worklet';
    const gl = GLView.getWorkletContext(contextId);
    render(gl);
  })(gl.contextId);
}

export default function App() {
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <GLView
        style={{ width: 300, height: 300 }}
        enableExperimentalWorkletSupport
        onContextCreate={onContextCreate}
      />
    </View>
  );
}

如果你想了解如何在 Reanimated 和 Gesture Handler 中使用 expo-gl 的更深入示例，可以查看这个示例。

限制

Worklet 运行时对在其中运行的代码施加了一些限制，因此如果你已经有现成的 WebGL 代码，很可能需要做一些修改才能在 worklet 线程中运行。

• 像 Pixi.js 或 Three.js 这样的第三方库无法在 worklet 中使用，你只能使用在开头添加了 'worklet' 的函数。
• 如果你需要加载一些资源传递给 WebGL 代码，需要在主线程中完成，并通过某种引用传递给 worklet。如果你使用的是 expo-assets，你可以直接将由 Asset.fromModule 返回的资源对象，或通过 hook useAssets 获取的资源对象，传递给 runOnUI 函数。
• 要实现渲染循环，你需要使用 requestAnimationFrame，像 setTimeout 这样的 API 不受支持。

更多信息请查看Reanimated 文档。

远程调试与 GLView

在启用远程调试时，此 API 无法按预期工作。React Native 调试器会在你的电脑上运行 JavaScript，而不是在移动设备上。GLView 需要同步的原生调用，而这些在 Chrome 中不受支持。

API

import { GLView } from 'expo-gl';

Component

Static Methods

Component Methods

Methods

Interfaces

Types

Enums

WebGL API

组件挂载并且 OpenGL ES 上下文创建完成后，通过 onContextCreate 属性接收的 gl 对象就会成为 OpenGL ES 上下文的接口，并提供 WebGL API。它类似于 WebGL 2 规范中的 WebGL2RenderingContext。

某些较旧的 Android 设备可能不支持 WebGL2 功能。要检查设备是否支持 WebGL2，建议使用 gl instanceof WebGL2RenderingContext。

还提供了一个额外的方法 gl.endFrameEXP()，它会通知上下文当前帧已准备好呈现。这类似于其他 OpenGL 平台中的“交换缓冲区”API 调用。

以下 WebGL2RenderingContext 方法目前未实现：

• getFramebufferAttachmentParameter()
• getRenderbufferParameter()
• compressedTexImage2D()
• compressedTexSubImage2D()
• getTexParameter()
• getUniform()
• getVertexAttrib()
• getVertexAttribOffset()
• getBufferSubData()
• getInternalformatParameter()
• renderbufferStorageMultisample()
• compressedTexImage3D()
• compressedTexSubImage3D()
• fenceSync()
• isSync()
• deleteSync()
• clientWaitSync()
• waitSync()
• getSyncParameter()
• getActiveUniformBlockParameter()

texImage2D() 的 pixels 参数必须是 null、包含像素数据的 ArrayBuffer，或形如 { localUri } 的对象，其中 localUri 是设备文件系统中某个图像的 file:// URI。因此，在调用 .downloadAsync() 并完成后，会使用 Asset 对象来获取资源。

出于效率考虑，当前这些方法的实现不会对其参数执行类型或边界检查。因此，传入无效参数可能会导致原生崩溃。计划在未来的 SDK 版本中更新 API，以进行参数检查。

目前，错误检查的优先级较低，因为引擎通常并不依赖 OpenGL API 来执行参数检查；否则，由底层 OpenGL ES 实现执行的检查通常已经足够。