NOVEMBER 2008 NOTES:
1. vvsp is no longer available on the DOS machines. However, this manual is still mostly relevant because the successor to vvsp, stimpres(2) , is functionally similar and the stimpres(2) manual was written as an extension to this (and the cavsp(2) ) manual. Hopefully someday the manuals will be properly merged into one.
2. In the early days when the ERP programs were being developed the term ISI (InterStimulus Interval) was being used incorrectly to refer to the time interval between the beginning of one stimulus and the beginning of another, and the legacy of this can be seen today in some ERP programs and documentation. When used correctly ISI refers to the time interval between the end of one stimulus and the beginning of another; SOA (Stimulus Onset Asynchrony) is the correct term to use to refer to the time interval between the beginnings of stimuli. In this manual the term ISI is being used incorrectly (except where noted in section 6.3.9, "Branching") and the reader should mentally substitute the correct term, SOA.
1. INTRODUCTION 2. USAGE 2.1. Invocation 2.2. Options 2.3. Hardware Connections 3. OPERATION 3.1. Control and Status Display 3.1.1. Files and Current Frame 3.1.2. Invocation Options 3.1.3. Current State 3.1.4. Control Options 3.1.5. Scrolling Synopsis 3.2. Pauses 3.3. Codes 3.4. Errors 3.4.1. Compilation Errors 3.4.2. Execution Errors 4. VGA GRAPHICS ENVIRONMENT 4.1. Resolution and Coordinates 4.2. Colors and Palettes 5. DISPLAY, TIMING, AND BUFFERING ALGORITHMS 5.1. Frame Buffering 5.2. Screen Erase/Replace Rectangles 5.3. Timing Considerations 5.3.1. VVSP Operation 5.3.2. VVSP -sbg Operation 6. SCENARIO FILES 6.1. General 6.1.1. Lines and Arguments 6.1.2. Comments 6.2. Mandatory Arguments 6.2.1. ISI 6.2.2. Presentation Duration 6.2.3. Code 6.2.4. Basic Image 6.3. Options 6.3.1. Xoff and Yoff 6.3.2. Color 6.3.3. Label Origin 6.3.4. Font 6.3.5. Monitor String 6.3.6. Selective Pauses 6.3.7. Scenario Pauses 6.3.8. No Erase/Replace 6.3.9. Branching 6.3.10. Wait For Response 6.3.11. End of Run 6.3.12. Label 6.3.13. Continuation 6.4. Stimulus Image Types 6.4.1. Text 6.4.2. Cri 6.4.3. Pgi 7. PGI FILES 7.1. General 7.2. Pgi Plotting Environment 7.3. Commands 7.3.1. State Commands 7.3.1.1. setfgcolor pixelvalue 7.3.1.2. setbgcolor pixelvalue 7.3.1.3. setlinetype mask 7.3.1.4. setdrawmode drawmode 7.3.1.5. selectfp fillpatternindex 7.3.1.6. setlblorig labelorigin 7.3.2. lineto xc yc 7.3.3. rlineto xc yc 7.3.4. moveto xc yc 7.3.5. rmoveto xc yc 7.3.6. orect nxpix nypix 7.3.7. frect nxpix nypix 7.3.8. dispcri crifile 7.3.9. label "text string" 7.3.10. font fontfile 7.3.11. subimage pgifile 7.3.12. Polygon Commands 7.3.12.1. Startpgon and Endpgon 7.3.12.2. outlinepgon rx ry 7.3.12.3. routlinepgon rx ry 7.3.12.4. fillpgon rx ry 7.3.12.5. rfillpgon rx ry Appendix 1: Default VGA Color-mapping Palette Appendix 2: Label Origins
VVSP is a program that displays visual images on an IBM PC/AT computer for use in event-related potential (ERP), perceptual, or psychophysical experiments. The visual images, termed stimuli, are presented with carefully meted durations and inter-stimulus intervals (ISIs) on a color monitor. VVSP uses an Orchid ProDesigner II super VGA to achieve an image resolution of 640 horizontal by 480 vertical pixels, displaying 256 simultaneous colors out of a palette of 262,000. Digital codes (termed event codes) accompany the onsets of stimuli and are used to denote the type and time of presentation of the stimuli for use in signal averaging, measurement of reaction times, or other analytic procedures. These codes are output via a Data Translation DT2821 card in the PC/AT connected to a stimulus-presentation interface (SPI) for code conditioning, display, and distribution to laboratory devices. Digital codes (termed response codes) are also accepted as input via a Scientific Solutions BaseBoard card in the PC/AT. These codes convey the responses that have been made to the stimuli, and can be used in conditional presentation scenarios. VVSP also supports the connection of the SPI to a game-port adapter for online control of stimulus presentation. Written in the "C" programming language, VVSP runs in an MS-DOS operating system environment and is compiled using version 5.0 of the MicroSoft C compiler and assembler (Masm).
The specifications for the visual images, their durations, ISIs, associated codes, and other parameters are contained in a text file termed a scenario file (SF). The scenario file can be created using any text editor (e.g. VI), or by a special purpose program designed for the specific experimental requirements. More often, however, they are created automatically by the program SG (Scenario Generator); for which a Use and Reference manual is available.
VVSP is quite flexible and can be used to present visual stimuli for a wide range of experiments; considerable effort was spent attempting to anticipate multifarious possible experimental stimulation requirements during its design and development. Some of its features include:
VVSP is the successor to VSPRES, SBVSPRES, and SHOWSTIM, and incorporates all their functions; various invocation options select the different modes of operation. That is, one invocation option causes VVSP to employ an arbitrary image as the background upon which stimuli are superimposed instead of a blank (black or other solid color) background, while another option causes VVSP to simply draw a stimulus on the screen and leave it there, allowing one to preview stimuli.
This manual is arranged so that information that one might need to refer to frequently when using the program is first, with explications of details and specific formats following. Unfortunately, this occasionally requires reference to terms and concepts not defined or explained in detail until later in the manual. But, in this way the manual is easier to use as both a user’s guide and a reference document for the program.
VVSP is easy to use once one has prepared a scenario file. One should ensure that the environment is set so that VVSP can be invoked from an appropriate disk partition/directory combination.
VVSP is invoked thusly:
vvsp scnfile [options]where scnfile is the name of the desired scenario file. By convention, the extension on scenario files is "scn". The options follow the scenario file argument on the command line and each begins with a minus sign, ’-’.
The currently implemented options include:
-isi delta_isi Add delta_isi to all ISIs. -dur delta_dur Add delta_dur to all durations. -font fontname Use fontname as default font. -bgc bgcolor Use bgcolor as default bg color. -pal palette Use palette as default color map. -sbg bg_cri Use bg_cri as a standing background image. -skipto label Start presentation from stimulus label. -prep frames Allow frames to prepare a stimulus. -spause Enable selective pauses. -mon Monitor only marked images. -stat Print synopsis and statistics. -bti Emit BTI style strobed codes. -show Draw and leave displayed the first stimulus. -noprompt Start and end program without prompting.
Here is a brief explanation of the use and effect of each option:
Any combination of options is permitted; if more than one is employed they can be supplied in any order.
When running conditional presentation scenarios (i.e. using the branching option in the scenario file), it is necessary to ensure proper cable connections between the stimulus equipment and the digitization equipment. The following connections are required:
After invoked, VVSP reads the scenario file and parses it into tokens, compiling and translating these into an internal, memory-resident format. When compilation is complete, the optional synopsis and statistics are printed. Next, the VGA screen is blanked to the solid background color (or, if the -sbg option is in use, the background image is drawn and displayed), and the template for the on-line control and monitoring information is drawn on the monochrome screen. At this point, VVSP is ready to begin stimulus presentation and so indicates at the bottom of the monochrome monitor with the message, "Press any key to begin stimulus presentation" (unless the -noprompt option has been given) One can also exit from VVSP at this stage by hitting ’Q’, as indicated by the functional options list on the left side of the monochrome monitor.
Once a key other than ’Q’ is pressed, VVSP enters the presentation phase. During this phase, only the keyboard actions in the functional options list (on the left of the monochrome monitor display) are recognized; any other keystrokes are ignored. As each stimulus is drawn, a synopsis of the stimulus is written on the monochrome monitor. A one second delay ensues before the first stimulus is displayed to allow time for the first stimulus to be drawn.
After the last stimulus has been presented, one can exit the program, re-run the same scenario, or re-run with a new scenario by entering the appropriate character from the keyboard as prompted on the monochrome monitor (exit will be automatic with the -noprompt option). Note that these paths can also be followed while paused during stimulus presentation. On exit, VVSP clears the VGA and monochromes screens.
Here follows a more detailed description of various aspects of the operation of VVSP.
During the presentation phase, the monochrome adapter is used to display information about the operation of VVSP and to indicate to the experimenter the control actions that can be taken. The screen is divided into five areas containing information about the scenario file, the invocation options, the currently available control actions, the current state of VVSP, and a scrolling synopsis of the stimuli recently and to be presented.
The top window of the monochrome screen contains the name of the scenario file currently in use on the left, while a running display of the current frame is shown on the right. The current frame display is updated only when drawing of stimuli is not possible. When an image that requires extensive processing is being drawn, the current frame display may temporarily retain the same number, but VVSP is internally maintaining an accurate frame count. If the -sbg option is in use, the name of the background "bg_cri" file is displayed in the middle of this window.
The right window on the monochrome monitor displays the command line options that were used when VVSP was invoked, and their arguments (if any).
During the presentation phase, VVSP is either paused or running, and the bottom window on the monochrome monitor displays this status information. Since there are three means to enter the paused state, there are actually four states that can be displayed: Running, Keyboard Pause, Scenario Pause, or Hardware Pause. The pause states are entered and exited by means of certain keys on the keyboard or by flipping a switch on the SPI, respectively (see "Control Options", below).
This window also contains prompts to the experimenter when a keyboard action must be taken to proceed. In particular, VVSP awaits a keyboard press prior to beginning the presentation of stimuli and prior to exiting to MS-DOS. In these cases, the current state window requests that the experimenter press a key on the keyboard to begin or exit.
The left window on the monochrome monitor contains a summary of the actions that can be taken at any particular time. Whenever a character is required from the keyboard to select the control action, the specific key is enclosed in parentheses, followed by the name of the action.
When the current state is running, one may enter either a Hardware Pause, Scenario Pause, or a Keyboard Pause state. If the pause is a result of the switch on the SPI, VVSP enters the Hard Pause state, which can only be exited and the Running state re-entered by changing the switch setting to "run". If the pause is a result of one having entered a capital ’P’ from the keyboard, one re-enters the Running state by entering a capital "C" (continue) from the keyboard. If the pause is a result of a pause scenario file option, one continues by hitting any key on the keyboard except capital N, R, or E. When in the Keyboard Pause or Scenario Pause state, these keys select options other than continuation. To restart presentation at the beginning of the scenario, one enters a capital "R"; to select and present a new scenario press a capital "N". The final option one can select when in these pause states is to exit VVSP by entering a capital ’E’. Capital letters were selected for the keyboard control characters so that inadvertent pressing of keys on the keyboard would be less likely to disrupt the operation of VVSP. Capital letters require the simultaneous depression of two keys on the keyboard, which is somewhat harder to achieve by dropping one’s coffee mug. Of course, dropping one’s coffee mug is not recommended in any case.
Whenever VVSP is about to terminate or to begin presentation of a scenario, the current state window requests that one press a key on the keyboard to continue. This allows the experimenter to synchronize VVSP to other equipment.
When VVSP is in the Running state, the frame count increments at the beginning of each frame and upcoming stimuli are drawn as memory areas in which the images are drawn (video frame buffers) become available. The center-most window on the monochrome monitor displays a running synopsis of the stimuli that have been drawn but not yet presented at the bottom of the window, the stimulus currently being displayed or last displayed on the intensified line of the window, and previous stimuli at the top of the window. When a new stimulus is presented, the contents of this window are scrolled upwards so that the next as-yet-unpresented stimulus or stimuli ("on board") becomes the current stimulus (the intensified line), and the already presented stimuli move upwards. When the duration of display of the current stimulus has elapsed, that drawing memory becomes available for drawing of another upcoming stimulus. When drawing of a stimulus is complete, the summary is written on the bottom line of the display, denoting that it is now "on board".
The synopsis includes the ordinal stimulus number, the ISI to the next stimulus, the duration of presentation of the image (both in units of frames, 16.66 msec), the emitted code, the number of frames that elapsed while the stimulus was drawn, the type type of the image, and the associated string. The type of the image is one of "txt", "cri", or "pgi", corresponding to basic image types of text, compressed raster image, and parameterized graphic image. The image type can also be "mon", indicating that the scenario file entry included a "mon=" option; in this case the string describing the stimulus is taken from the option itself, rather than from the associated string of the basic image. Additional characters indicate various options in the following manner. The appearance of an asterisk (*) between the drawing time and the type of image indicates that this stimulus is marked for a selective pause using the "esp" scenario file option. A period (.) in this location indicates that a "pause" scenario file option applies to this stimulus. If the space between the type of image and the associated string is an exclamation point (!), the basic image included the "nser" option in the scenario file. Finally, if the end of the line shows a plus sign (+), the scenario entry was continued on additional lines, and consists of more than one stimulus image. For more information on image types and scenario file options, see the section "Scenario Files", below.
The paused state can be entered either via the keyboard (a Keyboard Pause), via the scenario file pause option, or by way of the Pause/Run switch on the SPI (a Hardware Pause) as explained above under "Control Options". When paused, the frame count does not increment and VVSP waits for a control action to determine the course of processing. In the current implementation, no additional event code is emitted when the pause state is entered or exited.
Hardware pauses presume the use of an SPI in conjunction with VVSP. Hardware pauses are initiated by a low level on the game port input bit 7 so that if nothing is connected to the game port, hardware pauses are not possible and VVSP will respond only to keyboard characters, as the game port inputs float high.
The codes associated with stimuli in the scenario file are output via the DT2821 interface and are 16 bit, positive logic, unsigned integers. By convention, codes with bit 15 set are termed "metacodes", used to denote experimental control events rather than actual stimuli or subject responses. Since codes require a "strobe" signal to demarcate the time of occurrence and no such signal is available on the DT2821, bit 14 of the output of the DT2821 is used to generate a software strobe. Since this pre-empts the use of this bit for code representation and codes are, by convention, 16 bits, bit 15 is connected to bit 14 in most interfaces (such as the SPI), and thus only 32768 codes are possible, and half of these are reserved as metacodes. In addition, since the SPI can only display codes up to 8191, this number should be taken as the upper limit for stimulus codes. The code of zero (i.e. 0) is not valid; this fact is exploited to allow one to present stimuli without a concomitant code, if desired, by requesting a code of 0 in the scenario file. For more information on the use of codes, refer to the document "The IBM PC/AT Stimulus Presentation Interface". This format for event codes is the default, Event-Related Potential Laboratory standard. However, other invocation options may alter the code format as described under the option description (e.g. -bti causes a special code format to be employed that can be used by the BTI magnetometer).
Codes are emitted during the vertical blanking interval preceding the first frame of the display of a stimulus. Since a frame consists of a single vertical period during which all horizontal raster lines of the frame are drawn, taking 1/60 second (16.66 msec) to complete, the exact time of delivery of the image is somewhat difficult to define. For vertically "small" stimuli, the onset delay from code emission is about the fraction of the total screen (from the top to the stimulus) times 16.66 msec. For large or distributed stimuli, the onset delay is more ambiguous.
The manner in which the video system operates thus imposes a temporal quantization of frames on the ISIs and hence code intervals. This "frame quantization" also affects the duration of presentation of stimuli, since stimuli must appear for an integral number of frames. The situation is exacerbated by the fact that the phosphors used in the video monitor have an exponential decay characteristic which can take many 10s of msec to decay below the threshold of detectability. Hence, the use of long-persistence monitors is not recommended.
Errors that occur during the execution of VVSP are divided into two classes: those that occur during the reading and compilation of the scenario file, and those that occur during the presentation phase (execution of the memory-resident scenario and image information). The former are termed scenario compilation errors, while the latter are termed execution errors. All error messages are written to the monochrome screen and efforts have been made to ensure these messages can be read before the screen is cleared or re-written.
Errors that occur during opening, reading, parsing, and translating the scenario file generate a "routine trace" list of error messages, meaning that the inner-most nested routine in VVSP prints the cause of the error, and passes an error indication to the routine that called it, which then generates a new error and a message printed, and so on. Each message is meant to help explain the proximal cause and its sequence in the trace can help diagnose the problem. This approach results in a detailed indication of the nature of the error. While verbose, they are not too confusing since only the first error that is encountered generates an error message.
The fact that any compilation error is fatal and terminates VVSP has to do with the memory allocation system used by VVSP. While it can be annoying to have to iteratively refine a scenario file containing many errors, it results from a compromise that was needed to keep code size to a minimum.
Substantial checking is performed during the compilation process to ensure the integrity of the memory-resident commands for the presentation phase. For example, all the image files mentioned in the scenario file are opened and read during compilation, so the absence of any of these files is detected here. All stimulus memory is also allocated here, so those errors will cause termination during the compilation phase.
While many errors can be detected during compilation, others can arise during presentation when the memory-resident commands are executed. Timing errors can occur if drawing of images takes longer than the ISI, while certain graphics operations can also result in errors. To speed execution of graphics commands, specific error messages for the proximal cause of the error are not returned, only an indication that an error has occurred.
Execution errors are also fatal and cause termination of VVSP. Since these errors occur while the monochrome monitor has the control and status display on the screen, the monochrome screen is erased before the error message is written and VVSP terminates.
An Orchid ProDesigner II VGA adapter in the PC/AT is used to generate the video images that are displayed on the color monitor. While this adapter is widely supported by extra-mural software and can be operated in many modes using the BIOS graphics routines, VVSP employs its own VGA graphics routines both to increase speed of execution by limiting operation to one mode and to accomplish functions that are not generally available but needed for this application (e.g. the multiple paging and interrupt-driven timing). These routines operate the VGA in a manner similar to BIOS mode 2E (hex), with the following characteristics. The refresh rate is 60 Hz.
The display screen is divided into 480 raster lines of 640 horizontal pixels each. Since the electron beam scans from top to bottom, the native screen coordinate system ranges from 0 to 639 in the x direction (going from left to right), and from 0 to 479 in the y direction, y increasing downward on the screen. Unless coordinate translation is in effect, these screen coordinate units are used when specifying screen positions or extents. To speed execution, only a few routines implement clipping to the screen boundaries and since drawing beyond the boundaries can cause bad things to happen, one should strive to keep coordinates on the screen.
The VVSP graphics routines (as well as the related pgi file graphic commands, described below) employ the notion of a current coordinate. This can be considered an invisible cursor at a certain x, y screen position. Many pgi commands use the current coordinate as a reference point for the operation they perform. For example, the lineto command draws a line from the current coordinate to the coordinate specified in the arguments to the lineto command, with the endpoint becoming the current coordinate for the subsequent command(s). The current coordinate is also important for the scenario file options discussed under "Scenario Files", below.
In addition, coordinates or pixel extents are sometimes interpreted as relative to the current ccordinate, in which case the values are added to the current coordinate to arrive at the actual screen location. For example, the xoff and yoff scenario options are relative to the center of the screen, and if in the above example the pgi command had been rlineto, the line would have been drawn from the current coordinate to the current coordinate plus the argument values for the rlineto command.
All the pixels for an entire screen (640x480) are stored in a video frame buffer, and each pixel can take on values from 0 to 255 (inclusive). The value at each pixel, termed the pixel value or color value, is used to index into a table of red, green, and blue values which are used when the pixel is displayed. These color mapping tables are termed palettes, and allow dynamic selection of the colors displayed by an set of pixel values in the frame buffer. Since there are 256 possible values for each pixel, 256 colors can be displayed on the screen at a time. However, these 256 can be any of 262,000 colors when the VGA adapter is used. For more information on palettes, see Appendix 1.
When one specifies a color in a VVSP scenario file or in a pgi file, it represents the pixel value that will be employed. Hence, one must also know what palette is in use to unambiguously determine the color that will be displayed, although in most cases the default palette will suffice.
This section describes the algorithms used to draw stimuli, buffer the images for display, and time the ISIs and presentation durations.
Images are drawn in special memory areas, termed video frame buffers. The term "frame buffer" derives from the notion that the memory area contains all the pixel information needed to display an entire frame of video information. A video frame is one complete vertical scan on the video monitor; usually the frame rate is 60 Hz. Note that this is the origin of the "frame quantization" mentioned in the "Codes" subsection under "Operation", above. The frame buffers are special areas of memory physically located on the VGA adapter, and enjoy fast access, inter-buffer copying, and ability to be displayed as a set of pixels on the VGA monitor.
When operated at a resolution of 640 by 480 with 256 colors, the Orchid ProDesigner II supports three video frame buffers when 1 MByte of memory is installed. When a solid color background is employed, all three of these frame buffers can be used to draw stimuli since a solid color, blanked, background can be displayed without using a frame buffer between stimulus presentations. In this case, up to three stimulus images can be "on board", that is, drawn in the frame buffers prior to their time of display. However, if the -sbg option is in effect, one frame buffer is used to hold a copy of the background image that is displayed between stimuli, and hence only two frame buffers are available for drawing stimulus images.
The number of available frame buffers that can be used for pre-drawing stimuli affects the rate at which complex stimuli can be presented. The basic algorithm that is used by VVSP is to pre-draw as many stimuli as possible in the frame buffers, and then switch the display to the appropriate frame buffer when the starting frame for that stimulus arrives. After that stimulus has been displayed for the specified number of frames, the frame buffer for the image is freed so that another stimulus can be prepared. Hence, it is possible to rapidly present complex images as long as enough frame buffers are available to allow one to trade off the ISI with the drawing time for the images.
When a stimulus (consisting of one or more constituent images) is drawn, the area or areas of the frame buffer that were modified during the drawing process are entered into a list of "screen erase/replace rectangles" (serr). After the stimulus display duration has elapsed, these serr regions are either erased to the background color, or, if the -sbg option is in effect, replaced with the corresponding regions of the standing background. This technique is employed to reduce the amount of time required to "repair" altered areas; erasing or copying the entire screen is not necessary for most stimuli and would takes substantially longer.
In some applications, it is useful to not erase or replace certain subimages of the last stimulus drawn. These subimages can be so marked in the scenario file using the "nser" scenario file option, and are entered into a separate serr list. At first it might not seem to be necessary to store these areas. However, due to the buffering mechanism, the appropriate action to take for areas that are not to be erased or replaced is to copy them from the current stimulus frame buffer into the frame buffer(s) for stimulus images that are subsequently predrawn until all frame buffers include the "non-erased/replaced" regions". Hence, when a stimulus that includes "nser" regions is drawn, a list of those regions is retained and they are copied into all subsequent buffers prior to pre-drawing stimuli in them.
Using the "nser" scenario file option can be tricky because the serr regions are rectangular. In addition, if combinations of unerased/unreplaced and erased/replaced subimages are employed, one must ensure that they do not overlap, as the common region may or may not be treated appropriately depending on the sequence in which the images are drawn. Currently, the nser option is not properly implemented in VVSP.
As briefly mentioned when event codes were discussed (above), the nature of the video system imposes a "frame quantization", on all timing parameters. A "frame" is one vertical scan period of the display, and is usually takes 16.6666 msec. The vast majority of the 16.6666 msec elapses while the electron beam scans from the top of the screen to the bottom. However, remaining time in each cycle is used to reset the beam to the top of the screen in preparation for the next cycle. This period is termed the vertical blanking period, since the beam is shut off, or blanked, during this period. This is the period in which the frame buffer that is to be displayed during the next frame is selected. VVSP maintains an ordinal frame count, on which all timing of ISIs and durations is based.
One is often interested in determining the minimum ISIs and/or durations that can be employed when presenting stimuli. These parameters are determined by the drawing routines and the combinations of options (especially -sbg), and are directly related to the time required to draw the stimuli. In general, the number of separate images in a stimulus and their complexity determine the time that is required to draw an image. The scrolling synopsis on the monochrome monitor includes a field that reports the number of frames that were required to draw the stimulus image(s), and this information can be used, in conjunction with the details of the timing described here, to determine the minimum ISI and durations that can be attained. Note that the -show option can also be used to measure the time required to draw a particular stimulus. Usually, however, one empirically determines whether a particular set of stimuli in a given scenario can be presented by trying it. However, on occasion it is useful to understand the detailed operation of VVSP to design a strategy when a particular combination of stimuli in a scenario don’t work. Here is a brief description of the exact sequence of events that transpire during the running of VVSP.
When VVSP is used without the -sbg option, three frame buffers are available to hold stimulus images. An interrupt routine, a portion of the program that is invoked at the beginning of each vertical blanking period, maintains the frame count and controls the selection of the frame buffer that is currently displayed. While the interrupt routine is not executing, VVSP executes a loop, awaiting an empty frame buffer, drawing the next upcoming stimulus in it, and requesting that it be displayed (by the interrupt routine) at a particular frame count. In detail, here are the salient steps and the order in which they occur for the initialization routine, interrupt routine, and main display loop:
Note that the interrupt routine, which is called 60 times per second during the vertical blanking period, operates somewhat independently of the main display loop. The main loop supplies new stimulus images for the display queue, and the interrupt routine "consumes" them by displaying them and then freeing them at the appropriate frame counts.
An analysis of these algorithms reveals that the time available to draw a stimulus image begins when the n-1th previous stimulus finishes its display (n is the number of frame buffers available for predrawing stimuli, in this case three), and ends at the point when the stimulus being drawn must be displayed. This must hold for every stimulus in the scenario file, or a timing error will result, with termination of VVSP.
VVSP when invoked with the standing background option (-sbg) uses one frame buffer to hold the background image, leaving only two frame buffers available in which stimuli can be drawn. It also uses the interrupt routine to control the timing and selection of the displayed frame buffer. However, the details are different, as follows:
When the -sbg option is in effect, less time is available for drawing upcoming stimuli is available since one less frame buffer can be used to predraw stimuli. Otherwise, the same considerations apply as when VVSP is used without the -sbg option.
Scenario files specify the images that comprise stimuli as well as the corresponding codes, ISIs, and presentation durations. They are standard text files and can be generated with any text editor. Usually, however, one uses the SG program to automate the generation of scenario files. The resulting scenario files can be altered if needed using a text editor. For simple stimuli, such as text, all information needed to run VVSP can be contained in the scenario file. For other applications, one may need to generate images in separate files which are referred to in the scenario file. During the compilation phase all of these files will be read and placed in memory for use during the presentation phase.
Supplementary images can be "parameterized" as sequences of lines, points, polygons, etc, described in a text file. These files have a specific format as described below and are termed pgi files for parameterized graphic image.
It is also possible to employ files that contain a description of the actual sets of pixels to place in the frame buffer for the stimulus display. These are raster images, and are kept in a binary file. The raster information is compressed to decrease their size, and hence these files are termed cri files, for compressed raster image. Cri files form the mechanism used to import images from other software packages. Since these files cannot be edited with a text editor, the program GETVCRI is available to capture images on the VGA screen. GETVCRI retrieves the pixel values from the current VGA screen and encodes them into a compressed form, producing a cri file on the disk. The use of VVSP with the -show option is sufficient to display cri images. Since large cri files require large amounts of memory, one should strive to keep the size of these files as small as is possible given the stimulus requirements. That is, don’t include unnecessary border information when creating a cri file.
One can modify an image on a line in the scenario files by using certain options. Some options enable one to employ the same basic image but present it at different locations and/or different colors, thus conserving memory. Other options mark the stimulus in some way, such as enabling a selective pause or changing the string that is displayed int the scrolling synopsis of the controla and status display on the monochrome monitor. The remainder of this section describes the syntax and semantics of scenario file in detail.
Scenario files are line-oriented in the sense that all the basic information about a stimulus is contained on one line. The order of presentation of stimuli is the same as their sequence of description on lines in the scenario file (unless otherwise directed with the br= option). Since physical lines can become uncomfortably long when describing all the information about a stimulus, "virtual" lines are the unit of parsing, and can consist of one or more physical lines (for more information on physical and virtual lines, see the section "Lines and Arguments", below). In addition, one may wish to specify multiple images that should be presented as a single stimulus. Since these additional images do not require any information about the ISI, duration of presentation, or codes, these additional virtual lines are termed continuation lines, while the first virtual line describing a stimulus is termed the basic line, and the image described the basic image. A stimulus then is described by a basic virtual line and one or more continuation virtual lines. A line is continued if the last valid option on the line is a plus sign, ’+’.
Each virtual line of input is parsed into arguments or tokens, which are sequences of contiguous non-white characters separated by spaces or tabs (for more information on tokens and arguments, see the section Lines and Arguments below). A stimulus has four mandatory arguments on the basic line: an integral ISI, a presentation duration, an associated code, and the basic image. These arguments must appear in this order as the first four tokens on any basic line. Additional arguments on the line prior to any comments are options that in some way modify the drawing of the stimulus or its display. Continuation lines have a similar structure, except that the ISI, duration, and code arguments are not needed and should not be present; hence continuation lines begin with an image and the remainder of the functional arguments represent options.
To improve the readability of scenario files one can employ comments, indentation, and additional spacing between arguments if desired; this does not affect the parsing of arguments and is strongly encouraged.
Unfortunately, the need to express many types of strings and information as arguments on a virtual line of input creates a welter of special cases and rules that are used in parsing a virtual line. For example, it is reasonable to want to express the words hello world as a single argument. This is handled by enclosing arguments with embedded spaces or tabs with double quotes, thusly: "hello world". Now, however, a special mechanism must be introduced to allow the double quote character to appear in strings. The following describes the rules employed in the parsing of a virtual line.
A virtual line consists of arguments distinguished by separators, and is terminated by an unescaped newline. Thus, a virtual line can continue on more than one physical input line by the presence of an escape character ’\’ at the end of the line. Separators are spaces, tabs, or escaped newlines, that are not part of a quoted string or quoted substring.
The double quote character ’"’ introduces a quoted string
or quoted substring. Quoted strings or substrings can contain any characters,
including spaces and tabs, and are terminated by another double quote.
A quoted string or substring can contain a double quote character if it
is escaped (i.e. \"). If the quoted string is not surrounded by separators,
it is considered a "quoted substring" that is concatenated with the apposed
argument(s). For example, the input:
text="Hello World"
is parsed as a single argument comprised of the string
text=Hello World
If the quoted string is surrounded by separators, it constitutes a single
argument, and in this case is possible to specify a single null string
argument using a sequence consisting of an even number of contiguous double
quotes. If a quoted substring is null, it is ignored (the expected result
of the concatenation with the apposed argument(s)). A newline can be placed
in a quoted string by typing ’\n’, and, except when a ’\’ occurs at the end of
a physical line, a ’\’ is placed literally into the string. There are still
a few special situations that are not handled correctly, one being a null
string at the end of a continued "virtual" line.
Currently the total number of characters in the sum of all argument strings is limited to 1024, contained in a maximum of 256 arguments.
All characters following a ’#’ on a line are ignored as comments.
Each basic line for a stimulus must have the four mandatory arguments to describe the interstimulus interval to the next stimulus, the duration of presentation, the code to emit, and the basic stimulus itself beginning the line. Additional details regarding each of these mandatory arguments are detailed in the next four subsections.
The first argument on a basic line is the interstimulus interval from the beginning of the display of the stimulus to the beginning of the display of the next stimulus. This interval must not be less than the duration of display, and can be specified as either a positive integer representing a number of milliseconds, or the letter ’f’ or ’F’ immediately followed (no space) by a positive integral number of frames. Due to the "frame quantization" effect (described in more detail in the section "Codes" under "Operation" above), ISIs specified as a number of milliseconds will be rounded to an integral number of frames. Note that all the ISIs in a scenario file can be biased by a constant number of milliseconds (also rounded to units of frames) using the -i option. If, for any reason, the number of frames would be less than one, it is forced to one with a warning during the parsing of the scenario file.
The second argument on a basic line is the duration of presentation of the stimulus in milliseconds. It too is quantized in units of frames and can be specified as a number of milliseconds which are rounded and converted to a number of frames, or the number of frames directly, by immediately preceding the positive integer with the character ’f’ or ’F’. Again, as with the ISI, the durations of all stimuli in a scenario file can be biased by a specified number of milliseconds using the -d option on the invocation line. If, for any reason, the duration of presentation would be less than one frame, it is forced to one frame. Additionally, if it would exceed the associated ISI, it is forced to equal the ISI. In both cases, a warning is issued during compilation.
The third argument on a basic line of a scenario entry is the code that will be emitted during the vertical blanking period prior to the start of the first frame of display of the stimulus. The use of codes is explained extensively in the document "The IBM PC/AT Stimulus Presentation Interface", while their temporal quantization is briefly discussed in the subsection "Codes" under "Operation" above. Any integer is allowed and no checking is performed to verify the validity of a code. If the code is zero (0) or simply a minus sign (-), no code will be emitted when the stimulus is presented.
The fourth argument
on a basic line is the basic stimulus, which is also termed a stimulus
image, as the same syntax is used to specify additional images on continuation
lines. A stimulus image specifies one of a number of major classes of images
as well as the specific image itself. Currently, the classes of images are
text, cri, and pgi, and each stimulus image argument has the form
class=string
where class is one of text, cri, or pgi. Note that no separators can intervene
on either side of the ’=’; but the string element can contain any characters
by using the quoted string facility of the parsing routines (see "Lines
and Arguments", above) if necessary. This string is termed the associated
string of a stimulus image. Associated strings are either text strings to
be displayed (for the text class) or filenames (for pgi and cri). These
strings are stored in memory and entered into a hash table, both to speed
compilation as well as to enable different stimulus images to share the
data corresponding to the associated string, be it the string itself or
the contents of the file.
The class keyword (e.g. text, cri, pgi) is recognized regardless of whether it is entered in upper case, lower case, or some combination. However, case sensitivity is retained for the associated string, so that filenames and text strings can contain any character.
Here are
a few examples of syntactically valid stimulus image specifications:
text=coffee
text="Hello World, here I come!"
cri=monalisa.cri
pgi=pentagon.pgi
Note the use of the quoted string in the second example to enable the inclusion
of spaces in the text string.
Arguments following the stimulus image specification on a line in the scenario file specify options that modify the basic image or some aspect of its presentation. These options allow one to employ the same image while, for example, drawing it at different locations on the screen, or in a different color. Note that when an argument is encountered that begins with a ’#’, the rest of the line is considered a comment. Hence, option arguments must precede any comments. Except for the continuation option, the order of appearance of the option arguments is irrelevant, as long as they follow the stimulus image specification and precede comments (if any) on the line. The option keywords (e.g. xoff, yoff, esp, color, lblo) are not case sensitive, as they are converted to lower case prior to use. That is, option keywords will be recognized whether they are entered in upper case, lower case, or some combination. The data portion (if any) for an option specification is not converted to lower case, and hence retains case sensitivity, allowing both upper and lower case characters to be present.
Most of the scenario file options alter
a parameter or action that will otherwise have a default value; not all
of the VGA plotting library state parameters can be altered using scenario
file options. For special requirements, one may need to employ pgi files,
which can alter the entire plotting environment. Here is a list of some
of the salient parameters that can be preset using scenario file options
and their associated default values.
Parameter Default Value Current Coordinate x = 319, y = 239 (center) Foreground color 1 (White) Background color 0 (Black) Font Roman.16.14 (or option) Label Origin 5 (Centered, vertically and horizontally) Palette default (or option) Drawing Mode DMSETNote that the default font and palette can be specified by the invocation options -font and -pal, in which case they take on the values supplied prior to the drawing of each stimulus image.
Options are most useful for basic image types of text or cri, where re-positioning the image or selecting a color is all that is usually required to draw the desired image. Pgi image types entail a file of graphics commands that can be written so that they either do or do not override options from the scenario file. The specific experimental requirements must be considered when deciding whether a scenario file option should control a parameter or whether it should be selected in the pgi file itself.
Each scenario file option and its syntax is described below.
These two options allow one to alter the location
on the screen where the basic image will be drawn, assuming the image specification
allows this possibility. The xoff and yoff keywords specify an x offset
and y offset respectively from the center of the screen that will become
the starting location for drawing the stimulus image. None, one or both
of these positioning options can appear in any order, and have the form:
xoff=nnnn
where nnnn is an integer that will be added to the corresponding coordinate
for the center of the screen prior to drawing the stimulus image. Note that
xoff and yoff options imply a relative move, and hence nnnn can be positive
or negative. The value should be in units of screen coordinates, and should
not result in the current coordinate being off the screen.
One
can alter the current foreground color that is selected prior to drawing
the stimulus image by including a line of the form:
color=nnwhere nn is an integer between 0 and 255 (inclusive). These color values are used to index into the mapping palette to derive the actual color that is displayed, so this option interacts with the palette that is currently in use. Appendix 1 lists the color values and the associated display color for the default VGA palette.
The label origin, which determines
the position of text relative to the current coordinate, can be modified
by including the option:
lblo=nnwhere nn is an integer specifying the new label origin (see Appendix 2 for a description of the various label origins).
While one can
specify a default font for text images or pgi label commands, it is also
possible to dynamically and temporarily select a different font which will
be used to draw text. The current font, like other options, is reset to
its default value prior to drawing each stimulus image. One selects a font
by an argument of the form:
font=filenamewhere filename is the MS-DOS style file name for the desired raster font.
Fonts are not stored in memory during the compilation phase of VVSP in the current implementation. Hence, the inability to open the specified font file during stimulus presentation or the specified font file having the wrong format results in an execution error.
It is often
useful to specify the string that is displayed in the scrolling synopsis
window on the Control and Status display on the monochrome monitor, especially
when a stimulus is continued on additional lines and the associated string
for the basic image is not sufficiently specific. This can be accomplished
by including an optional argument of the form
mon="monitor message"where the string is the message one wishes displayed in the scrolling synopsis during online monitoring of the presentation phase.
This option interacts with the -mon invocation option (see above).
It is often useful to allow stimulus presentation to be paused only after specified stimuli in the scenario. This is accomplished by including the argument esp in the options for those stimuli in the scenario file. Since pauses are normally allowed between any stimuli, one must employ the -spause option during the invocation of VVSP to utilize this facility. Since an entire stimulus may consist of multiple images specified using continuation lines but all of these comprise the stimulus, the appearance of the esp argument on either the basic line or any associated continuation lines will mark that stimulus as one after which pauses should be recognized.
In some cases, one may wish to automatically enter the paused state after certain stimuli have been presented, perhaps to allow the experimenter to initiate the display of a stimulus or sequence of stimuli. This can be accomplished by including the word pause on the line (anywhere after the mandatory arguments) of the scenario file. After that stimulus is displayed, VVSP will enter the Scenario Pause state without any operator intervention. As described above, one can continue by pressing any key on the keyboard except N, R, or E, which select a new scenario, a restart with the same scenario, or immediate termination of VVSP. As with the esp option, the appearance of the esp argument on either the basic line or any associated continuation lines will mark that stimulus as one after which the Scenario Pause state should be entered.
Normally VVSP maintains a list of regions in frame buffer(s) in which drawing occurs containing the rectangular regions that need to be erased to the background color or copied from the background screen (if the -sbg option is employed) after the stimulus has finished display. For some applications, especially animation and displays that require changes in a standing background, it is useful to leave a subimage or entire image on the display until arrangements are made to remove it, while intervening stimuli are displayed upon these "unerased" regions. This is accomplished by including the option nser on all lines (anywhere after the mandatory arguments) specifying subimages which should not be erased or replaced for each stimulus. These "unerased/unreplaced" are also kept in a list so that they can be used appropriately. Refer to the section entitled "Display, Timing, and Buffering Algorithms", above, for more information on these erase/replace rectangle regions and the details of their application.
br="1040 stim1" (branch on receipt of response code 1040 to stimulus
labeled "stim1", and keep going from there)
br="256 stim2 2" (branch on receipt of response code 256 to stimulus
labeled "stim2", display 2 stimuli, then return)
(NOTE: in this section the terms SOA and ISI are used correctly)
This is the option that controls the branching behavior of the program, allowing the experimenter to alter the order of stimulus presentation depending on the subject’s response.
There are two forms of the option. The short form specifies a response code and a stimulus label (see the label option): if the response is received, presentation diverts to the labeled stimulus and continues from there. The long form includes a count: if the response is received, presentation diverts to the labeled stimulus, ’count’ number of stimuli are presented from that location, and presentation returns back to where it left off.
The SOA and duration for the stimulus still apply. If a branch takes effect, the SOA will dictate the time between the start of the stimulus and start of the stimulus being branched to. Responses are accepted only during the duration of the stimulus (and by default not all of the duration, an explanation about this follows) and are ignored and discarded during the ISI. If a specified response is not received "in time", the branch condition will be ignored and the next stimulus in the scenario file will be presented when the SOA has elapsed. "In time" requires explaining: by default STIMPRES stops accepting responses 100 ms before the end of the duration to allow itself time to prepare the next stimulus. This 100 ms can be adjusted up or down with the -prep invocation option. You may wish to use the -prep option: a) if the ISIs on branch stimuli are sufficiently large to allow enough time for preparing the stimuli that follow, the 100 ms can be reduced to 0 (-prep -100) to allow the acceptance of responses during the entire duration; or b) if the ISIs on branch stimuli are small or 0, the 100 ms can be adjusted up or down, trading between time needed to prepare the stimuli that follow and time spent accepting responses.
This option can be included multiple times for a single stimulus, to specify different branches for different responses. The first matching response received will take priority, and the others will be ignored.
The long form does not nest. That is, if a response initiates a branch to another location in the scenario file, and one of the ’count’ stimuli also has a br= option for which a response initiates another branch, control will not return to the original location - the latter branch will override the settings of the former.
NOTE: due to an apparent stimpres bug, when using the long form such that the ’count’ stimuli are placed at the physical end of the scenario file (as one might do when providing the subject repeated feedback to responses), use the end option on the stimulus preceding these (i.e. on the last intended stimulus of the run) to prevent stimpres crashing during the run.
Any pending responses are cleared at the start of each stimulus, to keep the frame of reference on the current stimulus.
wfron (wait for response, leaving stimulus on screen) wfroff (wait for response, taking stimulus off screen)
These options state that execution should halt after the current stimulus, waiting for a response. Wfron specifies that the stimulus is to be left on the screen while waiting; wfroff specifies the stimulus should be taken off the screen at the end of its duration. The ISI is somewhat preserved, in that the time from the eventual receipt of the response to the start of the next stimulus is equal to the ISI minus the duration.
end
This option specifies to end the run immediately after the stimulus has been presented. This is useful when there are stimuli at the end of the scenario file that have been used in br= branches, but which should not be displayed as the last stimuli in the run: the run can be ended at the stimulus preceding these by specifying it with the end option.
NOTE: due to an apparent stimpres bug consider this option mandatory on the last stimulus of the run when there are ’branch’ stimuli past this stimulus at the end of the scenario file; failure to use it may result in stimpres crashing during the run.
label=labelname
This option works in conjunction with br= option, and the -skipto invocation option. It enables the experimenter to label stimuli intended as targets for branching to. Labels must be one word (i.e. no blanks).
To enable one to specify multiple images as comprising a stimulus, the ’+’ (plus sign) alone as the last option argument on a line in a scenario file indicates that an additional image specification and option(s) continue on the next line in the scenario file. Note that this option must appear at a particular position in the options for a stimulus image, that being the last valid option argument (prior to any possible comments). A stimulus can entail as many stimulus images as necessary by using additional continuation lines.
A continuation line, unlike a basic line, does not include ISI, duration, or code arguments. The first argument on the line must be a stimulus image specification (e.g. text, cri, or pgi), and additional arguments before (optional) comments are interpreted as options that modify that stimulus image. Hence, continuation lines have the same structure as a basic line starting at the stimulus image specification.
Note that there is not a one-to-one correspondence between graphic entities that are included in a stimulus and the number of lines in the scenario file that specify that stimulus, since pgi or cri files can specify any number of distinct images.
A stimulus image specification currently can be text, cri, or pgi, selecting a text string, a compressed raster image, or a parameterized graphics image file as the type of stimulus image (described above). Each of these has different characteristics that require different treatments during presentation as well as different methods of image preparation.
The text type of stimulus image is the simplest; the associated string itself is used as text that is displayed. It is displayed using the default parameters (i.e. middle of the screen, in white) as modified by any options on the line in the scenario file. Using the format described in Lines and Arguments above, it is possible to employ arbitrary strings containing any characters.
Cri (compressed raster image) files contain an encoded representation of a rectangular region of pixels. The size of the rectangular region (in units of pixels) for a cri file is contained in a header that is prepended to each cri file. A number of programs are available to convert images from other software in other forms to cri format for use with VVSP.
Generally, cri files can be decoded and drawn on the screen at any position, so long as it would not require drawing beyond screen boundaries. When reconstructed and drawn on the VGA screen by VVSP, the center of the rectangular region corresponds to the current coordinate. Hence, without any xoff or yoff options, they will be placed in the center of the screen. When reconstructed, the pixel values in the cri file replace those on the screen.
Pgi (parameterized graphics image) files form a means of specifying images by means of primitive operations that are executed by VVSP to draw the image. Pgi files are most useful for representing low information content images that can be easily parameterized (e.g. in terms of lines, polygons, rectangles, and text), and have modest memory requirements.
Pgi files inherit all the scenario line options when they are executed, and the pgi file can employ this information or not, to achieve the desired result. For detailed information on writing pgi files, see the section entitled "Pgi Files".
Pgi (parameterized graphic image) files are text files containing sequences of graphics commands. They can be generated with any text editor, and can encode arbitrarily complex images, given sufficient image design and preparation. To effectively author pgi files, one should be familiar with the section entitled "VGA Graphics Environment", above, as well as this section.
Pgi files are line-oriented and are similar to scenario files in the way commands and arguments are parsed on each virtual line of input (see "Lines and Arguments" above, under "Scenario Files"). Briefly, blank lines and lines beginning with a ’#’ are ignored, and tokens on a line are separated by spaces, tabs, or escaped newlines.
VVSP compiles pgi files into an internal sequence of VGA graphics primitives. During the presentation phase, these commands are executed in the same sequence as they appeared in the pgi file. Almost all operations in the VGA plotting library are available to authors of pgi files except for selection of the drawing and display pages, which are controlled by VVSP to implement the timing and buffering mechanism.
The execution of pgi commands takes place in an environment of globally available state information that controls the color, line type, fill pattern, etc used by drawing commands. The environment consists of parameters in the following table, along with their initial value.
Parameter Default Value Current Coordinate x = 319, y = 239 Foreground Color WHITE (1) Background Color BLACK (0) Label Origin Center (5) Drawing Mode SET (0) Font Roman.16.14 (Inv. Option) Palette Appendix 1 (Inv. Option) Line Type Solid (0xFFFF) Polygon Fill Pattern Solid (0) In Polygon Definition? NoThose parameters marked (inv. Option) can have their default values selected by invocation options on the VVSP command line.
Before a pgi file that is specified in a line of a scenario file is executed, the plotting environment is set as indicated in the above table. Then, any associated options in the scenario file are executed, and can alter the font, foreground color, or current location. Then, execution of the pgi file begins. If, during the execution of a pgi file another pgi file is invoked (using the subimage command), the entire plotting environment is copied into a new area and becomes the plotting environment for the execution of the nested pgi commands. Hence, nested pgi files inherit the plotting environment from their callers. However, when execution of the nested pgi file is complete, the new environment is discarded and the caller retains the state of its plotting environment before the call. Thus, a type of first-in last-out stack of plotting environments is maintained by VVSP during the execution of PGI files.
The one state variable that is not kept in the stacked plotting environments and is thus "global" between nested executions of pgi files is the polygon definition flag, and the associated polygon definition. Since polygon processing requires substantial memory, only one polygon can be defined and held at a time. So, if one pgi file defines a polygon and then calls another pgi file that defines another polygon, when execution resumes in the calling pgi file the original polygon definition will have been replaced with the called file’s definition. This is not necessarily a disadvantage, since it allows one to define polygons in subimage pgi files, and invoke them to define a polygon which can be subsequently filled or outlined.
The first token on every line in a pgi file is termed the command, while subsequent tokens (prior to one beginning with ’#’) comprise the arguments to the command, if any. Additional arguments are ignored, if present. The case of the command token is not considered in recognizing the command; the entire first argument is always converted to lower case.
Some commands (e.g. lineto and moveto) have relative forms, in which the argument values are added to the current coordinate in order to arrive at the actual destination. For these commands, the relative form has the same name as the absolute form with an ’r’ prefixed to the name. In the following descriptions, the command name is set in boldface.
A number of commands set a parameter in the current plotting environment rather than actually cause any drawing on the screen. These commands take a single integer argument, and do not change the current coordinate. Different drawing commands employ different combinations of these parameters and their current values at the time they are executed. See the section entitled "Pgi Plotting Environment", above, for more details.
The setfgcolor command sets the current foreground color to pixelvalue, a number between 0 and 15, inclusive. Many commands use the foreground color as the value to which pixels are set during execution. The pixel values are used as indices into the current palette to obtain the actual color that is displayed on the screen. Appendix 1 has a list of the default palette mapping.
The setbgcolor is similar to the setfgcolor command, except that the current background color is set to pixelvalue.
The integer mask is used as a 16 bit mask which is used by the lineto command to create dotted, dashed, and other types of lines. The mask argument can be a decimal number, an octal number (the first digit should be ’0’), or a hexadecimal number (the hex value should be preceded by ’0x’ or 0X’).
The drawing mode is a state variable that indicates the way a pixel value should alter current values in the frame buffer when drawing occurs for certain commands. The valid values for drawmode are
Note that the exclusive or function is invertible; repeating a drawing operation on the frame when the drawing mode is 24 restores the pixel values to the state thay had before the first drawing operation. Note also that not all drawing mode are supported by all versions of the program, although set (8) and exclusive or (24) must be.
One selects the fill pattern for the fillpgon command using selectfp, where fillpatternindex is a small integer corresponding to the number of the desired fill pattern. The currently available fill pattern indices and the associated patterns can be viewed using the SHOWVFPS program. A number out of range is brought into range by taking the remainder of the supplied argument after dividing it by the number of fill patterns.
The current label origin is selected using this command, where labelorigin is one of the label origin reference locations that are specified in Appendix 2. The label origin is used only by the label command, and controls the relative location of text that is drawn with respect to the current coordinate.
The lineto command draws a line from the current coordinate to the xc and yc coordinate location using the current foreground color, line type, and drawing mode. The current coordinate becomes the end point of the line.
The moveto command only moves the current coordinate to the location specified in xc and yc.
The orect draws the outline of a rectangle with a width of nxpix and a height of nypix, with the current coordinate located at the upper left corner of the screen. Both nxpix and nypix should be positive integers, and the coordinates of all four corners of the rectangle should be on the screen. The current coordinate is unchanged.
The frect is similar to the orect command, except that the entire rectangular area is filled with the current foreground color. Note that only solid fills can be obtained with this command; rectangular regions with arbitrary fills should be implemented using the polygon commands. The current coordinate is unchanged.
One can read a cri file and reconstruct it on the screen using this command. Crifile is the name of the file containing the compressed raster image. If it is a monochrome cri, the current foreground color is used to set displayed pixels; color cri files contain the pixel values for all points on the screen. See "Cri" under "Stimulus Image Types" for scenario files for more information. If the specified file cannot be opened or it is not a valid cri file, an execution error is generated. The current coordinate is not altered by the execution of a dispcri command.
The label command places the argument string on the screen using the current font, foreground color, and label origin. The current coordinate becomes the reference point for the label origin. Note that double quotes (") can be used to represent strings containing separators. The current coordinate is not affected by the label command.
The named font (fontfile) becomes the current font for allsubsequent label commands if the font command is successful. An execution error will occur if the named file is not a valid font or does not exist. The current coordinate is not changed by the font command.
One can effectively employ subroutines in pgi files by using the subimage command. The pgifile is opened and used as the source of commands until the end of the file is reached, at which time reading of the current pgi file continues. The called pgi file inherits the current plotting environment of the caller, including font, foreground color, fill pattern, current coordinate, etc (see "Pgi Plotting Environment", above), but the caller’s environment remains unaltered across the call; thus, the current coordinate remains the same.
Pgi files can be nested to any level desired as long as sufficient memory space is available. The use of subimages can greatly reduce the memory requirements for stimuli, especially when images are constructed using many common elements.
If the named file cannot be read or an error occurs during its execution, an execution error occurs in the caller.
The VGA library and VVSP provide a simple polygon system that can be used in pgi files. Only one polygon can be defined at a time, and definitions are not stacked in the plotting environment (see "Pgi Plotting Environment", above). However, a polygon can consist of up to 64 subpolygons with a total of 1024 vertices in all. A polygon must first be defined using startpgon, lineto, moveto, and finally a endpgon command(s). It can then be filled with a fill pattern, or outlined using the current line type, using the current foreground color. Here follows a detailed description of the polygon-related commands:
The start polygon definition command does not require any arguments, and places the VGA plotting routines in the "polygon in definition" state. When the startpgon command is executed, the current coordinate becomes the first vertex, and subsequent lineto commands do not cause any drawing, but rather add the coordinates as another vertex for the sub-polygon. It is termed a sub-polygon, because if a moveto is encountered in the sequence of lineto commands, the current sub-polygon is closed, and a new sub-polygon definition begun, using the coordinates of the moveto command as the first vertex of the new sub-polygon. A sub-polygon must be closed, and this is enforced by assuming the last coordinate in each definition joins with the first. Polygon definition ends when the endpgon command is executed, thus taking VVSP and the VGA plotting routines out of the "polygon in definition" state, with the single defined polygon composed of all the sub-polygons that were defined. After the endpgon command, the current coordinate is as it was before the startpgon command.
The coordinates used in the lineto and moveto commands that are encountered while a polygon definition is in progress need not be valid screen coordinates, since the vertices will be translated by the arguments to subsequent outlinepgon or fillpgon commands. When drawn, however, all the vertices of the polygon should lie on the screen. The coordinates in a polygon definition thus form a sort of relative displacements from the reference point supplied when the polygon is drawn.
Note that if a sub-polygon definition consists of less than 3 vertices, the entire sub-polygon is rejected, and it is permissible to define polygons consisting of only one sub-polygon. Remember, polygon definitions and status are not stacked with the plotting environment.
Once a polygon has been defined, it can be outlined using the current line type and foreground color using the outlinepgon command. The arguments rx and ry form a reference location whose coordinates are added to those of each vertex in the polygon before the outline is drawn. In this way, one can draw the same polygon at different locations on the screen without repeating the definition every time. If the relative form of the command is invoked, the reference location is formed by adding rx and ry to the current coordinate, giving additional flexibility.
Filling a polygon works much like the outlinepgon command, except that the interior of the polygon is filled with the current fill pattern. Filling and outlining a polygon are two separate operations, one can have an outlined but unfilled polygon, a filled but un-outlined polygon, or a filled and outlined polygon.
When filling is performed, overlapping and/or enclosed subpolygons are filled so that areas are alternately filled. For example, if the polygon definition consists of three concentric triangles, the region between the outer and middle triangles will be filled as will the inner triangle, whereas the region between the inner triangle and the middle triangle will remain unfilled.
Appendix 1: Default VGA Color-mapping Palette
Color values specified in the various types of images are not bound to particular colors on the VGA screen, but use a color mapping table, or palette to determine the actual displayed color for a given pixel value. The pixel values on the VGA can range from 0 to 255 (inclusive), and thus 256 different colors can be displayed on the screen at a time. The 256 displayed colors can be selected from 262,144 possible colors; this mapping information comprises a palette.
Unless a different palette is specified on the invocation
line of VVSP, the default palette is used. To assist in selecting common
colors from the default palette, the first 16 colors are listed here.
VGA Default Palette
Pixel Value Description
0 Black (in vvsp)
1 White
2 Red
3 Orange
4 Pumpkin
5 Sienna
6 Yellow
7 Chartruese
8 Green
9 Sky Blue
10 Blue
11 Royal Blue
12 Violet
13 Purple
14 Lavender
15 Fuschia
16 Black (in stimpres)
Appendix 2: Label Origins
The label origin points represent
positions on an imaginary box in which the text will be drawn. Label origins
are provided which specify vertical labeling as well as horizontal labeling.
Here is an example of the label origins for the string "H E L L O".
Horizontal label origins:
13.......16.......19
. .
. 3_____6_____9 .
12 2|H E L L O|8 18
. 1-----4-----7 .
. .
11.......14.......17
Vertical label origins:
33....36.....39
. 26 .
. 23_29 .
. |H| .
. | | .
. |E| .
. | | .
32 22L28 38
. | | .
. |L| .
. | | .
. |O| .
. 21-27 .
. 24 .
31.....34....37
Label origins 5, 15, 25, and 35 would all sit directly on the first L
in "H E L L O". Label origins 11 through 19 and 31 through 39 add extra
space equal to one half a character width at the current text size. The
default label origin is 5, the center of the box.