Tscope5 is a C/C++ experiment programming library for cognitive scientists.
It is mainly targeted at the Windows platform but also runs on Mac OS X and Linux.
It provides functions for randomization, graphics, sound, timing, response registration and synchronisation between computers.
Tscope5 is the successor of Tscope. It is entirely rewritten from scratch and is therefore not source compatible with the old version, even though the same functionality (and more) is provided.
The Tscope5 functions are split into different groups. These groups are listed here:
System functions
Central to Tscope5 there is a small set of functions that allow you to
- Log information about the sequence of events in your experiment.
- Write out information about the computer you are running on.
- Exit your program gracefully in case of an unexpected event.
- The functions are documented in system.c
Randomizer functions
Tscope5 provides an interface to the randomization routines from the GNU Scientific Library (GSL).
- It can generate random lists with or without replacement.
- It can generate numbers from uniform, normal or exponential distributions.
- Other distributions are quite easy to implement, please feel free to ask if you need one.
- Internally the RANLUX algorithm is used, which has a period of about 10^171.
- The functions are documented in randomizer.c
Stimulus output functions
Display functions
This group of functions is used for opening/closing Tscope5 displays and for setting display parameters.
Tscope5 supports multiple displays, so you can
- Have two participants do interaction experiments.
- Add an experimenter interface with progress and performance statistics.
- All Tscope5 drawing operations are performed in sync with the vertical refresh rate of your display.
- Fullscreen and windowed modes are supported.
The graphics functions, primitives drawing functions, bitmap drawing functions, text input/output functions, mouse and keyboard functions require a display to be opened.
The system functions, randomizer functions, audio functions and timer functions do not require a display to be opened.
Graphics functions
This set of functions contains three groups:
- Helper functions for computing coordinates on the display.
- A coordinate system with the origin in the center of the screen is the default.
- A relative coordinate system that makes your experiment resolution-independent is available.
- Functions for defining colors
- RGB, HSL and HSL color definitions with (partially) transparant colors are supported.
- Parameter functions that control the appearance of graphical output and text.
Graphics parameters influence the primitives drawing functions, bitmap drawing functions and text input/output functions documented below.
Primitives drawing functions
This group of functions is used for drawing primitive objects on the display.
- Primitive objects are lines, rectangles, triangles, circles, etc.
- The functions are documented in primitives.c
Bitmap drawing functions
This group of functions is used for drawing bitmap objects on the display.
Bitmaps can either be
- Loaded from a file in most popular bitmap formats (bmp, pcx, tga, jpeg, png, mabye some others, ...).
- Prepared in advanced using the primitives and text output functions.
- The functions are documented in bitmaps.c
Text input/output functions
This group of functions is used for drawing text on the display and for reading text from the keyboard.
- Functions for both C strings and for Unicode strings are available.
- TrueType fonts (TTF) are supported.
- A small set of fonts is built in, any font that is available on your system can be imported very easily.
- The functions are documented in textio.c
Audio functions
This group of functions provides support for audio playback and recording.
- Supported input file formats are wav, flac and ogg (no mp3 support, that is a commercial format).
- wav is the only supported output file format.
- Sounds can be read from a file, generated online or recorded.
- A software voice key is available.
- The functions are documented in audio.c
Video functions
This group of functions provides video playback support.
- The only supported video format is ogg video (.ogv)
- Google will help you find the tools to convert other video formats to .ogv
- The functions are documented in video.c
Timer functions
This group of functions provides timer support.
The timer functions can
- Alter the program's priority to increase timing accuracy.
- Wait for a given time to elapse (stimulus timing).
- Wait for a response from the participant (response registration).
- Wait for a trigger from another computer (synchronisation between computers).
The valid reponse buttons or trigger signals have to be defined first using the mouse, keyboard, joystick, cedrusbox, parallel or serial port functions documented below.
On all response registration devices Tscope5 can detect both button press events and button release events.
On devices with sub-millisecond timing accuracy (cedrusboxes and parallel port response boxes) Tscope5 gives an estimate of the timing error. On other devices this estimate is not available (set to 0.0).
Trigger signals from another computer can be simulated internally so you don't need the other computer attached while programming your experiment.
- The functions are documented in timer.c
Mouse functions
This group of functions provides mouse (and touch screen) support.
The mouse can be used
- As a response device with low timing resolution.
- As a simple gui.
- Currenlty only button presses and releases can be defined as responses. Adding mouse movements as responses should be quite easy, feel free to ask if you need it.
- Touch screens have the same functionality as a mouse and are programmed in the same way. If you need touch screen input just use the mouse functions and it will work.
- Multiple mice can be attached to a computer, but to Tscope5 it is as if there is only one mouse (i.e. pressing the left button on the first mouse has the same effect as pressing the left button on the second mouse. Tscope5 has no idea on which mouse the button was pressed).
- The functions are documented in mouse.c
Keyboard functions
This group of functions provides keyboard support.
The keyboard can be used
- As a response device with low timing resolution.
- For scanf type input.
- Multiple keyboards can be attached to a computer, but to Tscope5 it is as if there is only one keyboard (i.e. pressing e.g. the 'A' on the first keyboard has the same effect as pressing the 'A' on the second keyboard. Tscope5 has no idea on which keyboard the button was pressed).
- The functions are documented in keyboard.c
Joystick functions
This group of functions provides joystick support.
- The joystick can be used as a response device with low timing resolution.
- Multiple joysticks can be used simultaneously as independent response devices.
- Currenlty only button presses and releases can be defined as responses.
- Adding axis movements as responses should be quite easy, feel free to ask if you need it.
- The functions are documented in joystick.c
Cedrusbox functions
This group of functions provides cedrusbox support.
- Cedrusboxes can be used as response devices with sub-millisecond timing resolution.
- Multiple cedrusboxes can be used simultaneously as independent response devices.
- Cedrusboxes can also send trigger signals to the computer.
- Cedrusboxes require a driver available from www.cedrus.com (Windows, Mac OS X and Linux).
- Tscope5 communicates with Cedrusboxes using the Cedrus XID protocol at 115000 Baud.
- On RB series boxes, flip dip switches 1, 2 and 3 down.
- On Lumina fMRI boxes, use the buttons on the controller to set the mode to 'Lumina' and 115000 Baud.
- When interfacing the SV-1 voice key, use Cedrus' Xidon program to select 'XID' protocol and 115000 Baud. This program can also be used to set the voice key treshold and other parameters.
- The functions are documented in cedrusbox.c
Parallel port functions
This group of functions provides support for communication over the parallel port .
The parallel port can be used
- For attaching home-made response boxes and voice keys with sub-millisecond timing resolution (pins 10-15, the status register).
- For sending and receiving trigger signals between computers with sub-millisecond timing resolution (pins 2-9, the data register).
- Up to sixteen parallel ports can be used simultaneously as independent response or trigger devices, but each port can only be used for one job: registering responses, registering triggers or sending triggers.
- The functions are documented in parport.c
Serial port functions
This group of functions provides support for communication over the serial port.
The serial port can be used
- For attaching home-made response boxes with sub-millisecond timing resolution.
- For sending and receiving trigger signals between computers with sub-millisecond timing resolution.
- Multiple serial ports can be used simultaneously as independent response or trigger devices.
- Each port can be used for both sending and receiving trigger signals with sub-millisecond timing resolution (you don't need two cables for bidirectional communication).
- Modern computers often don't have a serial port but serial communication can be simulated over usb (like the cedruxboxes or arduino's). These devices will also have sub-millisecond timing resolution.
- Serial protocol settings have to be set directly by the user (see examples).
- The functions are documented in serialport.c