https://github.com/node-3d/webgl-raub
OpenGL/WebGL for Node.js
https://github.com/node-3d/webgl-raub
addon bindings cpp gl graphics javascript native node-3d opengl webgl
Last synced: about 1 month ago
JSON representation
OpenGL/WebGL for Node.js
- Host: GitHub
- URL: https://github.com/node-3d/webgl-raub
- Owner: node-3d
- License: mit
- Created: 2017-01-22T19:18:33.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2025-03-01T10:23:26.000Z (2 months ago)
- Last Synced: 2025-03-28T12:02:22.536Z (about 2 months ago)
- Topics: addon, bindings, cpp, gl, graphics, javascript, native, node-3d, opengl, webgl
- Language: C++
- Homepage: https://github.com/node-3d/node-3d
- Size: 7.87 MB
- Stars: 86
- Watchers: 3
- Forks: 13
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# WebGL for Node.js
This is a part of [Node3D](https://github.com/node-3d) project.
[](https://badge.fury.io/js/webgl-raub)
[](https://github.com/node-3d/webgl-raub/actions/workflows/eslint.yml)
[](https://github.com/node-3d/webgl-raub/actions/workflows/test.yml)
[](https://github.com/node-3d/webgl-raub/actions/workflows/cpplint.yml)
```console
npm i -s webgl-raub
```
> This addon is ABI-compatible across Node.js versions. **There is no compilation** during `npm i`.
**TL;DR**: For a quick start, use [3d-core-raub](https://github.com/node-3d/3d-core-raub)
or look at [Examples](/examples).
```js
import webgl from 'webgl-raub';
```
Here `webgl` contains the **WebGL/OpenGL** API, like a `WebGLRenderingContext` instance would.
* See [WebGLRenderingContext docs](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext)
for reference.
* There are also non-WebGL methods exported in case you want to use advanced OpenGL functions.
* The addon **does not provide** a window control system, you can use
[glfw-raub](https://github.com/node-3d/glfw-raub) (or anything else!) to create a window.
* See [TS declarations](/index.d.ts) for the full list of exports.
## WebGL Libs
To use browser **WebGL** libs, like [three.js](https://threejs.org/),
several additional interfaces must also be provided to mimic the browser.
* Package [glfw-raub](https://github.com/node-3d/glfw-raub) provides window/context handling
and additional browser-like interfaces.
* Package [image-raub](https://github.com/node-3d/glfw-raub) loads and serves the image data as web
[Image](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement#example) would.
See [this example](/examples/textured.mjs) using both **GLFW** and **Image**.
The main idea being as follows:
```js
import Image from 'image-raub';
import webgl from 'webgl-raub';
import glfw from 'glfw-raub';
const { Document } = glfw;
Document.setImage(image); // plug Image impl into the Document
Document.setWebgl(webgl); // plug WebGL impl into the Document
const doc = new Document({ width: 1600, height: 900, vsync: true });
...
```
Similarly, these modules are utilized in [3d-core-raub](https://github.com/node-3d/3d-core-raub).
Using [3d-core-raub](https://github.com/node-3d/3d-core-raub), you can skip setting up
most environment features for those libs.
* [three.js](https://threejs.org/) - known to work well on **Node.js** with this
implementation of **WebGL**.
* [PixiJS](https://pixijs.com/) - seems to work with some minor hacks, as proven by this
[example](https://github.com/node-3d/3d-core-raub/blob/master/examples/pixi/index.js).
## Native OpenGL
This is real **native OpenGL**, not ANGLE or anything else.
You have direct access to GL resource IDs. Due to WebGL
convention, resource IDs are wrapped in objects, such as `WebGLBuffer`. All of them
contain raw IDs as `obj._` - the `_` property. You can also create such objects based on
OpenGL IDs that are obtained elsewhere (e.g. from other separate C++ addons).
The JS API mostly maps the native OpenGL function calls. E.g.:
```cpp
// gl.clear(target)
DBG_EXPORT JS_METHOD(clear) { NAPI_ENV;
REQ_INT32_ARG(0, target);
glClear(target);
RET_WEBGL_VOID;
}
```
You can optionally call `webgl.init()` after the GL context becomes available - this translates
into a `glewInit()` call. See [GLEW docs](https://glew.sourceforge.net/basic.html) for what
it does and if you need it (probably "yes"?).
## MacOS Note
Some features may depend on OpenGL profile being used. Core profile
is necessary for VAO and other OpenGL 3.2+ features. Depending on your windowing
backend, set the OpenGL profile of your preference.
In case [glfw-raub](https://github.com/node-3d/glfw-raub) is used,
the profile can be set through the `Window`/`Document`
[constructor](https://github.com/node-3d/glfw-raub#class-window) or with
`glfw.windowHint` calls.