Opening a Window - Demo 01¶

Initialize GLFW.¶

25if not glfw.init():
26    sys.exit()

Initialize GLFW. If initialization fails, the program should terminate. What does the initialization do? I don’t know. Think of it like a constructor for a class; it initializes some state that it needs for later function calls.

Set the version of OpenGL¶

OpenGL has been around a long time, and has multiple, occasionally incompatible versions. For this demo, we use OpenGL 1.4. By the end of this book, we will be using OpenGL 3.3 Core Profile.

Inform GLFW that we wish to used OpenGL 1.4:

30glfw.window_hint(glfw.CONTEXT_VERSION_MAJOR, 1)
31glfw.window_hint(glfw.CONTEXT_VERSION_MINOR, 4)

Create a Window¶

35window = glfw.create_window(500, 500, "ModelViewProjection Demo 1", None, None)

By calling glfw.create_window, we are creating a window. What are the arguments passed? It’s likely that the first two arguments are the width and height of the window, and the third likely the title of the window. What do the fourth and fifth arguments, both of which are “None”, mean? The author does not know. We could look it up the APIs online. But, Python has something called keyword arguments, which are used extensively throughout the rest of the book, where the intent of each parameter is clear at the site of calling the function.

39if not window:
40    glfw.terminate()
41    sys.exit()

• If GLFW cannot open the window, the Python process terminates by calling sys.exit.

45glfw.make_context_current(window)

• Make the window’s context current. The details of this do not matter for this book, but we need to call it anyways.

50def on_key(win, key, scancode, action, mods):
51    if key == glfw.KEY_ESCAPE and action == glfw.PRESS:
52        glfw.set_window_should_close(win, 1)
53
54
55glfw.set_key_callback(window, on_key)

If the user presses the “Escape” key while the program is running, inform GLFW that the user wants to quit, which we will handle this later in the Event Loop.

See First Class Functions for more information on functions as parameters to other functions.

59GL.glClearColor(0.0289, 0.071875, 0.0972, 1.0)

• Before a frame is drawn, it is first turned into a blank slate, where the color of each pixel is set to some value representing a color (we will see the importance of this in the first project). We are not clearing the framebuffer right now, but setting what color will be used for a later clear. Calling “glClearColor” “0,0,0,1”, means black “0,0,0”, without transparency (the “1”).

63GL.glMatrixMode(GL.GL_PROJECTION)
64GL.glLoadIdentity()
65GL.glMatrixMode(GL.GL_MODELVIEW)
66GL.glLoadIdentity()

• Don’t worry about the 4 lines here. Although they are necessary, we will cover them in depth later in this book. After all, this book is called ModelViewProjection. :-)

The Event Loop¶

When you pause a movie, motion stops and you see one picture. Movies are composed of sequence of pictures, when rendered in quick succession, provide the illusion of motion. Interactive computer graphics are rendered the same way, one “frame” at a time.

For our program, we need to render a frame, flush the complete framebuffer to the monitor. Repeat indefinitely until the user closes the window, or the program needs to terminate.

• Define the Event Loop

71while not glfw.window_should_close(window):
72    glfw.poll_events()
73
74    width, height = glfw.get_framebuffer_size(window)
75    GL.glViewport(0, 0, width, height)
76    GL.glClear(GL.GL_COLOR_BUFFER_BIT | GL.GL_DEPTH_BUFFER_BIT)
77    glfw.swap_buffers(window)

• Run a loop that will run infinitely, until some event causes it to decide to exit.

• Poll the operating system via the “poll_events” function (defined in the glfw module) for any events, such as mouse movements, keyboard input, etc. This call does not handle them, just queries to see if any of them have happened recently.

• Get the size of the Frame Buffer from glfw. A framebuffer contains 2D data representing all the pixels in a complete video frame. Python allows the returning of multiple values in the form of a tuple. Assigning to the variables width and height this way is a form of “destructuring”

• Using “glViewport” from the GL module, tell OpenGL that we wish to draw in the entire framebuffer, from the bottom left corner to the upper right corner.

• Make the framebuffer a blank slate by setting all of the pixels to have the same color. The color of each pixel will be value set to the clear color, which we set using glClearColor.. If we hadn’t cleared the framebuffer, then frame number n+1 would be drawing on top of whatever was drawn on frame number n. Programming in OpenGL is a bit different than normal programming in a normal language, in that individual function calls do not complete self-contained tasks, as subroutines typically do. Instead, the procedure calls to OpenGL functions only make sense based off of the context in which they are evaluated, and the sequence of OpenGL calls to complete a task.

• We have colored every pixel to be black, so flush the framebuffer to the monitor, and swap the back and front buffers.

One frame is created incrementally at a time, but the frame is sent to the monitor only when frame is completely drawn, and each pixel has a color. The act of sending the frame to the monitor is called flushing the frame.

OpenGL has two framebuffers (regions of memory which will eventually contain the full data for a frame), only one of which is “active”, or writable, at a given time. “glfwSwapBuffers” initiates the flushing the current buffer, and which switches the current writable framebuffer to the other one.