native-gles

OpenGL ES 3.0 bindings for Node.js via EGL. Uses native drivers on Linux/ARM and ANGLE on macOS/Windows.

Renders to an offscreen EGL pbuffer — no window system required. Designed for headless GPU rendering, game engines, and wasmcart GL carts.

Install

npm install native-gles

Linux

sudo apt install libegl-dev libgles-dev

macOS / Windows

ANGLE binaries are downloaded automatically during npm install. Set ANGLE_INC and ANGLE_LIB environment variables to use a custom ANGLE build.

Usage

const gl = require('native-gles')

// Create an offscreen EGL pbuffer context
gl.createContext(800, 600)

// Standard GLES3 calls
gl.glClearColor(0.2, 0.3, 0.3, 1.0)
gl.glClear(0x4000) // GL_COLOR_BUFFER_BIT

// Read pixels back
const pixels = new Uint8Array(800 * 600 * 4)
gl.glReadPixels(0, 0, 800, 600, 0x1908, 0x1401, pixels) // GL_RGBA, GL_UNSIGNED_BYTE

gl.destroyContext()

API

Context Management

| Function | Description | |----------|-------------| | createContext(width, height) | Create EGL pbuffer context. Returns true on success. | | destroyContext() | Destroy context and free resources. | | resizeContext(width, height) | Resize the pbuffer surface. | | makeCurrent() | Make this context current (useful after SDL or other EGL contexts). | | getContextInfo() | Returns { valid, width, height }. |

GL Functions (246 — full GLES 3.0 spec)

All functions use the gl.glFunctionName(...) convention. Every function in the OpenGL ES 3.0 specification is implemented.

State — glEnable, glDisable, glGetError, glGetIntegerv, glGetBooleanv, glGetFloatv, glGetInteger64v, glGetIntegeri_v, glGetInteger64i_v, glGetString, glGetStringi, glFinish, glFlush, glHint, glPixelStorei, glIsEnabled

Viewport & Clear — glViewport, glScissor, glClear, glClearColor, glClearDepthf, glClearStencil, glClearBufferiv, glClearBufferuiv, glClearBufferfv, glClearBufferfi

Blending — glBlendFunc, glBlendFuncSeparate, glBlendEquation, glBlendEquationSeparate, glBlendColor, glColorMask

Depth & Stencil — glDepthFunc, glDepthMask, glDepthRangef, glStencilFunc, glStencilFuncSeparate, glStencilOp, glStencilOpSeparate, glStencilMask, glStencilMaskSeparate

Face Culling — glCullFace, glFrontFace, glPolygonOffset, glLineWidth, glSampleCoverage

Buffers — glGenBuffers, glDeleteBuffers, glBindBuffer, glBufferData, glBufferSubData, glBindBufferRange, glBindBufferBase, glGetBufferParameteriv, glGetBufferParameteri64v, glIsBuffer, glMapBufferRange*, glUnmapBuffer, glFlushMappedBufferRange*, glGetBufferPointerv*

Textures — glGenTextures, glDeleteTextures, glBindTexture, glActiveTexture, glTexImage2D, glTexSubImage2D, glTexImage3D, glTexSubImage3D, glTexStorage2D, glTexStorage3D, glTexParameteri, glTexParameterf, glTexParameteriv, glTexParameterfv, glGenerateMipmap, glCompressedTexImage2D, glCompressedTexSubImage2D, glCompressedTexImage3D, glCompressedTexSubImage3D, glCopyTexImage2D, glCopyTexSubImage2D, glCopyTexSubImage3D, glGetTexParameteriv, glGetTexParameterfv, glIsTexture

Samplers — glGenSamplers, glDeleteSamplers, glBindSampler, glSamplerParameteri, glSamplerParameterf, glSamplerParameteriv, glSamplerParameterfv, glGetSamplerParameteriv, glGetSamplerParameterfv, glIsSampler

Shaders — glCreateShader, glDeleteShader, glShaderSource, glCompileShader, glGetShaderiv, glGetShaderInfoLog, glGetShaderSource, glGetShaderPrecisionFormat, glIsShader, glReleaseShaderCompiler, glShaderBinary*

Programs — glCreateProgram, glDeleteProgram, glAttachShader, glDetachShader, glLinkProgram, glUseProgram, glGetProgramiv, glGetProgramInfoLog, glValidateProgram, glBindAttribLocation, glGetAttribLocation, glGetUniformLocation, glGetActiveUniform, glGetActiveAttrib, glGetAttachedShaders, glGetFragDataLocation, glProgramParameteri, glGetProgramBinary*, glProgramBinary*, glIsProgram

Uniforms — glUniform{1,2,3,4}{i,f,ui}, glUniform{1,2,3,4}{iv,fv,uiv}, glUniformMatrix{2,3,4}fv, glUniformMatrix{2x3,3x2,2x4,4x2,3x4,4x3}fv, glGetUniformiv, glGetUniformfv, glGetUniformuiv

Uniform Buffer Objects — glGetUniformBlockIndex, glGetActiveUniformBlockiv, glGetActiveUniformBlockName, glUniformBlockBinding, glGetUniformIndices, glGetActiveUniformsiv

Vertex Attributes — glEnableVertexAttribArray, glDisableVertexAttribArray, glVertexAttribPointer, glVertexAttribIPointer, glVertexAttrib{1,2,3,4}f, glVertexAttrib{1,2,3,4}fv, glVertexAttribI4i, glVertexAttribI4ui, glVertexAttribI4iv, glVertexAttribI4uiv, glVertexAttribDivisor, glGetVertexAttribiv, glGetVertexAttribfv, glGetVertexAttribIiv, glGetVertexAttribIuiv, glGetVertexAttribPointerv

VAOs — glGenVertexArrays, glDeleteVertexArrays, glBindVertexArray, glIsVertexArray

Drawing — glDrawArrays, glDrawElements, glDrawRangeElements, glDrawArraysInstanced, glDrawElementsInstanced, glDrawBuffers

Framebuffers — glGenFramebuffers, glDeleteFramebuffers, glBindFramebuffer, glCheckFramebufferStatus, glFramebufferTexture2D, glFramebufferTextureLayer, glFramebufferRenderbuffer, glBlitFramebuffer, glInvalidateFramebuffer, glInvalidateSubFramebuffer, glReadBuffer, glGetFramebufferAttachmentParameteriv, glIsFramebuffer

Renderbuffers — glGenRenderbuffers, glDeleteRenderbuffers, glBindRenderbuffer, glRenderbufferStorage, glRenderbufferStorageMultisample, glGetRenderbufferParameteriv, glGetInternalformativ, glIsRenderbuffer

Readback — glReadPixels (with automatic float-to-ubyte conversion for float FBOs)

Queries — glGenQueries, glDeleteQueries, glBeginQuery, glEndQuery, glGetQueryiv, glGetQueryObjectiv, glGetQueryObjectuiv, glIsQuery

Sync — glFenceSync, glClientWaitSync, glWaitSync, glDeleteSync, glGetSynciv, glIsSync

Transform Feedback — glBeginTransformFeedback, glEndTransformFeedback, glTransformFeedbackVaryings, glGetTransformFeedbackVarying, glGenTransformFeedbacks, glDeleteTransformFeedbacks, glBindTransformFeedback, glPauseTransformFeedback, glResumeTransformFeedback, glIsTransformFeedback

* WASM-incompatible functions — glMapBufferRange returns null, glFlushMappedBufferRange/glGetBufferPointerv are no-ops (host pointers can't cross the WASM boundary; use glBufferSubData instead). glShaderBinary/glGetProgramBinary/glProgramBinary are no-ops (driver-specific binaries aren't portable).

EGL Context

The context uses EGL_EXT_device_enumeration when available for a device-based display independent of X11/Wayland/SDL. Falls back to the default EGL display otherwise. This prevents conflicts with other libraries that create their own EGL contexts.

Configuration: GLES 3.0, 8-bit RGBA, 24-bit depth, 8-bit stencil, pbuffer surface.

Tests

npm test

Runs three tests:

• test_context.js — context create/destroy/resize lifecycle
• test_triangle.js — renders a red triangle, reads back pixels, verifies color
• test_shader.js — shader compilation and program linking

Building from Source

npm run build

Requires node-gyp, node-addon-api, and platform GL libraries (see Install above).

License

MIT