libcaca basic functions


Functions

caca_display_tcaca_create_display (cucul_canvas_t *)
 Attach a caca graphical context to a cucul canvas.
void caca_free_display (caca_display_t *)
 Detach a caca graphical context from a cucul backend context.
void caca_set_delay (caca_display_t *, unsigned int)
 Set the refresh delay.
void caca_refresh_display (caca_display_t *)
 Flush pending changes and redraw the screen.
unsigned int caca_get_rendertime (caca_display_t *)
 Get the average rendering time.
unsigned int caca_get_display_width (caca_display_t *)
 Get the display width.
unsigned int caca_get_display_height (caca_display_t *)
 Get the display height.
int caca_set_display_title (caca_display_t *, char const *)
 Set the display title.

Detailed Description

These functions provide the basic libcaca routines for driver initialisation, system information retrieval and configuration.

Function Documentation

caca_display_t* caca_create_display cucul_canvas_t cv  ) 
 

Create a graphical context using device-dependent features (ncurses for terminals, an X11 window, a DOS command window...) that attaches to a libcucul canvas. Everything that gets drawn in the libcucul canvas can then be displayed by the libcaca driver.

Parameters:
cv The cucul cavas.
Returns:
The caca graphical context or NULL if an error occurred.

void caca_free_display caca_display_t dp  ) 
 

Detach a graphical context from its cucul backend and destroy it. The libcucul canvas continues to exist and other graphical contexts can be attached to it afterwards.

Parameters:
dp The libcaca graphical context.

void caca_set_delay caca_display_t dp,
unsigned int  usec
 

This function sets the refresh delay in microseconds. The refresh delay is used by caca_refresh_display() to achieve constant framerate. See the caca_refresh_display() documentation for more details.

If the argument is zero, constant framerate is disabled. This is the default behaviour.

Parameters:
dp The libcaca graphical context.
usec The refresh delay in microseconds.

void caca_refresh_display caca_display_t dp  ) 
 

This function flushes all graphical operations and prints them to the screen. Nothing will show on the screen until caca_refresh_display() is called.

If caca_set_delay() was called with a non-zero value, caca_refresh_display() will use that value to achieve constant framerate: if two consecutive calls to caca_refresh_display() are within a time range shorter than the value set with caca_set_delay(), the second call will be delayed before performing the screen refresh.

Parameters:
dp The libcaca graphical context.

unsigned int caca_get_rendertime caca_display_t dp  ) 
 

This function returns the average rendering time, which is the average measured time between two caca_refresh_display() calls, in microseconds. If constant framerate was activated by calling caca_set_delay(), the average rendering time will not be considerably shorter than the requested delay even if the real rendering time was shorter.

Parameters:
dp The libcaca graphical context.
Returns:
The render time in microseconds.

unsigned int caca_get_display_width caca_display_t dp  ) 
 

If libcaca runs in a window, get the usable window width. This value can be used for aspect ratio calculation. If libcaca does not run in a window or if there is no way to know the font size, most drivers will assume a 6x10 font is being used. Note that the units are not necessarily pixels.

Parameters:
dp The libcaca graphical context.
Returns:
The display width.

unsigned int caca_get_display_height caca_display_t dp  ) 
 

If libcaca runs in a window, get the usable window height. This value can be used for aspect ratio calculation. If libcaca does not run in a window or if there is no way to know the font size, assume a 6x10 font is being used. Note that the units are not necessarily pixels.

Parameters:
dp The libcaca graphical context.
Returns:
The display height.

int caca_set_display_title caca_display_t dp,
char const *  title
 

If libcaca runs in a window, try to change its title. This works with the X11 and Win32 drivers.

Parameters:
dp The libcaca graphical context.
title The desired display title.
Returns:
0 upon success, a non-zero value if an error occurs.