首页指南参考教程

Expo GLView iconExpo GLView

提供 GLView 的库,充当 OpenGL ES 渲染目标并提供 GLContext。对于渲染 2D 和 3D 图形很有用。

Android
iOS
Web

expo-gl 提供了充当 OpenGL ES 渲染目标的 View,对于渲染 2D 和 3D 图形很有用。安装时,会创建 OpenGL ES 上下文。其绘图缓冲区每帧渲染为 View 的内容。

¥expo-gl provides a View that acts as an OpenGL ES render target, useful for rendering 2D and 3D graphics. On mounting, an OpenGL ES context is created. Its drawing buffer is presented as the contents of the View every frame.

安装

¥Installation

Terminal
npx expo install expo-gl

If you are installing this in an existing React Native app (bare workflow), start by installing expo in your project. Then, follow the additional instructions as mentioned by library's README under "Installation in bare React Native projects" section.

用法

¥Usage

Basic GL usage
import React from 'react';
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);

  // Create vertex shader (shape & position)
  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);

  // Create fragment shader (color)
  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);

  // Link together into a program
  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

¥High-level APIs

由于 WebGL API 的级别相当低,因此通过下面的 GLView 使用更高级别的图形 API 渲染会很有帮助。以下库集成了流行的图形 API:

¥Since the WebGL API is quite low-level, it can be helpful to use higher-level graphics APIs rendering through a GLView underneath. The following libraries integrate popular graphics APIs:

  • expo-threethree.js

    ¥expo-three for three.js

  • expo-processingprocessing.js

    ¥expo-processing for processing.js

任何需要 WebGLRenderingContext 的 WebGL 支持库都可以使用。有时,此类库会假设一个 Web JavaScript 上下文(例如假设 document)。通常这是为了资源加载或事件处理,主要渲染逻辑仍然只使用纯 WebGL。因此,这些库通常仍然可以通过一些解决方法来使用。上面针对 Expo 的集成包括一些流行库的解决方法。

¥Any WebGL-supporting library that expects a WebGLRenderingContext could be used. Some times such libraries assume a web JavaScript context (such as assuming document). Usually this is for resource loading or event handling, with the main rendering logic still only using pure WebGL. So these libraries can usually still be used with a couple workarounds. The Expo-specific integrations above include workarounds for some popular libraries.

与 Reanimated 工作集集成

¥Integration with Reanimated worklets

要在 Reanimated 工作集中使用此 API,你需要将 GL 上下文 ID 传递给工作集并重新创建 GL 对象,如下例所示。

¥To use this API inside Reanimated worklet, you need to pass the GL context ID to the worklet and recreate the GL object like in the example below.

GL usage in reanimated worklet
import React from 'react';
import { View } from 'react-native';
import { runOnUI } from 'react-native-reanimated';
import { GLView } from 'expo-gl';

function render(gl) {
  'worklet';
  // add your WebGL code here
}

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>
  );
}

有关如何将 expo-gl 与 Reanimated 和 Gesture Handler 一起使用的更深入示例,你可以查看 这个例子

¥For more in-depth example on how to use expo-gl with Reanimated and Gesture Handler you can check this example.

局限性

¥Limitations

Worklet 运行时对其内部运行的代码施加了一些限制,因此,如果你有现有的 WebGL 代码,则可能需要进行一些修改才能在 Worklet 线程内运行。

¥Worklet runtime is imposing some limitations on the code that runs inside it, so if you have existing WebGL code, it'll likely require some modifications to run inside a worklet thread.

  • Pixi.js 或 Three.js 等第三方库无法在工作集中运行,你只能使用开头添加了 'worklet' 的函数。

    ¥Third-party libraries like Pixi.js or Three.js won't work inside the worklet, you can only use functions that have 'worklet' added at the start.

  • 如果你需要加载一些资源以传递给 WebGL 代码,则需要在主线程上完成并通过对工作集的某些引用传递。如果你使用 expo-assets,则只需将 Asset.fromModule 返回的资源对象或从钩子 useAssets 传递到 runOnUI 函数即可。

    ¥If you need to load some assets to pass to the WebGL code, it needs to be done on the main thread and passed via some reference to the worklet. If you are using expo-assets you can just pass asset object returned by Asset.fromModule or from hook useAssets to the runOnUI function.

  • 要实现渲染循环,你需要使用 requestAnimationFrame,不支持像 setTimeout 这样的 API。

    ¥To implement a rendering loop you need to use requestAnimationFrame, APIs like setTimeout are not supported.

  • 它仅在 Android 和 iOS 上受支持,在 Web 上不起作用。

    ¥It's supported only on Android and iOS, it doesn't work on Web.

检查 复活的文档 以了解更多信息。

¥Check Reanimated documentation to learn more.

远程调试和 GLView

¥Remote debugging and GLView

启用远程调试后,此 API 无法按预期运行。React Native 调试器在你的计算机上运行 JavaScript,而不是在移动设备上。GLView 需要 Chrome 不支持的同步原生调用。

¥This API does not function as intended with remote debugging enabled. The React Native debugger runs JavaScript on your computer, not the mobile device. GLView requires synchronous native calls that are not supported in Chrome.

API

import { GLView } from 'expo-gl';

Component

GLView

Type: React.Component<GLViewProps>

A View that acts as an OpenGL ES render target. On mounting, an OpenGL ES context is created. Its drawing buffer is presented as the contents of the View every frame.

GLViewProps

enableExperimentalWorkletSupport

Type: boolean • Default: false

Enables support for interacting with a gl object from code running on the Reanimated worklet thread.

Only for:
iOS

msaaSamples

Type: number • Default: 4

GLView can enable iOS's built-in multisampling. This prop specifies the number of samples to use. Setting this to 0 turns off multisampling.

onContextCreate

Type: (gl: ExpoWebGLRenderingContext) => void

A function that will be called when the OpenGL ES context is created. The function is passed a single argument gl that extends a WebGLRenderingContext interface.

Inherited Props

  • ViewProps

Static Methods

createContextAsync()

Imperative API that creates headless context which is devoid of underlying view. It's useful for headless rendering or in case you want to keep just one context per application and share it between multiple components. It is slightly faster than usual context as it doesn't swap framebuffers and doesn't present them on the canvas, however it may require you to take a snapshot in order to present its results. Also, keep in mind that you need to set up a viewport and create your own framebuffer and texture that you will be drawing to, before you take a snapshot.

Returns:

Promise<ExpoWebGLRenderingContext>

A promise that resolves to WebGL context object. See WebGL API for more details.

destroyContextAsync(exgl)

NameTypeDescription
exgl
(optional)
number | ExpoWebGLRenderingContext

WebGL context to destroy.


Destroys given context.

Returns:

Promise<boolean>

A promise that resolves to boolean value that is true if given context existed and has been destroyed successfully.

takeSnapshotAsync(exgl, options)

NameTypeDescription
exgl
(optional)
number | ExpoWebGLRenderingContext

WebGL context to take a snapshot from.

options
(optional)
SnapshotOptions-

Takes a snapshot of the framebuffer and saves it as a file to app's cache directory.

Returns:

Promise<GLSnapshot>

A promise that resolves to GLSnapshot object.

Component Methods

createCameraTextureAsync(cameraRefOrHandle)

NameType
cameraRefOrHandleComponentOrHandle

Returns:

Promise<WebGLTexture>

destroyObjectAsync(glObject)

NameType
glObjectWebGLObject

Returns:

Promise<boolean>

startARSessionAsync()

Returns:

Promise<any>

takeSnapshotAsync(options)

NameType
options
(optional)
SnapshotOptions

Same as static takeSnapshotAsync(), but uses WebGL context that is associated with the view on which the method is called.

Returns:

Promise<GLSnapshot>

Methods

GLView.getWorkletContext(contextId)

NameType
contextIdnumber

Returns:

ExpoWebGLRenderingContext | undefined

Interfaces

ExpoWebGLRenderingContext

Extends: WebGL2RenderingContext

ExpoWebGLRenderingContext Methods

endFrameEXP()

Returns:

void

flushEXP()

Returns:

void

ExpoWebGLRenderingContext Properties

NameTypeDescription
contextIdnumber-

Types

ComponentOrHandle

Literal Type: multiple types

Acceptable values are: null | number | Component<any, any> | ComponentClass<any>

GLSnapshot

NameTypeDescription
heightnumber

Height of the snapshot.

localUristring

Synonym for uri. Makes snapshot object compatible with texImage2D.

uristring | Blob | null

URI to the snapshot.

widthnumber

Width of the snapshot.

SnapshotOptions

NameTypeDescription
compress
(optional)
number

A value in range 0 to 1.0 specifying compression level of the result image. 1.0 means no compression and 0 the highest compression.

Default: 1.0
flip
(optional)
boolean

Whether to flip the snapshot vertically.

Default: false
format
(optional)
'jpeg' | 'png' | 'webp'

Specifies what type of compression should be used and what is the result file extension. PNG compression is lossless but slower, JPEG is faster but the image has visible artifacts.

Note: When using WebP format, the iOS version will print a warning, and generate a 'png' file instead. It is recommended to use platform-specific code in this case.

Default: 'jpeg'
framebuffer
(optional)
WebGLFramebuffer

Specify the framebuffer that we will be reading from. Defaults to underlying framebuffer that is presented in the view or the current framebuffer if context is headless.

rect
(optional)
{ height: number, width: number, x: number, y: number }

Rect to crop the snapshot. It's passed directly to glReadPixels.

SurfaceCreateEvent

NameTypeDescription
nativeEvent{ exglCtxId: number }-

WebGLObject

NameTypeDescription
idnumber-

Enums

GLLoggingOption

GLLoggingOption Values

DISABLED

GLLoggingOption.DISABLED = 0

Disables logging entirely.

METHOD_CALLS

GLLoggingOption.METHOD_CALLS = 1

Logs method calls, their parameters and results.

GET_ERRORS

GLLoggingOption.GET_ERRORS = 2

Calls gl.getError() after each other method call and prints an error if any is returned. This option has a significant impact on the performance as this method is blocking.

RESOLVE_CONSTANTS

GLLoggingOption.RESOLVE_CONSTANTS = 4

Resolves parameters of type number to their constant names.

TRUNCATE_STRINGS

GLLoggingOption.TRUNCATE_STRINGS = 8

When this option is enabled, long strings will be truncated. It's useful if your shaders are really big and logging them significantly reduces performance.

ALL

GLLoggingOption.ALL = 15

Enables all other options. It implies GET_ERRORS so be aware of the slowdown.

WebGL API

安装组件并创建 OpenGL ES 上下文后,通过 onContextCreate 属性接收的 gl 对象将成为 OpenGL ES 上下文的接口,提供 WebGL API。它类似于 WebGL 2 规范中的 WebGL2 渲染上下文

¥Once the component is mounted and the OpenGL ES context has been created, the gl object received through the onContextCreate prop becomes the interface to the OpenGL ES context, providing a WebGL API. It resembles a WebGL2RenderingContext in the WebGL 2 spec.

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

¥Some older Android devices may not support WebGL2 features. To check whether the device supports WebGL2 it's recommended to use gl instanceof WebGL2RenderingContext.

存在附加方法 gl.endFrameEXP(),其通知上下文当前帧已准备好渲染。这类似于其他 OpenGL 平台中的 '交换缓冲区' API 调用。

¥An additional method gl.endFrameEXP() is present, which notifies the context that the current frame is ready to present. This is similar to a 'swap buffers' API call in other OpenGL platforms.

以下 WebGL2RenderingContext 方法当前未实现:

¥The following WebGL2RenderingContext methods are currently unimplemented:

  • 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 对象。

¥The pixels argument of texImage2D() must be null, an ArrayBuffer with pixel data, or an object of the form { localUri } where localUri is the file:// URI of an image in the device's file system. Thus, an Asset object is used once .downloadAsync() has been called on it (and completed) to fetch the resource.

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

¥For efficiency reasons, the current implementations of the methods don't perform type or bounds checking on their arguments. So, passing invalid arguments may cause a native crash. There are plans to update the API to perform argument checking in upcoming SDK versions.

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

¥Currently, the priority for error checking is low since engines generally don't rely on the OpenGL API to perform argument checking; otherwise, checks performed by the underlying OpenGL ES implementation are often sufficient.

Expo 中文网 - 粤ICP备13048890号