Class Stimulus

         object --+    
                  |    
ClassWithParameters --+
                      |
                     Stimulus

Known Subclasses:

AlphaGratingCommon, AzElGrid, DotArea2D, FixationCross, FixationSpot, GlutTextBase, LuminanceGratingCommon, Model3DS, Rectangle3D, Target2D, TextureStimulusBaseClass

Base class for a stimulus.

Any stimulus element should be a subclass of this Stimulus class.
The draw() method contains the code executed before every buffer
swap in order to render the stimulus to the frame buffer.  It
should execute as quickly as possible.  The init_gl() method must
be called before the first call to draw() so that any internal
data, OpenGL display lists, and OpenGL:texture objects can be
established.

To illustrate the concept of the Stimulus class, here is a
description of several methods of drawing two spots.  If your
experiment displays two spots simultaneously, you could create two
instances of (a single subclass of) Stimulus, varying parameters
so each draws at a different location.  Another possibility is to
create one instance of a subclass that draws two spots.  Another,
somewhat obscure, possibility is to create a single instance and
add it to two different viewports.  (Something that will not work
would be adding the same instance two times to the same viewport.
It would also get drawn twice, although at exactly the same
location.)

OpenGL is a 'state machine', meaning that it has internal
parameters whose values vary and affect how it operates.  Because
of this inherent uncertainty, there are only limited assumptions
about the state of OpenGL that an instance of Stimulus should
expect when its draw() method is called.  Because the Vision Egg
loops through stimuli this also imposes some important behaviors:

First, the framebuffer will contain the results of any drawing
operations performed since the last buffer swap by other instances
of (subclasses of) Stimulus. Therefore, the order in which stimuli
are present in the stimuli list of an instance of Viewport may be
important.  Additionally, if there are overlapping viewports, the
order in which viewports are added to an instance of Screen is
important.

Second, previously established OpenGL display lists and OpenGL
texture objects will be available.  The __init__() method should
establish these things.

Third, there are several OpenGL state variables which are
commonly set by subclasses of Stimulus, and which cannot be
assumed to have any particular value at the time draw() is called.
These state variables are: blending mode and function, texture
state and environment, the matrix mode (modelview or projection),
the modelview matrix, depth mode and settings. Therefore, if the
draw() method depends on specific values for any of these states,
it must specify its own values to OpenGL.

Finally, a well-behaved Stimulus subclass resets any OpenGL state
values other than those listed above to their initial state before
draw() and init_gl() were called.  In other words, before your
stimulus changes the state of an OpenGL variable, use
glGetBoolean, glGetInteger, glGetFloat, or a similar function to
query its value and restore it later.  For example, upon calling
the draw() method, the projection matrix will be that which was
set by the viewport. If the draw() method alters the projection
matrix, it must be restored. The glPushMatrix() and glPopMatrix()
commands provide an easy way to do this.

The default projection of Viewport maps eye coordinates in a 1:1
fashion to window coordinates (in other words, it sets eye
coordinates to use pixel units from the lower left corner of the
viewport). Therefore the default parameters for a stimulus should
specify pixel coordinates if possible (such as for a 2D
stimulus). Assuming a window size of 640 by 480 for the default
parameters is a pretty safe way to do things.

Also, be sure to check for any assumptions made about the system
in the __init__ method.  For example, if your stimulus needs alpha
in the framebuffer, check the value of
glGetIntegerv(GL_ALPHA_BITS) and raise an exception if it is not
available.

Instantiate and get ready to draw.

Set parameter values and create anything needed to draw the
stimulus including OpenGL state variables such display lists
and texture objects.

Draw the stimulus. (Called by Viewport instance.)

This method is called every frame.  This method actually
performs the OpenGL calls to draw the stimulus.