twgl

Attempts to enable all of the following extensions
and add their functions and constants to the
WebGLRenderingContext using their normal non-extension like names.

 ANGLE_instanced_arrays
 EXT_blend_minmax
 EXT_color_buffer_float
 EXT_color_buffer_half_float
 EXT_disjoint_timer_query
 EXT_disjoint_timer_query_webgl2
 EXT_frag_depth
 EXT_sRGB
 EXT_shader_texture_lod
 EXT_texture_filter_anisotropic
 OES_element_index_uint
 OES_standard_derivatives
 OES_texture_float
 OES_texture_float_linear
 OES_texture_half_float
 OES_texture_half_float_linear
 OES_vertex_array_object
 WEBGL_color_buffer_float
 WEBGL_compressed_texture_atc
 WEBGL_compressed_texture_etc1
 WEBGL_compressed_texture_pvrtc
 WEBGL_compressed_texture_s3tc
 WEBGL_compressed_texture_s3tc_srgb
 WEBGL_depth_texture
 WEBGL_draw_buffers

For example if ANGLE_instanced_arrays exists then the functions
drawArraysInstanced, drawElementsInstanced, vertexAttribDivisor
and the constant VERTEX_ATTRIB_ARRAY_DIVISOR are added to the
WebGLRenderingContext.

Note that if you want to know if the extension exists you should
probably call gl.getExtension for each extension. Alternatively
you can check for the existence of the functions or constants that
are expected to be added. For example

if (gl.drawBuffers) {
// Either WEBGL_draw_buffers was enabled OR you're running in WebGL2
....

Binds a framebuffer

This function pretty much solely exists because I spent hours
trying to figure out why something I wrote wasn't working only
to realize I forget to set the viewport dimensions.
My hope is this function will fix that.

It is effectively the same as

gl.bindFramebuffer(gl.FRAMEBUFFER, someFramebufferInfo.framebuffer);
gl.viewport(0, 0, someFramebufferInfo.width, someFramebufferInfo.height);

Binds buffers for transform feedback.

Binds a uniform block to the matching uniform block point.
Matches by blocks by name so blocks must have the same name not just the same
structure.

If you have changed any values and you upload the values into the corresponding WebGLBuffer
call module:twgl.setUniformBlock instead.

Creates a BufferInfo from an object of arrays.

This can be passed to module:twgl.setBuffersAndAttributes and to
module:twgl:drawBufferInfo.

Given an object like

var arrays = {
  position: { numComponents: 3, data: [0, 0, 0, 10, 0, 0, 0, 10, 0, 10, 10, 0], },
  texcoord: { numComponents: 2, data: [0, 0, 0, 1, 1, 0, 1, 1],                 },
  normal:   { numComponents: 3, data: [0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1],     },
  indices:  { numComponents: 3, data: [0, 1, 2, 1, 2, 3],                       },
};

Creates an BufferInfo like this

bufferInfo = {
  numElements: 4,        // or whatever the number of elements is
  indices: WebGLBuffer,  // this property will not exist if there are no indices
  attribs: {
    position: { buffer: WebGLBuffer, numComponents: 3, },
    normal:   { buffer: WebGLBuffer, numComponents: 3, },
    texcoord: { buffer: WebGLBuffer, numComponents: 2, },
  },
};

The properties of arrays can be JavaScript arrays in which case the number of components
will be guessed.

var arrays = {
   position: [0, 0, 0, 10, 0, 0, 0, 10, 0, 10, 10, 0],
   texcoord: [0, 0, 0, 1, 1, 0, 1, 1],
   normal:   [0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1],
   indices:  [0, 1, 2, 1, 2, 3],
};

They can also be TypedArrays

var arrays = {
   position: new Float32Array([0, 0, 0, 10, 0, 0, 0, 10, 0, 10, 10, 0]),
   texcoord: new Float32Array([0, 0, 0, 1, 1, 0, 1, 1]),
   normal:   new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1]),
   indices:  new Uint16Array([0, 1, 2, 1, 2, 3]),
};

Or AugmentedTypedArrays

var positions = createAugmentedTypedArray(3, 4);
var texcoords = createAugmentedTypedArray(2, 4);
var normals   = createAugmentedTypedArray(3, 4);
var indices   = createAugmentedTypedArray(3, 2, Uint16Array);

positions.push([0, 0, 0, 10, 0, 0, 0, 10, 0, 10, 10, 0]);
texcoords.push([0, 0, 0, 1, 1, 0, 1, 1]);
normals.push([0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1]);
indices.push([0, 1, 2, 1, 2, 3]);

var arrays = {
   position: positions,
   texcoord: texcoords,
   normal:   normals,
   indices:  indices,
};

For the last example it is equivalent to

var bufferInfo = {
  attribs: {
    position: { numComponents: 3, buffer: gl.createBuffer(), },
    texcoord: { numComponents: 2, buffer: gl.createBuffer(), },
    normal: { numComponents: 3, buffer: gl.createBuffer(), },
  },
  indices: gl.createBuffer(),
  numElements: 6,
};

gl.bindBuffer(gl.ARRAY_BUFFER, bufferInfo.attribs.position.buffer);
gl.bufferData(gl.ARRAY_BUFFER, arrays.position, gl.STATIC_DRAW);
gl.bindBuffer(gl.ARRAY_BUFFER, bufferInfo.attribs.texcoord.buffer);
gl.bufferData(gl.ARRAY_BUFFER, arrays.texcoord, gl.STATIC_DRAW);
gl.bindBuffer(gl.ARRAY_BUFFER, bufferInfo.attribs.normal.buffer);
gl.bufferData(gl.ARRAY_BUFFER, arrays.normal, gl.STATIC_DRAW);
gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, bufferInfo.indices);
gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, arrays.indices, gl.STATIC_DRAW);

Creates a framebuffer and attachments.

This returns a module:twgl.FramebufferInfo because it needs to return the attachments as well as the framebuffer.
It also leaves the framebuffer it just created as the currently bound FRAMEBUFFER.
Note: If this is WebGL2 or if you called module:twgl.addExtensionsToContext then it will set the drawBuffers
to [COLOR_ATTACHMENT0, COLOR_ATTACHMENT1, ...] for how ever many color attachments were created.

The simplest usage

// create an RGBA/UNSIGNED_BYTE texture and DEPTH_STENCIL renderbuffer
const fbi = twgl.createFramebufferInfo(gl);

More complex usage

// create an RGB565 renderbuffer and a STENCIL_INDEX8 renderbuffer
const attachments = [
  { format: RGB565, mag: NEAREST },
  { format: STENCIL_INDEX8 },
]
const fbi = twgl.createFramebufferInfo(gl, attachments);

Passing in a specific size

const width = 256;
const height = 256;
const fbi = twgl.createFramebufferInfo(gl, attachments, width, height);

Note!! It is up to you to check if the framebuffer is renderable by calling gl.checkFramebufferStatus.
WebGL1 only guarantees 3 combinations of attachments work.

Creates a ProgramInfo from 2 sources.

A ProgramInfo contains

programInfo = {
   program: WebGLProgram,
   uniformSetters: object of setters as returned from createUniformSetters,
   attribSetters: object of setters as returned from createAttribSetters,
}

NOTE: There are 4 signatures for this function

twgl.createProgramInfo(gl, [vs, fs], options);
twgl.createProgramInfo(gl, [vs, fs], opt_errFunc);
twgl.createProgramInfo(gl, [vs, fs], opt_attribs, opt_errFunc);
twgl.createProgramInfo(gl, [vs, fs], opt_attribs, opt_locations, opt_errFunc);

Creates a texture based on the options passed in.

Note: may reset UNPACK_ALIGNMENT, UNPACK_ROW_LENGTH, UNPACK_IMAGE_HEIGHT, UNPACK_SKIP_IMAGES
UNPACK_SKIP_PIXELS, and UNPACK_SKIP_ROWS

UNPACK_FLIP_Y_WEBGL, UNPACK_PREMULTIPLY_ALPHA_WEBGL, UNPACK_COLORSPACE_CONVERSION_WEBGL
are left as is though you can pass in options for flipY, premultiplyAlpha, and colorspaceConversion
to override them.

As for the behavior of these settings

gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
t1 = twgl.createTexture({src: someImage }); // flipped
t2 = twgl.createTexture({src: someImage, flipY: true }); // flipped
t3 = twgl.createTexture({src: someImage, flipY: false }); // not flipped
t4 = twgl.createTexture({src: someImage }); // flipped

• t1 is flipped because UNPACK_FLIP_Y_WEBGL is true
• t2 is flipped because it was requested
• t3 is not flipped because it was requested
• t4 is flipped because UNPACK_FLIP_Y_WEBGL has been restored to true

Creates a bunch of textures based on the passed in options.

Example:

const textures = twgl.createTextures(gl, {
  // a power of 2 image
  hftIcon: { src: "images/hft-icon-16.png", mag: gl.NEAREST },
  // a non-power of 2 image
  clover: { src: "images/clover.jpg" },
  // From a canvas
  fromCanvas: { src: ctx.canvas },
  // A cubemap from 6 images
  yokohama: {
    target: gl.TEXTURE_CUBE_MAP,
    src: [
      'images/yokohama/posx.jpg',
      'images/yokohama/negx.jpg',
      'images/yokohama/posy.jpg',
      'images/yokohama/negy.jpg',
      'images/yokohama/posz.jpg',
      'images/yokohama/negz.jpg',
    ],
  },
  // A cubemap from 1 image (can be 1x6, 2x3, 3x2, 6x1)
  goldengate: {
    target: gl.TEXTURE_CUBE_MAP,
    src: 'images/goldengate.jpg',
  },
  // A 2x2 pixel texture from a JavaScript array
  checker: {
    mag: gl.NEAREST,
    min: gl.LINEAR,
    src: [
      255,255,255,255,
      192,192,192,255,
      192,192,192,255,
      255,255,255,255,
    ],
  },
  // a 1x2 pixel texture from a typed array.
  stripe: {
    mag: gl.NEAREST,
    min: gl.LINEAR,
    format: gl.LUMINANCE,
    src: new Uint8Array([
      255,
      128,
      255,
      128,
      255,
      128,
      255,
      128,
    ]),
    width: 1,
  },
});

Now

• textures.hftIcon will be a 2d texture
• textures.clover will be a 2d texture
• textures.fromCanvas will be a 2d texture
• textures.yohohama will be a cubemap texture
• textures.goldengate will be a cubemap texture
• textures.checker will be a 2d texture
• textures.stripe will be a 2d texture

Creates a transform feedback and sets the buffers

Create TransformFeedbackInfo for passing to bindTransformFeedbackInfo.

Creates a UniformBlockInfo for the specified block

Note: If the blockName matches no existing blocks a warning is printed to the console and a dummy
UniformBlockInfo is returned. This is because when debugging GLSL
it is common to comment out large portions of a shader or for example set
the final output to a constant. When that happens blocks get optimized out.
If this function did not create dummy blocks your code would crash when debugging.

Calls gl.drawElements or gl.drawArrays, whichever is appropriate

normally you'd call gl.drawElements or gl.drawArrays yourself
but calling this means if you switch from indexed data to non-indexed
data you don't have to remember to update your draw call.

Draws a list of objects

Gets a WebGL context. Will create a WebGL2 context if possible.

You can check if it's WebGL2 with

function isWebGL2(gl) {
return gl.getParameter(gl.VERSION).indexOf("WebGL 2.0 ") == 0;
}

Note: For a WebGL1 context will attempt to enable Vertex Array Objects
and add WebGL2 entry points. (unless you first set defaults with
twgl.setDefaults({enableVertexArrayObjects: false});

Gets a string for WebGL enum

Note: Several enums are the same. Without more
context (which function) it's impossible to always
give the correct enum. As it is, for matching values
it gives all enums. Checking the WebGL2RenderingContext
that means

 0     = ZERO | POINT | NONE | NO_ERROR
 1     = ONE | LINES | SYNC_FLUSH_COMMANDS_BIT
 32777 = BLEND_EQUATION_RGB | BLEND_EQUATION_RGB
 36662 = COPY_READ_BUFFER | COPY_READ_BUFFER_BINDING
 36663 = COPY_WRITE_BUFFER | COPY_WRITE_BUFFER_BINDING
 36006 = FRAMEBUFFER_BINDING | DRAW_FRAMEBUFFER_BINDING

It's also not useful for bits really unless you pass in individual bits.
In other words

const bits = gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT;
twgl.glEnumToString(gl, bits);  // not going to work

Note that some enums only exist on extensions. If you
want them to show up you need to pass the extension at least
once. For example

const ext = gl.getExtension('WEBGL_compressed_texture_s3tc');
if (ext) {
   twgl.glEnumToString(ext, 0);  // just prime the function

   ..later..

   const internalFormat = ext.COMPRESSED_RGB_S3TC_DXT1_EXT;
   console.log(twgl.glEnumToString(gl, internalFormat));

Notice I didn't have to pass the extension the second time. This means
you can have place that generically gets an enum for texture formats for example.
and as long as you primed the function with the extensions

If you're using twgl.addExtensionsToContext to enable your extensions
then twgl will automatically get the extension's enums.

Check if context is WebGL 1.0

Check if context is WebGL 2.0

Resize a canvas to match the size it's displayed.

Resizes the attachments of a framebuffer.

You need to pass in the same attachments as you passed in module:twgl.createFramebufferInfo
because TWGL has no idea the format/type of each attachment.

The simplest usage

// create an RGBA/UNSIGNED_BYTE texture and DEPTH_STENCIL renderbuffer
const fbi = twgl.createFramebufferInfo(gl);

...

function render() {
  if (twgl.resizeCanvasToDisplaySize(gl.canvas)) {
    // resize the attachments
    twgl.resizeFramebufferInfo(gl, fbi);
  }

More complex usage

// create an RGB565 renderbuffer and a STENCIL_INDEX8 renderbuffer
const attachments = [
  { format: RGB565, mag: NEAREST },
  { format: STENCIL_INDEX8 },
]
const fbi = twgl.createFramebufferInfo(gl, attachments);

...

function render() {
  if (twgl.resizeCanvasToDisplaySize(gl.canvas)) {
    // resize the attachments to match
    twgl.resizeFramebufferInfo(gl, fbi, attachments);
  }

Resizes a texture based on the options passed in.

Note: This is not a generic resize anything function.
It's mostly used by module:twgl.resizeFramebufferInfo
It will use options.src if it exists to try to determine a type
otherwise it will assume gl.UNSIGNED_BYTE. No data is provided
for the texture. Texture parameters will be set accordingly

Sets the contents of a buffer attached to an attribInfo

This is helper function to dynamically update a buffer.

Let's say you make a bufferInfo

var arrays = {
   position: new Float32Array([0, 0, 0, 10, 0, 0, 0, 10, 0, 10, 10, 0]),
   texcoord: new Float32Array([0, 0, 0, 1, 1, 0, 1, 1]),
   normal:   new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1]),
   indices:  new Uint16Array([0, 1, 2, 1, 2, 3]),
};
var bufferInfo = twgl.createBufferInfoFromArrays(gl, arrays);

And you want to dynamically update the positions. You could do this

// assuming arrays.position has already been updated with new data.
twgl.setAttribInfoBufferFromArray(gl, bufferInfo.attribs.position, arrays.position);

Sets values of a uniform block object

Sets attributes and buffers including the ELEMENT_ARRAY_BUFFER if appropriate

Example:

const programInfo = createProgramInfo(
    gl, ["some-vs", "some-fs");

const arrays = {
  position: { numComponents: 3, data: [0, 0, 0, 10, 0, 0, 0, 10, 0, 10, 10, 0], },
  texcoord: { numComponents: 2, data: [0, 0, 0, 1, 1, 0, 1, 1],                 },
};

const bufferInfo = createBufferInfoFromArrays(gl, arrays);

gl.useProgram(programInfo.program);

This will automatically bind the buffers AND set the
attributes.

setBuffersAndAttributes(gl, programInfo, bufferInfo);

For the example above it is equivalent to

gl.bindBuffer(gl.ARRAY_BUFFER, positionBuffer);
gl.enableVertexAttribArray(a_positionLocation);
gl.vertexAttribPointer(a_positionLocation, 3, gl.FLOAT, false, 0, 0);
gl.bindBuffer(gl.ARRAY_BUFFER, texcoordBuffer);
gl.enableVertexAttribArray(a_texcoordLocation);
gl.vertexAttribPointer(a_texcoordLocation, 4, gl.FLOAT, false, 0, 0);

Sets various defaults for twgl.

In the interest of terseness which is kind of the point
of twgl I've integrated a few of the older functions here

Sets a texture from an array or typed array. If the width or height is not provided will attempt to
guess the size. See module:twgl.TextureOptions.

Uploads the current uniform values to the corresponding WebGLBuffer
and binds that buffer to the program's corresponding bind point for the uniform block object.

If you haven't changed any values and you only need to bind the uniform block object
call module:twgl.bindUniformBlock instead.

Set uniforms and binds related textures.

example:

const programInfo = createProgramInfo(
    gl, ["some-vs", "some-fs"]);

const tex1 = gl.createTexture();
const tex2 = gl.createTexture();

... assume we setup the textures with data ...

const uniforms = {
  u_someSampler: tex1,
  u_someOtherSampler: tex2,
  u_someColor: [1,0,0,1],
  u_somePosition: [0,1,1],
  u_someMatrix: [
    1,0,0,0,
    0,1,0,0,
    0,0,1,0,
    0,0,0,0,
  ],
};

gl.useProgram(programInfo.program);

This will automatically bind the textures AND set the
uniforms.

twgl.setUniforms(programInfo, uniforms);

For the example above it is equivalent to

let texUnit = 0;
gl.activeTexture(gl.TEXTURE0 + texUnit);
gl.bindTexture(gl.TEXTURE_2D, tex1);
gl.uniform1i(u_someSamplerLocation, texUnit++);
gl.activeTexture(gl.TEXTURE0 + texUnit);
gl.bindTexture(gl.TEXTURE_2D, tex2);
gl.uniform1i(u_someSamplerLocation, texUnit++);
gl.uniform4fv(u_someColorLocation, [1, 0, 0, 1]);
gl.uniform3fv(u_somePositionLocation, [0, 1, 1]);
gl.uniformMatrix4fv(u_someMatrix, false, [
    1,0,0,0,
    0,1,0,0,
    0,0,1,0,
    0,0,0,0,
  ]);

Note it is perfectly reasonable to call setUniforms multiple times. For example

const uniforms = {
  u_someSampler: tex1,
  u_someOtherSampler: tex2,
};

const moreUniforms {
  u_someColor: [1,0,0,1],
  u_somePosition: [0,1,1],
  u_someMatrix: [
    1,0,0,0,
    0,1,0,0,
    0,0,1,0,
    0,0,0,0,
  ],
};

twgl.setUniforms(programInfo, uniforms);
twgl.setUniforms(programInfo, moreUniforms);

You can also add WebGLSamplers to uniform samplers as in

const uniforms = {
  u_someSampler: {
    texture: someWebGLTexture,
    sampler: someWebGLSampler,
  },
};

In which case both the sampler and texture will be bound to the
same unit.

Creates a webgl context.

Will return a WebGL2 context if possible.

You can check if it's WebGL2 with

twgl.isWebGL2(gl);

A callback for when an image finished downloading and been uploaded into a texture

Error Callback

A function to generate the source for a texture.

A callback for when an image finished downloading and been uploaded into a texture

A callback for when all images have finished downloading and been uploaded into their respective textures

A callback for when an image finished downloading and been uploaded into a texture