---
name: "caca"
section: "3caca"
platform: "linux"
package: "libcucul-dev"
version: "0.99.beta11.debian-2"
release: "Debian 4.0 (Etch)"
platforms: ["linux"]
url: "https://new.carta.tech/caca"
---

# caca(3caca)

## NAME

libcaca basic functions -

### Functions

**caca\_display\_t** \* **caca\_create\_display** (**cucul\_canvas\_t** \*)\
 *Attach a caca graphical context to a cucul canvas.*  int **caca\_free\_display** (**caca\_display\_t** \*)\
 *Detach a caca graphical context from a cucul backend context.*  int **caca\_refresh\_display** (**caca\_display\_t** \*)\
 *Flush pending changes and redraw the screen.*  int **caca\_set\_display\_time** (**caca\_display\_t** \*, unsigned int)\
 *Set the refresh delay.*  unsigned int **caca\_get\_display\_time** (**caca\_display\_t** \*)\
 *Get the display's 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.

If an error occurs, NULL is returned and **errno** is set accordingly:

- •

  `ENOMEM` Not enough memory.

- •

  `ENODEV` Graphical device could not be initialised.

**Parameters:**

*cv* The cucul cavas.

**Returns:**

The caca graphical context or NULL if an error occurred.

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

This function never fails.

**Parameters:**

*dp* The libcaca graphical context.

**Returns:**

This function always returns 0.

### int caca\_refresh\_display (caca\_display\_t \* dp)

Flush all graphical operations and print them to the display device. Nothing will show on the screen until this function is called.

If **caca\_set\_display\_time()** 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\_display\_time()**, the second call will be delayed before performing the screen refresh.

This function never fails.

**Parameters:**

*dp* The libcaca display context.

**Returns:**

This function always returns 0.

### int caca\_set\_display\_time (caca\_display\_t \* dp, unsigned int usec)

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

This function never fails.

**Parameters:**

*dp* The libcaca display context. \
 *usec* The refresh delay in microseconds.

**Returns:**

This function always returns 0.

### unsigned int caca\_get\_display\_time (caca\_display\_t \* dp)

Get 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\_display\_time()**, the average rendering time will be close to the requested delay even if the real rendering time was shorter.

This function never fails.

**Parameters:**

*dp* The libcaca display 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.

This function never fails.

**Parameters:**

*dp* The libcaca display 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.

This function never fails.

**Parameters:**

*dp* The libcaca display 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 ncurses, S-Lang, OpenGL, X11 and Win32 drivers.

If an error occurs, -1 is returned and **errno** is set accordingly:

- •

  `ENOSYS` Display driver does not support setting the window title.

**Parameters:**

*dp* The libcaca display context. \
 *title* The desired display title.

**Returns:**

0 upon success, -1 if an error occurred.