README

easy3d

npm npm

A 3D framework written by kresdl

Installation

npm i easy3d

Example

A simple app might look like this:

import { Camera, Scene, rotate, concat } from 'easy3d';
init();

async function init() {
  const vp = new Camera([0, 0, 165], [0, 0, 0], 1, 25, 1000, 1).matrix,

  canvas = document.getElementById('canvas'),
  scene = new Scene(canvas),
  assets = {
    prg: {
      fx: {
        vs: '/data/monkey_v.glsl', 
        fs: '/data/monkey_f.glsl'
      }
    },
    mesh: { 
      monkey: '/data/monkey.obj'
    },
    tex: {
      fur: '/data/monkey.png'
    }
  };

  await scene.add(assets);
  let mx = 0, my = 0;
  main();

  function main() {
    render({
      prg: 'fx',
      uni: {
        mvp: concat(rotate(my * 0.005, -mx * 0.005, 0), vp)
      },
      mesh: 'monkey',
      tex: 'fur'
    });
    mx += 4.0;
    my += 5.0;
    requestAnimationFrame(main)
  }
}

Scene

Abstraction class for asset management, uniforms handling and render procedure logic.

Constructor:

`Scene(canvas[, extensions])`

canvas: HTMLCanvasElement

extensions: String or Array defining extension(s).

Properties:

canvas: HTMLCanvasElement

assets: Assets

uni: Shader uniforms.

Methods:

add(assets)

Adds assets. Returns a promise that is resolved with the assets.

assets: Asset descriptions.

Throws if creation failed due to scene disposal.

render(arg)

Runs directive(s).

arg: Object or Iterable

Assets

Object containing the assets. Has the the same structure as asset descriptions.

tex: Textures
prg: Programs
tex: Meshes
rbo: Renderbuffers

Program

Methods:

drop()

Marks asset as obsolete after next directive invokation and that it should be disposed. Returns this asset.

Mesh

Properties:

cull: Boolean dictating face culling. Default is true.

ztest: Boolean dictating depth buffer testing. Default is true.

zwrite: Boolean dictating depth buffer writing. Default is true.

back: Boolean to use front side culling. Default is false.

Methods:

drop()

Marks asset as obsolete after next directive invokation and that it should be disposed. Returns this asset.

Texture

Properties:

[lod]: Level. lod is a positive integer where 0 represents the original image. Read-only.

Methods:

drop()

Marks asset as obsolete after next directive invokation and that it should be disposed. Returns this asset.

mip()

Generates mip levels and returns this texture.

Renderbuffer

Methods:

drop()

Marks asset as obsolete after next directive invokation and that it should be disposed. Returns this asset.

Asset descriptions

Object. Descriptions of assets which will be resolved with actual assets to be associated with the scene, grouped by type. The groups are:

prg: Object. Program descriptions by name.
tex: Object. Textures. By name, either a URL String, a texture description or an Iterable of these.
mesh: Object. Meshes. By name, either a URL String or a Mesh description.
rbo: Object. Renderbuffer descriptions by name.

Program description

Object describing a program.

vs: Either a URL String to vertex shader source or a Shader description. If omitted, the program will be created with a screen quad vertex shader.
fs: Either a URL String to fragment shader source or a Shader description.

Texture description

Object describing a texture.

src: Optional URL String or image data.
width: If width is unavailable on source. Texture width in pixels
height: If height is unavailable on source. Texture height in pixels
fmt: Internal format. Default gl.RGBA8.
srcFmt: Source format. Default is gl.RGBA.
type: Source data type. Default is gl.UNSIGNED_BYTE.
levels: A Boolean dictates the generation/storage reservation of/for mip levels. A Number specifies the amount of levels. Default is false for empty textues and true for non-empty.
wrap: Wrapping function. Default is gl.REPEAT.

Mesh description

Object describing a mesh.

src: A URL String to .obj-file.
computeTangentFrame: Boolean dictating generation of tangent and bitangent for each vertex, given a normal exists. This is done by default.

Renderbuffer description

width: width in pixels
height: height in pixels.
fmt: Internal format. Default format is gl.DEPTH24_STENCIL8.

Shader description

Object describing a shader.

src: A URL String to .glsl-file.
var: Alias mapper

Alias mapper

Object passed at shader creation with which to resolve aliases contained in shader source.

An alias is a word prefixed with $. It is mapped to a text fragment before compilation. If suffixed with .f it is considered a float and is casted accordingly.

Example:

//main.js 
//assets object
...
    fs: {
      blurx: {
        src: '/texy/data/shader.glsl', 
        vars: { x: 10 }
      }
    },
...

//shader.glsl
...
const float x = $x.f;
//Results in
//const float x = 10.0;
...

Shader uniform tree

Object for assigning shader uniforms. An assignment can either be a Number, a Number Array or an Array of Number arrays (matrix).

Example:

scene.uni = {
  uniformBlock: {
    uniform: 10,
    anotherUnifom: [1, 10, 20]
  }
}

Level

The render target at a certain detail level (lod) of a texture.

Color

Array of values between 0.0 and 1.0. Elements map to buffer format.

Vector

A Number Array of length 2 or 3.

Matrix

A 4x4 Number Array construction of format [column][row].

Blend modes

String. Can be 'over', 'atop', 'in', 'out', 'dest over', 'dest atop', 'dest in' or 'dest out'.

Directive

Object describing a render pass. Assets can be referenced with a String corresponding to the name defined in asset descriptions.

prg: Program to use. Either a program or a String. Default is paste.
mesh: Mesh to draw. Either a mesh or a String. Default is quad.
uni: Shader uniform tree
clear: Clear before draw. A Boolean dictates color- and depth clear. false disables clear and is default. true sets clear color to [0, 0, 0, 1] if target is the back buffer, or [0, 0, 0, 0] otherwise. An Array is either a color, or an Array of colors in case of multiple targets. An Object defines color and depth values. Default clear depth is 1.0.
blend: Boolean or blend mode. true enables 'over' blend mode and false disables blending. Default is false.
tex: Object, Array, texture, or String. If Object, key is a sampler as defined in the fragment shader of the program and value is a texture or a String. If Array, each sampler is assigned a texture with index corresponding to the order of the sampler's declaration in the fragment shader. If the program contains a single sampler, the texture can be assigned directly.
tg: Render target(s) if other than the back buffer. Either a level, a texture or a String, alternatively an Array of any of these. References are considered texture references and textures will be targeted at level 0.
z: Depth buffer if other than the back buffer's. Either a renderbuffer or a String.
area: Object. Clipping region defined by x, y, width and height in pixels.

If neither tex or prg is defined the target(s) will be cleared.

Utility assets

Screen quad

Mesh consisting of four vertices laid out in a rectangle. Each vertex has a texture coordinate attribute. For use in render operations to target the entire surface of the destination.

Paste program

Program that together with a screen quad copies the texture in sampler tex to the destination.

Screen quad vertex shader

The vertex shader component of Paste. Position is treated as a screen space coordinate which means that no perspective is applied. The texture coordinate attribute is passed to the fragment shader in data f_tex.

Utility classes

Camera

Convenience class for setup and handling of view- and perspective matrices

Properties:

view: View matrix

proj: Perspective matrix

matrix: View and perspective concatenated matrix. Lazily calculated.

Constructor:

new Camera(pos, lookAt, aspectRatio, zNear, zFar, fov[, glSpace])

pos: Observer position

target: Observation target position.

aspectRatio: Viewport width / height ratio

zNear: Near clipping plane

zFar: Far clipping plane

fov: Field of View in radians.

glSpace: Use gl matrices adapted to gl space. Default is true.

Methods:

move(pos, target)

Relocates and reorients camera.

pos: Observer position.

target: Observation target position.

Vector library

Methods for calculations on 3D-vectors:

add(a, b)

Returns the sum of two vectors.

cross(a, b)

Returns the cross product of two vectors.

div(v, d)

Returns the resulting vector of vector v divided by Number d.

dot(a, b)

Returns the dot product of two vectors.

length(v)

Returns the magnitude of a vector.

lerp(a, b, p)

Returns the interpolation of two vectors by parameter p (0.0 - 1.0).

mul(v, f)

Returns the resulting vector of vector v multiplied by Number f.

nrm(v)

Returns the normalized vector.

sub(v, b)

Returns the difference of two vectors.

tfc(coord, mat)

Transforms a vector as a coordinate by matrix mat.

tfn(normal, mat)

Transforms a vector as a normal by matrix mat.

Methods for calculations on 2D-vectors:

add2(a, b)

Returns the sum of two vectors.

cross2(a, b)

Returns the cross product of two vectors.

div2(v, d)

Returns the resulting vector of vector v divided by Number d.

dot2(a, b)

Returns the dot product of two vectors.

length2(v)

Returns the magnitude of a vector.

lerp2(a, b, p)

Returns the interpolation of two vectors by parameter p (0.0 - 1.0).

mul2(v, f)

Returns the resulting vector of vector v multiplied by Number f.

nrm2(v)

Returns the normalized vector.

sub2(a, b)

Returns the difference of two vectors.

Methods for calculations on matrices:

rotate(x, y, z)

Returns a matrix for rotation around x, y and z axes.

x, y and z: Rotation angle in radians around axis.

rotateX(r)

Returns a matrix for rotation around x axis.

r: Rotation angle in radians.

rotateY(r)

Returns a matrix for rotation around y axis.

r: Rotation angle in radians.

rotateZ(r)

Returns a matrix for rotation around z axis.

r: Rotation angle in radians.

scale(x, y, z)

Returns a scaling matrix.

x, y and z: Scaling factor for axis.

translate(x, y, z)

Returns a translation matrix.

x, y and z: Translation for axis.

arb(a, b, r)

Returns a matrix for rotation by r radians around an arbitrary axis defined by point a and b.

view(pos, target)

Returns a view matrix.

pos: Observer position

target: Observation target position.

glView(pos, target)

Same as view() but adapted to gl space.

proj(zNear, zFar, fov, aspectRatio)

Returns a perspective matrix.

zNear: Near clipping plane

zFar: Far clipping plane

fov: Field of View in radians.

aspectRatio: Viewport width / height ratio

glProj(zNear, zFar, fov, aspectRatio)

Same as proj() but adapted to gl space.

concat(a, b)

Returns the concatenation of two matrices.

a and b: Matrix

inverse(m)

Returns the inverse matrix.

m: Matrix to inverse.

transpose(m)

Returns the transpose matrix.

m: Matrix to transpose.

GLenums

GLenum parameters in context Methods: can be substituted by a String where _ is replaced by - and all letters are decapitalized. For example, gl.UNSIGNED_BYTE becomes 'unsigned-byte'.

Renderbuffer internal format

gl.RGBA4
gl.RGB565
gl.RGB5_A1
gl.DEPTH_COMPONENT16
gl.STENCIL_INDEX8
gl.DEPTH_STENCIL
gl.R8
gl.R8UI
gl.R8I
gl.R16UI
gl.R16I
gl.R32UI
gl.R32I
gl.RG8
gl.RG8UI
gl.RG8I
gl.RG16UI
gl.RG16I
gl.RG32UI
gl.RG32I
gl.RGB8
gl.RGBA8
gl.SRGB8_ALPHA8
gl.RGB10_A2
gl.RGBA8UI
gl.RGBA8I
gl.RGB10_A2UI
gl.RGBA16UI
gl.RGBA16I
gl.RGBA32I
gl.RGBA32UI
gl.DEPTH_COMPONENT24
gl.DEPTH_COMPONENT32F
gl.DEPTH24_STENCIL8
gl.DEPTH32F_STENCIL8

When using the EXT_color_buffer_float extension:

gl.R16F
gl.RG16F
gl.RGBA16F
gl.R32F
gl.RG32F
gl.RGBA32F
gl.R11F_G11F_B10F

Texture internal format

gl.ALPHA
gl.RGB
gl.RGBA
gl.LUMINANCE
gl.LUMINANCE_ALPHA
gl.DEPTH_COMPONENT
gl.DEPTH_STENCIL
gl.R16F
gl.R32F
gl.R8UI
gl.RG8
gl.RG16F
gl.RG32F
gl.RG8UI
gl.RG16UI
gl.RG32UI
gl.RGB8
gl.SRGB8
gl.RGB565
gl.R11F_G11F_B10F
gl.RGB9_E5
gl.RGB16F
gl.RGB32F
gl.RGB8UI
gl.RGBA8
gl.SRGB8_APLHA8
gl.RGB5_A1
gl.RGB10_A2
gl.RGBA4
gl.RGBA16F
gl.RGBA32F
gl.RGBA8UI

Texture source format

gl.RED
gl.RG
gl.RGB
gl.RGBA
gl.ALPHA
gl.RGBA_INTEGER
gl.LUMINANCE
gl.LUMINANCE_ALPHA
gl.DEPTH_COMPONENT
gl.DEPTH_STENCIL

Texture data type

gl.UNSIGNED_BYTE: 8 bits per channel for gl.RGBA
gl.UNSIGNED_SHORT_5_6_5: 5 red bits, 6 green bits, 5 blue bits.
gl.UNSIGNED_SHORT_4_4_4_4: 4 red bits, 4 green bits, 4 blue bits, 4 alpha bits.
gl.UNSIGNED_SHORT_5_5_5_1: 5 red bits, 5 green bits, 5 blue bits, 1 alpha bit.
gl.BYTE
gl.UNSIGNED_SHORT
gl.SHORT
gl.UNSIGNED_INT
gl.INT
gl.HALF_FLOAT
gl.FLOAT
gl.UNSIGNED_INT_2_10_10_10_REV
gl.UNSIGNED_INT_10F_11F_11F_REV
gl.UNSIGNED_INT_5_9_9_9_REV
gl.UNSIGNED_INT_24_8
gl.FLOAT_32_UNSIGNED_INT_24_8_REV (pixels must be null)

Texture wrapping function

gl.REPEAT
gl.CLAMP_TO_EDGE
gl.MIRRORED_REPEAT

Shader type

gl.VERTEX_SHADER
gl.FRAGMENT_SHADER

Buffer types

gl.ARRAY_BUFFER: Buffer containing vertex attributes, such as vertex coordinates, texture coordinate data, or vertex color data.
gl.ELEMENT_ARRAY_BUFFER: Buffer used for element indices.
gl.COPY_READ_BUFFER: Buffer for copying from one buffer object to another.
gl.COPY_WRITE_BUFFER: Buffer for copying from one buffer object to another.
gl.TRANSFORM_FEEDBACK_BUFFER: Buffer for transform feedback operations.
gl.UNIFORM_BUFFER: Buffer used for storing uniform blocks.
gl.PIXEL_PACK_BUFFER: Buffer used for pixel transfer operations.
gl.PIXEL_UNPACK_BUFFER: Buffer used for pixel transfer operations.

Buffer usage hints

gl.STATIC_DRAW: Contents of the buffer are likely to be used often and not change often. Contents are written to the buffer, but not read.
gl.DYNAMIC_DRAW: Contents of the buffer are likely to be used often and change often. Contents are written to the buffer, but not read.
gl.STREAM_DRAW: Contents of the buffer are likely to not be used often. Contents are written to the buffer, but not read.
gl.STATIC_READ: Contents of the buffer are likely to be used often and not change often. Contents are read from the buffer, but not written.
gl.DYNAMIC_READ: Contents of the buffer are likely to be used often and change often. Contents are read from the buffer, but not written.
gl.STREAM_READ: Contents of the buffer are likely to not be used often. Contents are read from the buffer, but not written.
gl.STATIC_COPY: Contents of the buffer are likely to be used often and not change often. Contents are neither written or read by the user.
gl.DYNAMIC_COPY: Contents of the buffer are likely to be used often and change often. Contents are neither written or read by the user.
gl.STREAM_COPY: Contents of the buffer are likely to be used often and not change often. Contents are neither written or read by the user.

Framebuffer status codes

gl.FRAMEBUFFER_COMPLETE: The framebuffer is ready to display.
gl.FRAMEBUFFER_INCOMPLETE_ATTACHMENT: The attachment types are mismatched or not all framebuffer attachment points are framebuffer attachment complete.
gl.FRAMEBUFFER_INCOMPLETE_MISSING_ATTACHMENT: There is no attachment.
gl.FRAMEBUFFER_INCOMPLETE_DIMENSIONS: Height and width of the attachment are not the same.
gl.FRAMEBUFFER_UNSUPPORTED: The format of the attachment is not supported or if depth and stencil attachments are not the same renderbuffer.
gl.FRAMEBUFFER_INCOMPLETE_MULTISAMPLE: The values of gl.RENDERBUFFER_SAMPLES are different among attached renderbuffers, or are non-zero if the attached images are a mix of renderbuffers and textures.

Source: MDN

Extensions

EXT_color_buffer_float

The following sized formats become color-renderable:

gl.R16F, gl.RG16F, gl.RGBA16F, gl.R32F, gl.RG32F, gl.RGBA32F, gl.R11F_G11F_B10F.

Color-renderable means: The WebGLRenderingContext.renderbufferStorage() method now accepts these formats. Framebuffers with attached textures of these formats may now be FRAMEBUFFER_COMPLETE.
EXT_texture_filter_anisotropic

Part of the WebGL API and exposes two constants for anisotropic filtering (AF). AF improves the quality of mipmapped texture access when viewing a textured primitive at an oblique angle. Using just mipmapping, these lookups have a tendency to average to grey.

Constants
- ext.MAX_TEXTURE_MAX_ANISOTROPY_EXT This is the pname argument to the gl.getParameter() call, and it returns the maximum available anisotropy.
- ext.TEXTURE_MAX_ANISOTROPY_EXT This is the pname argument to the gl.getTexParameter() and gl.texParameterf() / gl.texParameteri() calls and sets the desired maximum anisotropy for a texture.
OES_texture_float_linear

Allows linear filtering with floating-point pixel types for textures. With the help of this extension, you can now set the magnification or minification filter in the WebGLRenderingContext.texParameter() method to one of gl.LINEAR, gl.LINEAR_MIPMAP_NEAREST, gl.NEAREST_MIPMAP_LINEAR, or gl.LINEAR_MIPMAP_LINEAR, and use floating-point textures.
OES_texture_half_float_linear

Allows linear filtering with half floating-point pixel types for textures.
WEBGL_debug_renderer_info

Exposes two constants with information about the graphics driver for debugging purposes. Depending on the privacy settings of the browser, this extension might only be available to privileged contexts. Generally, the graphics driver information should only be used in edge cases to optimize your WebGL content or to debug GPU problems. The WebGLRenderingContext.getParameter() method can help you to detect which features are supported and the failIfMajorPerformanceCaveat context attribute lets you control if a context should be returned at all, if the performance would be dramatically slow.

Constants
- ext.UNMASKED_VENDOR_WEBGL Vendor string of the graphics driver.
- ext.UNMASKED_RENDERER_WEBGL Renderer string of the graphics driver.
WEBGL_debug_shaders

Exposes a method to debug shaders from privileged contexts. This extension is not directly available to web sites as the way of how the shader is translated may uncover personally-identifiable information to the web page about the kind of graphics card in the user's computer.

Methods:
- WEBGL_debug_shaders.getTranslatedShaderSource() Returns the translated shader source.
WEBGL_lose_context

Exposes functions to simulate losing and restoring a WebGLRenderingContext.

Methods:
- WEBGL_lose_context.loseContext() Simulates losing the context.
- WEBGL_lose_context.restoreContext() Simulates restoring the context.

Source: MDN

Image data

Any of the following:

Uint8Array if type is gl.UNSIGNED_BYTE.
Uint16Array if type is either gl.UNSIGNED_SHORT_5_6_5, gl.UNSIGNED_SHORT_4_4_4_4, gl.UNSIGNED_SHORT_5_5_5_1, gl.UNSIGNED_SHORT or ext.HALF_FLOAT_OES.
A Uint32Array if type is gl.UNSIGNED_INT or ext.UNSIGNED_INT_24_8_WEBGL.
A Float32Array if type is gl.FLOAT.
ImageData
HTMLImageElement
HTMLCanvasElement
HTMLVideoElement
ImageBitmap

Source: MDN

Usage no npm install needed!

README

easy3d

Installation

Example

Scene

Constructor:

Scene(canvas[, extensions])

Properties:

Methods:

Assets

Program

Methods:

Mesh

Properties:

Methods:

Texture

Properties:

Methods:

Renderbuffer

Methods:

Asset descriptions

Program description

Texture description

Mesh description

Renderbuffer description

Shader description

Alias mapper

Shader uniform tree

Level

Color

Vector

Matrix

Blend modes

Directive

Utility assets

Screen quad

Paste program

Screen quad vertex shader

Utility classes

Camera

Properties:

Constructor:

Methods:

Vector library

Methods for calculations on 3D-vectors:

Methods for calculations on 2D-vectors:

Methods for calculations on matrices:

GLenums

Extensions

Related

Image data

`Scene(canvas[, extensions])`