stimul.exe - open source video stimulator for visual elctrophysiology
=====================================================================

Copyright: Bela Torok, GNU GPL license -> www.gnu.org


Features:
=========
Stimulus type:  luminance and pattern stimuli

Pattern types:	checkerboard, vertical and horizontal bars, windmill and dartboard

Stimulation mode: reversal and onset

Synchronisation occures during vertical retrace

Synchronisation of external devices: TTL-compatible synch out signal generated on the parallel (printer) port

Vertical refresh rate: programmable using the vbehz utility (works only with VBE 3.0 compatible VGA cards)

Remote control over RS232 (Com1 / 9600 Baud, 8 bit, no parity, 1 stop bit, CTS/RTS protocol) 


System requirements:
====================
PC with PCI or AGP slot
Operating system: DOS (tested with DOS V6.2). 
Only a minimal operating system is needed, e.g.: a bootdisk from www.bootdisk.com.
VGA card with VESA BIOS 3.0 VBE 3.0 or higher (required for programmable vertical 
refresh rate). 
The program was tested with different versions of Nvidia TNT2, Geoforce2 grapic cards.

Additional information about VBE 3.0 can be found on www.vesa.org/vbe3.pdf

Installation:
=============
1. Unzip files to a folder, e.g., C:\stimul
2. Add c:\stimul to path (in Autoexec.bat)

To start program type: stimul.
If the program is remote controlled by an other computer insert c:\stimul\stimul
Autoexec.bat


Compilation:
============
A compiled version of the program is included in the file stimul.zip. 
Recompiling the files is not necessary.

This program was developed using the open source OpenWatcom C-Compiler (www.openwatcom.org).

The program can also be compiled with the Microsoft C-Compiler (7.0) for DOS, however 
for some reason it is unstable. (The program crashes after receiving several commands
over the RS232 interface.) Since the code generated by the OpenWatcom compiler is stable,
and much faster than the Microsoft version, I don't invest any energy to make it stable.
Since the 32 bit protected mode version of the program is slower than the 16 bit code
the "official" stable version is the 16 bit code.

At the time of this writing (February 2003) the 32 bit mode vesa driver was not fully functional.
The function setVBEPaletteData() does not work properly.

To compile the program for 16 bit mode with the OpenWatcom compiler:
1. jump into the subdirectory where the source files are stored
2. type "watcom"
the name of the executable is stimul.exe

To compile the program for 32 bit protected mode with the OpenWatcom compiler:
1. jump into the subdirectory where the source files are stored
2. type "watcom32"
the name of the executable is stimul.exe
Tu start the program in 32 bit protected mode type "dos4gw stimul"

To compile the program with the OpenWatcom compiler:
1. jump into the subdirectory where the source files are stored
2. type "nmake stimul"
the name of the executable is stimul.exe


Cable for remote control (RS232):
=================================
DB9 female				DB9 female
Pin No.					Pin No.
1--4					1--4
6--8------------------------------------7
7---------------------------------------6--8
2---------------------------------------3
3---------------------------------------2
5---------------------------------------5

Commands:
=========
Command line options: stimul -h will list the options

Keyboard commands:    
      pressing the + key will increase the fixation point size
                   - key decrease the fixation point size
                   D key disables fixation point
                   E enables the fixation point
                   R change fixation point color to red
                   G change fixation point color to green
                   B change fixation point color to blue
                   C change fixation point color to cyan
                   M change fixation point color to magenta
                   Y change fixation point color to yellow
                   W change fixation point color to white
            <Escape> exits program

Remote control (over Com1):    
===========================
protocol: command arg<term> ,e.g., pattern 5<term>
command -> the name of the command
arg     -> an integer number
<term>  -> is the terminator character CR or LF (carriage return or line feed)

Supported commands:
pattern type [size] [disparity] [RdsDotSize]
            type:      0 Luminance    (white flashes)
                       1 Checkerboard (default)
                       2 Vertical bars, 3 Horizontal bars
                       4 Windmill, 5 Windmill (full screen)
                       6 Dartboard, 7 Dartboard (full screen)
                       8 Snellen E right
                       9 Snellen E left
                       10 Snellen E up
                       11 Snellen E down
                       64 Random-dot stereogram -> Checkerboard
                       65 Random-dot stereogram -> Vertical bars
                       66 Random-dot stereogram -> Horizontal bars
                       67 Random-dot stereogram -> Snellen E right
                       68 Random-dot stereogram -> Snellen E left
                       69 Random-dot stereogram -> Snellen E up
                       70 Random-dot stereogram -> Snellen E down
                       71 Random-dot stereogram -> Square (same size like Snellen E)
                       128 Sinusoidal grating -> Vertical bars
                       129 Sinusoidal grating -> Horizontal bars
                       130 Sinusoidal grating -> Checkerboard
                       131 Sinusoidal grating -> Campbell and Robson chart

            size:      n -> pixels has to befined for checkerboard, and bar patterns
                       (default = 60)
                       For random dot stereogram -> size: number of RdsDotSize

            disparity: disparity of the random-dot stereogram (in pixels)

            RdsDotSize: Random-dot stereogram dot size (in pixels)

mode n               0 = reversal (default), 1 = pattern onset/offset

timing period onset       
           period:   time of the stimulation
                     1/stimulation frequency in No. of frames, default = 100

           onset:    width of the pattern onset in frames, default = 10
                     (has no effect during pattern reversal)

videoresolution x y
           x:        horizontal resolution in pixels (default = 1024)
           y:        vertical resolution (default = 768)

fixobject color diameter
           color:    0 red
                     1 green
                     2 blue                      
                     3 cyan                      
                     4 magenta                      
                     5 yellow
                     6 black
                     7 white
                     8 grey
                      
           diameter: diameter of the fixation point (in pixels)

beep frequency duration
           frequncy: frequency in Hz 20-20000 Hz (accuracy is decreasing with increasing frequency)
           duration: in milliseconds 30-5000 ms (accuracy +- <= 16.6 ms)

sleep milliseconds
           milliseconds: suspend execution of command for the specified number of milliseconds 
                         (accuracy +- <= 16.6 ms)

output n
           Writes n to the digital output (Lpt1, DB 25 connector, pins 2-9)
           n: 0-255

assigncolors red1 green1 blue1 red2 green2 blue2
                     defines colors for the pattern generator
           red1:     0-255 (default 0)
           green1:   0-255 (default 0)
           blue1:    0-255 (default 0)
           red2:     0-255 (default 255)
           green2:   0-255 (default 255)
           blue2:    0-255 (default 255)


Synchronisation signal for the data acquision system:
=====================================================
Parallel (printer) port -> TTL compatible signal
Pattern reversal: square wave, each edge of the signal signal signalize a pattern 
                  reversal.
Pattern onset:    The rising edge (0 to 5 V) signalize pattern onset,
                  the falling edge (5 to 0 V) pattern ofset.

Synchronisation cable:
======================
DB 25 Male
Pin No.
1-------------------Synchron out (TTL, /Strobe line of the line printer interface)
25------------------Ground

Vertical refresh rate:
======================
The vertical refresh rate is adjusted with the VBEHZ utility.
To use VBEHZ:
1. unzip the files in the vbehz.zip file to a folder, e.g., to C:\VBEHZ
2. read the readme file
3. adjust the vertical refresh rate for each resolution with vbehzcfg.exe
4. add the following line to the autoexec.bat:
c:\vbehz\vbehz

For a 21" Monitor I have adjusted the vertical refresh rate for 100 Hz for each supported
resolution (640x480 - 1600x1200).

The pogram was tested with different versions of Nvidia grafic cards.
Not every modern grafic card is VBE 3.0 compatible, e.g., Matrox cards are only VBE 2.0 compatible.
The VBE 3.0 emulator mentioned in the VBEHZ documentation was not working properly with 
my Matrox cards (G200-550).

Latest Version:
===============
http://www.torok.info

Contact address:
================
New users: Please send me an email!
I'm just curious about the users of this program... 

Please send bug reports, improvements, suggestions, etc. to:

bela@torok.info

Known problems:
===============
Only the 16 bit version of "stimul.exe" compiled with the OpenWatom compiler is stable. 

=============================================================================================
vbetest.exe - writes the VBE-version and the supported VBE-modes of a VGA-card to the console
=============================================================================================

To write the supported VBE version and video modes to a file, use following command:

vbetest > vbemodes.txt


