---

GLFramework Documentation

1

Introduction and Brief Overview

First of all, for those of you joining us here in the Winter Semester of 2001/2002: welcome aboard.

Let's start by taking a look at what this program does and how it can help you with creating your effects:
GL Effects Framework simplifies your task of programming a desired effect algorithm. It provides you with an application window, complete with a GL rendering display and basic controls, i.e. effect selection, a "virtual trackball" for choosing an arbitrary viewing angle for your scene, animation control buttons ("Play", "Stop" etc.) and small text display which can be optionally used to output status and debugging messages. The framework also contains a standardized image loading mechanism to facilitate the loading of various images / image sequences to be used as textures etc. in your effect, as well as basic event handling and GL rendering. All of this functionality is provided through various functions in the framework.

What you will need for writing your effect(s):

Essential C++ skills (understanding of abstract classes, inheritance and virtual functions is required) and basic knowledge of OpenGL.

Trolltech's Qt Non-Commercial Edition SDK, available free of charge at http://www.trolltech.com

Microsoft Visual C++ 6.0 (5.0 will probably work as well, but I haven't tested that yet) under Windows.

Mesa-Devel and Qt-2.3.1, along with the latest version of GCC, if you plan to work with this program under Linux

Doxygen, a powerful documentation generator, which is available free of charge on the internet.

Time, patience, donuts & coffee ;)

First, we'll discuss how this application is structured:

The GLFramework class contains all low-level initialization and control functionality of the main application window, as well as effect instantiation, selection, and image loading mechanisms. The GL rendering viewport is created here, along with animation control buttons, memory tracker, status display and virtual trackball controls. A global QgridLayout manager automatically manages all contents of the window. This class also contains the functions that are responsible for feeding image data to the selected effect, and event handlers for animation and effect control, which call in the corresponding event handlers of the selected effect. (See GLFramework documentation for detailed descriptions and instructions.)

The GLView class encapsulates the GL rendering sub-window. This class provides basic rendering support, camera control and event handlers for mouse and keyboard events originating inside the GL sub-window. (See documentation for further details.) This class also provides the 'virtual trackball' mode, in which you can arbitrarily rotate the scene and zoom in and out. To do this click the large square button with the orbit icon in the "Camera Control" group, and the view will switch to the trackball mode. The trackball posesses special "rotation locks" features, which constraint the rotation to one of the primary axes, depending on which primary axis the mouse cursor is close to. The red/green axes are provided as aids to help you lock onto X and Y axes - the mouse cursor will change when it is in the vicinity of one of these axes to indicate the corresponding rotation lock mode. Clicking the right mouse button and dragging will zoom in or out of scene. Click the aforementioned orbit button again to exit the trackball mode.

Now comes by far the most important class in the entire program: GLEffect.
This abstract class serves as a base for all your effects. You create individual effects by deriving them from GLEffect. GLEffect provides basic functionality that is common for all effects, i.e. instantiation/hiding/showing of child GUI controls, mouse/keyboard event handlers, a basic effect information structure, and some other useful functions. (See list of API functions for details). It also provides common predefined member variables than can be used by an effect to keep pointers to texture data, access current 2d/3d mouse coordinates, pressed keys, perspective projection parameters etc. (Please note that this is really an abstract class containing pure virtual functions, so it cannot be instantiated directly).

The mainapp.cpp instantiates the main window and starts the application.

I've also included a simple effect class template, comprised of EffectTemplate.h and EffectTemplate.cpp. These files are located in the src/ directory and contain a complete class outline, properly derived from GLEffect and containing outlines of all functions that need to be implemented. The necessary comment sections are also in place and can be directly extracted by Doxygen. See the tutorial section on how to use it. Moreover, look at SampleEffect and SampleEffect2 classes to learn more about possible effect implementations.

A complete documentation is provided in HTML format and explains all classes in sufficient detail. Also included are a sample Doxygen configuration file (you'll need to change the input paths to your own) and a MSVC 6 workspace. A makefile for gcc is also provided. See the Readme file in the top-level directory for instructions on how to build the program.

Be sure to watch for and download updates to source code and documentation as they become available. If you find bugs please submit them to the mailing list.

Well, that's it for the review, now read the A Simple Effect Tutorial section to see how you can cook up effects.

Happy coding!

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.\n\n

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License (gpl.txt) for more details.

---