GLSL Object

From OpenGL.org
Jump to: navigation, search

A GLSL Object is an object in the OpenGL API that encapsulates the compiled or linked programs that execute portions of the OpenGL Pipeline. These objects represent code written in the OpenGL Shading Language (GLSL). Though they are called "objects", they do not fit within the OpenGL Object 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 the full code for a shader stage. The only limitation is that it can only contain 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. What makes GLSL's model unique is that multiple shader objects from different stages can be linked into a single program. So Vertex Shader and Fragment Shader can be linked into a single program.

Note that if a shader stage is missing it's `main` function in the linker (ie: the program isn't given a shader object that defines `main` for that stage), then the stage is effectively not present in the program. It is possible to render with a program that only provides a Vertex Shader, but you need to glEnable(GL_RASTERIZER_DISCARD) in order to get away with it.

Normally, you can only render with a single program, and thus a single program must combine every shader stage you wish to render with. However, if you have access to GL 4.1 or ARB_separate_shader_objects, you may attach multiple programs, all with different shader stages, to a single program pipeline. This makes it easier to mix-and-match programs. See the Program separation section for more details.

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

A shader object is created by 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​. If OpenGL 4.0 or ARB_tessellation_shader is available, then GL_TESS_CONTROL_SHADER​ and GL_TESS_EVALUATION_SHADER​ may be used. 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​);

glCreateProgram does not take parameters.

Note that the creation and deletion functions only create one object 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 glAttachShader(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.

Pre-link setup

There are a number of operations that may need to be performed on programs before linking.

Vertex Attributes for a Vertex Shader (if present in the program object) can be manually assigned an attribute index. Obviously, if no vertex shader is in the program, you do not need to assign attributes manually. Note that it is still best to assign them explicitly in the shader, where possible.

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 using a Fragment Shader, the output values from the Fragment Shader 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 buffer index 0 (with dual-source index 0, when considering dual-source blending). Otherwise, the output indices will be automatically generated, just as for vertex shader inputs.

As with vertex attributes, fragment shader output indices can be manually assigned from within the shader, and this is the preferred way to handle them. They can also be automatically generated for any outputs that are not manually assigned, though this is highly unhelpful for multiple output buffers. This 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 and can affect FBO completeness. If you do not wish to change the draw buffers every time you use a new program, then you are advised to manually assign output indices for all of your programs.

To do this without explicitly providing it in the shader, 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.

For dual-source blending, you need to be able to associate a buffer index and a dual-source index with the output. This is done with this function:

 void glBindFragDataLocationIndexed(GLuint program​, GLuint colorNumber​, GLuint index​, const char *name​);

The index​ is either 0 or 1, defining which dual-source index is being assigned to the output.

If you are intending to use this program for Transform Feedback, then you must tell the program which outputs from the last shader stage before Vertex Post-Processing should be written to the transform feedback 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.

Linking

Once all of this has been set up as the user wishes, then you may call:

 void glLinkProgram(GLuint program​);

This will link the program.

You do not have to explicitly detach shader objects, even after linking the program. However, it is a good idea to do so once linking is complete, as otherwise the program object will keep its attached shader objects alive when you try to delete them. Shader objects can be detached with this function:

 void glDetachShader(GLuint program​, GLuint shader​);

If the shader no longer needs to be used, it can be deleted.

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/glGetProgram 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​, including space for the null terminator) 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. Rendering without a program (or program pipeline will cause errors.

Program objects store the state of GLSL Uniform values. These values can be retrieved and set as normal.

Program introspection

You can retrieve information about the uniforms, attribute, and fragment data stored in a program. This can be used to query for locations, but it can also be used to find general information about the user-facing interfaces within a program.

Program separation

Program Separation
Core in version 4.4
Core since version 4.1
ARB extension GL_ARB_separate_shader_objects

The above paradigm is functional, but with the increase in the number of shader stages, the combinatorial explosion of different combinations of shaders is very great. Therefore, it is possible to compile and link what is called a separate or separable program which only consists of executable code for one or more shader stages, e.g GL_VERTEX_SHADER​. The fact that shader stages can be separated in that manner opens the door for a technique referred to as mix-and-match. This means, for instance, that the shader author can develop multiple version of a fragment shader which all use a single vertex shader. This involves creating a single, separate program for the vertex shader and multiple separate programs for the fragment shaders.

Having separate programs alone will not do anything. One has to define a so called program pipeline, which is a container object for one or more separate programs, each of which may install shader executables for one or more shader stages.

The extension also introduces multiple functions for setting uniform values in a direct-state-access (DSA) style. This means that, in contrast to monolithic programs, one does not need to make a separate program the active program using glUseProgram before modifying uniform values.

There are also several implications to consider when using separate programs, i.e. attribute bindings or interface block matching, which will be discussed in the following sections.

Creating a Separable Program

There are multiple ways of setting up a separable program. One is very convenient and does a lot of work in a single function call. The other takes more effort, but offers more flexibility.

The Single Shader Variant

In contrast to a monolithic program described above, much of the API calls to create, compile and link shader and programs have been wrapped into a single function: glCreateShaderProgramv. It takes a shader type, e.g. GL_VERTEX_SHADER​, the number of source strings to be compiled and a pointer to an array of null-terminated source strings. Basically, calling this function is equivalent to

const GLuint shader = glCreateShader(type);
if (shader) {
    glShaderSource(shader, count, strings, NULL);
    glCompileShader(shader);
    const GLuint program = glCreateProgram();
    if (program) {
        GLint compiled = GL_FALSE;
        glGetShaderiv(shader, GL_COMPILE_STATUS, &compiled);
        glProgramParameteri(program, GL_PROGRAM_SEPARABLE, GL_TRUE);
        if (compiled) {
            glAttachShader(program, shader);
            glLinkProgram(program);
            glDetachShader(program, shader);
        }
        /* append-shader-info-log-to-program-info-log */
    }
    glDeleteShader(shader);
    return program;
} else {
    return 0;
}

As can be seen, this is basically similar to creating a monolithic program. The is only one differences are that before linking the program, the implementation calls glProgramParameter in the following way

 glProgramParameteri(program, GL_PROGRAM_SEPARABLE​, GL_TRUE​);

and that the shader object is subsequently detached and deleted. The latter only affects relinking with glLinkProgram, since no object code exists anymore after the shader has been detached. This will not impede the usability of the program in any other way. Technically, detaching and deleting is not necessary and could, if the program is setup manually as shown below, simply be left out.

Note: glCreateShaderProgramv will return either the name of a program object or zero - independent of which errors might occur during shader compilation or linkage! A return value of zero simply states that either the shader object or program object could be created. If a non-zero value is returned, you will still need to check the program info logs to make sure compilation and linkage succeeded! Also, the function itself my generate an error under certain conditions which will also result in zero being returned.

If the calls to glCreateShader and glCreateProgram succeed and both compilation and linkage succeed as well, the result is a program object consisting of a single executable for the specified shader stage.

Implications

Using glCreateShaderProgramv has several implications to consider. First, since the operation is principally transparent, the developer cannot call certain functions before the program is linked. These include

The solution is to declare input and output locations explicitly inside a shader. For instance, binding an input variable in the vertex shader to a generic vertex attribute array can be replaced by adding the following line to the vertex shader:

 layout(location = 0) in vec4 input;

This way, there need not be a call to glBindAttribLocation by the application. There may be similar additions to other shader stages.

The Multiple Shader Variant

Although it is very convenient, using glCreateShaderProgramv is not necessary to setup a separable program. In fact, doing so imposes a limitation on the program: it can only contain executable code installable for a single shader stage. However, a separable program can actually contain multiple stages. In general, this requires to setup a monolithic program object and set the program parameter GL_PROGRAM_SEPARABLE​ manually before linking.

Workaround for Location Binding

Modifying Uniform Values

For each uniform call, the extension introduced a corresponding DSA-style pendant. This family of new functions is summarized as glProgramUniform. Since these functions access the state of the corresponding program object directly, first activating the program is not necessary, i.e. a call to glUseProgram is obsolete for the purpose of modifying uniform values. glProgramUniform works on any program object, separable or not. Separability has no influence on location queries. glGetUniformLocation will work with any program object that has been successfully linked.

Using the DSA-style functions is particularly efficient with core OpenGL 4.3 or if GL_ARB_explicit_uniform_location is present. In that case, neither location queries nor making a program object current or active is necessary.

On the other hand, trying to use a call from the glUniform family of functions will not work with program pipelines unless certain conditions are met. First, the program pipeline the program is bound to must be current. Second, glActiveShaderProgram must first called to select the active program object in the pipeline. Using glActiveShaderProgram will not actually make the program current, but simply functions as a selector. Uniform updates will then be redirected to the active program object.

A separable program can also be made current by calling glUseProgram. Uniform update will then work as usual.

Setting up a Program Pipeline

Combining multiple, separable program objects is done by creating and setting up a program pipeline object. This is done by first letting the GL generate an appropriate name:

 GLuint pipeline;
 glGenProgramPipelines(1, &pipeline);

To actually install a separable program in the pipeline one has to use glUseProgramStages. For instance, installing a separate vertex shader program can be done like this:

GLuint pipeline;
glGenProgramPipelines(1, &pipeline);

GLuint vertexProgram = glCreateShaderProgramv(GL_VERTEX_SHADER​, ...);
glUseProgramStages(pipeline, GL_VERTEX_SHADER_BIT​, vShader);

If vShader​ was properly linked, this will install the shader program objects for the vertex shader stage of the program pipeline object pipeline​.

Looking at the call to glUseProgramStages indicates that it takes a bitmask as its second argument. This means a single program object contains executable code for one, multiple or even all shader stages. In effect, it is possible to bind a program to a pipeline object which install code for all stages and later bind an executable for a single stage on the same pipeline. For instance

GLuint allStagesProgram, fragmentProgram;
GLuint pipeline;
 
// setup separable programs and pipeline here ...

glUseProgramStages(pipeline, GL_ALL_SHADER_BITS​, allStagesProgram);

// do some rendering with all stages from a single program...

glUseProgramStages(pipeline, GL_FRAGMENT_SHADER_BIT​, fragmentProgram);

will first install executable code for all stages taken from a single, separable program object. Afterwards, the fragment stage is replace by a different program. This is an example of the mix-and-match approach.

Rendering with a Program Pipeline

Unlike monolithic programs, where one would use glUseProgram in order to set the active shader program, here a call to glBindProgramPipeline is needed. This will create an actual program pipeline object when a name generated by glGenProgramPipelines is bound the first time. If it is called with another name for a program pipeline object, any previous bindings will be replaced. Calling it with zero will break any previous binding.

glBindProgramPipeline will have no effect if there is currently an active monolithic program activated with glUseProgram. If in doubt, the safe way is to call the following sequence

 glUseProgram(0);
 glBindProgramPipeline(pipeline);
 // ... call rendering commands afterwards

Reference