7.4. Linking and Using Shaders

Each shader object is compiled independently. To create a program, applications need a mechanism for specifying a list of shader objects to be linked. You can specify the list of shaders objects to be linked by creating a program object and attaching to it all the shader objects needed to create the program.

To create a program object, use the following command:

GLuint glCreateProgram(void)

Creates an empty program object and returns a non-zero value by which it can be referenced. A program object is an object to which shader objects can be attached. This provides a mechanism to specify the shader objects that will be linked to create a program. It also provides a means for checking the compatibility between shaders that will be used to create a program (for instance, checking the compatibility between a vertex shader and a fragment shader). When no longer needed as part of a program object, shader objects can be detached.

After the program object has been defined, shader objects can be attached to it. Attaching simply means creating a reference to the shader object so that it will be included when an attempt to link a program object is made. This is the application's way of describing the recipe for creating a program. The command to attach a shader object to a program object is

void glAttachShader(GLuint program,                     GLuint shader)
Attaches the shader object specified by shader to the program object specified by program. This indicates that shader will be included in link operations that are performed on program.

There is no inherent limit on the number of shader objects that can be attached to a program object. All operations that can be performed on a shader object are valid whether or not the shader object is attached to a program object. It is permissible to attach a shader object to a program object before source code has been loaded into the shader object or before the shader object has been compiled. It is also permissible to attach a shader object to more than one program object. In other words, glAttachShader simply specifies the set of shader objects to be linked.

To create a valid program, all the shader objects attached to a program object must be compiled and the program object itself must be linked. The link operation assigns locations for uniform variables, initializes user-defined uniform variables, resolves references between independently compiled shader objects, and checks to make sure the vertex and fragment shaders are compatible with one another. To link a program object, use the command

void glLinkProgram(GLuint program)

Links the program object specified by program. If any shader objects of type GL_VERTEX_SHADER are attached to program, they are used to create an executable that will run on the programmable vertex processor. If any shader objects of type GL_FRAGMENT_SHADER are attached to program, they are used to create an executable that will run on the programmable fragment processor. The status of the link operation is stored as part of the program object's state. This value is set to GL_TRUE if the program object was linked without errors and is ready for use and set to GL_FALSE otherwise. It can be queried by calling glGetProgram with arguments program and GL_LINK_STATUS. As a result of a successful link operation, all active user-defined uniform variables (see Section 7.8) belonging to program are initialized to 0, and each of the program object's active uniform variables is assigned a location that can be queried with glGetUniformLocation. Also, any active user-defined attribute variables (see Section 7.7) that have not been bound to a generic vertex attribute index are bound to one at this time. If program contains shader objects of type GL_VERTEX_SHADER but it does not contain shader objects of type GL_FRAGMENT_SHADER, the vertex shader is linked to the implicit interface for fixed functionality fragment processing. Similarly, if program contains shader objects of type GL_FRAGMENT_SHADER but it does not contain shader objects of type GL_VERTEX_SHADER, the fragment shader is linked to the implicit interface for fixed functionality vertex processing. glLinkProgram also installs the generated executables as part of the current rendering state if the link operation was successful and the specified program object is already currently in use as a result of a previous call to glUseProgram. If the program object currently in use is relinked unsuccessfully, its link status is set to GL_FALSE, but the previously generated executables and associated state remain part of the current state until a subsequent call to glUseProgram removes them. After they are removed, they cannot be made part of current state until the program object has been successfully relinked.

Linking of a program object can fail for a number of reasons.

• The number of active attribute variables supported by the implementation has been exceeded.

• The number of active uniform variables supported by the implementation has been exceeded.

• The main function is missing for the vertex shader or the fragment shader.

• A varying variable actually used in the fragment shader is not declared with the same type (or is not declared at all) in the vertex shader.

• A reference to a function or variable name is unresolved.

• A shared global is declared with two different types or two different initial values.

• One or more of the attached shader objects has not been successfully compiled.

• Binding a generic attribute matrix caused some rows of the matrix to fall outside the allowed maximum of GL_MAX_VERTEX_ATTRIBS.

• Not enough contiguous vertex attribute slots could be found to bind attribute matrices.

The program object's information log is updated at the time of the link operation. If the link operation is successful, a program is generated. It may contain an executable for the vertex processor, an executable for the fragment processor, or both. Whether the link operation succeeds or fails, the information and executables from the previous link operation will be lost. After the link operation, applications are free to modify attached shader objects, compile attached shader objects, detach shader objects, and attach additional shader objects. None of these operations affect the information log or the program that is part of the program object until the next link operation on the program object.

Information about the link operation can be obtained by calling glGetProgramInfoLog (described in Section 7.6) with program. If the program object was linked successfully, the information log is either an empty string or contains information about the link operation. If the program object was not linked successfully, the information log contains information about any link errors that occurred, along with warning messages and any other information the linker chooses to provide.

When the link operation has completed successfully, the program it contains can be installed as part of the current rendering state. The command to install the program as part of the rendering state is

void glUseProgram(GLuint program)

Installs the program object specified by program as part of current rendering state. A program object contains an executable that will run on the vertex processor if it contains one or more shader objects of type GL_VERTEX_SHADER that have been successfully compiled and linked. Similarly, a program object contains an executable that will run on the fragment processor if it contains one or more shader objects of subtype GL_FRAGMENT_SHADER that have been successfully compiled and linked. If program contains shader objects of type GL_VERTEX_SHADER but it does not contain shader objects of type GL_FRAGMENT_SHADER, an executable is installed on the vertex processor but fixed functionality is used for fragment processing. Similarly, if program contains shader objects of type GL_FRAGMENT_SHADER but it does not contain shader objects of type GL_VERTEX_SHADER, an executable is installed on the fragment processor but fixed functionality is used for vertex processing. If program is 0, the programmable processors are disabled, and fixed functionality is used for both vertex and fragment processing.

Successfully installing an executable on a programmable processor causes the corresponding fixed functionality of OpenGL to be disabled. Specifically, if an executable is installed on the vertex processor, the OpenGL fixed functionality is disabled as described in Section 4.1. Similarly, if an executable is installed on the fragment processor, the OpenGL fixed functionality is disabled as described in Section 4.2.

While a program object is in use, applications are free to modify attached shader objects, compile attached shader objects, attach additional shader objects, detach shader objects, delete any shader objects attached, or delete the program object itself. None of these operations affect the executables that are part of the current state. However, relinking the program object that is currently in use installs the program as part of the current rendering state if the link operation was successful. While a program object is in use, the state that controls the disabled fixed functionality can also be updated with the normal OpenGL calls.