GLSL Wrapper Library

Overview

The following classes were developed for use in Andy Johnson's Special Topics course GPU programming by Don Olmstead. The objective in these classes is to provide an easy way object oriented way for students to get GLSL programs up and running quickly. All the steps to setup OpenGL to use GLSL are abstracted away so focus can be put on writing the vertex and fragment programs.

All the source code for this library is available under the GNU Lesser General Public License. All other libraries required to use this library are available under their respective licenses.

• Download Library (updated 02-07-06) - The source files, Linux Makefile, and Visual Studio .NET 2003 Solution
• Download Documentation - HTML Documentation created through Doxys

Installation

The library comes with both a Visual Studio .NET 2003 workspace as well as a makefile for Linux. If you are running Mac OS X for the time being you're on your own, but if someone does get this running on Mac OS X please contact me so I can update the source code with a way to build on a Mac. The library requires additional libraries to get everything up and running.

• GLEW (GL Extensions Wrangler) - Provides an easy way to use the various OpenGL Extensions available including GLSL
• FreeGLUT - Provides an alternative to the long dormant GLUT which provides all of what GLUT provided while adding some modern features
• DevIL - An image library that provides facilities to easily load the majority of image formats into OpenGL

You can replace DevIL with another image library or roll your own if you desire. It was included since GLSL can access and manipulate textures, and DevIL provides a painless way to load images into OpenGL. To remove it just remove any mention of DevIL (the header files and functions begin with il, ilu, or ilut) and remove the link to the library.

Installing On Windows

Download each of the dependency libraries. Either compile the individual libraries, using their respective instructions, or get the Windows binary. Each library should have instructions on installing the library for Windows. The general rules though for where the files go are as follows.

• Header Files (.h, .hpp) - (VC Root)/Include/
• Static Library (.lib) - (VC Root)/Lib
• Dynamicly Linked Library (.dll) - %SystemRoot%/system32

After all the libraries are installed open up the included Visual Studio Workspace. Compile the Solution, and verify that the OpenGL

Installing on Linux

Download each of the dependency libraries. Either compile the individual libraries, using their respective instructions, or get the binary for your distribution. Each library should have instructions on installing the library for linux. If you have permission to write to /usr/local the libraries should be able to put themselves in there for use. If that is not the case then just create a directory in your home directory mirroring the structure of usr/local and install the libraries manually. If you are having problems finding the .so files look for a hidden directory containing the library files, and copy the contents of the directory.

• Header Files (.h, .hpp) - /local/Include/
• Shared Object (.so) - /local/Lib

Next depending on where you put the libraries you may need to modify the makefiles. Within the Application/makelib.lnx file modify the INCPATH to include where you placed the header files for the libraries. Within the Examples/makeapp.lnx modify the LIBPATH to include where you placed the shared object files for the libraries. In the root of the GLSL directory type make and the library and examples will be made. If for whatever reason there are problems including the headers for the libraries you can go ahead and put it in the GLSL/Library directory.

Installing on Mac OS X

At this time no xcode files are available in the download. If anyone creates an xcode project for use with Mac OS X please contact me to get it included in the source files.

Using

The goal of the library was to make it as simple as possible to create a working application with GLSL. The sample application provided in the download is the quickest way to get up and running with the library. An excessive amount of comments were added to aid development. The following are the general steps to get an application, and further on are compiler specific elements.

• Create a directory in the Examples directory with your applications name
• Create a header file and code file for the application
• Within the header file
• Include the GLSL.hpp file
• Create the application class as a subclass of Application
• Override the onEntry and onClose methods. Both are called only once during execution
• Override the onIdle and onDisplay methods
• Override any methods for controlling input from the keyboard an mouse. The full list of methods and what they do are in the Documentation
• Within the code file
• Place the IMPLEMENT_APPLICATION(className) where className is the name of the class for the application. This creates the entry point, int main(), into your application
• Within the constructor call the parent class Application's constructor with the appropriate arguments
• Define the onEntry method, include any initialization of shaders here and not in the constructor
• Define the onClose method, cleanup the application here
• Define the onIdle method, perform any logic here and call the parent class' onIdle method to post a redisplay
• Define the onDisplay method, perform all drawing here
• Define any other methods from the header file

Using with Visual Studio .NET 2003

Start off by creating a new project within the Solution for the GLSL Library. Make sure that you point the Location of the project to be within the Examples directory within the directory you put the GLSL library. Click the Solution on the right side of the window, right click it and select Properties. Within the properties select Project Dependencies and select the newly created project. Check that the project depends on Application and click OK. Now close Visual Studio.

Rather than going through the properties of the project and setting them all manually, the project file from the sample application can be used. The project files are nothing more than XML files so open up the sample application's project file and the newly created application's project file in a text editor. Copy the area within the Configurations tag from the sample project and replace the Configuration tag from the new project with the samples. Save the project file and reload the solution in Visual Studio.

Using with GCC

Open the makefile.lnx file in the root of the Examples directory. Create a corresponding entry for your application in the build and clean portions of the makefile. The value for APP is the directory where your application is housed. Now run make from the root of the library directory and assuming no compiler errors your application will be built.

Common Gotchas using GLSL

Make sure you haven't fallen prey to one of these gotchas before sending any questions regarding this library

• There must always be a blank line of the vertex and fragment code files. There may or may not be a compiler error but nothing will display. This may be due to my use of fstream rather than using C style FILE pointers to read the file in.
• You need to call the ProgramObject's link method after adding all the vertex and fragment shaders and before calling begin
• You need to set the uniforms between the begin and end methods. This can be done during the onInitialize method.

Thank You's

Thank you Andy Johnson for creating this class and using this framework for it. Also thank you Bob Kooima for answering my various OpenGL questions. And finally the author of 3D Game Engine Architecture : Engineering Real-Time Applications with Wild Magic, David H. Eberly for giving me the idea to abstract away the application to make it easy to create new ones.