Tscope5
display.c File Reference

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 ()
void ts5_clear_display ()
double ts5_flip_display ()
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)
int ts5_get_active_display ()
TS5_BITMAP * ts5_set_drawing_target (TS5_BITMAP *target)
TS5_BITMAP * ts5_get_drawing_target ()
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 ()
void ts5_get_display_adapter_size (const int adapter, double *w, double *h)
double ts5_get_display_adapter_width (const int adapter)
double ts5_get_display_adapter_height (const int adapter)
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)
int ts5_get_display_adapter (const int display)
void ts5_set_display_size (double w, double h)
void ts5_get_display_size (const int display, double *w, double *h)
double ts5_get_display_width (const int display)
double ts5_get_display_height (const int display)
void ts5_set_display_position (double x, double y)
void ts5_get_display_position (const int display, double *x, double *y)
double ts5_get_display_x (const int display)
double ts5_get_display_y (const int display)
int ts5_set_refreshrate (const int rate)
int ts5_get_refreshrate (const int display)
int ts5_set_display_mode (const int mode)
int ts5_get_display_mode (const int display)
int ts5_set_vsync_mode (const int mode)
int ts5_get_vsync_mode (const int display)

Detailed Description

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:
bitmaps1.c, bitmaps2.c, bitmaps3.c, bitmaps4.c, bitmaps5.c, display1.c, display2.c, display3.c, display4.c, display5.c, graphics1.c, graphics10.c, graphics2.c, graphics3.c, graphics4.c, graphics5.c, graphics6.c, graphics7.c, graphics8.c, graphics9.c, primitives1.c, primitives2.c, primitives3.c, primitives4.c, randomizer1.c, randomizer2.c, randomizer3.c, system1.c, textio1.c, textio2.c, textio3.c, textio4.c, textio5.c, timer1.c, timer2.c, timer3.c, timer4.c, timer5.c, and timer6.c.

Definition at line 56 of file display.c.

void ts5_clear_display ( )

Clear the current drawing target.

The drawing target can either be a display or a bitmap (to clear a bitmap: set it as drawing target and call ts5_clear_display()).

The background color is controlled by ts5_set_background_color().

Examples:
bitmaps1.c, bitmaps2.c, bitmaps3.c, bitmaps4.c, bitmaps5.c, display1.c, display2.c, display3.c, display4.c, display5.c, graphics1.c, graphics10.c, graphics2.c, graphics3.c, graphics4.c, graphics5.c, graphics6.c, graphics7.c, primitives1.c, primitives2.c, primitives3.c, primitives4.c, textio3.c, textio4.c, timer1.c, timer2.c, timer3.c, timer4.c, timer5.c, and timer6.c.

Definition at line 357 of file display.c.

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:
bitmaps1.c, bitmaps2.c, bitmaps3.c, bitmaps4.c, bitmaps5.c, display1.c, display2.c, display3.c, display4.c, display5.c, graphics1.c, graphics10.c, graphics2.c, graphics3.c, graphics4.c, graphics5.c, graphics6.c, graphics7.c, graphics8.c, graphics9.c, primitives1.c, primitives2.c, primitives3.c, primitives4.c, textio4.c, textio5.c, timer1.c, timer2.c, timer3.c, timer4.c, timer5.c, and timer6.c.

Definition at line 379 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:
bitmaps5.c, display2.c, display3.c, display4.c, graphics1.c, graphics2.c, graphics3.c, and graphics4.c.

Definition at line 419 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 443 of file display.c.

TS5_BITMAP* ts5_set_drawing_target ( TS5_BITMAP *  target)

Set the active drawing target.

Parameters:
targetPointer to the bitmap that will be used for drawing operations.
Returns:
A pointer to the previous active drawing target.
Examples:
bitmaps5.c, display3.c, graphics1.c, graphics2.c, graphics3.c, and graphics4.c.

Definition at line 459 of file display.c.

TS5_BITMAP* ts5_get_drawing_target ( )

Get the active drawing target.

Returns:
A pointer to the active drawing target.

Definition at line 484 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:
display4.c.

Definition at line 512 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:
graphics1.c, graphics2.c, graphics3.c, and graphics4.c.

Definition at line 534 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.

Definition at line 575 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 596 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:
display4.c, and display5.c.

Definition at line 633 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 662 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:
display5.c, graphics1.c, graphics2.c, graphics3.c, and graphics4.c.

Definition at line 688 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:
bitmaps1.c, bitmaps2.c, bitmaps3.c, bitmaps4.c, bitmaps5.c, graphics1.c, graphics2.c, graphics3.c, graphics4.c, primitives1.c, primitives2.c, primitives3.c, and primitives4.c.

Definition at line 720 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 767 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 788 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:
display2.c, display4.c, display5.c, graphics1.c, graphics2.c, graphics3.c, and graphics4.c.

Definition at line 812 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:
graphics1.c, graphics2.c, graphics3.c, and graphics4.c.

Definition at line 865 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 946 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 966 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:
display5.c, and timer2.c.

Definition at line 993 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 1017 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.

The default window mode is TS5_WINDOWED.

Examples:
display5.c.

Definition at line 1056 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 1087 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_WHATEVER, TS5_VSYNC_ON or TS5_VSYNC_OFF.
Returns:
The previous vsync mode.

The default vsync mode is TS5_VSYNC_ON.

Examples:
display5.c, and timer2.c.

Definition at line 1114 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 1143 of file display.c.