libcaca documentation

Main Page | Modules | Directories | File List | Globals

# 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. Parameters:
  | feature | The requested feature.

int caca_set_window_title | ( | char const * | title | ) |

  | If libcaca runs in a window, try to change its title. This works with the X11 and Win32 drivers. Parameters:
  | title | The desired window title.
Returns: 0 upon success, a non-zero value if an error occurs.