Tscope5
display.c File Reference

Definitions of display functions. More...

Go to the source code of this file.

Functions

Basic operations

A display can either be a window or a fullscreen display.

There are three basic display operations:

int ts5_install_display ()
 Open a new display. More...
 
void ts5_clear_display ()
 Clear the current drawing target. More...
 
double ts5_flip_display ()
 Make what has been drawn visible on the screen. More...
 
Setting the display target

Tscope5 supports multiple displays (each call to ts5_install_display() opens a new display).

  • By default everything is drawn on the display that was opened last.
  • With ts5_set_active_display() you can change the target display.

You can also redirect drawing to memory bitmaps (see bitmaps.c) using ts5_set_drawing_target().

int ts5_set_active_display (const int display)
 Set the active display. More...
 
int ts5_get_active_display ()
 Get the active display. More...
 
Display adapter settings

A display adapter is a physical monitor that is attached to the computer.

Tscope5 supports multiple display adapters. Functions are available to query the number and dimensions of each display adapter.

int ts5_get_num_display_adapters ()
 Get the number of display adapters that are connected to the system. More...
 
void ts5_get_display_adapter_size (const int adapter, double *w, double *h)
 Get the size of the monitor attached to a display adapter. More...
 
double ts5_get_display_adapter_width (const int adapter)
 Get the width of the monitor attached to a display adapter. More...
 
double ts5_get_display_adapter_height (const int adapter)
 Get the heigth of the monitor attached to a display adapter. More...
 
Display settings

Before opening a display various settings can be requested using the functions below.

Once a display is opened the settings remain until the end of the program.

int ts5_set_display_adapter (const int adapter)
 Set the display adapter for the next display that will be opened. More...
 
int ts5_get_display_adapter (const int display)
 Get the index of the display adapter of a display. More...
 
void ts5_set_display_size (double w, double h)
 Set the size of the next display. More...
 
void ts5_get_display_size (const int display, double *w, double *h)
 Get the size of a display. More...
 
double ts5_get_display_width (const int display)
 Get the width of a display. More...
 
double ts5_get_display_height (const int display)
 Get the height of a display. More...
 
void ts5_set_display_position (double x, double y)
 Set the position of the next display. More...
 
void ts5_get_display_position (const int display, double *x, double *y)
 Get the position of a display. More...
 
double ts5_get_display_x (const int display)
 Get the horizontal position of a display. More...
 
double ts5_get_display_y (const int display)
 Get the vertical position of a display. More...
 
int ts5_set_refreshrate (const int rate)
 Set the requested refreshrate for the next display. More...
 
int ts5_get_refreshrate (const int display)
 Get the refreshrate of a display. More...
 
int ts5_set_display_mode (const int mode)
 Set the display mode for the next display. More...
 
int ts5_get_display_mode (const int display)
 Get the display mode of a display. More...
 
int ts5_set_vsync_mode (const int mode)
 Set the vsync mode for the next display. More...
 
int ts5_get_vsync_mode (const int display)
 Get the vsync mode of a display. More...
 
int ts5_set_multisampling (const int multisampling)
 Set the multisampling mode for the next display. More...
 
int ts5_get_multisampling (const int display)
 Get the multisampling mode of a display. More...
 

Detailed Description

Definitions of display functions.

Definition in file display.c.

Function Documentation

int ts5_install_display ( )

Open a new display.

Returns
The index of the new display.

TS5_FULLSCREEN_WINDOW mode:

  • A fullscreen display will be opened using the same display size and refreshrate as the desktop.
  • In this mode, the display size, position and refreshrate cannot be set by the user. These parameters will be ignored.
  • Tscope5 will check whether the new display is the first display on the adapter. If not, the program is aborted.

TS5_FULLSCREEN mode:

  • A fullscreen display will be opened. The user can specify the display size and refreshrate.
  • In this mode, the display position cannot be set by the user. This parameter will be ignored.
  • Tscope5 will check whether the new display is the first display on the adapter. If not, the program is aborted.
  • Tscope5 will check whether the display size and refreshrate is supported by the adapter. If not, the program is aborted.
  • A call to ts5_print_status() will list all combinations of size and refreshrate that are supported by the adapter.

TS5_WINDOWED mode:

  • Opens a window. The user can specifiy the display size and position.
  • In this mode, the refreshrate cannot be set by the user. This parameter will be ignored.
  • Tscope5 will check whether the adapter is already in use by a TS5_FULLSCREEN_WINDOW or TS5_FULLSCREEN display. If so, the program is aborted.
  • Tscope5 will check whether the window will fit on the display. If not, the dimensions of the display are reduced.
  • Tscope5 will check whether the window will be visible on the screen. If not, the window position is changed.

The new display is the drawing target for future drawing operations.

Examples:
audio03.c, audio04.c, bitmaps01.c, bitmaps02.c, bitmaps03.c, bitmaps04.c, bitmaps05.c, cedrusbox01.c, display01.c, display01.cpp, display02.c, display03.c, display04.c, display05.c, display06.c, graphics01.c, graphics02.c, graphics03.c, graphics04.c, graphics05.c, graphics06.c, graphics07.c, graphics08.c, graphics09.c, graphics10.c, joystick01.c, keyboard01.c, mouse01.c, mouse02.c, parport01.c, primitives01.c, primitives02.c, primitives03.c, primitives04.c, randomizer01.c, randomizer02.c, randomizer03.c, serialport01.c, textio01.c, textio02.c, textio03.c, textio04.c, textio05.c, timer01.c, timer02.c, timer03.c, timer04.c, timer05.c, timer06.c, and video01.c.

Definition at line 84 of file display.c.

void ts5_clear_display ( )
double ts5_flip_display ( )

Make what has been drawn visible on the screen.

Returns
The time when the display flip occurs.

All drawing operations (primitives, text, bitmaps, ...) are performed on a back buffer. Once you have finished drawing you should call this function to make your drawings visible on the screen. After a call to this function the back buffer is not cleared.

Examples:
audio03.c, audio04.c, bitmaps01.c, bitmaps02.c, bitmaps03.c, bitmaps04.c, bitmaps05.c, cedrusbox01.c, display01.c, display01.cpp, display02.c, display03.c, display04.c, display05.c, display06.c, graphics01.c, graphics02.c, graphics03.c, graphics04.c, graphics05.c, graphics06.c, graphics07.c, graphics08.c, graphics09.c, graphics10.c, joystick01.c, keyboard01.c, mouse01.c, mouse02.c, parport01.c, primitives01.c, primitives02.c, primitives03.c, primitives04.c, serialport01.c, textio04.c, textio05.c, timer01.c, timer02.c, timer03.c, timer04.c, timer05.c, timer06.c, and video01.c.

Definition at line 539 of file display.c.

int ts5_set_active_display ( const int  display)

Set the active display.

Parameters
displayIndex of the display.
Returns
The index of the previous active display.

The 'active' display is the display that will be used for drawing operations.

Examples:
bitmaps05.c, display02.c, display03.c, display04.c, graphics01.c, graphics02.c, graphics03.c, and graphics04.c.

Definition at line 637 of file display.c.

int ts5_get_active_display ( )

Get the active display.

Returns
The index of the active display.

The 'active' display is the display that will be used for drawing operations.

Definition at line 665 of file display.c.

int ts5_get_num_display_adapters ( )

Get the number of display adapters that are connected to the system.

Returns
The number of display adapters that are connected to the system.
Examples:
display04.c.

Definition at line 694 of file display.c.

void ts5_get_display_adapter_size ( const int  adapter,
double *  w,
double *  h 
)

Get the size of the monitor attached to a display adapter.

Parameters
adapterIndex of the display adapter.
wVariable that will store the width.
hVariable that will store the height.

w and h are the maximum size of a window that can be opened on that adapter.

Pass 0 to get the size of the display adapter for the next display.

You can pass NULL for values you are not interested in.

Examples:
display04.c, graphics01.c, graphics02.c, graphics03.c, and graphics04.c.

Definition at line 716 of file display.c.

double ts5_get_display_adapter_width ( const int  adapter)

Get the width of the monitor attached to a display adapter.

Parameters
adapterIndex of the display adapter.
Returns
the width of the display adapter.

Pass 0 to get the width of the display adapter for the next display.

Examples:
display03.c.

Definition at line 758 of file display.c.

double ts5_get_display_adapter_height ( const int  adapter)

Get the heigth of the monitor attached to a display adapter.

Parameters
adapterIndex of the display adapter.
Returns
the height of the display adapter.

Pass 0 to get the height of the display adapter for the next display.

Definition at line 779 of file display.c.

int ts5_set_display_adapter ( const int  adapter)

Set the display adapter for the next display that will be opened.

Parameters
adapterIndex of the active display adapter.
Returns
The index of the previous active display adapter.

A display adapter corresponds to a physical display that is attached to the computer. The first adapter has index 1, etc.

The display is attached to adapter 1 by default.

Examples:
display04.c, and display05.c.

Definition at line 818 of file display.c.

int ts5_get_display_adapter ( const int  display)

Get the index of the display adapter of a display.

Parameters
displayIndex of the display.
Returns
The index of the adapter that the display is attached to.

Pass 0 to get the index of the display adapter for the next display.

Definition at line 849 of file display.c.

void ts5_set_display_size ( double  w,
double  h 
)

Set the size of the next display.

Parameters
wWidth of the next display in pixels.
hHeight of the next display in pixels.

The default width and height is 320 x 240. This is also the minimum.

Examples:
bitmaps01.c, bitmaps02.c, bitmaps03.c, bitmaps04.c, display05.c, graphics01.c, graphics02.c, graphics03.c, graphics04.c, mouse02.c, textio01.c, textio05.c, and video01.c.

Definition at line 875 of file display.c.

void ts5_get_display_size ( const int  display,
double *  w,
double *  h 
)

Get the size of a display.

Parameters
displayIndex of the display.
wVariable that will store the width.
hVariable that will store the height.

Set display to 0 to get the width of the next display.

You can pass NULL for values you are not interested in.

Examples:
bitmaps01.c, bitmaps02.c, bitmaps03.c, bitmaps04.c, bitmaps05.c, display02.c, graphics01.c, graphics02.c, graphics03.c, graphics04.c, primitives01.c, primitives02.c, primitives03.c, and primitives04.c.

Definition at line 910 of file display.c.

double ts5_get_display_width ( const int  display)

Get the width of a display.

Parameters
displayIndex of the display.
Returns
the width of the display.

Set display to 0 to get the width of the next display.

Definition at line 945 of file display.c.

double ts5_get_display_height ( const int  display)

Get the height of a display.

Parameters
displayIndex of the display.
Returns
the height of the display.

Set display to 0 to get the height of the next display.

Definition at line 966 of file display.c.

void ts5_set_display_position ( double  x,
double  y 
)

Set the position of the next display.

Parameters
xHorizontal position of the display on the desktop.
yVertical position of the display on the desktop.

Only meaningful for non-fullscreen displays.

CARTESIAN coordinates: Center of the display is the origin, default position is the center of the display.

COMPUTER coordinates: The upper left corner of the display is the origin, default position is top left corner of the display.

Examples:
display03.c, display04.c, display05.c, display06.c, graphics01.c, graphics02.c, graphics03.c, and graphics04.c.

Definition at line 992 of file display.c.

void ts5_get_display_position ( const int  display,
double *  x,
double *  y 
)

Get the position of a display.

Parameters
displayIndex of the display.
xVariable that will store the horizontal position.
yVariable that will store the vertical position.

Only meaningful for non-fullscreen displays.

Set display to 0 to get the x position of the next display.

You can pass NULL for values you are not interested in.

Examples:
graphics01.c, graphics02.c, graphics03.c, and graphics04.c.

Definition at line 1055 of file display.c.

double ts5_get_display_x ( const int  display)

Get the horizontal position of a display.

Parameters
displayIndex of the display.
Returns
The horizontal position of the display.

Definition at line 1143 of file display.c.

double ts5_get_display_y ( const int  display)

Get the vertical position of a display.

Parameters
displayIndex of the display.
Returns
The vertical position of the display.

Definition at line 1163 of file display.c.

int ts5_set_refreshrate ( const int  rate)

Set the requested refreshrate for the next display.

Parameters
rateRefreshrate in cycles per second.
Returns
The previous refresh rate.

The refreshrate can only be changed for real fullscreen displays.

Even then this is only a request.

The default value 0 (let the system choose).

Examples:
display05.c, and timer02.c.

Definition at line 1190 of file display.c.

int ts5_get_refreshrate ( const int  display)

Get the refreshrate of a display.

Parameters
displayIndex of the display.
Returns
The refresh rate of the display.

Set display to 0 to get the refreshrate of the next display.

Definition at line 1216 of file display.c.

int ts5_set_display_mode ( const int  mode)

Set the display mode for the next display.

Parameters
modeWindow mode. Can be TS5_WINDOWED, TS5_FULLSCREEN or TS5_FULLSCREEN_WINDOW.
Returns
The previous display mode.

In TS5_WINDOWED mode the window can have any dimension that will fit on the physical display and the position of the window on the display can be adjusted. Multiple TS5_WINDOWED displays can be combined on one physical display. The refreshrate is always the refreshrate of the physical display.

In TS5_FULLSCREEN_WINDOW mode the display always has the dimension of the desktop. The refreshrate is always the refreshrate of the physical display. Only one TS5_FULLSCREEN_WINDOW display can be used per physical display.

TS5_FULLSCREEN modes are the most flexible: any combination of display dimension and refreshrate that is supported by the monitor can be set. Does not seem to work on Mac OS X.

The default window mode is TS5_WINDOWED.

Examples:
display05.c.

Definition at line 1261 of file display.c.

int ts5_get_display_mode ( const int  display)

Get the display mode of a display.

Parameters
displayIndex of the display.
Returns
The window mode of the display.

Set display to 0 to get the display mode of the next display.

Definition at line 1294 of file display.c.

int ts5_set_vsync_mode ( const int  mode)

Set the vsync mode for the next display.

Parameters
modeVsync mode. Can be TS5_VSYNC_OFF, TS5_VSYNC_ON or TS5_VSYNC_WHATEVER.
Returns
The previous vsync mode.

The default vsync mode is TS5_VSYNC_ON.

Examples:
display05.c, and timer02.c.

Definition at line 1322 of file display.c.

int ts5_get_vsync_mode ( const int  display)

Get the vsync mode of a display.

Parameters
displayIndex of the display.
Returns
The vsync mode of the display.

Set display to 0 to get the requested vsync mode for the next display.

Definition at line 1353 of file display.c.

int ts5_set_multisampling ( const int  multisampling)

Set the multisampling mode for the next display.

Parameters
multisamplingMultisampling mode. Can be TS5_MULTISAMPLING_OFF or TS5_MULTISAMPLING_ON.
Returns
The previous multisampling mode.

Turning multisampling on gives smoother pictures.

On some older machines this should be turned off.

The default multisampling mode is TS5_MULTISAMPLING_OFF.

Examples:
display06.c.

Definition at line 1385 of file display.c.

int ts5_get_multisampling ( const int  display)

Get the multisampling mode of a display.

Parameters
displayIndex of the display.
Returns
The multisampling mode of the display.

Set display to 0 to get the requested multisampling mode for the next display.

Definition at line 1419 of file display.c.