---
name: "migrating"
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/migrating"
---

# migrating(3caca)

Migrating from libcaca 0.x to the 1.0 API This section will guide you through the migration of a libcaca 0.x application to the latest API version.

## NAME

migrating - Migrating from libcaca 0.x to the 1.0 API This section will guide you through the migration of a *libcaca* 0.x application to the latest API version.

## Overview

The most important changes in the 1.0 API of *libcaca* are the *libcaca* / *libcucul* split and the object-oriented design. See these two examples for a rough idea of what changed:

```
#include <caca.h>
/* libcaca program - 0.x API */
int main(void)
{
    /* Initialise libcaca */
    caca_init();
    /* Set window title */
    caca_set_window_title('Window');
    /* Choose drawing colours */
    caca_set_color(CACA_COLOR_BLACK,
                   CACA_COLOR_WHITE);
    /* Draw a string at (0, 0) */
    caca_putstr(0, 0, 'Hello world!');
    /* Refresh display */
    caca_refresh();
    /* Wait for a key press event */
    caca_wait_event(CACA_EVENT_KEY_PRESS);
    /* Clean up library */
    caca_end();
    return 0;
}
```

```
#include <cucul.h>
#include <caca.h>
/* libcaca program - 1.0 API */
int main(void)
{
    /* Initialise libcaca */
    cucul_canvas_t *cv;
    caca_display_t *dp;
    cv = cucul_create_canvas(0, 0);
    dp = caca_create_display(cv);
    /* Set window title */
    caca_set_display_title(dp, 'Window');
    /* Choose drawing colours */
    cucul_set_color_ansi(cv, CUCUL_BLACK,
                             CUCUL_WHITE);
    /* Draw a string at (0, 0) */
    cucul_put_str(cv, 0, 0, 'Hello world!');
    /* Refresh display */
    caca_refresh_display();
    /* Wait for a key press event */
    caca_get_event(dp, CACA_EVENT_KEY_PRESS,
                   NULL, -1);
    /* Clean up library */
    caca_free_display(dp);
    cucul_free_canvas(cv);
    return 0;
}
```

Note the following important things:

- •

  Functions now take an object handle as their first argument.

- •

  All input/output functions start with **caca\_** and all drawing and text handling functions start with **cucul\_** .

## Migration strategy

You have two ways to migrate your application to use *libcaca* 1.x:

- •

  Port your code using the function equivalence list. This is the preferred way because new functions are thread safe and offer much more features to both the programmer and the end user.

- •

  Use the legacy compatibility layer.

Using the compatibility layer is as easy as adding the following three lines:

```
#include <caca.h>
/* libcaca program - 0.x API */
```

```
#include <caca.h>
#ifdef CACA_API_VERSION_1
#   include <caca0.h>
#endif
/* libcaca program - 0.x API */
```

## Function equivalence list

### Basic functions

- •

  **caca\_init()**: use **cucul\_create\_canvas()** to create a *libcucul* canvas, followed by **caca\_create\_display()** to attach a *libcaca* display to it.

- •

  **caca\_set\_delay()**: use **caca\_set\_display\_time()**.

- •

  **caca\_get\_feature()**: deprecated.

- •

  **caca\_set\_feature()**: deprecated, see **cucul\_set\_dither\_antialias()**, **cucul\_set\_dither\_color()** and **cucul\_set\_dither\_mode()** instead.

- •

  **caca\_get\_feature\_name()**: deprecated, see **cucul\_get\_dither\_mode\_list()**, **cucul\_get\_dither\_antialias\_list()** and **cucul\_get\_dither\_color\_list()** instead.

- •

  **caca\_get\_rendertime()**: use **caca\_get\_display\_time()**.

- •

  **caca\_get\_width()**: use **cucul\_get\_canvas\_width()**.

- •

  **caca\_get\_height()**: use **cucul\_get\_canvas\_height()**.

- •

  **caca\_set\_window\_title()**: use **caca\_set\_display\_title()**.

- •

  **caca\_get\_window\_width()**: use **caca\_get\_display\_width()**.

- •

  **caca\_get\_window\_height()**: use **caca\_get\_display\_height()**.

- •

  **caca\_refresh()**: use **caca\_refresh\_display()**.

- •

  **caca\_end()**: use **caca\_free\_display()** to detach the *libcaca* display, followed by **cucul\_free\_canvas()** to free the underlying *libcucul* canvas.

### Event handling

- •

  **caca\_get\_event(): unchanged, but the event information retrieval changed a lot.**

- •

  **caca\_wait\_event(): use caca\_get\_event() with a** `timeout` **argument of -1.**

- •

  **caca\_get\_mouse\_x(): unchanged.**

- •

  **caca\_get\_mouse\_y(): unchanged.**

### Character printing

- •

  **caca\_set\_color(): use cucul\_set\_color\_ansi() or cucul\_set\_color\_argb().**

- •

  **caca\_get\_fg\_color(): use cucul\_get\_attr().**

- •

  **caca\_get\_bg\_color(): use cucul\_get\_attr().**

- •

  **caca\_get\_color\_name(): this function is now deprecated due to major uselessness.**

- •

  **caca\_putchar(): use cucul\_put\_char().**

- •

  **caca\_putstr(): use cucul\_put\_str().**

- •

  **caca\_printf(): use cucul\_printf().**

- •

  **caca\_clear(): use cucul\_clear\_canvas().**

### Primitives drawing

**These functions are almost unchanged, except for Unicode support and the fact that they now act on a given canvas.**

- •

  **caca\_draw\_line(): use cucul\_draw\_line().**

- •

  **caca\_draw\_polyline(): use cucul\_draw\_polyline().**

- •

  **caca\_draw\_thin\_line(): use cucul\_draw\_thin\_line().**

- •

  **caca\_draw\_thin\_polyline(): use cucul\_draw\_thin\_polyline().**

- •

  **caca\_draw\_circle(): use cucul\_draw\_circle().**

- •

  **caca\_draw\_ellipse(): use cucul\_draw\_ellipse().**

- •

  **caca\_draw\_thin\_ellipse(): use cucul\_draw\_thin\_ellipse().**

- •

  **caca\_fill\_ellipse(): use cucul\_fill\_ellipse().**

- •

  **caca\_draw\_box(): use cucul\_draw\_box().**

- •

  **caca\_draw\_thin\_box(): use cucul\_draw\_thin\_box() or cucul\_draw\_cp437\_box().**

- •

  **caca\_fill\_box(): use cucul\_fill\_box().**

- •

  **caca\_draw\_triangle(): use cucul\_draw\_triangle().**

- •

  **caca\_draw\_thin\_triangle(): use cucul\_draw\_thin\_triangle().**

- •

  **caca\_fill\_triangle(): use cucul\_fill\_triangle().**

### Mathematical functions

- •

  **caca\_rand(): use cucul\_rand(). The second argument is different, make sure you take that into account.**

- •

  **caca\_sqrt(): this function is now deprecated, use your system's sqrt() call instead.**

### Sprite handling

**The newly introduced canvases can have several frames. Sprites are hence completely deprecated.**

- •

  **caca\_load\_sprite(): use cucul\_import\_file().**

- •

  **caca\_get\_sprite\_frames(): use cucul\_get\_frame\_count().**

- •

  **caca\_get\_sprite\_width(): use cucul\_get\_canvas\_width().**

- •

  **caca\_get\_sprite\_height(): use cucul\_get\_canvas\_height().**

- •

  **caca\_get\_sprite\_dx(): use cucul\_get\_canvas\_handle\_x().**

- •

  **caca\_get\_sprite\_dy(): use cucul\_get\_canvas\_handle\_y().**

- •

  **caca\_draw\_sprite(): use cucul\_set\_frame() and cucul\_blit().**

- •

  **caca\_free\_sprite(): use cucul\_free\_canvas().**

### Bitmap handling

**Bitmaps have been renamed to dithers, because these objects do not in fact store any pixels, they just have information on how bitmaps will be dithered.**

- •

  **caca\_create\_bitmap(): use cucul\_create\_dither().**

- •

  **caca\_set\_bitmap\_palette(): use cucul\_set\_dither\_palette().**

- •

  **caca\_draw\_bitmap(): use cucul\_dither\_bitmap().**

- •

  **caca\_free\_bitmap(): use cucul\_free\_dither().**

## Compilation

**The** `caca-config` **utility is deprecated in favour of the standard** `pkg-config` **interface:**

```
gcc -c foobar.c -o foobar.o `pkg-config --cflags caca`
gcc foobar.o -o foobar `pkg-config --libs caca`
```

`caca-config` **is still provided as a convenience tool but may be removed in the future.**