1. Coordinating events

#
1. Coordinating events

There are several ways to organize the sequence of your experiments using the Vision Egg. You can write your own custom flow control and event handling, using the Vision Egg solely for drawing graphics. This is often useful in psychophysics experiments where interaction with a subject is interleaved with presentation of stimuli.

Alternatively, you can make use of the classes in `VisionEgg.FlowControl`. For example, `Presentation` is a class that maintains an association between the parameters of stimuli and their control functions, calls these functions, and initiates drawing of the stimuli. There are several ways to use the `Presentation` class described below. This mode of operation is useful for electrophysiology experiments.

# 1.1 Custom flow control and event handling

By writing your own custom flow control code, you have much more flexibility in designing experiments, but also less of the work involved has been done for you. Perhaps the best place to start is simply to look at some examples. See the demonstration scripts dots_simple_loop.py, mouseTarget_user_loop.py, and multi_stim.py. Each of these programs has its own main loop which performs the same role as the `Presentation` class's `go` and `run_forever` methods, which are described further in this chapter.

# 1.2 Using the Presentation class: Running a single trial

Most of the Vision Egg demonstration scripts run a single trial and then quit. From a programming perspective, this is the easiest way to get started. The timing and control of events within a single trial is performed by a ``go loop'', which is entered by calling the `go()` method of the `Presentation` class.

A cycle of the go loop consists of updating any relevant stimulus parameters, clearing the framebuffer, and calling the stimuli to draw themselves. The buffers are swapped and the cycle begins again, usually after waiting for the vertical blanking interval (see the section in this manual on double buffering). When waiting for the vertical blanking interval (``sync swap buffers'') is enabled, cycles through the ``go loop'' never occur faster than the frame rate. If the go loop is burdened with lots of calculations or if the operating system takes the CPU away from the Vision Egg, the cycle through the go loop is not completed before the video card begins drawing the next frame and therefore a frame is skipped.

A go loop can run indefinitly or have its duration limited to a duration measured in seconds or in number of frames drawn. (Measuring duration based on frames drawn is only meaningful when buffer swapping is synchronized with the vertical blanking interval and frame skipping would be particularly undesirable in this case.)

# 1.3 Using the Presentation class: Continuous operation

Often, the visual stimulus needs to continue running between trials. At a minimum this could be used to keep the display constant and to prevent the Vision Egg from quitting, but could also be used to maintain a moving pattern on the display between trials. In addition, it may be necessary to trigger a go loop with a minimum of latency after the receipt of some signal, such as a digital input on the parallel port.

To use the Vision Egg in this manner, the `run_forever()` method of `Presentation` is called, which begins a loop that performs the same tasks as a go loop with the exception that functions controlling stimulus parameters are informed that it is a ``between go loops'' state. At any point this `run_forever` loop can create a go loop, which returns control back to the `run_forever` loop when done. Alternatively, if the controlling functions for stimulus parameters operate between go loops, the entire experiment could be run without entering a go loop. (This could also be acheived by starting a go loop with a duration parameter set to ``forever''.)