GLSL Object
GLSL Objects are objects in the OpenGL API that encapsulate the compiled, linked programs that execute portions of the OpenGL Pipeline. These objects are written in the OpenGL Shading Language (GLSL). Though they are called objects, they do not fit within the OpenGL Objects paradigm.
GLSL compilation model
GLSL is quite unique among shading languages due to its compilation model. Most shading languages use a simpler, one-stage model: you give it a string representing a shader for one of the shader stages, and it gives you a shader object that you can bind to the context and render with.
GLSL uses a more complicated model based on the compilation of C programs. In C, a compilation unit, typically a single source file that may include several external header files, is compiled into an object file. A number of object files are then linked into a single program.
GLSL operates in a similar fashion. A set of source files, given as a series of strings, are compiled into a shader object. This is the analog of an object file. Unlike typical shading languages, there is no requirement that this shader object represent a full shader stage. The only limitation is that it can only compile code that is appropriate for a single, specific shader stage.
Shader objects are useless in that form, just as object files from compiled C programs are useless directly. Shader objects must be linked into a single program object. Unlike most shader languages, the program objects contain all programmable stages at once. Only one program can be bound for rendering at any one time, and it is illegal for a program object to omit any required stages entirely. Required stages are those for which there is no non-shader equivalent.
Terminology
Because of GLSL's unique compilation model, GLSL uses unique terminology.
According to GLSL's standard terminology, a shader is just a compiled set of strings for a particular programmable stage; it does not even need to have the complete code for that stage. A program is a fully linked program that covers multiple programmable stages.
Shader and program objects
Since GLSL's compilation model has 2 separate concepts, shaders and programs, there are 2 kinds of objects: shader objects and program objects. Shader objects represent compiled shaders, while program objects represent fully linked programs.
Neither of these object types conforms to the standard OpenGL Objects paradigm. Rather than using a state-based methadology for most of their functions, they use a more object-based API. The compilation, linking, and state access functions for these objects all take the object as a parameter, rather than requiring that the object be bound to the context before use.
Object creation
Shader objects are created with a call to:
GLuint glCreateShader(GLenum type);
The type field refers to the kind of shader object you wish to compile. A shader object can be of type GL_VERTEX_SHADER, GL_FRAGMENT_SHADER, or GL_GEOMETRY_SHADER. Once created, this object can only ever be used for shaders of that particular type.
{legacy note|In pre-OpenGL 3.1, you could ignore the glGen* functions, using any non-zero unsigned 32-bit integer as an object name. This was true for any OpenGL Object. However, because shader objects are not OpenGL Objects, you cannot do this, even in GL 2.0.}
They are deleted by calling:
void glDeleteShader(GLuint shader);
Similarly, program objects are created and deleted with:
GLuint glCreateProgram(); void glDeleteProgram(GLuint program);
Note that the creation and deletion functions work one at a time, unlike those for regular OpenGL Objects.
Shader compiling
Compiling a shader object is pretty simple. Before you can compile a shader, you must add strings to it. This is done with this command:
void glShaderSource(GLuint shader, GLsizei count, const char **string, const int *length);
The shader parameter is a previously created shader object. You can compile multiple strings in a single shader. This works exactly like appending these strings to one another, in the order given in the array. count tells how many strings are in the array, string is the array of strings to compile, and length is an array of lengths of those strings. length can be NULL; if it is, then all of the strings in string must be NULL-terminated. Otherwise, the lengths of the strings will be taken from the length value. If one of the elements in length is negative, then the corresponding string must be NULL-terminated.
Calling this function will also undo any previous calls to this function for this command. So calling this multiple times will not add multiple strings; that's why the function intrinsically takes multiple strings.
Note that, like any other OpenGL function that takes pointers, the information in those pointers is copied to the OpenGL context before the function returns. Therefore, you may free this memory afterward.
Once strings have been set, you can then compile the shader:
void glCompileShader(GLuint shader);
This does not return a value; you can query the success or failure of the compilation via glGetShaderiv. See the section on #Error handling for this.
A shader object, once it has successfully compiled, can be compiled with a different set of strings. All you need to do is call glShaderSource and glCompileShader again. This is not advisable, however. It is preferable to simply delete the shader object and build a new one, as recompiling the shader will likely not have the effect you intend.
For example, if you have a program and you attach a shader to it, recompiling the shader with new code will not update the program. This is exactly like it is for object files on the disk; it doesn't matter that you change a .o file once you've already used it to generate the executable. You must re-link the executable manually in order for the changes to take effect.
Program linking
Linking a program is not as simple as compiling a shader. The linking process involves more than just taking a collection of compiled shader objects and building a program from them. Though that is the first step.
In order to link a program, you must attach one or more compiled shader objects to the program. This is done with this API:
void glAttachProgram(GLuint program, GLuint shader);
This will cause the shader object shader to become attached to the program object program. A shader object can be attached to any number of program objects. The shader object, due to being attached to the program object, will continue to exist even if you delete the shader object. It will only be deleted by the system when it is no longer attached to any program object (and when the user has asked to delete it, of course). Even so, it is not a good idea to refer to shader objects after deleting them.
You do not have to explicitly detach shader objects, even after linking the program. However, if you wish to do so, you may use this function:
void glDetachProgram(GLuint program, GLuint shader);
The next step in linking the program is to provide attribute indices for any vertex attributes. This is only important if you have a vertex shader as part of the program.
This step is also optional. If you wish, OpenGL can automatically assign your vertex attributes to an index. However, since you must know this index in order to set up your VAO correctly, and you will likely want to be able to mix and match VAOs and programs as much as you want, it is best to pick your own vertex attribute indices.
To do this, call this API before linking the program:
void glBindAttribLocation(GLuint program, GLuint index, const char *name);
The index is the attribute value you want to assign, and name is the string name of the attribute in the vertex shader that you want to use. The binding this function creates only takes effect when the program is linked. The attribute name does not have to actually be in the linked program; this allows you to set up a global mapping of names to indices and simply always use them for every program you create.
If one is rendering to a framebuffer (as opposed to a vertex buffer through transform feedback), then the output values must be mapped to the current framebuffer's draw buffer indices. If the fragment shader only writes to one user-defined output, then this output will be automatically bound to output index 0. Otherwise, the output indices will be automatically generated, just as for vertex shader inputs.
Automatic generation of output indices is less useful than for attribute indices. That is because you are far more likely to need to use multiple program with the same framebuffer, and the changes made by glDrawBuffers is part of the framebuffer's state. If you do not wish to change this parameter for every use of a program, then you are advised to manually assign output indices for all of your programs.
To do this, call this API before linking:
void glBindFragDataLocation(GLuint program, GLuint colorNumber, const char *name);
The colorNumber is the index into the glDrawBuffers list that the output named name will be written into.
If you are instead intending to use this program for transform feedback, then you must tell the program which outputs from the last shader stage should be written to the buffer objects.
To do this, call this API before linking:
void glTransformFeedbackVaryings(GLuint program, GLsizei count, const char **varyings, GLenum bufferMode);
The varyings is a string array of count elements. These named outputs, in order, will be written to the buffer. The bufferMode says whether the written attributes will be interleaved or written separately to the buffer.
Once all of this has been set up as the user wishes, then you may call:
void LinkProgram(GLuint program);
This will link the program.
Error handling
Compiling and linking can cause errors. Unlike most OpenGL Errors however, these errors are delivered in the form of text.
To check to see if a shader successfully compiled, call glGetShaderiv(shader, GL_COMPILE_STATUS, &bDidCompile). The integer pointer will be filled with GL_TRUE if the compilation was successful and GL_FALSE if it was not. Similarly, to check to see if a program linked, call glGetProgramiv(program, GL_LINK_STATUS, &bDidLink).
Compiling and linking, whether successful or not, will generate a textual log. The log will contain warnings and errors, as appropriate to the shader and program in question. The length of the log can be queried with glGetShader/Programiv with GL_INFO_LOG_LENGTH as the parameter. The logs themselves can be queried with this function:
void glGetShaderInfoLog( GLuint shader, GLsizei bufSize, GLsizei *length, char *infoLog ); void glGetProgramInfoLog( GLuint program, GLsizei bufSize, GLsizei *length, char *infoLog );
This will cause the infoLog buffer (of size bufSize) to be filled in with the log. If length is non-NULL, it will be filled in with the number of characters written to infoLog.
Program usage
The only thing you can use shader objects for is to make programs. Program objects however, have many uses.
To bind a program to the context for rendering, call:
void glUseProgram(GLuint program);
As with the usual glBind* calls, this will cause program to become the actively bound program and cause the previously bound program to be unbound. And just as with the usual glBind* calls, binding the 0 program object will cause the program to be unbound.
Program objects store the state of GLSL Uniform values. These can be queried and set through program objects.
You can retrieve information about the attribute and fragment data location bindings as well.
Like uniforms, attributes can be active or inactive. Attributes that are unused are inactive; they do not have a binding. The number of active attributes in a program can be retrieved with glGetProgramiv with GL_ACTIVE_ATTRIBUTES.
To retrieve information about an attribute, call this function:
void glGetActiveAttrib( GLuint program, GLuint index, GLsizei bufSize, GLsizei *length, GLint *size, GLenum *type, char *name );
The index is a number on the half-open range [0, GL_ACTIVE_ATTRIBUTES); it represents a particular active attribute. name will be filled in with the name of the attribute; bufSize is the size of this character array. If length is not NULL, it will be filled in with the number of characters written to name. The size will be filled with the number of elements in the attribute array, if the attribute is an array type. Otherwise, it will be set to 1. The type will be set to the OpenGL enumeration for the GLSL type of the attribute.
To get the attribute location (the one used by glVertexAttribPointer, not the index field used above), we use this function:
GLint glGetAttribLocation( GLuint program, const char *name );
If name is not an active attribute in program, the function will return -1.
Similarly, to get the fragment data location we use this function:
GLint glGetFragDataLocation( GLuint program, const char *name );
Again, if name is not a fragment data location in program, the function returns -1.