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

GLEffect Class Reference

Abstract base class for various user-defined effects. More...

#include <GLEffect.h>

Inheritance diagram for GLEffect::

AccumEffect CBSplineWrapperEffect ContourWarpEffect ShadowCaster SimpleEffect Waterwaves List of all members.

Public Methods

Construction/desctruction
Public API functions
Rendering, animation and effect control functions
Attention:
Derived effect classes should override and implement these as necessary. Default implementations do nothing nor are they supposed to doanything!


Event handlers
Attention:
These can (but don't need to) be reimplemented in the derived classes. They retrieve all necessary information from events and make it available through predefined variables, and also automatically call update(). You can modify / reimplement them for specific purposes if you need. See further documentation for details.


Protected Methods

Helper functions

Protected Attributes

Data members
GL parameters/states

Detailed Description

This abstract base class provides basic functionality common for all effects, i.e. instantiation/hiding/showing of child GUI controls, mouse/keyboard event handlers, a basic 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.

Todo:


Constructor & Destructor Documentation

GLEffect::GLEffect ( GLFramework * parent_gui )
 

Parameters:
parentGui   Pointer to the parent window.

Constructs an effect object and initializes internal state variables. The parentGui pointer is passed on to QObject constructor. Also obtains a pointer to the GL rendering window and places it into the glView variable.

Warning:
Almost all of general variables/states are set to 0 initially, so do not assume anything as default values for mouse coords, image pointers etc. Also, please keep in mind that the default projection parameters are as follows: fov angle - 60 degrees, view distance from the origin - 5 units (in world coordinates), distance to near clipping plane - 0, to far - 30 units. While this seems to be acceptable in usual cases, it is advisable to nevertheless set those parameters to your own acceptable values, as some effects might not look correctly with the defaults.

Precondition:
The parent window object must be fully constructed and available prior to creating any effect instances. Furthermore, the GL rendering window should also be fully constructed and avaiable, as the constructor will try to obtain a pointer to it.

Remarks:
Even though the effects are not derived from QWidget, they still need to be constructed with a pointer to the parent window because they need to be able to access various functions contained in GLFramework and GLView. 

Todo:
Additional init may be added later

See also:
GLFramework::glView, effectInfo..

GLEffect::~GLEffect ( ) [virtual]
 

Destroys an effect object. The settings panel and local effectInfo struct are deleted here.

Exceptions:
see   Warning...

Warning:
The local effectInfo struct and settings panel must still exist at the time the object is destroyed, otherwise pointer exceptions may occur.


Member Function Documentation

void GLEffect::init ( )
 

This is really just a wrapper for calling initialize() from outside. Although having such a simple function might seem silly(or stupid....), there are two important reasons for having it around: First, I tried to keep initialize() protected, as to not expose any unnecessary implementation details. Second, what it also does is set the perspective projection parameters in GLView that correspond to the selected effect. This guarantees that the selected effect will look correctly. (If you had to manually call the setProjectionParams() in initialize() and for some reason forgot to do it, your effect would probably look incorrectly).

See also:
GLView::setProjectionParams()

void GLEffect::createControlPanel ( bool needSeparateWindow = false )
 

Parameters:
needSeparateWindow   Controls where the control panel will be placed.

This instantiates the control panel and places it into a separate top-level dialog window if needSeparateWindow is set to TRUE. Otherwise ,the control panel will be placed into the side panel of the primary window (default option). The details of implementation are a bit tricky - you're advised to look at the internal comments if you wish to fully understand how this function works. It calls the user-defined implementation of createControls(), passing it the pointer to the correct parent...
Exceptions:
May   generate warning messages (these originate from Qt's inner mechanisms), if incorrect child-to-parent widget relationships are detected. This could happen in createControls() if you acidentally construct some widget with a wrong/unacceptable parent...

Warning:
You're responsible for calling createControlPanel() from the constructor of your derived class - it won't happen automatically. (The reason for this is that a control panel is part of an individual effect class, and as such it cannot be instantiated in the constructor of the base class). If you don't want any controls, you'll still have to provide at least an empty implementation of createControls() and call createControlPanel() for the effect selection mechanism to be able to properly show/hide your effect. A small frame with "No controls available" title will be generated automatically for you.

Precondition:
The base class part of an effect object must be initialized...

See also:
showControls(), hideControls(), show(), hide(), createControlPanel()

void GLEffect::createControls ( QWidget * parentWindow ) [pure virtual]
 

Parameters:
parentWindow   Pointer to the parent widget.

This is where you create your own conrol panel for your effect. The absolute minimum here is to provide an empty definition of this function, i.e
void createControls(QWidget* parent) {}, if you don't need any control widgets. This will put up an empty frame with "No controls available" title in the right panel of the main window.
Otherwise, here's how you build such a panel:
The controlPanel member variable will already contain a pointer to the correct parent widget(depending on what you chose in createControlPanel() ) at the time this function is called. So, construct some kind of container first, a QVBox for instance, with controlPanel as the parent widget. Then construct your control widgets with your QVBox container as the parent, and don't forget to define suitable slots for these widgets in your class. Finally, establish all necessary signal/slot connections, and the panel is ready to use.

Attention: When you have implemented the panel, its instantiation is taken care of automatically in GLEffect, so make sure you don't call this function from anywhere - the resulting behaviour of the program would be upredictable!

Reimplemented in AccumEffect, CBSplineWrapperEffect, ContourWarpEffect, SimpleEffect, and Waterwaves.

void GLEffect::hideControls ( )
 

This function hides the control panel of the current effect. You should call it once at the end of your derived class' constructor so that the control panel of your effect is initially hidden from view (otherwise the main GUI will look weird...)

Remarks:
This may seem strange, but this call to hideControls() at the end of your constructor is really necessary to ensure proper operation of the program. If I later come up with a better, more intuitive design, I'll change this implementation.

Warning:
May cause a crash if the control panel has been deallocated or didn't exist at the moment this function was called, so be careful with those controlPanel and controlWindow pointers.

See also:
showControls(), hide(), show()

void GLEffect::showControls ( )
 

This shows an effect's control panel. Both showControls() and hideControls() are used internally by GLFramework::onSelectEffect() member of the GLFramework class to control the visibility of individual effects upon selection. You should never call showControls() explicitly.
By default, this function detects if the panel had been instantiated as a separate top-level window. It then aligns it to the right border of the main window (if the main window is normal) or in the right side panel of the main window (if the main window is maximized).

Warning:
Same as in hideControls()

Todo:
If this 'docking' behaviour proves to be irritating, I'll introduce an additional parameter with which to turn it on and off.

void GLEffect::hide ( ) [virtual]
 

This function is called when an effect is hidden. It is doesn't currently do much, except reset the parameters of the effect being hidden to their defaults. Some additional commands might be added here later.

Reimplemented in CBSplineWrapperEffect, and ContourWarpEffect.

void GLEffect::show ( ) [virtual]
 

This function is called when an effect is shown. May be later used for a variety of different purposes.

Reimplemented in CBSplineWrapperEffect, and ContourWarpEffect.

bool GLEffect::needRawTextures ( ) const [inline]
 

This function is used by GLFramework to ask an effect whether it wants to handle originally loaded image data. If you set the newRawTextures member of the EffectInfo struct to true, the loaded images will no longer be automatically converted to the most common openGL-compatible format (32-bit RGBA) and you will be responsible for handling the data yourself in an appropriate way. You may wish to do so if the automatic conversion doesn't meet your requirements for some reason.

void GLEffect::reloadTextures ( )
 

This function is used internally by image loading mechanism within GLFramework to notify the current effect when the user loads a new set of images. The texture pointers are set to first image frames from each of 3 possible image lists (depending on how many image lists there are). The scene is then immediately updated to reflect the changes.

See also:
GLFramework::onLoadFiles()

void GLEffect::render ( ) [pure virtual]
 

This is the 'heart' of the effect rendering system. Derived classes will need to put implementation of their rendering algorithm into this function.

Reimplemented in AccumEffect, CBSplineWrapperEffect, ContourWarpEffect, SimpleEffect, and Waterwaves.

void GLEffect::mouseMoveEvent ( QMouseEvent * event ) [virtual]
 

Parameters:
mEv   Pointer to the incoming QMouseEvent. The event is supplied by the GL window.

Description, warnings etc. almost identical to mousePressEvent(), except this one processes mouse movement events, i.e. what is normally known as "dragging" the mouse.

See also:
mousePressEvent, GLView::mouseMoveEvent()

Reimplemented in CBSplineWrapperEffect, ContourWarpEffect, and ShadowCaster.

void GLEffect::mousePressEvent ( QMouseEvent * mEv ) [virtual]
 

Parameters:
mEv   Pointer to the incoming QMouseEvent. The event is supplied by the GL window.

Note:
A general note on all of these event handlers: if you want to override their default implementations, you have two options:
1. You override them completely and will then need to explicitly call get3DMouseCoords() and update() functions as necessary...
2. You override them with your specific code and add GLEffect::mouseMoveEvent (or others, respectively) as the last line of your implementation. Normalized and 3-d mouse coordinates will be then generated automatically. Be aware that update() will be called automatically,too, so don't include a call to update() yourself.

This event handler processes mouse click events generated by the GL window. The resulting information is stored as X and Y 2-D mouse coordinates (relative to the GL window) in mouseX and mouseY, respectively. The button states are stored in the mouseButtonPressed variable. See the Qt documentation for details on possible values of ButtonState and how to interpret them. The coordinates are also automatically normalized to [-1...1] range and are stored in normMouseX and normMouseY. As a convenience, 2-D mouse coordinates are also always automatically "unprojected" back into 3-D world coordinate space and are given back in mouse3D* variables. The scene is updated immediately after an event has been processed.
Exceptions:
None   , but see description of get3DMouseCoords() for possible "unprojection" errors/difficulties...

Precondition:
See get3DMouseCoords() for details...

See also:
get3DMouseCoords(), mouseMoveEvent(), GLView::mouseClickEvent()

Reimplemented in CBSplineWrapperEffect, ContourWarpEffect, and ShadowCaster.

void GLEffect::mouseReleaseEvent ( QMouseEvent * Event ) [virtual]
 

Parameters:
mEv   Pointer to the incoming QMouseEvent. The event is supplied by the GL window.

Reacts to the mouse being released after a click and/or drag. The default implementation does nothing, as all the relevant information is normally gathered by the preceding mousePressEvent() or mouseMoveEvent().

Reimplemented in CBSplineWrapperEffect, ContourWarpEffect, and ShadowCaster.

void GLEffect::wheelEvent ( QWheelEvent * wEv ) [virtual]
 

Parameters:
wEv   A pointer to the incoming QWheelEvent. The event is supplied by the GL window.

This handler processes incoming mouse wheel events. The default implementation does nothing and ignores the event (as required by Qt event processing hierarchy). The GLView window is set up to automatically assume focus upon any incoming wheel events to facilitate your event handler programming.

See also:
GLView::wheelEvent()

Reimplemented in ContourWarpEffect, and ShadowCaster.

void GLEffect::keyPressEvent ( QKeyEvent * event ) [virtual]
 

Parameters:
kEv   A pointer to the incoming QKeyEvent. The event is supplied by the GL window

This event handler processes incoming keyboard events. Nothing complicated here, the pressed key is stored in the keyPressed variable. Look into documentation of the global Qt namespace for possible key values. Many of them have convenient symbolic names. The scene is updated immediately after an event has been processed.

See also:
GLView::keyPressEvent()

Reimplemented in CBSplineWrapperEffect, and ShadowCaster.

void GLEffect::initialize ( ) [protected, virtual]
 

This function initializes the parameters of an effect and its associated GL modes/states. Default implementation does nothing, so override this as necessary. Be sure to set up and initialize any necessary variables / data here, and to enable/disable any required openGL states.

Exceptions:
None   , but check for possible GL errors when enabling/disabling/initalizing various GL states....

Warning:
Please remember that this function is called every time the effect is selected. This is done to properly re-initialize all necessary parameters and GL states in order to avoid conflicts with any residual data/GL modes that may have been left by the previously active effect. Therefore, write your initialization code accordingly, so that its behaviour is consistent.

See also:
GLView::initializeGL(), init()

Reimplemented in AccumEffect, CBSplineWrapperEffect, ContourWarpEffect, SimpleEffect, and Waterwaves.

void GLEffect::update ( ) [protected, virtual]
 

This is the base implementation - it will simply redraw the GL window. If you need something more sophisticated before redraw, re-implement this in your class and don't forget to include glView->update(); as the last line of your implementation.

Note:
Try to keep all necessary transforms etc. within your implementation of render(). Do not override this function unless it is really necessary.

Precondition:
Assumes all params are set up correctly..

Remarks:
This function, among several others, interfaces to the GL window to provide rendering and animation control. It is actually used as a wrapper for glView->update() to keep the class interface of GLEffect consistent.

See also:
GLView::update()

Reimplemented in ContourWarpEffect.

void GLEffect::forceMouseTracking ( bool enable ) [inline, protected]
 

Activates mouse tracking in GLView to track the mouse position regardless of mouse button states. This is useful in situations where you want your effect to react to mouse movements even if the button(s) aren't clicked.

void GLEffect::get3DMouseCoords ( GLdouble DepthCoord,
GLdouble & worldX,
GLdouble & worldY,
GLdouble & worldZ ) [protected]
 

Parameters:
DepthCoord   Current value of the depth coordinate.
worldX, worldY, worldZ   The variables in which the resulting 3-D world space coordinates will be returned.

This is a helper function that is used internally to "unproject" the 2-D mouse coordinates coming from the window back into 3-D world coordinate system, in order to facilitate such things as picking points on a plane etc. The results are returned in worldX, worldY, worldZ. They depend on the current modelview & projection matrices and viewport bounds, as well as supplied value of DepthCoord.
Exceptions:
Will   send warning messages to the console if the given coordinates cannot be unprojected for some reason.

Warning:
Quoting the OpenGL Programming Guide, "There are inherent difficulties in trying to reverse the transformation process.". In certain cases, the unprojection can become impossible, because of a non-invertible matrix etc,etc. The two pretty common culprits I have experienced were incorrect distances to near/far clipping planes and coordinates that originated outside the GL window. The latter has been fixed in event handlers. There still are some points to check if you see warnings that the coordinates could not be unprojected - current transformations, camera position, fov angle, and those clipping plane distances being likely candidates.

Precondition:
You'll need to set the value of currentDepthCoord to something sensible. If you set it to 0.0, this function will obtain the 3-D coordinates lying on the near clipping plane. Likewise, setting it to 1.0 will obtain the 3-D coordinates on the far clipping plane. Will either of those, it's quite simple to "shoot" a ray through the obtained point and then pick up any point on that ray.

See also:
mousePressEvent(), mouseMoveEvent()


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