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.