https://github.com/node-3d/3d-core-raub
An extensible Node.js 3D core for desktop applications
https://github.com/node-3d/3d-core-raub
3d gl glfw gpu gpu-computing graphics image javascript js native node-3d opengl pixijs simulation threejs vao vbo webgl window
Last synced: about 1 month ago
JSON representation
An extensible Node.js 3D core for desktop applications
- Host: GitHub
- URL: https://github.com/node-3d/3d-core-raub
- Owner: node-3d
- License: mit
- Created: 2017-01-27T10:33:14.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2024-11-09T15:13:00.000Z (6 months ago)
- Last Synced: 2024-12-27T09:17:39.488Z (5 months ago)
- Topics: 3d, gl, glfw, gpu, gpu-computing, graphics, image, javascript, js, native, node-3d, opengl, pixijs, simulation, threejs, vao, vbo, webgl, window
- Language: JavaScript
- Homepage: https://github.com/node-3d/node-3d
- Size: 11.9 MB
- Stars: 73
- Watchers: 4
- Forks: 4
- 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
# Node.js 3D Core
This is a part of [Node3D](https://github.com/node-3d) project.
[](https://badge.fury.io/js/3d-core-raub)
[](https://github.com/node-3d/3d-core-raub/actions/workflows/eslint.yml)
[](https://github.com/node-3d/3d-core-raub/actions/workflows/test.yml)
```console
npm i -s 3d-core-raub
```
> This package uses pre-compiled Node.js addons. **There is no compilation** during `npm i`.
The addons are compiled for: Win64, Linux64, Linux ARM64, MacOS ARM64.
* WebGL/OpenGL on **Node.js** with support for web libs, such as **three.js**.
* Multi-window apps, low-level window control with [glfw-raub](https://github.com/node-3d/glfw-raub).
* Modern OpenGL functions also available, see [webgl-raub](https://github.com/node-3d/webgl-raub).
* Image loading/saving in popular formats with [image-raub](https://github.com/node-3d/image-raub).
This module exports 2 methods:
1. `export const init: (opts?: TInitOpts) => TCore3D;`
Initialize Node3D. Creates the first window/document and sets up the global environment.
This function can be called repeatedly, but will ignore further calls.
The return value is cached and will be returned immediately for repeating calls.
2. `export const addThreeHelpers: (three: TUnknownObject, gl: typeof webgl) => void;`
Teaches `three.FileLoader.load` to work with Node `fs`. Additionally implements
`three.Texture.fromId` static method to create THREE textures from known GL resource IDs.
See [TS declarations](/index.d.ts) for more details.
## Example
(As in [crate-lean.mjs](/examples/crate-lean.mjs)):
```javascript
import * as THREE from 'three';
import node3d from '../index.js';
const { init, addThreeHelpers } = node3d;
const { gl, loop, Screen } = init({
isGles3: true, vsync: true, autoEsc: true, autoFullscreen: true, title: 'Crate',
});
addThreeHelpers(THREE, gl);
const screen = new Screen({ three: THREE, fov: 70, z: 2 });
const texture = new THREE.TextureLoader().load('three/textures/crate.gif');
texture.colorSpace = THREE.SRGBColorSpace;
const geometry = new THREE.BoxGeometry();
const material = new THREE.MeshBasicMaterial({ map: texture });
const mesh = new THREE.Mesh(geometry, material);
screen.scene.add(mesh);
loop((now) => {
mesh.rotation.x = now * 0.0005;
mesh.rotation.y = now * 0.001;
screen.draw();
});
```
Example Notes:
1. You can use **mjs**, **tsx** or commonjs with `require()`.
1. `loop` is a convenience method, you can use `requestAnimationFrame` too.
1. `autoFullscreen` option enables "CTRL+F", "CTRL+SHIFT+F", "CTRL+ALT+F" to switch
window modes.
1. `Screen` helps with **three.js**-oriented resource management, but is not required.
1. **three.js** uses VAO, so if not using `Screen`, handling the window mode changes
(which creates a separate OpenGL context) is up to you.
Basically, `doc.on('mode', () => {...})` -
here you should [re-create THREE.WebGLRenderer](/js/objects/screen.js#L127).
## OpenGL Features
1. This is real **native OpenGL**, and you have direct access to GL resource IDs. This may be
useful for resource sharing and compute interop (such as
[CUDA-GL interop](https://docs.nvidia.com/cuda/cuda-runtime-api/group__CUDART__OPENGL.html)).
1. The flag `isGles3` lets you use a **GL ES 3** preset, which is closest to "real" WebGL.
If set to `false`, WebGL stuff (such as three.js) will still work, but now with some hacks.
However, if you are planning to use non-WebGL features (e.g. **OpenGL 4.5** features),
you might want it off, and then select a specific context version manually.
1. The flag `isWebGL2` impacts how web libraries recognize the WebGL version.
But it doesn't really change the capabilities of the engine.
1. **Offscreen rendering** is possible on Windows and Linux, as demonstrated by the tests
running in GitHub Actions. There are test cases that generate and compare screenshots,
and they do work in headless mode.
1. OpenGL **context sharing** is enabled. You can obtain `HDC, HWND, CTX` for Windows and whatever
those are called on Linux and MacOS. See [glfw-raub](https://github.com/node-3d/glfw-raub).
## License
**You get this for free. Have fun!**
Some of the components have their separate licenses, but all of them may be used
commercially, without royalty.