Name
glLinkProgram Links a program object
C Specification
void glLinkProgram(GLuint program)
Parameters
program
|
Specifies the handle of the program object to be linked.
|
Description
glLinkProgram 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.[glLinkProgram]
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 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 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 that have not been bound to a generic vertex attribute index are bound to one at this time.[glLinkProgram]
Linking of a program object can fail for a number of reasons as specified in the OpenGL Shading Language Specification. The following lists some of the conditions that cause a link error.
- The number of active attribute variables supported by the implementation has been exceeded.
- The storage limit for uniform variables 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 in the same way (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.
When a program object has been successfully linked, the program object can be made part of current state with glUseProgram. Whether or not the link operation was successful, the program object's information log is over-written. The information log can be retrieved with glGetProgramInfoLog.
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 executables and associated state remain part of the current state until a subsequent call to glUseProgram removes it from use. After it is removed from use, it cannot be made part of current state until it has been successfully relinked.
If program contains shader objects of type GL_VERTEX_SHADER but does not contain shader objects of type GL_FRAGMENT_SHADER, the vertex shader is linked against the implicit interface for fixed functionality fragment processing. Similarly, if program contains shader objects of type GL_FRAGMENT_SHADER but does not contain shader objects of type GL_VERTEX_SHADER, the fragment shader is linked against the implicit interface for fixed functionality vertex processing.
The program object's information log is updated and the program is generated at the time of the link operation. After the link operation, applications are free to modify attached shader objects, compile attached shader objects, detach shader objects, delete 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.
Notes
glLinkProgram is available only if the GL version is 2.0 or greater.
If the link operation is unsuccessful, any information about a previous link operation on program is lost (i.e., a failed link does not restore the old state of program). Certain information can still be retrieved from program even after an unsuccessful link operation. See, for instance, glGetActiveAttrib and glGetActiveUniform.
Errors
GL_INVALID_VALUE is generated if program is not a value generated by OpenGL.
GL_INVALID_OPERATION is generated if program is not a program object.
GL_INVALID_OPERATION is generated if glLinkProgram is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with the argument GL_CURRENT_PROGRAM
glGetActiveAttrib with argument program and the index of an active attribute variable
glGetActiveUniform with argument program and the index of an active uniform variable
glGetAttachedShaders with argument program
glGetAttribLocation with argument program and an attribute variable name
glGetProgram with arguments program and GL_LINK_STATUS
glGetProgramInfoLog with argument program
glGetUniform with argument program and a uniform variable location
glGetUniformLocation with argument program and a uniform variable name
glIsProgram
See Also
glAttachShader, glBindAttribLocation, glCompileShader, glCreateProgram, glDeleteProgram, glDetachShader, glUniform, glUseProgram, glValidateProgram
Example of glLinkProgram
{
/* The vertex shader */ char *vsSource = file2string("wave.vert"); char *fsSource = file2string("wave.frag"); /* Compile and load the program */ GLuint vs, /* Vertex Shader */ fs, /* Fragment Shader */ sp; /* Shader Program */ vs = glCreateShader(GL_VERTEX_SHADER); glShaderSource(vs, 1, &vsSource, NULL); glCompileShader(vs); printLog(vs); fs = glCreateShader(GL_FRAGMENT_SHADER); glShaderSource(fs, 1, &fsSource, NULL); glCompileShader(fs); printLog(fs); free(vsSource); free(fsSource); sp = glCreateProgram(); glAttachShader(sp, vs); glAttachShader(sp, fs); glLinkProgram(sp); printLog(sp);
glUseProgram(sp);
}
