Subsections

Screen and double buffer operations

This part contains:

A function to initialize the library and to set up a directX screen for the experiment to run in.
Functions to change the setup of the screen.
Functions to manipulate the double buffer.

int ts_init ();

Initializes the graphics mode and makes a double buffer if needed. The default settings are:

Opens in a window.
Resolution of 320 x 240 pixels.
16 bit color depth for fullscreen modes, same color depth as the desktop for window modes.
60Hz refresh rate for fullscreen modes (for window modes the refresh rate cant logically be different from the desktop refresh rate).
No double buffer.

The default settings should be satisfactory while programming your experiment. The screen parameters can be changed with the functions ts_refreshrate, ts_colordepth, ts_scrsize, ts_scrmode en ts_doublebuff. These parameter functions have to be called before you call ts_init. With the next call of ts_init the requested values will be used.

Some of the most frequent changes to the default values are:

full screen modes with a higher resolution during data collection.
playing with refresh rates when doing priming experiments.
using the double buffer for presenting complicated stimuli.

Most of the Tscope functions need the graphics screen to be opened (exceptions are the screen parameter functions themselves, randomizer functions, timer functions and sound stream functions). Therefore, any calls to these functions before you open the graphics screen with ts_init will trigger a graphics screen automatically.

Multiple instances of ts_init can be called throughout your program, for instance to change the refresh rate between two blocks.

If you successively change color depth and/or screen resolution, the current double buffer is destroyed and replaced by a new one. This means that the current buffer contents are removed and have to be reconstructed if desired. The destruction of the old buffer is necessary to avoid conflicts between old and new resolutions and/or color depths.

If the requested color depth is changed between two successive calls of ts_init, the foreground, background and mouse cursor colors are reset.

If opening a graphics screen fails, Tscope closes with an error message. This can happen for instance with some combinations of screen parameters that are not possible. The possibilities and limitations depend on the hardware used (load increases with increasing resolution, color depth and/or refresh rate). In the tests section, you will find a program called testscreen.c that can be used to determine which graphics modes are possible with your hardware.

While running in a window (e.g. during preliminary programming) the window is always kept smaller than the desktop. Furthermore, the window uses the color depth of the desktop for the sake of speed. Once going full screen, the actual requested settings will be used. If these settings are not realistic, the program quits with an error-message. The only exception to this behavior concerns the refresh rate. If the requested refresh rate is too high (we know that a refresh rate of 1000Hz would come handy), the program is not aborted but the refresh rate is automatically lowered. Tscope will inform you when it automatically lowers the requested refresh rate (see also ts_refreshrate).

The return value of ts_init is the actual refresh rate. This value and some more information about the operating system, desktop settings and the graphics mode are printed to the console.

void ts_fatal (const char *format, ...);

Closes the library safely, and prints the error-message provided in the format string *format to the console.

void ts_scrcfg (char *file)

Reads screen 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_scrcfg only reads the [screen] section. In this section there are five possible entries for setting the screen parameters. The entries are ts_debug=, ts_refreshrate=, ts_colordepth=, ts_scrsize= and ts_scrmode=.

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.

If one of the entries is not in the file (or commented out with #) the corresponding parameter will not be altered by ts_scrcfg.

If an entry appears more than once in the file, only the first appearance has effect.

The screen is not automatically opened or re-opened by this function.

int ts_debug(int mode);

Controls the amount of debugging info that is printed on the console while Tscope is running. The default setting is DEBUG1. There are five possible settings:

DEBUG0 no debugging info
DEBUG1 report automatic changes to screen parameters
DEBUG2 report when Tscope subsystems are loaded
DEBUG3 print some info about the system we're running on
DEBUG4 report when data files and response keys are loaded

If other values are passed to this function, Tscope closes with an error message.

Returns previous setting.

int ts_refreshrate (int rate);

Changes the refresh rate to be requested with the next call of ts_init. The default value is 60 Hertz.

There are limitations in the use of refresh rates. The possibilities depend on a combination of the hardware, the color depth and the resolution you want to use. If the refresh rate you asked for is beyond the possibilities of your system, the closest possible rate is used. When working in a window (not fullscreen) the refresh rate of the desktop is used. The eventual used refresh rate is returned with the next call of ts_init.

Frequently used refresh rates are 60, 70, 72, 75, 85 and 100. All values between 50 and 150 will be accepted by ts_refreshrate, but remind that this doesn't necessarily mean that your hardware supports these values. When feeding this function with values below 50 or above 150, Tscope closes with an error message.

Returns the previous refresh rate.

int ts_colordepth (int depth);

Changes the color depth to be requested with the next call of ts_init. The default color depth is 16 bit. When working in a window (not fullscreen) the color depth adopts to the color depth of the desktop for the sake of speed.

Possible values are 8, 15, 16, 24 or 32 bits. If other values are passed to this function, Tscope closes with an error message.

Returns previous color depth.

int ts_scrsize (int size);

Changes the screen resolution to be requested with the next call of ts_init. The default resolution is 320 x 240 pixels. When working in a window, the dimensions of the window are always kept smaller than the dimensions of the desktop.

Possible dimensions are given below, together with their industry-standard name - which can also be used in calls to ts_scrsize - and corresponding resolution.

SIZE0 (QVGA, 320 x 240 pixels).
SIZE1 (VGA, 640 x 480 pixels).
SIZE2 (SVGA, 800 x 600 pixels).
SIZE3 (XGA, 1024 x 768 pixels).
SIZE4 (XGAplus, 1152 x 864 pixels).
SIZE5 (SXGA, 1280 x 1024 pixels).
SIZE6 (SXGAplus, 1400 x 1050 pixels).
SIZE7 (UXGA, 1600 x 1200 pixels).

Sizes 3 to 7 also have a widescreen version:

WSIZE3 (WXGA, 1280 x 768 pixels).
WSIZE4 (WXGAplus, 1440 x 900 pixels).
WSIZE5 (WSXGA, 1600 x 1024 pixels).
WSIZE6 (WSXGAplus, 1680 x 1050 pixels).
WSIZE7 (WUXGA, 1920 x 1200 pixels).

For those interested in the weird industry-standard names: VGA stands for Video Graphics Array, QVGA for Quarter VGA, SVGA for Super VGA, XGA for eXtended Graphics array, SXGA for Super XGA, UGXA for Ultra XGA. The W means: Widescreen.

If other values are passed to this function, Tscope closes with an error message.

If a fullscreen resolution is too big for your monitor or graphics adaptor, Tscope also closes with an error message.

Returns the previous resolution.

int ts_scrxy (int x, int y);

As an alternative to ts_scrsize, this function can be used to specify the width and height of the screen separately (in number of pixels on the x and y axis). Only use this if none of the resolutions that can be set using ts_scrsize match your requirements.

Returns the previous resolution.

int ts_scrmode (int mode);

Sets the screen mode. Default is WINDOW. WINDOW opens a window, FULLSCREEN opens fullscreen without hardware acceleration, FULLSCREEN_ACCEL opens fullscreen with hardware acceleration. If other values are passed to this function, Tscope closes with an error message.

Returns the previous screen mode.

int ts_doublebuff (int mode);

Sets the double buffer setting to be requested with the next call of ts_init. Default is OFF. ON means working with double buffer, OFF without. If other values are passed to this function, Tscope closes with an error message.

The double buffer can be used if your stimuli are too complex to draw within one refresh cycle of the screen. In that case, you take the time necessary to draw your stimuli on the buffer, and after it's finished you can blit the buffer onto the screen within a few milliseconds.

The double buffer will be automatically destroyed and replaced by a new one if the color depth or resolution of the screen are changed.

Returns the previous double buffer setting.

void ts_clrscr();

Clears the screen. If the screen is not running yet, Tscope closes with an error message.

void ts_scrdump ();

Grabbing function that makes a dump of the screen to a file in the present working directory. The first screendump made by a program will be called dump1.bmp, the second dump2.bmp, etc. If the screen is not running yet, Tscope closes with an error message.

void ts_tobuff ();

When calling drawing or text output operations, Tscope needs to know the destination (screen or double buffer). The default destination is the screen. This function makes the double buffer the destination. If the screen is not running yet, or no double buffer is present, Tscope closes with an error message.