Light | Dark

docs.GL

glLinkProgram

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. Shader objects of type GL_VERTEX_SHADER attached to program are used to create an executable that will run on the programmable vertex processor. Shader objects of type GL_FRAGMENT_SHADER attached to program are used to create an executable that will run on the programmable fragment processor.

The status of the link operation will be stored as part of the program object's state. This value will be 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 glGetProgramiv with arguments program and GL_LINK_STATUS.

As a result of a successful link operation, all active user-defined uniform variables belonging to program will be initialized to 0, and each of the program object's active uniform variables will be assigned a location that can be queried by calling glGetUniformLocation. All active uniforms belonging to the program’s named uniform blocks are assigned offsets (and strides for array and matrix type uniforms) within the uniform block. Also, any active user-defined attribute variables that have not been bound to a generic vertex attribute index will be bound to one at this time.

Linking of a program object can fail for a number of reasons as specified in the OpenGL ES Shading Language Specification. The following lists some of the conditions that will cause a link error.

  • A vertex shader and a fragment shader are not both present in the program object.

  • The vertex and fragment shader do not use the same shader language version.

  • 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 or 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 (via glCompileShader) or loaded with a pre-compiled shader binary (via glShaderBinary).

  • 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.

  • Any variable name specified to glTransformFeedbackVaryings in the varyings array is not declared as an output in the vertex shader.

  • Any two entries in the varyings array given glTransformFeedbackVaryings specify the same varying variable.

  • The total number of components to capture in any transform feedback varying variable is greater than the constant GL_MAX_TRANSFORM_FEEDBACK_SEPARATE_COMPONENTS and the buffer mode is GL_SEPARATE_ATTRIBS.

  • The total number of components to capture in any transform feedback varying variable is greater than the constant GL_MAX_TRANSFORM_FEEDBACK_INTERLEAVED_COMPONENTS and the buffer mode is GL_INTERLEAVED_ATTRIBS.

When a program object has been successfully linked, the program object can be made part of current state by calling glUseProgram. Whether or not the link operation was successful, the program object's information log will be overwritten. The information log can be retrieved by calling glGetProgramInfoLog.

glLinkProgram will also install 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 will be set to GL_FALSE , but the executables and associated state will 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.

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 affects the information log or the program that is part of the program object.

Notes

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 program is the currently active program object and transform feedback mode is active.

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

glGetActiveUniformBlockiv with argument program and the index of an active uniform block

glGetAttachedShaders with argument program

glGetAttribLocation with argument program and an attribute variable name

glGetProgramiv 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

Examples

Compile a program from a vertex shader and a fragment shader.
GLuint vshader = glCreateShader(GL_VERTEX_SHADER);
glShaderSource(vshader, 1, &vertex_shader_source, NULL); // vertex_shader_source is a GLchar* containing glsl shader source code
glCompileShader(vshader);

GLint vertex_compiled;
glGetShaderiv(vshader, GL_COMPILE_STATUS, &vertex_compiled);
if (vertex_compiled != GL_TRUE)
{
    GLsizei log_length = 0;
    GLchar message[1024];
    glGetShaderInfoLog(vshader, 1024, &log_length, message);
    // Write the error to a log
}

GLuint fshader = glCreateShader(GL_FRAGMENT_SHADER);
glShaderSource(fshader, 1, &fragment_shader_source, NULL); // fragment_shader_source is a GLchar* containing glsl shader source code
glCompileShader(fshader);

GLint fragment_compiled;
glGetShaderiv(fshader, GL_COMPILE_STATUS, &fragment_compiled);
if (fragment_compiled != GL_TRUE)
{
    GLsizei log_length = 0;
    GLchar message[1024];
    glGetShaderInfoLog(fshader, 1024, &log_length, message);
    // Write the error to a log
}

GLuint program = glCreateProgram();

// This step is unnecessary if you use the location specifier in your shader
// e.g. layout (location = 0) in vec3 position;
glBindAttribLocation(program, 0, "position"); // The index passed into glBindAttribLocation is
glBindAttribLocation(program, 1, "texcoord"); // used by glEnableVertexAttribArray. "position"
glBindAttribLocation(program, 2, "normal");   // "texcoord" "normal" and "color" are the names of the
glBindAttribLocation(program, 3, "color");    // respective inputs in your fragment shader.

glAttachShader(program, vshader);
glAttachShader(program, fshader);
glLinkProgram(program);

GLint program_linked;
glGetProgramiv(program, GL_LINK_STATUS, &program_linked);
if (program_linked != GL_TRUE)
{
    GLsizei log_length = 0;
    GLchar message[1024];
    glGetProgramInfoLog(program, 1024, &log_length, message);
    // Write the error to a log
}

API Version Support

OpenGL ES API Version
Function Name 2.0 3.0 3.1
glLinkProgram ✔ ✔ ✔
Think you can improve this page? Edit this page on GitHub.