man basic () -

NAME

Basic functions -

Functions

int caca_init (void)

Initialise libcaca. void caca_set_delay (unsigned int)

Set the refresh delay. enum caca_feature caca_get_feature (enum caca_feature)

Get the current value of a feature. void caca_set_feature (enum caca_feature)

Set a feature. char const * caca_get_feature_name (enum caca_feature)

Translate a feature value into the feature's name. unsigned int caca_get_rendertime (void)

Get the average rendering time. unsigned int caca_get_width (void)

Get the screen width. unsigned int caca_get_height (void)

Get the screen height. int caca_set_window_title (char const *)

Set the window title. unsigned int caca_get_window_width (void)

Get the window width. unsigned int caca_get_window_height (void)

Get the window height. void caca_refresh (void)

Flush pending changes and redraw the screen. void caca_end (void)

Uninitialise libcaca.

Detailed Description

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

Function Documentation

void caca_end (void)

This function frees all resources allocated by caca_init(). After caca_end() has been called, no other libcaca functions may be used unless a new call to caca_init() is done.

enum caca_feature caca_get_feature (enum caca_feature feature)

This function retrieves the value of an internal libcaca feature. A generic feature value is expected, such as CACA_ANTIALIASING.

Parameters: feature The requested feature.

Returns: The current value of the feature or CACA_FEATURE_UNKNOWN if an error occurred..

char const* caca_get_feature_name (enum caca_feature feature)

This function translates a caca_feature enum into a human-readable description string of the associated feature.

Parameters: feature The feature value.

Returns: A static string containing the feature's name.

unsigned int caca_get_height (void)

This function returns the current screen height, in character cells.

Returns: The screen height.

unsigned int caca_get_rendertime (void)

This function returns the average rendering time, which is the average measured time between two caca_refresh() 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.

Returns: The render time in microseconds.

unsigned int caca_get_width (void)

This function returns the current screen width, in character cells.

Returns: The screen width.

unsigned int caca_get_window_height (void)

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.

Returns: The window height.

unsigned int caca_get_window_width (void)

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, assume a 6x10 font is being used. Note that the units are not necessarily pixels.

Returns: The window width.

int caca_init (void)

This function initialises internal libcaca structures and the backend that will be used for subsequent graphical operations. It must be the first libcaca function to be called in a function. caca_end() should be called at the end of the program to free all allocated resources.

Returns: 0 upon success, a non-zero value if an error occurs.

void caca_refresh (void)

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

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

void caca_set_delay (unsigned int usec)

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

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

Parameters: usec The refresh delay in microseconds.

void caca_set_feature (enum caca_feature feature)

This function sets an internal libcaca feature such as the antialiasing or dithering modes. If a specific feature such as CACA_DITHERING_RANDOM, caca_set_feature() will set it immediately. If a generic feature is given instead, such as CACA_DITHERING, the default value will be used instead.