You can find the code files present in this chapter on GitHub at https://github.com/PacktPublishing/3D-Graphics-Rendering-Cookbook/tree/master/Chapter2

The GLFW library hides all the complexity of creating windows, graphics contexts, and surfaces, and getting input events from the operating system. In this recipe, we build a minimalistic application with GLFW and OpenGL to get some basic 3D graphics out onto the screen.

Getting ready

We are building our examples with GLFW 3.3.4. Here is a JSON snippet for the Bootstrap script so that you can download the proper library version:

{
  "name": "glfw",
  "source": {
    "type": "git",
    "url": "https://github.com/glfw/glfw.git",
    "revision": "3.3.4"
  }
}

The complete source code for this recipe can be found in the source code bundle under the name of Chapter2/01_GLFW.

How to do it...

Let's write a minimal application that creates a window and waits for an exit command from the user. Perform the following steps:

1. First, we set the GLFW error callback via a simple lambda to catch potential errors:

   #include <GLFW/glfw3.h>
   ...
   int main() {
     glfwSetErrorCallback(
        []( int error, const char* description ) {
           fprintf( stderr, "Error: %s\n", description );
        });

2. Now, we can go forward to try to initialize GLFW:

     if ( !glfwInit() )
        exit(EXIT_FAILURE);

3. The next step is to tell GLFW which version of OpenGL we want to use. Throughout this book, we will use OpenGL 4.6 Core Profile. You can set it up as follows:

     glfwWindowHint(GLFW_CONTEXT_VERSION_MAJOR, 4);
     glfwWindowHint(GLFW_CONTEXT_VERSION_MINOR, 6);
     glfwWindowHint(    GLFW_OPENGL_PROFILE, GLFW_OPENGL_CORE_PROFILE);
     GLFWwindow* window = glfwCreateWindow(    1024, 768, "Simple example", nullptr, nullptr);
     if (!window) {
       glfwTerminate();
       exit( EXIT_FAILURE );
     }

4. There is one more thing we need to do before we can focus on the OpenGL initialization and the main loop. Let's set a callback for key events. Again, a simple lambda will do for now:

     glfwSetKeyCallback(window,
       [](GLFWwindow* window,       int key, int scancode, int action, int mods) {
         if ( key == GLFW_KEY_ESCAPE && action == 
             GLFW_PRESS )
                glfwSetWindowShouldClose(               window, GLFW_TRUE );
       });

5. We should prepare the OpenGL context. Here, we use the GLAD library to import all OpenGL entry points and extensions:

     glfwMakeContextCurrent( window );
     gladLoadGL( glfwGetProcAddress );
     glfwSwapInterval( 1 );

Now we are ready to use OpenGL to get some basic graphics out. Let's draw a colored triangle. To do that, we need a vertex shader and a fragment shader, which are both linked to a shader program, and a vertex array object (VAO). Follow these steps:

1. First, let's create a VAO. For this example, we will use the vertex shader to generate all vertex data, so an empty VAO will be sufficient:

     GLuint VAO;
     glCreateVertexArrays( 1, &VAO );
     glBindVertexArray( VAO );

2. To generate vertex data for a colored triangle, our vertex shader should look as follows. Those familiar with previous versions of OpenGL 2.x will notice the layout qualifier with the explicit location value for vec3 color. This value should match the corresponding location value in the fragment shader, as shown in the following code:

   static const char* shaderCodeVertex = R"(
   #version 460 core
   layout (location=0) out vec3 color;
   const vec2 pos[3] = vec2[3](
     vec2(-0.6, -0.4),
     vec2(0.6, -0.4),
     vec2(0.0, 0.6)
   );
   const vec3 col[3] = vec3[3](
     vec3(1.0, 0.0, 0.0),
     vec3(0.0, 1.0, 0.0),
     vec3(0.0, 0.0, 1.0)
   );
   void main() {
     gl_Position = vec4(pos[gl_VertexID], 0.0, 1.0);
     color = col[gl_VertexID];
   }
   )";

   Important note

   More details on OpenGL Shading Language (GLSL) layouts can be found in the official Khronos documentation at https://www.khronos.org/opengl/wiki/Layout_Qualifier_(GLSL).

   We use the GLSL built-in gl_VertexID input variable to index into the pos[] and col[] arrays to generate the vertex positions and colors programmatically. In this case, no user-defined inputs to the vertex shader are required.

3. For the purpose of this recipe, the fragment shader is trivial. The location value of 0 of the vec3 color variable should match the corresponding location in the vertex shader:

   static const char* shaderCodeFragment = R"(
   #version 460 core
   layout (location=0) in vec3 color;
   layout (location=0) out vec4 out_FragColor;
   void main() {
     out_FragColor = vec4(color, 1.0);
   };
   )";

4. Both shaders should be compiled and linked to a shader program. Here is how we do it:

     const GLuint shaderVertex =    glCreateShader(GL_VERTEX_SHADER);
     glShaderSource(    shaderVertex, 1, &shaderCodeVertex, nullptr);
     glCompileShader(shaderVertex);
     const GLuint shaderFragment =    glCreateShader(GL_FRAGMENT_SHADER);
     glShaderSource(shaderFragment, 1,    &shaderCodeFragment, nullptr);
     glCompileShader(shaderFragment);
     const GLuint program = glCreateProgram();
     glAttachShader(program, shaderVertex);
     glAttachShader(program, shaderFragment);
     glLinkProgram(program);
     glUseProgram(program);

   For the sake of brevity, all error checking is omitted in this chapter. We will come back to it in the next Chapter 3, Getting Started with OpenGL and Vulkan.

Now, when all of the preparations are complete, we can jump into the GLFW main loop and examine how our triangle is being rendered.

Let's explore how a typical GLFW application works. Perform the following steps:

1. The main loop starts by checking whether the window should be closed:

     while ( !glfwWindowShouldClose(window) )  {

2. Implement a resizable window by reading the current width and height from GLFW and updating the OpenGL viewport accordingly:

        int width, height;
        glfwGetFramebufferSize(
          window, &width, &height);
        glViewport(0, 0, width, height);

   Important note

   Another approach is to set a GLFW window resize callback via glfwSetWindowSizeCallback(). We will use this later on for more complicated examples.

3. Clear the screen and render the triangle. The glDrawArrays() function can be invoked with the empty VAO that we bound earlier:

        glClearColor(1.0f, 1.0f, 1.0f, 1.0f);
        glClear(GL_COLOR_BUFFER_BIT);
        glDrawArrays(GL_TRIANGLES, 0, 3);

4. The fragment shader output was rendered into the back buffer. Let's swap the front and back buffers to make the triangle visible. To conclude the main loop, do not forget to poll the events with glfwPollEvents():

        glfwSwapBuffers(window);
        glfwPollEvents();
     }

5. To make things nice and clean at the end, let's delete the OpenGL objects that we created and terminate GLFW:

     glDeleteProgram(program);
     glDeleteShader(shaderFragment);
     glDeleteShader(shaderVertex);
     glDeleteVertexArrays(1, &VAO);
     glfwDestroyWindow(window);
     glfwTerminate();
     return 0;
   }

Here is a screenshot of our tiny application:

Figure 2.1 – Our first triangle is on the screen

There's more...

The GLFW setup for macOS is quite similar to the Windows operating system. In the CMakeLists.txt file, you should add the following line to the list of used libraries: -framework OpenGL -framework Cocoa -framework CoreView -framework IOKit.

Further details about how to use GLFW can be found at https://www.glfw.org/documentation.html.

Every 3D graphics application needs some sort of math utility functions, such as basic linear algebra or computational geometry. This book uses the OpenGL Mathematics (GLM) header-only C++ mathematics library for graphics, which is based on the GLSL specification. The official documentation (https://glm.g-truc.net) describes GLM as follows:

GLM provides classes and functions designed and implemented with the same naming conventions and functionalities as GLSL so that anyone who knows GLSL, can use GLM as well as C++.

Getting ready

Get the latest version of GLM using the Bootstrap script. We use version 0.9.9.8:

{
  "name": "glm",
  "source": {
    "type": "git",
    "url": "https://github.com/g-truc/glm.git",
    "revision": "0.9.9.8"
  }
}

Let's make use of some linear algebra and create a more complicated 3D graphics example. There are no lonely triangles this time. The full source code for this recipe can be found in Chapter2/02_GLM.

How to do it...

Let's augment the example from the previous recipe using a simple animation and a 3D cube. The model and projection matrices can be calculated inside the main loop based on the window aspect ratio, as follows:

1. To rotate the cube, the model matrix is calculated as a rotation around the diagonal (1, 1, 1) axis, and the angle of rotation is based on the current system time returned by glfwGetTime():

   const float ratio = width / (float)height;
   const mat4 m = glm::rotate(  glm::translate(mat4(1.0f), vec3(0.0f, 0.0f, -3.5f)),  (float)glfwGetTime(), vec3(1.0f, 1.0f, 1.0f));
   const mat4 p = glm::perspective(  45.0f, ratio, 0.1f, 1000.0f);

2. Now we should pass the matrices into shaders. We use a uniform buffer to do that. First, we need to declare a C++ structure to hold our data:

   struct PerFrameData {
     mat4 mvp;
     int isWireframe;
   };

   The first field, mvp, will store the premultiplied model-view-projection matrix. The isWireframe field will be used to set the color of the wireframe rendering to make the example more interesting.

3. The buffer object to hold the data can be allocated as follows. We use the Direct-State-Access (DSA) functions from OpenGL 4.6 instead of the classic bind-to-edit approach:

   const GLsizeiptr kBufferSize = sizeof(PerFrameData);
   GLuint perFrameDataBuf;
   glCreateBuffers(1, &perFrameDataBuf);
   glNamedBufferStorage(perFrameDataBuf, kBufferSize,  nullptr, GL_DYNAMIC_STORAGE_BIT);
   glBindBufferRange(GL_UNIFORM_BUFFER, 0,  perFrameDataBuf, 0, kBufferSize);

   The GL_DYNAMIC_STORAGE_BIT parameter tells the OpenGL implementation that the content of the data store might be updated after creation through calls to glBufferSubData(). The glBindBufferRange() function binds a range within a buffer object to an indexed buffer target. The buffer is bound to the indexed target of 0. This value should be used in the shader code to read data from the buffer.

4. In this recipe, we are going to render a 3D cube, so a depth test is required to render the image correctly. Before we jump into the shaders' code and our main loop, we need to enable the depth test and set the polygon offset parameters:

   glEnable(GL_DEPTH_TEST);
   glEnable(GL_POLYGON_OFFSET_LINE);
   glPolygonOffset(-1.0f, -1.0f);

   Polygon offset is needed to render a wireframe image of the cube on top of the solid image without Z-fighting. The values of -1.0 will move the wireframe rendering slightly toward the camera.

Let's write the GLSL shaders that are needed for this recipe:

1. The vertex shader for this recipe will generate cube vertices in a procedural way. This is similar to what we did in the previous triangle recipe. Notice how the PerFrameData input structure in the following vertex shader reflects the PerFrameData structure in the C++ code that was written earlier:

   static const char* shaderCodeVertex = R"(
   #version 460 core
   layout(std140, binding = 0) uniform PerFrameData {
     uniform mat4 MVP;
     uniform int isWireframe;
   };
   layout (location=0) out vec3 color;

2. The positions and colors of cube vertices should be stored in two arrays. We do not use normal vectors here, which means we can perfectly share 8 vertices among all the 6 adjacent faces of the cube:

   const vec3 pos[8] = vec3[8](
     vec3(-1.0,-1.0, 1.0), vec3( 1.0,-1.0, 1.0),
     vec3(1.0, 1.0, 1.0), vec3(-1.0, 1.0, 1.0),
   
  vec3(-1.0,-1.0,-1.0), vec3(1.0,-1.0,-1.0),
     vec3( 1.0, 1.0,-1.0), vec3(-1.0, 1.0,-1.0)
   );
   const vec3 col[8] = vec3[8](
     vec3(1.0, 0.0, 0.0), vec3(0.0, 1.0, 0.0),
     vec3(0.0, 0.0, 1.0), vec3(1.0, 1.0, 0.0),
   
  vec3(1.0, 1.0, 0.0), vec3(0.0, 0.0, 1.0),
     vec3(0.0, 1.0, 0.0), vec3(1.0, 0.0, 0.0)
   );

3. Let's use indices to construct the actual cube faces. Each face consists of two triangles:

   const int indices[36] = int[36](
     // front   0, 1, 2, 2, 3, 0,
     // right   1, 5, 6, 6, 2, 1,
     // back   7, 6, 5, 5, 4, 7,
     // left   4, 0, 3, 3, 7, 4,
     // bottom   4, 5, 1, 1, 0, 4,
     // top   3, 2, 6, 6, 7, 3
   );

4. The main() function of the vertex shader looks similar to the following code block. The gl_VertexID input variable is used to retrieve an index from indices[], which is used to get corresponding values for the position and color. If we are rendering a wireframe pass, set the vertex color to black:

   void main() {
     int idx = indices[gl_VertexID];
     gl_Position = MVP * vec4(pos[idx], 1.0);
     color = isWireframe > 0 ? vec3(0.0) : col[idx];
   }
   )";

5. The fragment shader is trivial and simply applies the interpolated color:

   static const char* shaderCodeFragment = R"(
   #version 460 core
   layout (location=0) in vec3 color;
   layout (location=0) out vec4 out_FragColor;
   void main()
   {
     out_FragColor = vec4(color, 1.0);
   };
   )";

The only thing we are missing now is how we update the uniform buffer and submit actual draw calls. We update the buffer twice per frame, that is, once per each draw call:

1. First, we render the solid cube with the polygon mode set to GL_FILL:

   PerFrameData perFrameData = {  .mvp = p * m,  .isWireframe = false };
   glNamedBufferSubData(  perFrameDataBuf, 0, kBufferSize, &perFrameData);
   glPolygonMode(GL_FRONT_AND_BACK, GL_FILL);
   glDrawArrays(GL_TRIANGLES, 0, 36);

2. Then, we update the buffer and render the wireframe cube using the GL_LINE polygon mode and the -1.0 polygon offset that we set up earlier with glPolygonOffset():

   perFrameData.isWireframe = true;
   glNamedBufferSubData(  perFrameDataBuf, 0, kBufferSize, &perFrameData);
   glPolygonMode(GL_FRONT_AND_BACK, GL_LINE);
   glDrawArrays(GL_TRIANGLES, 0, 36);

The resulting image should look similar to the following screenshot:

Figure 2.2 – The rotating 3D cube with wireframe contours

There's more...

As you might have noticed in the preceding code, the glBindBufferRange() function takes an offset into the buffer as one of its input parameters. That means we can make the buffer twice as large and store two different copies of PerFrameData in it. One with isWireframe set to true and another one set to false. Then, we can update the entire buffer with just one call to glNamedBufferSubData(), instead of updating the buffer twice, and use the offset parameter of glBindBufferRange() to feed the correct instance of PerFrameData into the shader. This is the correct and most attractive approach, too.

The reason we decided not to use it in this recipe is that the OpenGL implementation might impose alignment restrictions on the value of offset. For example, many implementations require offset to be a multiple of 256. Then, the actual required alignment can be queued as follows:

GLint alignment;
glGetIntegerv(  GL_UNIFORM_BUFFER_OFFSET_ALIGNMENT, &alignment);

The alignment requirement would make the simple and straightforward code of this recipe more complicated and difficult to follow without providing any meaningful performance improvements. In more complicated real-world use cases, particularly as the number of different values in the buffer goes up, this approach becomes more useful.

Almost every graphics application requires texture images to be loaded from files in some image file formats. Let's take a look at the STB image loader and discuss how we can use it to support popular formats, such as .jpeg, .png, and a floating point format .hdr for high dynamic range texture data.

Getting ready

The STB project consists of multiple header-only libraries. The entire up-to-date package can be downloaded from https://github.com/nothings/stb:

{
  "name": "stb",
  "source": {
    "type": "git",
    "url": "https://github.com/nothings/stb.git",
    "revision": "c9064e317699d2e495f36ba4f9ac037e88ee371a"
  }
}

The demo source code for this recipe can be found in Chapter2/03_STB.

How to do it...

Let's add texture mapping to the previous recipe. Perform the following steps:

1. The STB library has separate headers for loading and saving images. Both can be included within your project, as follows:

   #define STB_IMAGE_IMPLEMENTATION
   #include <stb/stb_image.h>
   #define STB_IMAGE_WRITE_IMPLEMENTATION
   #include <stb/stb_image_write.h>

2. To load an image as a 3-channel RGB image from any supported graphics file format, use this short code snippet:

   int w, h, comp;
   const uint8_t* img = stbi_load(  "data/ch2_sample3_STB.jpg", &w, &h, &comp, 3);

3. Besides that, we can save images into various image file formats. Here is a snippet that enables you to save a screenshot from an OpenGL GLFW application:

   int width, height;
   glfwGetFramebufferSize(window, &width, &height);
   uint8_t* ptr = (uint8_t*)malloc(width * height * 4);
   glReadPixels(0, 0, width, height, GL_RGBA,  GL_UNSIGNED_BYTE, ptr);
   stbi_write_png(  "screenshot.png", width, height, 4, ptr, 0);
   free(ptr);

   Please check stb_image.h and stb_image_write.h for a list of supported file formats.

4. The loaded img image can be used as an OpenGL texture in a DSA fashion, as follows:

   GLuint texture;
   glCreateTextures(GL_TEXTURE_2D, 1, &texture);
   glTextureParameteri(texture, GL_TEXTURE_MAX_LEVEL, 0);
   glTextureParameteri(  texture, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
   glTextureParameteri(  texture, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
   glTextureStorage2D(texture, 1, GL_RGB8, w, h);
   glPixelStorei(GL_UNPACK_ALIGNMENT, 1);
   glTextureSubImage2D(texture, 0, 0, 0, w, h, GL_RGB,  GL_UNSIGNED_BYTE, img);
   glBindTextures(0, 1, &texture);

Please refer to the source code in Chapter2/03_STB for a complete working example and the GLSL shader changes that are necessary to apply the texture to our cube.

There's more...

STB supports the loading of high-dynamic-range images in Radiance .HDR file format. Use the stbi_loadf() function to load files as floating-point images. This will preserve the full dynamic range of the image and will be useful to load high-dynamic-range light probes for physically-based lighting in the Chapter 6, Physically Based Rendering Using the glTF2 Shading Model.