Main Page   Modules   Class Hierarchy   Compound List   File List   Compound Members   File Members   Related Pages  

GLFramework Class Reference

Primary application class. More...

#include <GLFramework.h>

List of all members.

Public Methods

Creation, desctruction
Public API functions
The following functions feed image data to an effect:
Layout-related Functions

Protected Methods

Private Methods

Helper Functions

Private Slots

Slots:
Event handlers

Detailed Description

This is the primary application GUI class. All primary gui controls, as well as the openGL viewport are instantiated and placed into a common layout here. This class provides functions for loading image sequences, controlling the view via a virtual trackball control, effect selection and controls. Also takes care of all necessary initialization/event handling at the top level of the application.

Todo:
There are a few small things left here and there. In the near future I will link in the FreeImage library so that the program can support additional file formats like TGA, JPG, etc.


Constructor & Destructor Documentation

GLFramework::GLFramework ( QWidget * parent = 0,
const char * name = 0 )
 

Parameters:
parent   A pointer to the parent widget (In this case 0, because it is top-level widget)
name   A name for this widget, used only internally by Qt. Can be safely set to 0. Both parameters are passed on to the QWidget constructor.

This the primary class constructor. Most of GUI initialization is actually done in initFramework(), while the constructor instantiates the effect objects and does other required initialization. See implementation for details.
Exceptions:
Contains   pointer checks. Will issue an error and quit if there isn't enough memory available.

Todo:
New effects will be gradually added here as they are ready

See also:
initFramework()

GLFramework::~GLFramework ( )
 

Destroys the widget. Most cleanup is done via cleanUp().

Warning:
May cause a crash if you prematurely deallocate imageLists, fileNameLists or any member controls (buttons, labels etc.), because those vars are eventually freed by cleanUp().

See also:
cleanUp()


Member Function Documentation

void GLFramework::addToStatus ( const QString & line )
 

Parameters:
line   The line of text to display

Takes the contents of line and adds it as the last line of the status display. The display will automatically scroll if full or the line is longer than the width of the display.

Warning:
The display capacity is set to 500 lines of text. When it overflows, it automatically deletes the first line (that is, the oldest one). Keep this in mind if you output large messages such as series of mouse coords etc.

Todo:
Provide a smarter status display...

See also:
clearStatusDisplay()

void GLFramework::clearStatusDisplay ( void )
 

Clears the status display

void GLFramework::enableMemTracker ( bool en )
 

Parameters:
enable   Set to false to disable the tracker, to true to enable it.

Enables/disables the memory tracker display & tracker update timer

Warning:
The update interval is set to 100 ms. I found this to be an optimal value. We can change this later if needed. However, I would not recommend it since using a smaller interval wont't make the tracker much preciser, and will probably increase the processor load since more timer events will need to be processed. (The triangle indicator will probably also flash too fast and only annoy the users...)

Todo:
UNIX-specific section in updateMemoryTracker()

See also:
updateMemoryTracker()

unsigned int GLFramework::getNumImages ( unsigned int listNum )
 

Parameters:
listNum   Specifies the image list to be acessed.

Returns:
Number of images in the specified list.
Exceptions:
Contains   checks for possible out-of-bounds errors. Will issue a suitable error and quit the apllication.

Warning:
The returned number is the real full number of images in the list. If you want to use it in say, a loop for working with the image list, use this number - 1, or else you will get an "off by 1" error and likely a crash, too.

Precondition:
Properly initialized and loaded image lists

QImage * GLFramework::fetchPreviousImage ( unsigned int listNum = 0 )
 

Parameters:
listNum   Specifies the number of the image list to be acessed. Allowed parameter range is 0 - 2 . Default value of 0 is suitable for effects using only one set of textures (i.e. one image list).

Returns:
A pointer to the retrieved image. Will return 0 if called and the current effect does not require any textures, i.e. its numImageLists is 0.

Retrieves the previous image (relative to the current one) from the sequence of the specified image list. The default behaviour of this function is as follows: if with the next call to it the currentImage counter 'underflows' i.e. is less than 0 that counter is set to the number of the last image in the sequence - the function loops backwards through the image sequence during animation.
Exceptions:
Contains   checks for possible out-of-bounds errors. Will issue a suitable error and quit the apllication.

Warning:
See fetchImage()

Precondition:
Properly initialized and loaded image lists.

Todo:
Streaming mode....

Bug:
See fetchImage(), fetchNextImage(), fetchCurrentImage()

QImage * GLFramework::fetchCurrentImage ( unsigned int listNum = 0 )
 

Parameters:
listNum   Specifies the number of the image list to be acessed. Allowed parameter range is 0 - 2 .Default value of 0 is suitable for effects using only one set of textures (i.e. one image list).

Returns:
A pointer to the retrieved image. Will return 0 if called and the current effect does not require any textures, i.e. its numImageLists is 0.

Retrieves the current image from the sequence of the specified image list.
Exceptions:
Contains   checks for possible out-of-bounds errors. Will issue a suitable error and quit the apllication.

Warning:
See fetchImage()

Precondition:
Properly initialized and loaded image lists

Todo:
Streaming mode....

Bug:
See fetchImage(), fetchNextImage(), fetchPreviousImage()

QImage * GLFramework::fetchNextImage ( unsigned int listNum = 0 )
 

Parameters:
listNum   Specifies the number of the image list to be acessed. Allowed parameter range is 0 - 2 . Default value of 0 is suitable for effects using only one set of textures (i.e. one image list).

Returns:
A pointer to the retrieved image. Will return 0 if called and the current effect does not require any textures, i.e. its numImageLists is 0.

Retrieves the next image from the sequence of the specified image list. The default behaviour of this function is as follows: if with the next call to it the currentImage counter 'overflows' i.e. is greater than the number of corresponding texture objects, that counter is set back to 0. - the function loops through the image sequence during animation.
Exceptions:
Contains   checks for possible out-of-bounds errors. Will issue a suitable error and quit the apllication.

Warning:
See fetchImage()

Precondition:
Properly initialized and loaded image lists

Todo:
Streaming mode....

Bug:
See fetchImage(), fetchPreviousImage(), fetchCurrentImage()

QImage * GLFramework::fetchImage ( unsigned int listNum,
unsigned int imgNum )
 

Parameters:
listNum   Specifies the number of the image list to be acessed. Allowed parameter range is 0 - 2 .
imgNum   Specifies the image to be retrieved. Allowed parameter range is 0 - (number of images in the list) -1.

Returns:
A pointer to the retrieved image. Will return an empty QImage placeholder if called and the current effect does not require any textures, i.e. its numImageLists is 0.

Fetches the image specified by imgNum from the list specified by listNum.
Exceptions:
Contains   checks for possible out-of-bounds errors. Will issue a suitable error and quit the apllication.

Warning:
See warning for onLoadFiles().
Precondition:
Properly initialized and loaded image lists

Todo:
Streaming mode....

Bug:
The description in warning might be considered a bug by some....

Remarks:
The reason for returning an empty QImage object if the numImageLists of an effect is 0 is to provide at least a rudimentary (for now) protection mechanism. Consider a case where you specify an effect that doesn't need any textures and yet accidentally forget and try to access the image lists in your effect implementation. What will happen?
Thus, with at least an empty QImage object to operate on, you will easily avoid crashes. Same applies for all other fetch*Image() functions. See warning section of onLoadFiles() for additional precautions....

See also:
fetchNextImage(), fetchPreviousImage(), fetchCurrentImage()

void GLFramework::placeEffectControlPanel ( QWidget * panel )
 

Parameters:
panel   Pointer to an effect's control panel

Places the control panel of an effect into the 2nd column of the primary GUI and centers it vertically. Notice: To be precise, this function will take the control box and place it into the 2nd row of the 1st (and only) column of the panelGrid sub-layout.

Warning:
The control panel can be anything that derives from a QFrame, including the 'geometry management' widget types, but not from QLayout!

Precondition:
The control panel should be properly initialized and instantiated before passing it to this function

See also:
GLEffect::createControls(), GLEffect::createControlPanel(), GLEffect::showControls(), GLEffect::hideControls()

void GLFramework::updateMemoryTracker ( ) [private, slot]
 

Updates memory tracker indicators with current values. The green/red arrow indicator is simply for additional visual reference and shows whether the amount of free memory is currently increasing or decreasing.

Attention:
This function currently shows the global memory status, i.e. it doesn't reflect the amount of memory consumed by the program (except the texel data size indicator). It should not be considered precise, and should be used rather as a debugging aid for checking for possible memory leaks etc.

Warning:
Available only on Win32 platforms for now. UNIX part will be added later.

Precondition:
See above

Todo:
UNIX part of implementation

void GLFramework::onLoadFiles ( ) [private, slot]
 

Called when "Load Images..." button is clicked or a new effect requiring a different set of textures is selected. This calls the file loading dialog, up to 3 times, depending on requirements of the current effect, and loads the specified files into memory. The loaded files are automatically converted into an OpenGL-compatible image format and can be subsequently acessed through the fetch*Image() family of functions. The scene is then re-rendered with new textures applied.

Exceptions:
Contains   pointer checks. Will issue an error and quit if there isn't enough memory available.

Precondition:
The information about the number of required texture sets is picked up from the effectInfo struct of the current effect, so make sure you supply correct values in requiredImageLists and needNewTextures members of this struct. If you don't need any textures, set the requiredImageLists to 0 and needNewTextures to false. Optionally, you can provide more descriptive names for the file dialogs by setting fileDialogNames[0],[1], and [2] to desired text, for example effectInfo->fileDialogNames[0] = "Load texture images" .

Warning:
There is currently only a simple protection available against uninitialized image data arrays. If you want to load the images, and cancel file loading in one or more file dialogs, or do not specify any images, the program will automatically fall back and provide one empty QImage object for each list that was not loaded. Thus. subsequent access by fetch*Image() functions will return these objects instead of dangling pointers, thereby avoiding possible crash situations. Your objects will then simply be rendered with no texture(s).
Be advised that this protection is probably not 100 % bulletproof, so be careful and do not overly rely on this protection mechanism....

Todo:
Streaming mode

See also:
fetchNextImage(),fetchPreviousImage(),fetchCurrentImage(), fetchImage(),onSelectEffect()

void GLFramework::onQuit ( ) [private, slot]
 

Called when the "Quit" button is clicked. Presents the user with a "yes/no" dialog box asking whether or not he/she really wants to exit the application. Will stop the animation of the currently active effect before showing the dialog box.

Todo:
Fix that damn dialog box...

Bug:
For some reason some modal dialog widgets in Qt such as dialog boxes don't properly recieve move() and setGeometry() commands sometimes. As the result, depending on the current (operating system????) conditions, the aforementioned "yes/no" box might or might not sometimes appear at the upper-left corner of the main window, or at coordinates of another recently displayed dialog window... I have yet to find a fix for this.

See also:
onStop() (perhaps...)

void GLFramework::onSelectEffect ( int effectNum ) [private, slot]
 

Parameters:
effectNumber   The number of effect to be selected.

Uses the number returned by the effect selector combo box to select into the effect pool array. This functions stops and resets the previously active effect and hides its child control panel, then sets the current effect to the selected one and passes a pointer to it to the GL rendering window. Also checks if the selected effect is already current, to avoid unnecessary hiding/showing etc.

Warning:
This function automatically calls onLoadFiles() when a new effect is selected, provided the following conditions are met: the selected effect really needs a new set of textures OR has a different required number of image lists AND its required number of image lists is not 0. This kind of behaviour may not be liked by some people.... Talk to me and we'll work something out....

Precondition:
All effects available in the selector box must be properly instantiated.

See also:
onLoadFiles(), glView()

void GLFramework::polish ( ) [protected, virtual]
 

This function performs any post-construction initialization, just before the window is displayed. Some additional code may be included here later, for now it's empty.

void GLFramework::initFramework ( ) [private]
 

This carries out all essential GUI initialization by creating the components of the main window and establishing any necessary slot/signal connections.

See also:
GLFramework::GLFramework()

void GLFramework::cleanUp ( ) [private]
 

This function performs all necessary clean-up upon exiting the program

Warning:
May cause a crash if you prematurely deallocate imageLists, fileNameLists or any member controls (buttons, labels etc.). Be careful with those pointers.

Todo:
Some additional cleanup may be added here later

void GLFramework::getFileNames ( unsigned int listCount ) [private]
 

Parameters:
listCount   specifies the number of required file name lists

Returns:
None. Generates file name lists from the file loading dialogs

Note:
This function is not used in the actual program yet. It will like be utilized for the streaming mode (still working on it). It shows the file loading dialog(s), just like onLoadFiles(), but only creates the file name lists, without actually loading any images into memory.
Exceptions:
Contains   pointer checks. Will issue an error and quit if there isn't enough memory available.

Todo:
Streaming mode....


The documentation for this class was generated from the following files:
Generated at Fri Apr 19 16:53:06 2002 for GLFramework by doxygen1.2.6 written by Dimitri van Heesch, © 1997-2001