This document describes the full specification of the shader system API.

The shader system includes both a python API and a GLSL API. Since we are targeting OpenGL 2.1, GLSL should be limited to version 120.

In python, shaders are instances of a Shader class (or subclass) and are combined together to make programs that are instances of a ShaderProgram class (or subclass).

Some shaders and shader programs will define uniforms or attributes which require a very specific data format. Where appropriate, subclasses of Shader or ShaderProgram should be made which include data handling functions and appropriate documentation.

In many cases, it is desirable to configure a shader to use either a uniform or a varying attribute to represent the same input. For example, lines could be drawn with a varying color attribute if needed, or with a uniform color to reduce memory usage and improve performance. This might be best accomplished by combining multiple shaders with the use of hooks:

Shaders may be combined together to produce customized programs. For example, a program that generates nice antialiased lines might be combined with auxiliary shaders that customize the fragment colors, vertex transformation, stippling, etc.

This can be accomplished with the use of function hooks in the shader code. For example, the main vertex shader might look like this:

// The main vertex shader defines a function prototype to serve as 
// a hook for other shaders to customize. 
vec4 global_transform(vec4);

void main() {
    // Set the vertex position based on the output of global_transform.
    // Since this function is undefined, this shader must be linked
    // with another that provides the definition.
    gl_Position = global_transform(vec4(in_position, 1.0));
}

And an auxiliary vertex shader might look like this:

// One possible definition to be linked with the main vertex shader
uniform mat4 transform;
vec4 global_transform(vec4 pos) {
    return transform * pos;
}

Shaders might also be customized by programmatically generating shader code. However, this should be discouraged except where it provides clear performance (or other) benefits.

It would be nice if we could transparently support both Desktop and ES 2.0 flavors of OpenGL. OpenGL ES is supported on mobile devices, in WebGL, and sometimes, in VirtualBox. The Shader layer should be able to generate both Desktop and ES compatible GLSL code. It's mainly a matter of generating slightly differently the declaration variables, and adding a few preprocessor commands. Or maybe it is possible to support directly both versions with the exact same code?