node-gles-webgl2

Headless WebGL2 / OpenGL ES 3 runtime for Node.js backed by ANGLE.

This package is a fork of node-gles. It preserves the existing WebGL1 surface and exposes additional GLES3-backed APIs through WebGL2-compatible JavaScript method names.

WebGL2 Coverage

| Feature | Status | | --- | --- | | Runtime and context lifecycle | ✅ | | WebGL1 API and selected extension aliases | ✅ | | WebGL2 core method names | ✅ | | VAO, instancing, draw buffers, and multisample framebuffers | ✅ | | Buffer, sampler, sync, and PBO operations | ✅ | | WebGL2 uniform and matrix APIs | ✅ | | 3D textures and 2D texture arrays | ✅ | | Queries, transform feedback, and integer vertex attributes | ✅ | | Browser-compatible overloads and error semantics | 🟡 | | Browser-complete WebGL2 conformance | ❌ |

Platform Support

| Platform | CI | | ------------- | ------------------------------------------------------------------ | | Linux x64 | | | Linux arm64 | | | macOS arm64 | | | macOS x64 | | | Windows x64 | | | Windows arm64 | |

macOS x64 is build-only in CI because hosted-runner smoke currently hits Error: No display.

Extension Support

getSupportedExtensions() reports WebGL extension names, not raw GL_* ANGLE extension strings. Runtime availability still depends on the selected ANGLE backend.

Exposed

• ANGLE_instanced_arrays
• EXT_blend_minmax
• EXT_color_buffer_float / WEBGL_color_buffer_float
• EXT_color_buffer_half_float
• EXT_frag_depth
• EXT_float_blend
• EXT_sRGB
• EXT_shader_texture_lod
• EXT_texture_filter_anisotropic
• EXT_texture_mirror_clamp_to_edge
• OES_element_index_uint
• OES_standard_derivatives
• OES_texture_float / OES_texture_float_linear
• OES_texture_half_float / OES_texture_half_float_linear
• OES_vertex_array_object
• WEBGL_compressed_texture_s3tc / WEBGL_compressed_texture_s3tc_srgb
• WEBGL_debug_renderer_info
• WEBGL_depth_texture
• WEBGL_draw_buffers
• WEBGL_lose_context

Not Exposed

• EXT_disjoint_timer_query / EXT_disjoint_timer_query_webgl2

Install

From npm:

npm install node-gles-webgl2

Usage

const nodeGles = require("node-gles-webgl2");

const gl = nodeGles.createWebGLRenderingContext({
  width: 800,
  height: 500,
  majorVersion: 3,
  minorVersion: 0,
});

console.log(gl.getParameter(gl.VERSION));

Context Options

• width / height: drawing buffer size, default 1.
• majorVersion / minorVersion: requested OpenGL ES version, default 3.0.
• webGLCompatibility: requests ANGLE WebGL compatibility mode. The legacy misspelled webGLCompability option is still accepted as an alias.
• enabledExtensions: optional WebGL extension allowlist. When set, only listed supported extensions are exposed.
• disabledExtensions: optional WebGL extension blocklist. This takes precedence over enabledExtensions.

Context Lifecycle

For batch rendering, call gl.destroy() or gl.dispose() after the final readPixels() for a context. This releases the native EGL context and pbuffer surface immediately instead of waiting for JavaScript garbage collection.

const gl = nodeGles.createWebGLRenderingContext({ width: 3000, height: 2000 });

try {
  // render and readPixels
} finally {
  gl.destroy();
}

Build From Source

From git:

git clone https://github.com/dsafdsaf132/node-gles-webgl2.git
cd node-gles-webgl2
npm install --ignore-scripts
node scripts/install.js
npm run build

From a release source tarball, use the same commands after extracting the archive.

ANGLE headers are bundled in the main package. Prebuilt libraries are published as platform packages for Linux, macOS, and Windows on x64 and arm64. npm automatically installs only the package matching the current platform, so installation does not fetch a separate ANGLE release archive.

The platform packages are maintained under packages/angle-*. scripts/install.js validates the selected package and builds the native addon with node-gyp. The bundled ANGLE revision and platform inventory are recorded in deps/angle/angle-build.json. ANGLE is distributed under its BSD-style license in deps/angle/LICENSE and each platform package.

The publish workflow releases the six platform packages before the main package. The first release requires an npm granular access token in the NPM_TOKEN repository secret because npm trusted publishing can only be configured after a package exists. After bootstrapping, configure publish.yml as the trusted publisher for each platform package.

On Linux, the native build needs X11 development headers. On Ubuntu:

sudo apt-get install -y build-essential python3 libx11-dev libxext-dev

License

This package is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

node-gles-webgl2 is a fork of node-gles. Original source files retain their upstream copyright notices, including Google LLC / Google Inc. notices where applicable. Modifications in this repository add WebGL2 / OpenGL ES 3 bindings, packaging, CI, and publishing workflows for node-gles-webgl2.