- A C library for programming cognitive experiments on Windows
Defined in timer.h and timer.c
This part contains:
While most other function groups in Tscope only use Allegro and standard C functions, this function group pulls together three different libraries. In case you want to program a custom timing function, you will need to know the following:
Reads timing parameters from a configuration file.
A sample configuration file (tscope.cfg) is given in the examples section of the site.
The configuration file consists of sections which are marked by [NAME OF
SECTION]. ts_timercfg only reads the [timing] section. In this section
there are five possible entries for setting the timing parameters. The entries are
ts_priority=, ts_waitmode=, ts_vsyncmode=, ts_vsynclimit= and ts_defkey=.
Each entry controls what the parameter function with the same name would control.
All possible values for each entry are listed as comments in the sample configuration file. If a wrong value or more than one value is entered for a given entry tscope closes with an error message.
The ts_defkey= entry is an exception to this: here, more than one parameter (response key) can be set. All of the response key should be listed on one line, separated by spaces. The first key listed gets number 1, the second gets number 2, etc.
If one of the entries is not in the file (or commented out with #) the corresponding parameter will not be altered by ts_timercfg.
If an entry appears more than once in the file, only the first appearance has effect.
When calling this function, all existing response key definitions are removed and the timing subsystem is automatically restarted.
Reads timing parameters from a configuration file.
Returns value of previous priority setting.
Be careful with higher priority modes. To avoid problems, set higher priority modes only when needed (during a block of trials) and switch back to normal priority when timing accuracy is not an issue.
Only start increasing the priority when you are sure your program works without any problems. HIGH priority is the best compromise between timing accuracy and safety. A program that runs with HIGH priority will not be put aside by normal programs, but it will still be possible to stop the program using the task manager.
Only use REALTIME priority when the other priority modes are not sufficient. With realtime priority, an endless loop in your program will hang the system - there is no way to stop a program running with REALTIME priority!.
Also keep in mind that reading input from keyboard, mouse and joystick is impossible when running with REALTIME priority on Windows XP. Playing .wav files will not be possible either when running with REALTIME priority.
The BELOW_NORMAL and IDLE priority modes are not really useful for running experiments. For running simulations they are: in IDLE mode, a program will only use system resources if there are no other processes running (i.e. when you're not using your computer for anything else).
ts_waitmode controls under which conditions Tscope will explicitly give up cpu time and allow other programs to run. There are four possible parameters:
Returns the value of the previous waiting mode.
Returns the response number assigned to the key.
All key codes can be found in the appendix. To remove the whole key definition use ts_clrkeys (see infra). To temporarily hide one key from the list of defined keys, use ts_hidekey (see infra).
At present Tscope can read the parallel port and game port with millisecond accuracy. Reading the keyboard, mouse and joystick is also possible but with limited precision. Don't use these under realtime priority. Use the parallel and game port during the actual experiment. Use the mouse, keyboard or joystick while developing. Try to avoid input from multiple devices. This can cause delays.
All necessary permission settings and driver requests are automatically handled at start-up and shutdown of your program. When loading a driver fails, the program will stop with an error message.
The argument to this function is the response value that has to be deactivated, not the key code.
Reactivating all defined keys is possible by calling ts_hidekey(0).
Returns the number of active keys left. If no active keys are left, Tscope closes with an error message (to avoid endless loops).
Waits for a response. Writes the number of tics between computer start-up and the response to *time, writes the estimated timing error to *error. Returns the number of the response key pressed.
The value of maxtime defines the maximum time to wait for a response (in tics). Setting maxtime to 0 means waiting until response, however long. If no response is registered at the end of the interval 0 is returned and the time and timing error at the end of the interval are written to *time and *error.
When no keys are defined, this function closes Tscope with an error message (to avoid endless loops).
Waits until all response buttons are released. Writes the number of tics between computer start-up and the release to *time, writes the estimated timing error to *error. The function returns the number of the response key pressed (should always return 0, meaning that all buttons are released).
The value of maxtime defines the maximum time to wait for a release (in tics). Setting maxtime to 0 means waiting until release, however long. When no keys are defined, this function closes Tscope with an error message (to avoid endless loops).
Waits for a vertical retrace. Writes the number of tics between computer start-up and the moment of the sync-signal to *time, writes the estimated timing error to *error.
Under ideal circumstances, the function reads the status of vertical retrace signal directly from the computer's registry. In situations where that's not possible, a vertical retrace signal is simulated.
Tscope will simulate the retrace signal at the actual refresh rate in the following cases:
If no window is opened yet, Tscope will simulate the retrace at the requested refresh rate.
With every change of the graphics mode, the vsync mode will be updated.
Note that the reliability of the readout or simulation of the vertical retrace is highly influenced by the priority of the program. Reliability increases with the priority of the program (but be aware of the possible problems with realtime priority).
Adapted ts_vsync. Waits until the beginning of the nsync-th vsync. Can be useful in priming-experiments (e.g.: prime remains on screen for 3 refresh cycles).
Writes the number of tics between computer start-up and the moment of then nsync-th sync-signal to *time, writes the estimated timing error to *error.
Like ts_resp, but waits for a given number of vsyncs instead of milliseconds. Use this function when you want the stimulus to be removed in a proper way (synchronized with the screen) during the response interval.
By default, Tscope chooses between reading out the vsync signal from the registry, simulating a vsync signal at the requested refresh rate, or simulating a vsync signal at the actual refresh rate. With this function, you can force Tscope to choose one of the alternatives.
Parameter values are:
Forcing Tscope to read out the vsync signal from the registry can result in endless loops, if the signal cannot be caught. Forcing Tscope to simulate the vsync signal at the requested refresh rate will result in bad estimates of how long your stimulus was on screen, when the requested and actual refresh rate differ.
This function returns the previous vsync mode.
On some systems, this frequency limit might be higher. Only change this value if you are confident that the new value will work on your system. Expect endless loops if you set the value too high.
All values between 50 and 150 will be accepted by ts_vsynclimit (this doesn't mean that your hardware supports these values).
This function returns the previous vsync limit.
Use this function at your own risk.
This function needs to be called before defining response keys on the Cedrus response pad (S1-S7).
This function returns the previous serial port number.
Port contains the number of the parallel port you want to write to (1, 2 or 3), time contains the number of tics each trigger has to stay on (depends on the timing resolution of the computer you're sending triggers to).
Trigger parameters have to be set before you call this function. Tscope will close with an error message if you don't.