Practical 01 Getting Started with GLFW

Getting Started
This is the first practical for the graphics programming module, and we will start by setting up our runtime environment. In this module we will be using a number of different libraries which you can download and use for any future OpenGL applications. The main advantage with the approach we are taking is that it is generally platform independent (our approach can be used on Windows, Linux and Apple operating systems). However, in this module, we will consider that you are using Windows as a platform, and Visual Studio as a development tool. For other platforms and tools, please see the relevant documentation from the websites of the libraries we will be using, and the relevant documentation of the tools you are using. To get started, we will be downloading and using the GL Framework (GLFW).

Downloading GLFW
GLFW is available from http://www.glfw.org/. From here, select the Download link, and download the relevant version for your platform. I will assume that you are downloading for Windows, which is available as a pre-built library on the GLFW website (under Binary Archive for Windows). This will provide you with a ZIP archive. Download this file, and unzip it, placing it somewhere sensible. I put the libraries that I work with in a folder with the address C:\Users\Kevin\Libraries.

Creating a New Visual Studio Project

Start Visual Studio 2010 from the Start Menu. Once Visual Studio has started, you should see the following screen:

Now, select File->New Project from the menu, and find the entry for creating a new Win32 Console Application under the Visual C++ heading:

Call the project whatever you want, but you probably want to be systematic about your naming mechanism for the entire module. Once you've given the project a name, click OK. On the next window, simply click Next. You should now see the following window:

Make sure that you change your settings on this screen to the same as above. This is very important. We are essentially saying that we are creating a Console application, and we do not want Visual Studio to create any extra files for us. Click Finish and Visual Studio will create your project for you. Now we need to do some setup so that we can use GLFW. Visual Studio Property Sheets You might be familiar with using external libraries using C# in Visual Studio, where we have to tell Visual Studio what library to use, and where to find it. For C++ programmes, we need to tell it Visual Studio two different pieces of information - the location of our header files (where functions and classes are declared) which is usually in a folder called include, and also the location of our library files (where actual existing compiled code exists) which is usually in a folder called lib. Now, we are going to do this in a reusable manner, so that once we have done the set up once, we can use it in our future projects. In Visual Studio, find the Property Manager window, which is usually attached to the Solution Explorer. Make sure your project is selected in this window, and select the Add New Project Property Sheet button:

This will bring up the new property sheet dialogue:

For the location entry, enter somewhere sensible again. I use the same location as I placed the unzipped GLFW files (C:\Users\Kevin\Libraries). Call the file OpenGL and click Add. This should make your Property Manager window look as follows:

Double-click the OpenGL entry to allow us to edit the property sheet. This will bring up the following window:

Select VC++ Directories on the left of the window. We are now going to modify two of the entries you see on the right - the Include Directories and the Library Directories entries. First, select the Include Directories entry and press the click the small triangle and select Edit.

You will now see a new window which allows you to add entries to your Include Directories entry.

Click the New Line button (the little yellow folder with a star) and this will allow you to enter a new entry. Click the little button with three dots, and then browse to the location of the Include folder where you put GLFW (for example, mine will be C:\Users\Kevin\Libraries\glfw2.7.2.bin.WIN32\include). Click the Select Folder button, and then click OK in the Include Directories window. Now Visual Studio knows where the header files for GLFW are. Do the same process for Library Directories entry, but this time you will want to use the directory where the release versions of the GLFW libraries for Visual Studio 2010 are located. On my machine, this will be C:\Users\Kevin\Libraries\glfw-2.7.2.bin.WIN32\lib-msvc100\release. Once done, you can click OK on the Property Sheet window, and go back to just Visual Studio. We are now ready to get started.

Your First GLFW Application

Now that we have Visual Studio up and running, we can create our first GLFW application. We need to add a code file to our Visual Project. If you are not familiar on how to do this, use the following steps. First, right-click on the Project in the Solution Explorer and select Add -> New Item:

In the new item window, select C++ File and call it main. This will add a new code file to your project:

We are now ready to enter our code for our first GLFW application. The first two lines of code tell Visual Studio which libraries to include when building the final application. The lines of code are:

These lines of code are particular to Microsoft's C++ compiler and linker, and will not work in other development environments. We are just including these libraries in the link step, so if you are using another environment, refer to the relevant documentation. The next line is where we include the header declaration for using GLFW:

This is the only header files we will be using at present. The first line is for GLFW, and the second is for some standard C functions that we will be using (such as exit). Now, we are going to create a small skeleton to allow us to separate out our code. We will do this by creating three functions - initialise, update and render. Add the following code to your main file:

The running variable we will use to indicate that the application is still running. The first function is where we will place any initialisation code we may want, the update function is where any updates done during the frame are placed, and the render function is where we perform our drawing. Now let us add the main function:

Line 23 we initialise GLFW by calling glfwInit. If this function call responds with false (GLFW cannot be initialised) then we exit the application (line 24). We then try and open a window (line 26) giving it a size of 800 pixels by 600 pixels. If this fails, we terminate GLFW and exit (lines 28 and 29). We then call the initialise function (line 32). Once everything is initialised, we enter the main rendering loop. GLFW provides a method of getting the current time since the application started using glfwGetTime. We get the current time (line 34) and declare a value to store the current time (line 35). Then we enter the main application loop. While running is true (line 36), we get the current time (line 38) and then call update by subtracting the previous frame time from the current frame time (line 39) which gives us the time passed since the last frame. We then call render (line 40) and then set the previous frame time to the current time frame (line 41). This loop will continue until the running is set to false. Once the main loop has been exited, we terminate GLFW, and exit the application. You can run this application, and you should get a black window appearing on screen. If it doesn't then double check your code and setup, and if you are sure it is right, ask for help. Setting Clear Colour Black is actually one of the worst clear colours we can use, as if we ever render something to the screen which isn't lit properly, or doesn't quite render correctly, the details will come out black, which means we cannot see any detail. Therefore, we are going to change the clear colour so we can better see problems. We do this in the initialise function:

Here, we are setting the clear colour to 0% red, 100% green, 100% blue and 100% alpha (the colour is opaque). Checking Keyboard Input We will also need to do some checking to see if the user wants to exit the application. We will do this by checking to see if Escape has been pressed. Add the following line to the update function.

If we get GLFW_KEY_ESC and it returns true (button pressed) we set running to false (we also check that the window created by GLFW is still open, which is good practice). Clearing the Screen and Swapping the Buffer Now all we need to do is perform standard drawing functions, such as clearing the screen and swapping the buffers (displaying what we have drawn). This involves just a couple of function calls in the render function:

Line 21 clears the current colours on the screen, using the clear colour. Line 22 swaps the buffer with GLFW. If you run your application now you will see the following window:

Important - the application you have now will form the basis for all our future applications. It would be a good idea to store this code somewhere.

Exercises
1. Change the clear colour of the screen. Colours to get working are: a. Red b. Green c. Blue d. White e. Black f. Yellow g. Cyan h. Magenta