---
name: "basic"
section: "3caca"
platform: "linux"
package: "libcaca-dev"
version: "0.9-4"
release: "Debian 3.1 (Sarge)"
platforms: ["linux"]
url: "https://new.carta.tech/basic/3caca"
---

# basic(3caca)

## 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.

**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.