twgl/attributes

Low level attribute and buffer related functions

You should generally not need to use these functions. They are provided
for those cases where you're doing something out of the ordinary
and you need lower level access.

For backward compatibily they are available at both twgl.attributes and twgl
itself

See module:twgl for core functions

Methods

(static) createAttribsFromArrays(gl, arrays) → {Object.<string, module:twgl.AttribInfo>}

Creates a set of attribute data and WebGLBuffers from set of arrays

Given

 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],     },
   color:    { numComponents: 4, data: [255, 255, 255, 255, 255, 0, 0, 255, 0, 0, 255, 255], type: Uint8Array, },
   indices:  { numComponents: 3, data: [0, 1, 2, 1, 2, 3],                       },
 };

returns something like

 var attribs = {
   position: { numComponents: 3, type: gl.FLOAT,         normalize: false, buffer: WebGLBuffer, },
   texcoord: { numComponents: 2, type: gl.FLOAT,         normalize: false, buffer: WebGLBuffer, },
   normal:   { numComponents: 3, type: gl.FLOAT,         normalize: false, buffer: WebGLBuffer, },
   color:    { numComponents: 4, type: gl.UNSIGNED_BYTE, normalize: true,  buffer: WebGLBuffer, },
 };

notes:

  • Arrays can take various forms

    Bare JavaScript Arrays

    var arrays = {
       position: [-1, 1, 0],
       normal: [0, 1, 0],
       ...
    }

    Bare TypedArrays

    var arrays = {
       position: new Float32Array([-1, 1, 0]),
       color: new Uint8Array([255, 128, 64, 255]),
       ...
    }
  • Will guess at numComponents if not specified based on name.

    If coord is in the name assumes numComponents = 2

    If color is in the name assumes numComponents = 4

    otherwise assumes numComponents = 3

Parameters:
Name Type Description
gl WebGLRenderingContext

The webgl rendering context.

arrays module:twgl.Arrays

The arrays

Returns:

the attribs

Type
Object.<string, module:twgl.AttribInfo>

(static) createBufferFromArray(gl, array, arrayName) → {WebGLBuffer}

Creates a buffer from an array, typed array, or array spec

Given something like this

[1, 2, 3],

or

new Uint16Array([1,2,3]);

or

{
   data: [1, 2, 3],
   type: Uint8Array,
}

returns a WebGLBuffer that constains the given data.

Parameters:
Name Type Description
gl WebGLRenderingContext

A WebGLRenderingContext.

array module:twgl.ArraySpec

an array, typed array, or array spec.

arrayName string

name of array. Used to guess the type if type can not be dervied other wise.

Returns:

a WebGLBuffer containing the data in array.

Type
WebGLBuffer

(static) createBufferFromTypedArray(gl, typedArray, typeopt, drawTypeopt) → {WebGLBuffer}

Given typed array creates a WebGLBuffer and copies the typed array
into it.

Parameters:
Name Type Attributes Description
gl WebGLRenderingContext

A WebGLRenderingContext

typedArray ArrayBuffer | ArrayBufferView | WebGLBuffer

the typed array. Note: If a WebGLBuffer is passed in it will just be returned. No action will be taken

type number <optional>

the GL bind type for the buffer. Default = gl.ARRAY_BUFFER.

drawType number <optional>

the GL draw type for the buffer. Default = 'gl.STATIC_DRAW`.

Returns:

the created WebGLBuffer

Type
WebGLBuffer

(static) createBufferInfoFromArrays(gl, arrays) → {module:twgl.BufferInfo}

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: {
    a_position: { buffer: WebGLBuffer, numComponents: 3, },
    a_normal:   { buffer: WebGLBuffer, numComponents: 3, },
    a_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 by 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: {
    a_position: { numComponents: 3, buffer: gl.createBuffer(), },
    a_texcoods: { numComponents: 2, buffer: gl.createBuffer(), },
    a_normals: { numComponents: 3, buffer: gl.createBuffer(), },
  },
  indices: gl.createBuffer(),
  numElements: 6,
};

gl.bindBuffer(gl.ARRAY_BUFFER, bufferInfo.attribs.a_position.buffer);
gl.bufferData(gl.ARRAY_BUFFER, arrays.position, gl.STATIC_DRAW);
gl.bindBuffer(gl.ARRAY_BUFFER, bufferInfo.attribs.a_texcoord.buffer);
gl.bufferData(gl.ARRAY_BUFFER, arrays.texcoord, gl.STATIC_DRAW);
gl.bindBuffer(gl.ARRAY_BUFFER, bufferInfo.attribs.a_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);
Parameters:
Name Type Description
gl WebGLRenderingContext

A WebGLRenderingContext

arrays module:twgl.Arrays

Your data

Returns:

A BufferInfo

Type
module:twgl.BufferInfo

(static) createBuffersFromArrays(gl, arrays) → {Object.<string, WebGLBuffer>}

Creates buffers from arrays or typed arrays

Given something like this

var arrays = {
   positions: [1, 2, 3],
   normals: [0, 0, 1],
}

returns something like

buffers = {
  positions: WebGLBuffer,
  normals: WebGLBuffer,
}

If the buffer is named 'indices' it will be made an ELEMENT_ARRAY_BUFFER.

Parameters:
Name Type Description
gl WebGLRenderingContext

A WebGLRenderingContext.

arrays module:twgl.Arrays
Returns:

returns an object with one WebGLBuffer per array

Type
Object.<string, WebGLBuffer>

(static) setAttribInfoBufferFromArray(gl, attribInfo, array, offsetopt)

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 upate the positions. You could do this

// assuming arrays.position has already been updated with new data.
twgl.setAttribInfoBufferFromArray(gl, bufferInfo.attribs.position, arrays.position);
Parameters:
Name Type Attributes Description
gl WebGLRenderingContext
attribInfo AttribInfo

The attribInfo who's buffer contents to set. NOTE: If you have an attribute prefix
the name of the attribute will include the prefix.

array ArraySpec

Note: it is arguably ineffient to pass in anything but a typed array because anything
else will have to be converted to a typed array before it can be used by WebGL. During init time that
inefficiency is usually not important but if you're updating data dynamically best to be efficient.

offset number <optional>

an optional offset into the buffer. This is only an offset into the WebGL buffer
not the array. To pass in an offset into the array itself use a typed array and create an ArrayBufferView
for the portion of the array you want to use.

   var someArray = new Float32Array(1000); // an array with 1000 floats
   var someSubArray = new Float32Array(someArray.buffer, offsetInBytes, sizeInUnits); // a view into someArray

Now you can pass someSubArray into setAttribInfoBufferFromArray`

(static) setAttributePrefix(prefix)

Sets the default attrib prefix

When writing shaders I prefer to name attributes with a_, uniforms with u_ and varyings with v_
as it makes it clear where they came from. But, when building geometry I prefer using unprefixed names.

In otherwords I'll create arrays of geometry like this

var arrays = {
  position: ...
  normal: ...
  texcoord: ...
};

But need those mapped to attributes and my attributes start with a_.

Parameters:
Name Type Description
prefix string

prefix for attribs

Deprecated: