Light | Dark

# docs.GL

OpenGL 4
OpenGL 3
OpenGL 2
OpenGL ES 3
OpenGL ES 2

# 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`. If any shader objects of type `GL_VERTEX_SHADER` are attached to `program`, they will be used to create an executable that will run on the programmable vertex processor. If any shader objects of type `GL_GEOMETRY_SHADER` are attached to `program`, they will be used to create an executable that will run on the programmable geometry processor. If any shader objects of type `GL_FRAGMENT_SHADER` are attached to `program`, they will be 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 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` 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. 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 Shading Language Specification. The following lists some of the conditions that will 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, geometry 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, or geometry shader shader if present.

- 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 contains objects to form a fragment shader but does not contain objects to form a vertex shader.

- The program object contains objects to form a geometry shader but does not contain objects to form a vertex shader.

- The program object contains objects to form a geometry shader and the input primitive type, output primitive type, or maximum output vertex count is not specified in any compiled geometry shader object.

- The program object contains objects to form a geometry shader and the input primitive type, output primitive type, or maximum output vertex count is specified differently in multiple geometry shader objects.

- The number of active outputs in the fragment shader is greater than the value of `GL_MAX_DRAW_BUFFERS`.

- The program has an active output assigned to a location greater than or equal to the value of `GL_MAX_DUAL_SOURCE_DRAW_BUFFERS` and has an active output assigned an index greater than or equal to one.

- More than one varying out variable is bound to the same number and index.

- The explicit binding assigments do not leave enough space for the linker to automatically assign a location for a varying out array, which requires multiple contiguous locations.

- The `count` specified by glTransformFeedbackVaryings is non-zero, but the program object has no vertex or geometry shader.

- Any variable name specified to glTransformFeedbackVaryings in the `varyings` array is not declared as an output in the vertex shader (or the geometry shader, if active).

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

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.

If `program` contains shader objects of type `GL_VERTEX_SHADER`, and optionally of type `GL_GEOMETRY_SHADER`, but does not contain shader objects of type `GL_FRAGMENT_SHADER`, the vertex shader executable will be installed on the programmable vertex processor, the geometry shader executable, if present, will be installed on the programmable geometry processor, but no executable will be installed on the fragment processor. The results of rasterizing primitives with such a program will be undefined.

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``

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

## 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
    }

## Tutorials

open.gl - Geometry Shaders
open.gl - The Graphics Pipeline
open.gl - Transform Feedback
opengl-tutorial.org - Tutorial 2 : The first triangle

## See Also

glAttachShader, glBindAttribLocation, glCompileShader, glCreateProgram, glDeleteProgram, glDetachShader, glUniform, glUseProgram, glValidateProgram

## Copyright

Copyright © 2003-2005 3Dlabs Inc. Ltd. Copyright © 2010 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. https://opencontent.org/openpub/.

Think you can improve this page? Edit this page on GitHub.