Skip to content

Commit 594bf9c

Browse files
raubraub
committed
Update readme
1 parent 688cd1c commit 594bf9c

File tree

4 files changed

+234
-152
lines changed

4 files changed

+234
-152
lines changed

‎README.md

Lines changed: 25 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -9,43 +9,47 @@ This is a part of [Node3D](https://github.com/node-3d) project.
99
npm i webgl-raub
1010
```
1111

12-
**Node.js** addon with **WebGL** bindings.
12+
![Example](examples/screenshot.jpg)
1313

14-
This module **does not provide** a window control system, and it
14+
**WebGL**/**OpenGL** bindings. The addon **does not provide** a window control system, and it
1515
**can not set up an OpenGL context** on its own. This API simply maps the
16-
native OpenGL function calls to their JS counterpart.
17-
18-
**TL;DR**: see [3d-core-raub](https://github.com/node-3d/3d-core-raub)
19-
for a quick start in a fully sufficient environment.
16+
native OpenGL function calls to their JS counterparts.
2017

21-
![Example](examples/screenshot.jpg)
18+
**TL;DR**: For a quick start, use [3d-core-raub](https://github.com/node-3d/3d-core-raub)
19+
or try the [Examples](/examples) (and note [package.json](/examples/package.json)).
2220

2321
> Note: this **addon uses N-API**, and therefore is ABI-compatible across different
2422
Node.js versions. Addon binaries are precompiled and **there is no compilation**
2523
step during the `npm i` command.
2624

2725

28-
## Usage
26+
## Details
2927

3028
```js
3129
const webgl = require('webgl-raub');
3230
```
3331

34-
Here `webgl` contains all the **WebGL** API, like a `WebGLRenderingContext` instance would.
35-
See
36-
[WebGLRenderingContext docs](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext).
32+
Here `webgl` contains the **WebGL** API, like a `WebGLRenderingContext` instance would. See
33+
[WebGLRenderingContext docs](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext)
34+
for reference, and [TypeSctipt defenitions](/index.d.ts) for the full list of exports.
3735

3836
To use browser **WebGL** libs, like [three.js](https://threejs.org/),
3937
several additional interfaces must also be provided to mimic the browser.
4038

41-
There is [node-glfw](https://github.com/raub/node-glfw) module, which solves both
42-
window handling and additional browser-like interfaces. It is also bundled into
43-
the [3d-core-raub](https://github.com/node-3d/3d-core-raub) module, for that matter.
39+
* Package [glfw-raub](https://github.com/node-3d/glfw-raub) provides window/context handling
40+
and additional browser-like interfaces.
41+
* Package [image-raub](https://github.com/node-3d/glfw-raub) loads and serves the image data as web
42+
[Image](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement#example) would.
43+
44+
Those two are bundled into
45+
the [3d-core-raub](https://github.com/node-3d/3d-core-raub) in a following manner:
4446

4547
```
48+
const image = require('image-raub');
4649
const webgl = require('webgl-raub');
4750
const { Document } = require('glfw-raub');
4851
52+
Document.setImage(image); // plug this Image impl into the Document
4953
Document.setWebgl(webgl); // plug this WebGL impl into the Document
5054
5155
const doc = new Document();
@@ -58,21 +62,20 @@ const gl = canvas.getContext('webgl'); // === webgl
5862
> OSX Note: some features may depend on OpenGL profile being used. Core profile
5963
is necessary for VAO and other OpenGL 3.2+ features. Depending on your windowing
6064
backend, set the OpenGL profile of your preference.
61-
In case [glfw-raub](https://github.com/raub/node-glfw) is used,
65+
In case [glfw-raub](https://github.com/node-3d/glfw-raub) is used,
6266
the profile can be set through the `Window`/`Document`
6367
[constructor](https://github.com/node-3d/glfw-raub#class-window) or with
6468
`glfw.windowHint` calls.
6569

6670

6771
---
6872

69-
## Three.js
73+
## WebGL Libs
7074

71-
Being a low level interface, **WebGL** requires a lot of effort to build apps. For
72-
that matter there are numerous frameworks around it. One of them is
73-
[three.js](https://threejs.org/). It is known to work well on **Node.js** with this
75+
* [three.js](https://threejs.org/) - known to work well on **Node.js** with this
7476
implementation of **WebGL**.
77+
* [PixiJS](https://pixijs.com/) - seems to work with some minor hacks, as proven by this
78+
[example](https://github.com/node-3d/3d-core-raub/blob/master/examples/pixi/index.js).
7579

76-
You can try to use **three.js** your own way, but there is
77-
a far better option: [node-3d-core](https://github.com/raub/node-3d-core),
78-
which gets you two steps ahead for free.
80+
Using [node-3d-core](https://github.com/node-3d/3d-core-raub), you can skip setting up
81+
most environment features for those libs.

‎index.d.ts

Lines changed: 118 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,21 @@ declare module "webgl-raub" {
66
name: string;
77
}>;
88

9+
export type TContextAttributes = Readonly<{
10+
alpha: boolean,
11+
antialias: boolean,
12+
depth: boolean,
13+
failIfMajorPerformanceCaveat: boolean,
14+
powerPreference: string,
15+
premultipliedAlpha: boolean,
16+
preserveDrawingBuffer: boolean,
17+
stencil: boolean,
18+
desynchronized: boolean,
19+
}>;
20+
921
export type TResourceId = number;
1022

11-
export type TSize = Readonly<{ width: number; height: number }>;
23+
export type TSize = Readonly<{ width: number; height: number }>;
1224

1325
export type TImage = TSize & Readonly<{
1426
data: Buffer;
@@ -33,6 +45,7 @@ declare module "webgl-raub" {
3345
export class WebGLRenderingContext extends TGLObject {}
3446
export class WebGLProgram extends TGLObject {}
3547
export class WebGLShader extends TGLObject {}
48+
export class WebGLVertexArrayObject extends TGLObject {}
3649
export class WebGLBuffer extends TGLObject {}
3750
export class WebGLVertexArray extends TGLObject {}
3851
export class WebGLFramebuffer extends TGLObject {}
@@ -42,10 +55,13 @@ declare module "webgl-raub" {
4255
export class WebGLActiveInfo extends TGLActiveInfo {}
4356
export class WebGLTransformFeedback extends TGLObject {}
4457

45-
const webgl: WebGL
46-
export default webgl
58+
const webgl: WebGL;
59+
export default webgl;
60+
4761
export interface WebGL {
48-
init: () => void;
62+
contextAttributes: TContextAttributes;
63+
getContextAttributes: () => TContextAttributes;
64+
4965
bindAttribLocation: (program: WebGLProgram, index: number, name: string) => void;
5066
disableVertexAttribArray: (index: number) => void;
5167
enableVertexAttribArray: (id: number) => void;
@@ -100,9 +116,14 @@ declare module "webgl-raub" {
100116
offset: number,
101117
size: number,
102118
) => void;
119+
bufferSubData: (
120+
target: number,
121+
offset: number,
122+
v: number[] | Float32Array,
123+
) => void;
103124
bufferData: (
104125
target: number,
105-
value: number | number[] | Float32Array| Uint16Array,
126+
value: number | number[] | Float32Array | Uint16Array,
106127
usage: number,
107128
srcOffset?: number,
108129
length?: number,
@@ -129,6 +150,7 @@ declare module "webgl-raub" {
129150
getBufferParameter: (target: number, name: number) => number;
130151
createFramebuffer: () => WebGLFramebuffer;
131152
deleteFramebuffer: (frameBuffer: WebGLFramebuffer) => void;
153+
invalidateFramebuffer: (target: number, attachments: number[]) => void;
132154
isFramebuffer: (frameBuffer: WebGLFramebuffer) => boolean;
133155
bindFramebuffer: (target: number, buffer?: WebGLFramebuffer) => void;
134156
blitFramebuffer: (
@@ -157,6 +179,13 @@ declare module "webgl-raub" {
157179
texture: WebGLTexture,
158180
level: number,
159181
) => void;
182+
framebufferTextureLayer: (
183+
target: number,
184+
attachment: number,
185+
texture: WebGLTexture,
186+
level: number,
187+
layer: number,
188+
) => void;
160189
getFramebufferAttachmentParameter: (
161190
target: number,
162191
attachment: number,
@@ -181,6 +210,13 @@ declare module "webgl-raub" {
181210
width: number,
182211
height: number,
183212
) => void;
213+
renderbufferStorageMultisample: (
214+
target: number,
215+
samples: number,
216+
internalformat: number,
217+
width: number,
218+
height: number,
219+
) => void;
184220
createShader: (type: number) => WebGLShader;
185221
deleteShader: (shader: WebGLShader) => void;
186222
isShader: (shader: WebGLShader) => boolean;
@@ -191,6 +227,7 @@ declare module "webgl-raub" {
191227
getShaderInfoLog: (shader: WebGLShader) => string;
192228
getShaderParameter: (shader: WebGLShader, pname: number) => (number | boolean);
193229
getShaderSource: (shader: WebGLShader) => string;
230+
getShaderPrecisionFormat: (shaderType: number, precisionType: number) => string;
194231
shaderSource: (shader: WebGLShader, code: string) => void;
195232
clearStencil: (index: number) => void;
196233
stencilFunc: (
@@ -255,6 +292,18 @@ declare module "webgl-raub" {
255292
type: number,
256293
ptr?: TImage | number,
257294
) => void;
295+
texImage3D: (
296+
target: number,
297+
level: number,
298+
internalformat: number,
299+
width: number,
300+
height: number,
301+
depth: number,
302+
border: number,
303+
format: number,
304+
type: number,
305+
ptr?: TImage,
306+
) => void;
258307
texParameterf: (
259308
target: number,
260309
name: number,
@@ -276,6 +325,16 @@ declare module "webgl-raub" {
276325
type: number,
277326
image?: TImage,
278327
) => void;
328+
compressedTexSubImage2D: (
329+
target: number,
330+
level: number,
331+
xoffset: number,
332+
yoffset: number,
333+
width: number,
334+
height: number,
335+
format: number,
336+
image?: TImage,
337+
) => void;
279338
texStorage2D: (
280339
target: number,
281340
levels: number,
@@ -345,6 +404,10 @@ declare module "webgl-raub" {
345404
alpha: number,
346405
) => void;
347406
clearDepth: (depth: number) => void;
407+
clearBufferfv: (buffer: number, drawBuffer: number, value: number[]) => void;
408+
clearBufferiv: (buffer: number, drawBuffer: number, value: number[]) => void;
409+
clearBufferuiv: (buffer: number, drawBuffer: number, value: number[]) => void;
410+
clearBufferfi: (buffer: number, drawBuffer: number, depth: number, stencil: number) => void;
348411
colorMask: (
349412
red: boolean,
350413
green: boolean,
@@ -374,6 +437,11 @@ declare module "webgl-raub" {
374437
frontFace: (id: number) => void;
375438
getError: () => number;
376439
getParameter: (name: number) => (number | boolean | number[] | string | boolean[]);
440+
getInternalformatParameter: (
441+
target: number,
442+
internalformat: number,
443+
name: number,
444+
) => (Int32Array | null);
377445
getRenderTarget: (
378446
width: number,
379447
height: number,
@@ -464,6 +532,8 @@ declare module "webgl-raub" {
464532
BACK: number;
465533
FRONT_AND_BACK: number;
466534
TEXTURE_2D: number;
535+
TEXTURE_2D_ARRAY: number;
536+
TEXTURE_3D: number;
467537
CULL_FACE: number;
468538
BLEND: number;
469539
DITHER: number;
@@ -538,6 +608,7 @@ declare module "webgl-raub" {
538608
UNSIGNED_SHORT: number;
539609
INT: number;
540610
UNSIGNED_INT: number;
611+
UNSIGNED_INT_24_8: number;
541612
FLOAT: number;
542613
FIXED: number;
543614
DEPTH_COMPONENT: number;
@@ -546,6 +617,29 @@ declare module "webgl-raub" {
546617
RGBA: number;
547618
LUMINANCE: number;
548619
LUMINANCE_ALPHA: number;
620+
RGBA4: number;
621+
RGB5_A1: number;
622+
R16F: number;
623+
R16I: number;
624+
R16UI: number;
625+
R32F: number;
626+
R32I: number;
627+
R32UI: number;
628+
R8: number;
629+
R8I: number;
630+
R8UI: number;
631+
RED: number;
632+
RED_INTEGER: number;
633+
RG: number;
634+
RG_INTEGER: number;
635+
RG16F: number;
636+
RG32F: number;
637+
RG8: number;
638+
RGBA_INTEGER: number;
639+
RGBA16F: number;
640+
RGBA32F: number;
641+
RGBA8: number;
642+
SRGB8_ALPHA8: number;
549643
UNSIGNED_SHORT_4_4_4_4: number;
550644
UNSIGNED_SHORT_5_5_5_1: number;
551645
UNSIGNED_SHORT_5_6_5: number;
@@ -569,6 +663,7 @@ declare module "webgl-raub" {
569663
ACTIVE_ATTRIBUTE_MAX_LENGTH: number;
570664
SHADING_LANGUAGE_VERSION: number;
571665
CURRENT_PROGRAM: number;
666+
UNIFORM_BUFFER: number;
572667
NEVER: number;
573668
LESS: number;
574669
EQUAL: number;
@@ -600,6 +695,7 @@ declare module "webgl-raub" {
600695
TEXTURE_MIN_FILTER: number;
601696
TEXTURE_WRAP_S: number;
602697
TEXTURE_WRAP_T: number;
698+
TEXTURE_WRAP_R: number;
603699
TEXTURE: number;
604700
TEXTURE_CUBE_MAP: number;
605701
TEXTURE_BINDING_CUBE_MAP: number;
@@ -680,16 +776,17 @@ declare module "webgl-raub" {
680776
NUM_SHADER_BINARY_FORMATS: number;
681777
LOW_FLOAT: number;
682778
MEDIUM_FLOAT: number;
779+
HALF_FLOAT: number;
683780
HIGH_FLOAT: number;
684781
LOW_INT: number;
685782
MEDIUM_INT: number;
686783
HIGH_INT: number;
687784
FRAMEBUFFER: number;
688785
RENDERBUFFER: number;
689-
RGBA4: number;
690-
RGB5_A1: number;
691786
RGB565: number;
692787
DEPTH_COMPONENT16: number;
788+
DEPTH_COMPONENT24: number;
789+
DEPTH_COMPONENT32F: number;
693790
STENCIL_INDEX: number;
694791
STENCIL_INDEX8: number;
695792
DEPTH_STENCIL: number;
@@ -707,6 +804,7 @@ declare module "webgl-raub" {
707804
FRAMEBUFFER_ATTACHMENT_OBJECT_NAME: number;
708805
FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL: number;
709806
FRAMEBUFFER_ATTACHMENT_TEXTURE_CUBE_MAP_FACE: number;
807+
COLOR: number;
710808
COLOR_ATTACHMENT0: number;
711809
DEPTH_ATTACHMENT: number;
712810
STENCIL_ATTACHMENT: number;
@@ -719,6 +817,9 @@ declare module "webgl-raub" {
719817
FRAMEBUFFER_INCOMPLETE_DIMENSIONS: number;
720818
FRAMEBUFFER_UNSUPPORTED: number;
721819
FRAMEBUFFER_BINDING: number;
820+
DRAW_FRAMEBUFFER_BINDING: number;
821+
DRAW_FRAMEBUFFER: number;
822+
READ_FRAMEBUFFER: number;
722823
RENDERBUFFER_BINDING: number;
723824
MAX_RENDERBUFFER_SIZE: number;
724825
INVALID_FRAMEBUFFER_OPERATION: number;
@@ -738,11 +839,21 @@ declare module "webgl-raub" {
738839
TRANSFORM_FEEDBACK_PAUSED: number;
739840
TRANSFORM_FEEDBACK_ACTIVE: number;
740841
TRANSFORM_FEEDBACK_BINDING: number;
842+
UNPACK_IMAGE_HEIGHT: number;
843+
UNPACK_SKIP_IMAGES: number;
844+
UNPACK_SKIP_PIXELS: number;
845+
UNPACK_SKIP_ROWS: number;
846+
TEXTURE_COMPARE_FUNC: number;
847+
TEXTURE_COMPARE_MODE: number;
848+
COMPARE_REF_TO_TEXTURE: number;
741849
UNPACK_FLIP_Y_WEBGL: number;
742850
UNPACK_PREMULTIPLY_ALPHA_WEBGL: number;
743851
CONTEXT_LOST_WEBGL: number;
744852
UNPACK_COLORSPACE_CONVERSION_WEBGL: number;
745853
BROWSER_DEFAULT_WEBGL: number;
854+
MAX: number;
855+
MIN: number;
856+
UNPACK_ROW_LENGTH: number;
746857
PIXEL_PACK_BUFFER: number;
747858
PIXEL_UNPACK_BUFFER: number;
748859
PIXEL_PACK_BUFFER_BINDING: number;

0 commit comments

Comments
 (0)