twgl/programs

Low level shader program 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.programs and twgl
itself

See module:twgl for core functions

Methods

(static) bindUniformBlock(gl, programInfo, uniformBlockInfo) → {bool}

Binds a unform 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 valus into the corresponding WebGLBuffer
call module:twgl.setUniformBlock instead.

Parameters:
Name Type Description
gl WebGL2RenderingContext

A WebGL 2 rendering context.

programInfo module:twgl.ProgramInfo | module:twgl.UniformBlockSpec

a ProgramInfo
as returned from module:twgl.createProgramInfo or or UniformBlockSpec as
returned from module:twgl.createUniformBlockSpecFromProgram.

uniformBlockInfo module:twgl.UniformBlockInfo

a UniformBlockInfo as returned from
module:twgl.createUniformBlockInfo.

Returns:

true if buffer was bound. If the programInfo has no block with the same block name
no buffer is bound.

Type
bool

(static) createAttributeSetters(program) → {Object.<string, function()>}

Creates setter functions for all attributes of a shader
program. You can pass this to module:twgl.setBuffersAndAttributes to set all your buffers and attributes.

Parameters:
Name Type Description
program WebGLProgram

the program to create setters for.

See:
  • module:twgl.setAttributes for example
Returns:

an object with a setter for each attribute by name.

Type
Object.<string, function()>

(static) createProgram(shaders, opt_attribsopt, opt_locationsopt, opt_errorCallbackopt) → (nullable) {WebGLProgram}

Creates a program, attaches (and/or compiles) shaders, binds attrib locations, links the
program and calls useProgram.

NOTE: There are 4 signatures for this function

twgl.createProgram(gl, [vs, fs], options);
twgl.createProgram(gl, [vs, fs], opt_errFunc);
twgl.createProgram(gl, [vs, fs], opt_attribs, opt_errFunc);
twgl.createProgram(gl, [vs, fs], opt_attribs, opt_locations, opt_errFunc);
Parameters:
Name Type Attributes Description
shaders Array.<WebGLShader> | Array.<string>

The shaders to attach, or element ids for their source, or strings that contain their source

opt_attribs module:twgl.ProgramOptions | Array.<string> <optional>

Options for the program or an array of attribs names. Locations will be assigned by index if not passed in

opt_locations Array.<number> <optional>

The locations for the. A parallel array to opt_attribs letting you assign locations.

opt_errorCallback module:twgl.ErrorCallback <optional>

callback for errors. By default it just prints an error to the console
on error. If you want something else pass an callback. It's passed an error message.

Returns:

the created program or null if error.

Type
WebGLProgram

(static) createProgramFromScripts(gl, shaderScriptIds, opt_attribsopt, opt_locationsopt, opt_errorCallback) → {WebGLProgram}

Creates a program from 2 script tags.

NOTE: There are 4 signatures for this function

twgl.createProgramFromScripts(gl, [vs, fs], opt_options);
twgl.createProgramFromScripts(gl, [vs, fs], opt_errFunc);
twgl.createProgramFromScripts(gl, [vs, fs], opt_attribs, opt_errFunc);
twgl.createProgramFromScripts(gl, [vs, fs], opt_attribs, opt_locations, opt_errFunc);
Parameters:
Name Type Attributes Description
gl WebGLRenderingContext

The WebGLRenderingContext
to use.

shaderScriptIds Array.<string>

Array of ids of the script
tags for the shaders. The first is assumed to be the
vertex shader, the second the fragment shader.

opt_attribs Array.<string> <optional>

An array of attribs names. Locations will be assigned by index if not passed in

opt_locations Array.<number> <optional>

The locations for the. A parallel array to opt_attribs letting you assign locations.

opt_errorCallback module:twgl.ErrorCallback

callback for errors. By default it just prints an error to the console
on error. If you want something else pass an callback. It's passed an error message.

Returns:

The created program.

Type
WebGLProgram

(static) createProgramFromSources(gl, shaderSources, opt_attribsopt, opt_locationsopt, opt_errorCallback) → {WebGLProgram}

Creates a program from 2 sources.

NOTE: There are 4 signatures for this function

twgl.createProgramFromSource(gl, [vs, fs], opt_options);
twgl.createProgramFromSource(gl, [vs, fs], opt_errFunc);
twgl.createProgramFromSource(gl, [vs, fs], opt_attribs, opt_errFunc);
twgl.createProgramFromSource(gl, [vs, fs], opt_attribs, opt_locations, opt_errFunc);
Parameters:
Name Type Attributes Description
gl WebGLRenderingContext

The WebGLRenderingContext
to use.

shaderSources Array.<string>

Array of sources for the
shaders. The first is assumed to be the vertex shader,
the second the fragment shader.

opt_attribs Array.<string> <optional>

An array of attribs names. Locations will be assigned by index if not passed in

opt_locations Array.<number> <optional>

The locations for the. A parallel array to opt_attribs letting you assign locations.

opt_errorCallback module:twgl.ErrorCallback

callback for errors. By default it just prints an error to the console
on error. If you want something else pass an callback. It's passed an error message.

Returns:

The created program.

Type
WebGLProgram

(static) createProgramInfo(gl, shaderSources, opt_attribsopt, opt_locationsopt, opt_errorCallback) → (nullable) {module:twgl.ProgramInfo}

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);
Parameters:
Name Type Attributes Description
gl WebGLRenderingContext

The WebGLRenderingContext
to use.

shaderSources Array.<string>

Array of sources for the
shaders or ids. The first is assumed to be the vertex shader,
the second the fragment shader.

opt_attribs module:twgl.ProgramOptions | Array.<string> <optional>

Options for the program or an array of attribs names. Locations will be assigned by index if not passed in

opt_locations Array.<number> <optional>

The locations for the attributes. A parallel array to opt_attribs letting you assign locations.

opt_errorCallback module:twgl.ErrorCallback

callback for errors. By default it just prints an error to the console
on error. If you want something else pass an callback. It's passed an error message.

Returns:

The created ProgramInfo or null if it failed to link or compile

Type
module:twgl.ProgramInfo

(static) createProgramInfoFromProgram(gl, program) → {module:twgl.ProgramInfo}

Creates a ProgramInfo from an existing program.

A ProgramInfo contains

programInfo = {
   program: WebGLProgram,
   uniformSetters: object of setters as returned from createUniformSetters,
   attribSetters: object of setters as returned from createAttribSetters,
}
Parameters:
Name Type Description
gl WebGLRenderingContext

The WebGLRenderingContext
to use.

program WebGLProgram

an existing WebGLProgram.

Returns:

The created ProgramInfo.

Type
module:twgl.ProgramInfo

(static) createUniformBlockInfo(gl, programInfo, blockName) → {module:twgl.UniformBlockInfo}

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.

Parameters:
Name Type Description
gl WebGL2RenderingContext

A WebGL2RenderingContext

programInfo module:twgl.ProgramInfo

a ProgramInfo
as returned from module:twgl.createProgramInfo

blockName string

The name of the block.

Returns:

The created UniformBlockInfo

Type
module:twgl.UniformBlockInfo

(static) createUniformBlockInfoFromProgram(gl, program, blockName) → {module:twgl.UniformBlockInfo}

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.

Parameters:
Name Type Description
gl WebGL2RenderingContext

A WebGL2RenderingContext

program WebGLProgram

A WebGLProgram

uinformBlockSpec. module:twgl.UniformBlockSpec

A UniformBlockSpec as returned
from module:twgl.createUniformBlockSpecFromProgram.

blockName string

The name of the block.

Returns:

The created UniformBlockInfo

Type
module:twgl.UniformBlockInfo

(static) createUniformBlockSpecFromProgram(gl, program) → {module:twgl.UniformBlockSpec}

Creates a UniformBlockSpec for the given program.

A UniformBlockSpec represents the data needed to create and bind
UniformBlockObjects

Parameters:
Name Type Description
gl WebGL2RenderingContext

A WebGL2 Rendering Context

program WebGLProgram

A WebGLProgram for a successfully linked program

Returns:

The created UniformBlockSpec

Type
module:twgl.UniformBlockSpec

(static) createUniformSetters(program) → {Object.<string, function()>}

Creates setter functions for all uniforms of a shader
program.

Parameters:
Name Type Description
program WebGLProgram

the program to create setters for.

See:
Returns:

an object with a setter by name for each uniform

Type
Object.<string, function()>

(static) setAttributes(setters, buffers)

Sets attributes and binds buffers (deprecated... use module:twgl.setBuffersAndAttributes)

Example:

var program = createProgramFromScripts(
    gl, ["some-vs", "some-fs");

var attribSetters = createAttributeSetters(program);

var positionBuffer = gl.createBuffer();
var texcoordBuffer = gl.createBuffer();

var attribs = {
  a_position: {buffer: positionBuffer, numComponents: 3},
  a_texcoord: {buffer: texcoordBuffer, numComponents: 2},
};

gl.useProgram(program);

This will automatically bind the buffers AND set the
attributes.

setAttributes(attribSetters, attribs);

Properties of attribs. For each attrib you can add
properties:

  • type: the type of data in the buffer. Default = gl.FLOAT
  • normalize: whether or not to normalize the data. Default = false
  • stride: the stride. Default = 0
  • offset: offset into the buffer. Default = 0

For example if you had 3 value float positions, 2 value
float texcoord and 4 value uint8 colors you'd setup your
attribs like this

var attribs = {
  a_position: {buffer: positionBuffer, numComponents: 3},
  a_texcoord: {buffer: texcoordBuffer, numComponents: 2},
  a_color: {
    buffer: colorBuffer,
    numComponents: 4,
    type: gl.UNSIGNED_BYTE,
    normalize: true,
  },
};
Parameters:
Name Type Description
setters Object.<string, function()>

Attribute setters as returned from createAttributeSetters

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

AttribInfos mapped by attribute name.

Deprecated:

(static) setBlockUniforms(uniformBlockInfo, values)

Sets values of a uniform block object

Parameters:
Name Type Description
uniformBlockInfo module:twgl.UniformBlockInfo

A UniformBlockInfo as returned by module:twgl.createUniformBlockInfo.

values Object.<string, ?>

A uniform name to value map where the value is correct for the given
type of uniform. So for example given a block like

  uniform SomeBlock {
    float someFloat;
    vec2 someVec2;
    vec3 someVec3Array[2];
    int someInt;
  }

You can set the values of the uniform block with

  twgl.setBlockUniforms(someBlockInfo, {
     someFloat: 12.3,
     someVec2: [1, 2],
     someVec3Array: [1, 2, 3, 4, 5, 6],
     someInt: 5,
  }

Arrays can be JavaScript arrays or typed arrays

Any name that doesn't match will be ignored

(static) setBuffersAndAttributes(gl, setters, buffers)

Sets attributes and buffers including the ELEMENT_ARRAY_BUFFER if appropriate

Example:

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

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],                 },
};

var 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 equivilent 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);
Parameters:
Name Type Description
gl WebGLRenderingContext

A WebGLRenderingContext.

setters module:twgl.ProgramInfo | Object.<string, function()>

A ProgramInfo as returned from module:twgl.createProgrmaInfo or Attribute setters as returned from module:twgl.createAttributeSetters

buffers module:twgl.BufferInfo | module:twgl.vertexArrayInfo

a BufferInfo as returned from module:twgl.createBufferInfoFromArrays.
or a VertexArrayInfo as returned from module:twgl.createVertexArrayInfo

(static) setUniformBlock(gl, programInfo, uniformBlockInfo)

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.

Parameters:
Name Type Description
gl WebGL2RenderingContext

A WebGL 2 rendering context.

programInfo module:twgl.ProgramInfo | module:twgl.UniformBlockSpec

a ProgramInfo
as returned from module:twgl.createProgramInfo or or UniformBlockSpec as
returned from module:twgl.createUniformBlockSpecFromProgram.

uniformBlockInfo module:twgl.UniformBlockInfo

a UniformBlockInfo as returned from
module:twgl.createUniformBlockInfo.

(static) setUniforms(setters, values)

Set uniforms and binds related textures.

example:

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

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

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

var 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(program);

This will automatically bind the textures AND set the
uniforms.

twgl.setUniforms(programInfo, uniforms);

For the example above it is equivalent to

var 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

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

var 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

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

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

Parameters:
Name Type Description
setters module:twgl.ProgramInfo | Object.<string, function()>

a ProgramInfo as returned from createProgramInfo or the setters returned from
createUniformSetters.

values Object.<string, ?>

an object with values for the
uniforms.
You can pass multiple objects by putting them in an array or by calling with more arguments.For example

var sharedUniforms = {
  u_fogNear: 10,
  u_projection: ...
  ...
};

var localUniforms = {
  u_world: ...
  u_diffuseColor: ...
};

twgl.setUniforms(programInfo, sharedUniforms, localUniforms);

// is the same as

twgl.setUniforms(programInfo, [sharedUniforms, localUniforms]);

// is the same as

twgl.setUniforms(programInfo, sharedUniforms);
twgl.setUniforms(programInfo, localUniforms};