library logo

Program

Class: Program

The Program class has very useful methods to create a Program out of shaders in different ways, methods for using buffers, textures, setting uniforms and more.

Properties:

A program instance has as public properties:

Notes:

All instance methods in a program (unless they return some documented value) are chainable.

Program Static Method: fromShaderURIs

Creates a new program by asynchronously fetching the source contained in the files pointed by the given urls. Ths method is very convenient because it enables you to write your shaders in separate files and keep your project organized.

Syntax:

PhiloGL.Program.fromShaderURIs(options);

Arguments:

  1. options - (object) An object with the following properties:

Options:

Examples:

Create a Program from the given script files.

In shaders/fragment.glsl

#ifdef GL_ES
precision highp float;
#endif

void main(void) {
  gl_FragColor = vec4(1.0, 1.0, 1.0, 1.0);
}

In shaders/vertex.glsl

attribute vec3 aVertexPosition;

uniform mat4 uMVMatrix;
uniform mat4 uPMatrix;

void main(void) {
  gl_Position = uPMatrix * uMVMatrix * vec4(aVertexPosition, 1.0);
}

JavaScript code:

PhiloGL.Program.fromShaderURIs({
  path: 'shaders/',
  vs: 'vertex.glsl',
  fs: 'fragment.glsl',
  onSuccess: function(program) {
    alert("Got the program!");
  },
  onError: function(e) {
    alert("An error ocurred while fetching or compiling the shaders");
  }
});

Program Static Method: fromShaderIds

Creates a new program by fetching the source contained into the DOM scripts with ids provided in the method.

Syntax:

var program = PhiloGL.Program.fromShaderIds(vertexShaderId, fragmentShaderId);

Arguments:

  1. vertexShaderId - (string) The id of the script tag containig the source code for the vertex shader.
  2. fragmentShaderId - (string) The id of the script tag containig the source code for the fragment shader.

Examples:

Create a Program from the given script ids.

HTML code:

<script id="shader-fs" type="x-shader/x-fragment">
  #ifdef GL_ES
  precision highp float;
  #endif

  void main(void) {
    gl_FragColor = vec4(1.0, 1.0, 1.0, 1.0);
  }
</script>

<script id="shader-vs" type="x-shader/x-vertex">
  attribute vec3 aVertexPosition;

  uniform mat4 uMVMatrix;
  uniform mat4 uPMatrix;

  void main(void) {
    gl_Position = uPMatrix * uMVMatrix * vec4(aVertexPosition, 1.0);
  }
</script>

JavaScript code:

var program = PhiloGL.Program.fromShaderIds('shader-vs', 'shader-fs');

Program Static Method: fromShaderSources

Creates a new program by using the strings passed as arguments as source for the shaders.

Syntax:

var program = PhiloGL.Program.fromShaderIds(vertexShaderSource, fragmentShaderSource);

Arguments:

  1. vertexShaderSource - (string) The vertex shader source as a string.
  2. fragmentShaderSource - (string) The fragment shader source as a string.

Examples:

Create a Program from the given sources.

var program = PhiloGL.Program.fromShaderSources([
  "attribute vec3 aVertexPosition;",

  "uniform mat4 uMVMatrix;",
  "uniform mat4 uPMatrix;",

  "void main(void) {",
    "gl_Position = uPMatrix * uMVMatrix * vec4(aVertexPosition, 1.0);",
  "}" ].join('\n'),
  , [
 "#ifdef GL_ES",
  "precision highp float;",
  "#endif",

  "void main(void) {",
    "gl_FragColor = vec4(1.0, 1.0, 1.0, 1.0);",
  "}" ].join('\n'));

Program Static Method: fromDefaultShaders

Creates a new program by using the sources taken from Shaders.Vertex and Shaders.Fragment.

Syntax:

var program = PhiloGL.Program.fromShaderIds(vertexDefaultShaderId, fragmentDefaultShaderId);

Arguments:

  1. vertexDefaultShaderId - (string, optional) The vertex shader id from Shaders.Vertex. Default’s Default.
  2. fragmentShaderSource - (string) The fragment shader id from Shaders.Fragment. Default’s Default.

Examples:

Extend Shaders.Fragment with a default shader and create a Program from defaults. Taken from lesson 8 example.

//Add Blend Fragment Shader
PhiloGL.Shaders.Fragment.Blend = [

    "#ifdef GL_ES",
    "precision highp float;",
    "#endif",
    
    "varying vec4 vColor;",
    "varying vec2 vTexCoord;",
    "varying vec3 lightWeighting;",
    
    "uniform bool hasTexture1;",
    "uniform sampler2D sampler1;",
    "uniform float alpha;",

    "void main(){",
      
      "if (hasTexture1) {",
      
        "gl_FragColor = vec4(texture2D(sampler1, vec2(vTexCoord.s, vTexCoord.t)).rgb * lightWeighting, alpha);",

      "}",
    
    "}"

].join("\n");

var program = PhiloGL.Program.fromDefaultShaders('Default', 'Blend');

Notes:

For more information about the default shader code Default included in the Framework take a look at the Shaders script.

Program Method: setUniform

Sets the value of an uniform. There’s no need to convert the array into a typed array, that’s done automatically. The name of the uniform matches the name of the uniform declared in the shader.

Syntax:

program.setUniform(name, value);

Arguments:

  1. name - (string) The name of the uniform to be set.
  2. value - (mixed) The value to be set. Can be a float, an array of floats, a boolean, etc.

Examples:

Set matrix information for the projection matrix and element matrix of the camera and world. The context of this example can be seen here.

program.setUniform('uMVMatrix', view);
program.setUniform('uPMatrix', camera.projection);

Program Method: setUniforms

For each key, value of the object passed in it executes setUniform(key, value).

Syntax:

program.setUniforms(object);

Arguments:

  1. object - (object) An object with key value pairs matching a uniform name and its value respectively.

Examples:

Set matrix information for the projection matrix and element matrix of the camera and world. The context of this example can be seen here.

program.setUniforms({
  'uMVMatrix': view,
  'uPMatrix': camera.projection
});

Program Method: setBuffer

This method is useful to set properties (and data) to a buffer and/or attributes. If the buffer does not exist it will be created. Also, for all properties set to a buffer, these properties are remembered so they’re optional for later calls.

Syntax:

program.setBuffer(name, options);

Arguments:

  1. name - (string) The name (unique id) of the buffer. If no attribute value is set in options then the buffer name will be used as attribute name.
  2. options - (object) An object with options/data described below:

Options:

Examples:

Set buffer values for the vertices of a triangle. The context of this example can be seen here.

program.setBuffer('triangle', {
  attribute: 'aVertexPosition',
  value: new Float32Array([0, 1, 0, -1, -1, 0, 1, -1, 0]),
  size: 3
});

Program Method: setBuffers

For each key, value of the object passed in it executes setBuffer(key, value).

Syntax:

program.setBuffers(object);

Arguments:

  1. object - (object) An object with key value pairs matching a buffer name and its value respectively.

Examples:

Set buffer values for the vertices of a triangle and a square. The context of this example can be seen here.

program.setBuffers({
  'triangle': {
    attribute: 'aVertexPosition',
    value: new Float32Array([0, 1, 0, -1, -1, 0, 1, -1, 0]),
    size: 3
  },
  
  'square': {
    attribute: 'aVertexPosition',
    value: new Float32Array([1, 1, 0, -1, 1, 0, 1, -1, 0, -1, -1, 0]),
    size: 3
  }
});

Program Method: setFrameBuffer

Creates or binds/unbinds a framebuffer. You can also use this method to bind the framebuffer to a texture and renderbuffers. If the framebuffer already exists then calling setFrameBuffer with true or false as options will bind/unbind the framebuffer. Also, for all properties set to a buffer, these properties are remembered so they’re optional for later calls.

Syntax:

program.setFrameBuffer(name[, options]);

Arguments:

  1. name - (string) The name (unique id) of the buffer.
  2. options - (mixed) Can be a boolean used to bind/unbind the framebuffer or an object with options/data described below:

Options:

Examples:

Using a frambuffer to render a scene into a texture. Taken from lesson 16.

//create framebuffer
program.setFrameBuffer('monitor', {
  width: screenWidth,
  height: screenHeight,
  bindToTexture: {      
    parameters: [{
      name: 'TEXTURE_MAG_FILTER',
      value: 'LINEAR'
    }, {
      name: 'TEXTURE_MIN_FILTER',
      value: 'LINEAR_MIPMAP_NEAREST',
      generateMipmap: false
    }]
  },
  bindToRenderBuffer: true
});

Program Method: setFrameBuffers

For each key, value of the object passed in it executes setFrameBuffer(key, value).

Syntax:

program.setFrameBuffers(object);

Arguments:

  1. object - (object) An object with key value pairs matching a buffer name and its value respectively.

Program Method: setRenderBuffer

Creates or binds/unbinds a renderbuffer. If the renderbuffer already exists and the second parameter is a boolean it’ll bind or unbind the renderbuffer. Also, for all properties set to a buffer, these properties are remembered so they’re optional for later calls.

Syntax:

program.setRenderBuffer(name[, options]);

Arguments:

  1. name - (string) The name (unique id) of the buffer.
  2. options - (mixed) Can be a boolean used to bind/unbind the renderbuffer or an object with options/data described below:

Options:

Program Method: setRenderBuffers

For each key, value of the object passed in it executes setRenderBuffer(key, value).

Syntax:

program.setRenderBuffers(object);

Arguments:

  1. object - (object) An object with key value pairs matching a buffer name and its value respectively.

Program Method: setTexture

This method is used to either bind/unbind an existing texture or also to create a new texture form an Image element or to create an empty texture with specified dimensions. Also, for all properties set to a texture, these properties are remembered so they’re optional for later calls.

Syntax:

program.setTexture(name[, options]);

Arguments:

  1. name - (string) The name (unique id) of the texture.
  2. options - (mixed) Can be a boolean or enum used to bind/unbind the texture (or set the enum as active texture) or an object with options/data described below:

Options:

Examples:

Setting a texture for a box. Adapted from lesson 6.

var img = new Image();

img.onload = function() {
  program.setTexture('nearest', {
    data: {
      value: img
    }
  });
};

img.src = 'path/to/image.png';

Program Method: setTextures

For each key, value of the object passed in it executes setTexture(key, value).

Syntax:

program.setTextures(object);

Arguments:

  1. object - (object) An object with key value pairs matching a texture name and its value respectively.

Examples:

Set multiple type of textures from the same image. Taken from lesson 6.

//load textures from image
var img = new Image();
img.onload = function() {
  program.setTextures({
    'nearest': {
      data: {
        value: img
      }
    },

    'linear': {
      data: {
        value: img
      },
      parameters: [{
        name: gl.TEXTURE_MAG_FILTER,
        value: gl.LINEAR
      }, {
        name: gl.TEXTURE_MIN_FILTER,
        value: gl.LINEAR
      }]
    },

    'mipmap': {
      data: {
        value: img
      },
      parameters: [{
        name: gl.TEXTURE_MAG_FILTER,
        value: gl.LINEAR
      }, {
        name: gl.TEXTURE_MIN_FILTER,
        value: gl.LINEAR_MIPMAP_NEAREST,
        generateMipmap: true
      }]
    }
  });
};

img.src = 'path/to/image.png';

Program Method: use

Calls gl.useProgram(this.program). To set the current program as active.

Syntax:

program.use();
Copyright © Nicolas Garcia Belmonte.