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:
Type:
bool

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

(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.

See:
  • module:twgl.setAttributes for example
Parameters:
Name Type Description
program WebGLProgram

the program to create setters for.

Returns:
Type:
Object.<string, function()>

an object with a setter for each attribute by name.

(static) createProgram(gl, shaders, opt_attribsopt, 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
gl WebGLRenderingContext

The WebGLRenderingContext to use.

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> | module:twgl.ErrorCallback <optional>

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

opt_locations|module:twgl.ErrorCallback Array.<number> <optional>

The locations for the. A parallel array to opt_attribs letting you assign locations or an error callback.

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:
Type:
WebGLProgram

the created program or null if error.

(static) createProgramFromScripts(gl, shaderScriptIds, opt_attribsopt, opt_errorCallbackopt) → (nullable) {WebGLProgram|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 module:twgl.ProgramOptions | Array.<string> | module:twgl.ErrorCallback <optional>

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

opt_locations|module:twgl.ErrorCallback Array.<number> <optional>

The locations for the. A parallel array to opt_attribs letting you assign locations or an error callback.

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:
  • Type:
    WebGLProgram

    the created program or null if error.

  • Type:
    WebGLProgram

    The created program.

(static) createProgramFromSources(gl, shaderSources, opt_attribsopt, opt_errorCallbackopt) → (nullable) {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 module:twgl.ProgramOptions | Array.<string> | module:twgl.ErrorCallback <optional>

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

opt_locations|module:twgl.ErrorCallback Array.<number> <optional>

The locations for the. A parallel array to opt_attribs letting you assign locations or an error callback.

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:
Type:
WebGLProgram

the created program or null if error.

(static) createProgramInfo(gl, shaderSources, opt_attribsopt, opt_errorCallbackopt) → (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> | module:twgl.ErrorCallback <optional>

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

opt_locations|module:twgl.ErrorCallback Array.<number> <optional>

The locations for the. A parallel array to opt_attribs letting you assign locations or an error callback.

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:
Type:
module:twgl.ProgramInfo

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

(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:
Type:
module:twgl.ProgramInfo

The created 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:
Type:
module:twgl.UniformBlockInfo

The created 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:
Type:
module:twgl.UniformBlockInfo

The created 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:
Type:
module:twgl.UniformBlockSpec

The created UniformBlockSpec

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

Creates setter functions for all uniforms of a shader
program.

See:
Parameters:
Name Type Description
program WebGLProgram

the program to create setters for.

Returns:
Type:
Object.<string, function()>

an object with a setter by name for each uniform

(static) setAttributes(setters, buffers)

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

Example:

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

const attribSetters = createAttributeSetters(program);

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

const 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
  • divisor: the divisor for instances. Default = undefined

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

const 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,
  },
};
Deprecated:
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.

(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:

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 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:

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(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

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.

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

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

const 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};

(inner) createShaderFromScript(gl, scriptId, opt_shaderTypeopt, opt_errorCallbackopt) → (nullable) {WebGLShader}

Loads a shader from a script tag.

Parameters:
Name Type Attributes Description
gl WebGLRenderingContext

The WebGLRenderingContext to use.

scriptId string

The id of the script tag.

opt_shaderType number <optional>

The type of shader. If not passed in it will
be derived from the type of the script tag.

opt_errorCallback module:twgl.ErrorCallback <optional>

callback for errors.

Returns:
Type:
WebGLShader

The created shader or null if error.

(inner) getBindPointForSamplerType()

Returns the corresponding bind point for a given sampler type

(inner) getProgramOptions(opt_attribsopt, opt_locationsopt, opt_errorCallbackopt) → {module:twgl.ProgramOptions}

Gets the program options based on all these optional arguments

Parameters:
Name Type Attributes Description
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:
Type:
module:twgl.ProgramOptions

an instance of ProgramOptions based on the arguments pased on

(inner) isBuiltIn(info) → {bool}

Returns true if attribute/uniform is a reserved/built in

It makes no sense to me why GL returns these because it's
illegal to call gl.getUniformLocation and gl.getAttribLocation
with names that start with gl_ (and webgl_ in WebGL)

I can only assume they are there because they might count
when computing the number of uniforms/attributes used when you want to
know if you are near the limit. That doesn't really make sense
to me but the fact that these get returned are in the spec.

Parameters:
Name Type Description
info WebGLActiveInfo

As returned from gl.getActiveUniform or
gl.getActiveAttrib.

Returns:
Type:
bool

true if it's reserved

(inner) loadShader(gl, shaderSource, shaderType, opt_errorCallback) → {WebGLShader}

Loads a shader.

Parameters:
Name Type Description
gl WebGLRenderingContext

The WebGLRenderingContext to use.

shaderSource string

The shader source.

shaderType number

The type of shader.

opt_errorCallback module:twgl.ErrorCallback

callback for errors.

Returns:
Type:
WebGLShader

The created shader.

(inner) unbindTransformFeedbackInfo(gl, transformFeedbackInfo, bufferInfoopt)

Unbinds buffers after transform feedback.

Buffers can not be bound to 2 bind points so if you try to bind a buffer used
in a transform feedback as an ARRAY_BUFFER for an attribute it will fail.

This function unbinds all buffers that were bound with module:twgl.bindTransformFeedbackInfo.

Parameters:
Name Type Attributes Description
gl WebGLRenderingContext

The WebGLRenderingContext to use.

transformFeedbackInfo module:twgl.ProgramInfo | Object.<string, module:twgl.TransformFeedbackInfo>

A ProgramInfo or TransformFeedbackInfo.

bufferInfo module:twgl.BufferInfo | Object.<string, module:twgl.AttribInfo> <optional>

A BufferInfo or set of AttribInfos.