Fork me on GitHub

W

A micro WebGL2 framework

Features


Download

(v.1.02)
Commented, full
(23kb)
Minified, full
(8.1kb, 2.6kb zipped)
Minified, lite
(5.8kb, 2.0kb zipped)
No built-in models or smooth shading

or load it in HTML:

<script src=//xem.github.io/W/w.min.full.js></script>

API


// Start the framework
W.reset(canvasElement);

// Set clear color ("#fff" by default)
W.clearColor("#rgb");

// Set camera
// Settings: position (x, y, z), angle (rx, ry, rz), fov
W.camera({x, y, z, rx, ry, rz, fov});

// Set light direction
W.light({x, y, z});

// Set ambient light's force (between 0 and 1)
W.ambient(f);

// Create a group of objects: name, position, rotation
W.group({n, x, y, z, rx, ry, rz});

// Draw a built-in 3D object
// Settings: group, name, size, position, rotation, background, texture, smooth...
let settings = {g, n, size, x, y, z, rx, ry, rz, b, t, mix, s, ns, mode};
W.plane(settings);
W.billboard(settings);
W.cube(settings);
W.pyramid(settings);
W.sphere(settings);

// Add and draw a custom 3D model (see the OBJ file loader below)
W.add("custom_model", { vertices, uv, indices });
W.custom_model(settings);

// Move/resize a group or object: name, position, rotation, animation, delay (in ms)
W.move({n, size, x, y, z, rx, ry, rz, a}, delay);

// You can also use M to set a custom transformation matrix
W.move({n, M}, delay);

// Move camera / light: settings, animation, delay
W.camera({x, y, z, rx, ry, rz, a}, delay);
W.light({x, y, z, a}, delay);

// Delete an element: name, delay
W.delete(n, delay);

Examples / Tutorial



1) Setup
First, create a HTML5 canvas
<canvas id=canvasElement>
and call
W.reset(canvasElement)
.
By default, the camera is placed at [0,0,0], looking at the -Z axis, with a 30 degrees FoV.
The scene contains an ambient light and a directional light pointing to the bottom: [0, -1, 0].
You can set the camera's position, rotation and FoV using
W.camera({x, y, z, rx, ry, rz, fov})
.
You can set the directional light using
W.light({x, y, z})
and the ambient light leved using
W.ambient(n)
.
You can change the background color using
W.clearColor(c)
(where c is a hex RGB/RGBA string).
No need to start a render loop, the canvas is redrawn after each screen refresh.


2) Draw built-in 3D models
The full version of the framework includes 5 built-in shapes:
W.plane
,
W.billboard
,
W.cube
,
W.pyramid
and
W.sphere
.
(Billboards are planes that always face the camera, and can be used to show sprites or particles for example.)
The shapes settings can contain the following values:
{g, n, size, w, h, d, x, y, z, rx, ry, rz, b, t, mix, s, mode}
Groups can be created using
W.group({n, x, y, z, rx, ry, rz})
(or
W.group({n, M})
) and can be nested.

Edit on Codepen

3) Draw custom 3D models
Besides the built-in shapes, W can also import and display custom 3D models.
You'll need: Add the new model using
W.add("custom_shape", {vertices, uv, indices})
and draw it using
W.custom_shape(settings)
.
Custom models can be drawn with the same settings as the built-in ones (group, size, position, rotation, background, shading...).
Flat shading is applied by default, smooth shading is only available in the full version of the framework.
OBJ files can be converted into W custom models using the following online tool: OBJ2JS!

Edit on Codepen


4) Transformations and animation
The groups and 3D shapes can be moved and transformed using
W.move({n, size, x, y, z, rx, ry, rz, b, t, a}, delay)
.
If a
delay
is provided, the transformation will be done after that delay in milliseconds. (0 by default)
If an
a
parameter is provided, the transformation will be animated. The animation will last for
a
milliseconds. (0 by default)

The camera can be moved and animated using
W.camera({x, y, z, rx, ry, rz, a}, delay)
.
The directional light can be moved and animated with
W.light({x, y, z, a}, delay)
.

Edit on Codepen


5) Advanced techniques


Bonus:



2021-2022 - Made by xem, stas & kchplr