OpenGL SuperBible: Comprehensive Tutorial and Reference, Sixth Edition (2013)

Part I: Foundations

Chapter 6. Shaders and Programs

What You’ll Learn in This Chapter

• The fundamentals of the OpenGL shading language

• How to find out if your shaders compiled, and what went wrong if they didn’t

• How to retrieve and cache binaries of your compiled shaders and use them later for rendering

By this point in the book, you have read about the OpenGL pipeline, written some simple OpenGL programs, and seen some rendering. We have covered basic computer graphics fundamentals, some 3D math, and more. Modern graphics applications spend most of their time executing shaders, and graphics programmers spend a lot of their time writing shaders. Before you can write really compelling programs, you’ll need to understand shaders, the OpenGL programming model, and the types of operations that a graphics processor does well (and those that it does poorly). In this chapter, we’ll take a deeper dive into The OpenGL Shading Language, also known as GLSL. We’ll discuss a number of its features and subtleties and provide you with a strong foundation with which you can put your ideas into practice.

Language Overview

GLSL is in the class of languages that can be considered “C-like.” That is, its syntax and model are much like that of C with a number of differences that make it more suitable for graphics and parallel execution in general. One of the major differences between C and GLSL is that matrix and vector types are first class citizens. That means that they are built into the language. Another major difference between GLSL and C is that GLSL is designed to be run on massively parallel implementations — most graphics processors will run thousands of copies (or invocations) of your shaders at the same time. GLSL also has several limitations to make allowances for these types of implementations. For example, recursion is not allowed in GLSL, and precision requirements for floating-point numbers are not as strict as the IEEE standards that govern most C implementations.

Data Types

GLSL supports both scalar and vector data types, arrays and structures, and a number of opaque data types that represent textures and other data structures.

Scalar Types

The scalar data types supported in GLSL are 32- and 64-bit floating point, 32-bit signed and unsigned integers, and Boolean values. No support is provided for other commonly used types available in C such as short, char, or strings. Also, GLSL doesn’t support pointers or integer types larger than 32 bits. The scalar types supported are shown in Table 6.1.

Table 6.1. Scalar Types in GLSL

Signed and unsigned integers behave as would be expected in a C program. That is, signed integers are stored as two’s complement and have a range from -2,147,483,648 to 2,147,483,647, and unsigned integers have a range from 0 to 4,294,967,295. If you add numbers together such that they overflow their ranges, they will wrap around.

Floating-point numbers are effectively defined as they are in the IEEE-754 standard. That is, 32-bit floating-point numbers have a sign bit, 8 exponent bits, and 23 mantissa bits. The sign bit is set if the number is negative and clear if it is positive. The 8 exponent bits represent a number between -127 and +127, which is biased into the range 0 to 254 by adding 127 to its value. The mantissa represents the significant digits of the number, and there are 23 of them, plus an implied binary 1 digit in the 24^th position. Given the sign bit, s, exponent, e, and manitissa, m, the actual value of a 32-bit floating-point number is given by

Similarly, double-precision numbers also follow the IEEE-754 standard with a sign bit, 11 exponent bits, and 52 mantissa bits. The sign bit is defined as in 32-bit floating point, the exponent represents a value between -1022 and 1023, and the 52-bit mantissa represents the significant digits of the number, with an additional implied 1 in the 53^rd position. The actual value of the 64-bit double-precision floating-point number is

GLSL is not required to adhere strictly to the IEEE-754 standard for everything. For most operations the precision will be good enough and behavior is well defined. However, for some operations such as propagation of NaNs (Not a Number) and behavior of infinities and denormals, some deviation is allowed for. In general, though, writing code that relies on exact behavior of NaNs and infinities is not a good idea as many processors perform poorly on these types of values. For built-in functions such as trigonometric functions, even more leeway is given by GLSL. Finally, GLSL has no support for exceptions. That means that if you do something unreasonable such as dividing a number by zero, you won’t know until you see unexpected results come out of your shader.

Vectors and Matrices

Vectors of all supported scalar types and matrices of single- and double-precision floating-point types are supported by GLSL. Vector and matrix type names are decorated with their underlying scalar type’s name, except for floating-point vectors and matrices, which have no decoration. Table 6.2 shows all of the vector and matrix types in GLSL.

Table 6.2. Vector and Matrix Types in GLSL

Vectors may be constructed from other vectors, a single scalar, from sequences of scalars, or from any combination of scalars and vectors of the appropriate type, so long as there are enough fields in total to fill the destination. Thus, the following are all legal constructors:

vec3 foo = vec3(1.0);
vec3 bar = vec3(foo);
vec4 baz = vec4(1.0, 2.0, 3.0, 4.0);
vec4 bat = vec4(1.0, foo);

The components of a vector may be accessed as if it were an array. That is, the four components of

vec4 foo;

may be accessed as

float x = foo[0];
float y = foo[1];
float z = foo[2];
float w = foo[3];

In addition to accesses as an array, vectors may be accessed as if they were structures with fields representing their components. The first component can be accessed through the .x, .s, or .r field. The second component is accessed through the .y, .t, or .g field. The third is accessed through the .z, .p, or .b field, and finally, the fourth component can be accessed through the .w, .q, or .a field. This seems confusing, but x, y, z, and w are often used to denote positions or directions, r, g, b, and a are often used to represent colors, and s, t, p,¹ and q² are used to denote texture coordinates. If you were to write the vector’s structure in C, it would look something like this:

1. p is used as the third component of a texture coordinate because r is already taken for color.

2. q is used for the fourth component of a texture coordinate because it comes after p.

typedef union vec4_t
{
struct
{
float x;
float y;
float z;
float w;
};
struct
{
float s;
float t;
float p;
float q;
};
struct
{
float r;
float g;
float b;
float a;
};
} vec4;

However, this isn’t the end of the story — vectors also support what is called swizzling. This is the stacking of fields into vectors of their own. For example, the first three components of foo (which is a vec4) could be extracted by writing foo.xyz (or foo.rgb or foo.stp). The powerful thing is that you can also specify these fields in any order you wish, and you can repeat them. So, foo.zyx would produce a three-element vector with the x and z fields of foo swapped, and foo.rrrr would produce a four-element vector with the r component of foo in every field. Note that you can’t mix and match the conceptually separate x, y, z, and w fields with the s, t, p, and q or r, g, b, and a fields. That is, you can’t write foo.xyba, for example.

Matrices also first-class types in GLSL and may be treated like arrays. In GLSL, matrices appear as if they are arrays of vectors, and each element of that array (which is therefore a vector) represents a column of the matrix. Because each of those vectors can also be treated like an array, a column of a matrix behaves as an array, effectively allowing matrices to be treated like two-dimensional arrays. For example, if we declare bar as a mat4 type, then bar[0] is a vec4 representing its first column, and bar[0][0] is the first component of that vector (as is bar[0].x), bar[0][1] is the second component of the vector (which is equivalent to bar[0].y), and so on. Continuing, bar[1] is the second column, bar[2] is the third, and so on. Again, if you were to write this in C, it would look something like

typedef vec4 mat4[4];

Standard operators, such as + and -, are defined for vectors and matrices. The multiplication operator (*) is defined between two vectors to be component-wise, and between two matrices or a matrix and a vector as a matrix-matrix or matrix-vector multiplication operation. Division of vectors and matrices by scalars behaves as expected, and division of vectors and matrices by other vectors and matrices is executed component-wise, therefore requiring the two operands to be of the same dimension.

Arrays and Structures

You can build aggregate types both as arrays and structures, including arrays of structures and structures of arrays. Structure types are declared much as they would be in C++, and in particular, there is no typedef keyword in GLSL but rather structure definitions in GLSL implicitly declare a new type as they do in C++. Structure types may be forward declared by simply writing struct my_structure;, where my_structure is the name of the new structure type being declared.

There are two ways to declare an array in GLSL. The first is similar to that of C or C++, where the array size is appended to the variable name The following are examples of this type of declaration:

float foo[5];
ivec2 bar[13];
dmat3 baz[29];

The second syntax is to implicitly declare the type of the whole array by appending the size to the element type rather than the variable name. The above declaration could equivalently be written

float[5] foo;
ivec2[13] bar;
dmat3[29] baz;

To a C programmer, this may seem odd. However, it’s actually a very powerful feature as it allows types to be implicitly defined without the typedef keyword, which GLSL lacks. One example use of this is to declare a function that returns an array:

vec4[4] functionThatReturnsArray()
{
vec4[4] foo = ...

return foo;
}

Declaring array types in this form also implicitly defines the constructor for the array. This means that you can write

float[6] var = float[6](1.0, 2.0, 3.0, 4.0, 5.0, 6.0);

However, in this case, recent versions³ of GLSL also allow the traditional, C-style array initializer syntax to be used, as in

3. Curly brace {...} style initializer lists were introduced in GLSL 4.20 along with OpenGL 4.2. If you are writing shaders that might need to run in an earlier version of GLSL, you may want to stick to the implicit array type initialization by construction.

float var[6] = { 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 };

Arrays may be included in structures, and you can build arrays of structure types (which may themselves include structures). So, for example, the following structure and array definitions are legal in GLSL:

struct foo
{
int a;
vec2 b;
mat4 c;
};

struct bar
{
vec3 a;
foo[7] b;
};

bar[29] baz;

In this listing, baz is an array of 29 instances of bar, which contains one vec3 and 7 instances of foo, which contains an int, a vec2, and a mat4.

Arrays also include a special method⁴ called .length(), which returns the number of elements in the array. This allows, for example, loops to be constructed that iterate over all the elements in array. It’s also interesting to note that because there is a duality between vectors and arrays in GLSL, the .length() function works on vectors (giving their size, naturally) and that because matrices are essentially arrays of vectors, .length() when applied to a matrix gives you the number of columns it has. The following are a few examples of applications of the .length() function:

4. GLSL doesn’t support member functions in the traditional C++ sense, but an exception is made in this case.

float a[10]; // Declare an array of 10 elements
float b[a.length()]; // Declare an array of the same size
mat4 c;
float d = float(c.length()); // d is now 4
int e = c[0].length(); // e is the height of c (4)

int i;

// This loop iterates 10 times
for (i = 0; i < a.length(); i++)
{
b[i] = a[i];
}

Although GLSL doesn’t officially support multi-dimensional arrays, it does support arrays of arrays. This means that you can put array types into arrays — when you index into the first array, you get back an array, into which you can index, and so on. So, consider the following:

float a[10]; // "a" is an array of 10 floats
float b[10][2]; // "b" is an array of 2 arrays of 10 floats
float c[10][2][5]; // "c" is an array of 5 arrays of 2 arrays of 10 floats

Here, a is a regular, one-dimensional array. b may look like a two-dimensional array, but it’s actually a one-dimensional array of arrays, each of which has ten elements. There is a subtle difference here. In particular, if you were to write b[1].length(), you would get 10. Following on then, c is a one-dimensional array of five one-dimensional arrays of two elements, each of which is a one-dimensional array of ten elements. c[3].length() produces 2, and c[3][1].length() produces 10.

Built-In Functions

There are literally hundreds of built-in functions in GLSL. Many of them are used to work with textures and memory and will be covered in detail in those contexts. In this subsection, we’re going to look at functions that deal strictly with data — basic math, matrix, vector, and data packing and unpacking functions will be covered here.

Terminology

Given the very large number of types in GLSL, the language includes support for function overloading, which means that functions can have multiple definitions, each with a different set of parameters. Rather than enumerate all of the types supported for each of the functions, some standard terminology is used in the GLSL Specification to group classes of data types together such that families of functions can be referred to more concisely. We will sometimes use those terms here to refer to groups of types also. The following are terms that are used both in the GLSL Specification and in this book:

• genType means any single-precision floating-point scalar or vector, or one of float, vec2, vec3, or vec4.

• genUType means any unsigned integer scalar or vector, or one of uint, uvec2, uvec3, or uvec4.

• genIType means any signed integer scalar or vector, or one of int, ivec2, ivec3, or ivec4.

• genDType means any double-precision floating-point scalar or vector, or one of double, dvec2, dvec3, or dvec4.

• mat means any single-precision floating-point matrix. For example, mat2, mat3, mat4, or any of the non-square matrix forms.

• dmat means any double-precision floating-point matrix. For example, dmat2, dmat3, dmat4, or any of the non-square matrix forms.

Built–In Matrix and Vector Functions

As has been discussed in some detail, vectors and matrices are first-class citizens in GLSL, and where it makes sense, built-in operators such as +, -, *, and / work directly on vector and matrix types. However, a number of functions are provided to deal specifically with vectors and matrices.

The matrixCompMult() function performs a component-wise multiplication of two matrices. Remember, the * operator for two matrices is defined to perform a traditional matrix multiplication in GLSL. Clearly, the two matrix parameters to matrixCompMult() must be the same size.

Matrices may be transposed using the built-in transpose() function. If you transpose a non-square matrix, its dimensions are simply swapped.

To find the inverse of a matrix, GLSL provides the inverse() built-in function for the mat2, mat3, and mat4 types as well as their double-precision equivalents, dmat2, dmat3, and dmat4. Be aware though, that finding the inverse of a matrix is fairly expensive, and so if the matrix is likely to be constant, calculate the inverse in your application and load it into your shader as a uniform. Non-square matrices do not have inverses and so are not supported by the inverse() function. Similarly, the determinant() function calculates the determinant of any square matrix. For ill-conditioned matrices, the determinant and inverse do not exist, and so calling inverse() or determinant() on such a matrix will produce an undefined result.

The outerProduct() function performs an outer product of two vectors. Effectively, this takes two vectors as input, treats the first as a 1 × N matrix and the second as an N × 1 matrix, and then multiplies them together. The resulting N × N matrix is returned.

If you need to compare two vectors to one another, a number of built-in functions will do this for you in a component-by-component manner. These are lessThan(), lessThanEqual(), greaterThan(), greaterThanEqual(), equal(), and notEqual(). Each of these functions takes two vectors of the same type and size, applies the operation that their name suggests, and returns a Boolean vector of the same size of the function’s parameters (that is, a bvec2, bvec3, or bvec4). Each component of this Boolean vector contains the result of the comparison for the corresponding components in the source parameters.

Given a Boolean vector, you can test it to see if any of its components are true using the any() function, or to see if all of its components are true with the all() function. You can also invert the value of a Boolean vector using the not() function.

A large number of built-in functions for dealing with vectors are provided by GLSL. These include length(), which returns the length of a vector, and distance(), which returns the distance between two points (which is the same as the length of the vector produced by subtracting one point from the other). The normalize() function divides a vector by its own length, producing a vector that has a length of one, but points in the same direction as the source. The dot() and cross() functions can be used to find the dot and cross products of two vectors, respectively.

The reflect() and refract() functions take an input vector, a normal to a plane, and calculate the reflected or refracted vector that results. refract() takes the index of refraction, eta, as a parameter in addition to the incoming and normal vectors. The math behind this is explained in “Reflection and Refraction” in Chapter 4, “Math for 3D Graphics.”

Likewise, the faceforward() function takes an input vector and two surface normals — if the dot product of the input vector and the second normal vector is negative, then it returns the first normal vector; otherwise, it returns the negative of the first normal vector. As you might have guessed from its name, this can be used to determine whether a plane is front- or back-facing with respect to a particular view direction. Facingness was covered in Chapter 3, “Following the Pipeline.”

Built–In Math Functions

GLSL supports many built-in functions to perform mathematical operations and to manipulate data in variables. The common math functions include abs(), sign(), ceil(), floor(), trunc(), round(), roundEven(), fract(), mod(), modf(), min(), and max(). For the most part, these functions operate on vectors as well as scalars, but otherwise behave as their counterparts in the C standard libraries. The roundEven() function doesn’t have a direct equivalent in C — this function rounds its argument to the nearest integer, but breaks ties when there is a fractional part of 0.5 by rounding to the nearest even number. That is, 7.5 and 8.5 will both round to 8, 42.5 will round to 42 and 43.5 will round to 44.

Two implicit declarations of the clamp() function are

vec4 clamp(vec4 x, float minVal, float maxVal);
vec4 clamp(vec4 x, vec4 minVal, vec4 maxVal);

This function clamps the incoming vector x to the range specified by minVal and maxVal (which may be scalars or vectors). For example, specifying minVal to be 0.0 and maxVal to be 1.0 constrains x to be in the range 0.0 to 1.0. This is such a common range to which to clamp numbers that graphics hardware often has a special case for this range, and some shading languages even include a built-in function specifically to clamp inputs to this range.

A few more special functions are mix(), step(), and smoothstep(). mix() performs a linear interpolation between two of its inputs using the third as a weighting factor. It can effectively be implemented as

vec4 mix(vec4 x, vec4 y, float a)
{
return x + a * (y - x);
}

Again, this is such a common operation in graphics that it is a built-in function in the shading language, and graphics hardware may have special functionality to implement this directly.

The step() function generates a step function (a function that has a value of either 0.0 or 1.0) based on its two inputs. It is defined as

vec4 step(vec4 edge, vec4 x);

and it returns 0.0 if x < edge and 1.0 if x >= edge. The smoothstep() function is not as aggressive and produces a smooth fade between two of its inputs based on where the value of its third lies between the first two. It is defined as

vec4 smoothstep(vec4 edge0, vec4 edge1, vec4 x);

smoothstep() can effectively be implemented as

vec4 smoothstep(vec4 edge0, vec4 edge1, vec4 x)
{
vec4 t = clamp((x - edge0) / (edge1 - edge0), 0.0, 1.0);

return t * t * (vec4(3.0) - 2.0 * t);
}

The shape produced by smoothstep() is known as a Hermite curve, and the operation it performs is Hermite interpolation. The general shape of the curve is shown in Figure 6.1.

Figure 6.1: Shape of a Hermite curve

The fma() function performs a fused multiply-add operation. That is, it multiplies the first two of its parameters together and then adds the third. The intermediate result of the operation is generally kept at a higher precision than the source operands, producing a more accurate result than if you were to write those two operations directly in your code. In some graphics processors, the fused multiply-add function may be more efficient than a sequence of a multiplication followed by a separate addition operation.

Most of the math functions in GLSL presume that you are using floating-point numbers in the majority of your shader code. However, there are a few cases where you might be using integers, and GLSL includes a handful of functions that are designed to help you perform arithmetic on very large integer (or fixed-point) numbers. In particular, uaddCarry() and usubBorrow() allow you to perform add with carry and subtract with borrow operations, and imulExtended() and umulExtended() allow you to multiply a pair of 32-bit signed- or unsigned-integer values together, respectively, producing a 64-bit result as a further pair of 32-bit values.

In addition to all this low-level arithmetic functionality, GLSL also includes support for all of the expected trigonometry functions, such as sin(), cos(), and tan(); their inverses, asin(), acos() and atan(); and the hyperbolic forms of those functions, sinh(), cosh(), tanh(), asinh(), acosh(), and atanh(). Exponential functions are also included. These are pow(), exp(), log(), exp2(), log2(), sqrt(), and inversesqrt(). Because most of the GLSL functions dealing with angles work in radians, even though sometimes it might be convenient to work in degrees, GLSL also includes the radians() function (which takes an angle in degrees and converts it to radians) and the degrees() function (which takes an angle in radians and converts it into degrees).

Built-In Data Manipulation Functions

In addition to all of the functions that do real processing work, GLSL includes a lot of built-in functions that allow you to get at the innards of your data. For example, the frexp() allows you to break apart a floating-point number into its mantissa and exponent parts, and ldexp() allows you to build a new floating-point number from a mantissa and exponent that you supply. This allows some direct manipulation of the values of floating-point numbers.

If you need even more control over floating-point numbers, intBitsToFloat() and uintBitsToFloat() allow you to take a signed- or unsigned-integer number, respectively, and reinterpret its raw bits as a 32-bit floating-point number. To go the opposite way, floatBitsToInt() andfloatBitsToUint() take a floating-point number and hand it back to you as either a signed- or unsigned-integer value, respectively. These four functions let you literally tear a floating-point number apart, mess with its bits, and put it back together again. You need to be careful when doing this, however, as not all bit combinations form valid floating-point numbers, and it’s quite possible to generate NaNs (Not-a-Number), denormals or infinities. To test whether a floating-point number represents a NaN or an infinity, you can call isnan() or isinf().

In addition to being able to tear apart floating-point numbers and then put them back together again, GLSL includes a number of functions to take floating-point vectors, scale them to various bit depths (such as 8- or 16-bit values), and pack them together into a single 32-bit quantity. For example, the packUnorm4x8() and packSnorm4x8() functions pack a vec4 value into four unsigned- or signed- 8-bit integer values, respectively, and then pack those four 8-bit values together into a single uint. The unpackUnorm4x8() and unpackSnorm4x8() go the other way. The packUnorm2x16(),packSnorm2x16(), unpackUnormx16(), and unpackSnorm16() functions are the equivalents that handle vec2 variables, packing and unpacking them as 16-bit quantities into a uint.

The term norm in these functions refers to normalized. In this context, normalization essentially means scaling a value to map it onto a new range. Here, floating-point values are either in the range 0.0 to 1.0 for unsigned normalized data, or −1.0 to 1.0 for signed normalized data. The ends of the input range are mapped to the lower and upper bounds of the output range. This means that for unsigned normalized 8-bit data, for example, an unsigned byte with a value of 0 corresponds to 0.0 in floating point, and an unsigned byte with a value of 255 (the maximum value representable by an unsigned 8-bit number) maps to 1.0.

The packDouble2x32() and unpackDouble2x32() functions perform similar operations on double variables, and the packHalf2x16() functions perform these operations on 16-bit floating-point quantities. It should be noted that GLSL does not include direct support for 16-bit floating-point variables, although data can be stored in memory in that format, and so GLSL includes functionality to unpack it into usable data types in the shading language.

If you just want to get at a subsection of the bits in a signed or unsigned integer, you can use the bitfieldExtract() function to pull a specified chunk of bits out of an unsigned integer (or vector of unsigned integers). If the input value to the function is a signed integer, then the result is sign extended, otherwise it is zero extended. Once you have manipulated the bits, you can put them back into the integer using the bitfieldInsert() function.

Other bitfield operations supported by GLSL include bitfieldReverse(), bitCount(), findLSB(), and findMSB() functions, which reverse the order of a subset of bits in an integer, count the number of set bits in an integer, and find the index of the least significant or most significant bit that is set in an integer, respectively.

Compiling, Linking, and Examining Programs

Each OpenGL implementation has a compiler and linker built in that will take your shader code, compile it to an internal binary form, and link it together so that it can be run on a graphics processor. This process may fail for various reasons, and so it is important to be able to figure out why. The compilation or link stage may have failed, and even if they succeed, it may be that some other factor has changed the way that your program behaves.

Getting Information from the Compiler

To this point in the book, all of the shaders we’ve presented have been perfect, tested and bug free. We’ve done very little, if any error checking and have just blasted ahead assuming that everything will work fine. However, in the real world, at least during development, your shaders will have bugs, typos, or errors in them, and the shader compiler can help you find problems and squash them. The first step is to determine whether a shader compiled or not. Once you have set the shader’s source code and called glCompileShader(), you can get the compilation status back from OpenGL by calling glGetShaderiv(). Its prototype is

void glGetShaderiv(GLuint shader,
GLenum pname,
GLint * params);

Here, shader is the name of the shader object you’d like to know about, pname is the parameter you want to get from the shader object, and params is the address of a variable where OpenGL should put the result. To find out if a shader compiled successfully, you can set pname toGL_COMPILE_STATUS. The variable pointed to by params will be set to zero if the shader failed to compile and to one if it compiled successfully. Incidentally, one and zero are the numerical values of GL_TRUE and GL_FALSE, so you can test against those defines if you wish.

Other values for pname that can be passed to glGetShaderiv() are

• GL_SHADER_TYPE, which returns the type of shader that the object is (GL_VERTEX_SHADER, GL_FRAGMENT_SHADER, etc.),

• GL_DELETE_STATUS, which will return GL_TRUE or GL_FALSE to indicate whether glDeleteShader() has been called on the shader object,

• GL_SHADER_SOURCE_LENGTH, which returns the total length of the source code associated with the shader object, and

• GL_INFO_LOG_LENGTH, which returns the length of the information log contained in the shader object.

This last token, GL_INFO_LOG_LENGTH, tells you the length of the information log that the shader object contains. This log is generated when the shader is compiled. Initially, it’s empty, but as the shader compiler parses and compiles the shader, it generates a log that contains output similar to what you might be familiar with in the regular compiler world. You can then go ahead and retrieve the log from the shader object by calling glGetShaderInfoLog(), whose prototype is

void glGetShaderInfoLog(GLuint shader,
GLsizei bufSize,
GLsizei * length,
GLchar * infoLog);

Again, shader is the name of the shader object whose log you want to get at. infoLog should be pointed at a buffer that will have the log written into it by OpenGL. The buffer should be big enough to hold the entire log — the size of which you can get through the glGetShaderiv() function that we just introduced. If you only care about the first few lines of the log, you can use a fixed size buffer for infoLog, but regardless, the size of the buffer you’re using should be in bufSize. The actual amount of data written into infoLog will be written into the variable pointed to by lengthby OpenGL. Listing 6.1 shows an example of how to retrieve the log from a shader object.