caca_display(3caca)

🌈 caca_display 🌈

okay so bestie, this page is from the libcaca manual, section 3caca, and it is literally the display-functions era. No cap, this is where libcaca learns how to show your canvas on a real device. 💅

---

💖 NAME 💖

caca_display — libcaca display functions. That is the whole name vibe. ✨

✨ SYNOPSIS ✨

📚 Topics 📚

• libcaca event handling

🛠️ Functions 🛠️

• __extern caca_display_t * caca_create_display (caca_canvas_t *) — hooks a caca graphical context onto a caca canvas. 🫶
• __extern caca_display_t * caca_create_display_with_driver (caca_canvas_t *, char const *) — hooks a specific caca graphical context onto a caca canvas. 💫
• __extern char const *const * caca_get_display_driver_list (void ) — hands you the list of available display drivers. 📋
• __extern char const * caca_get_display_driver (caca_display_t *) — shows the current output driver for a caca graphical context. 🔍
• __extern int caca_set_display_driver (caca_display_t *, char const *) — sets the output driver. 🎛️
• __extern int caca_free_display (caca_display_t *) — detaches a caca graphical context from a caca backend context. 🎈
• __extern caca_canvas_t * caca_get_canvas (caca_display_t *) — grabs the canvas attached to a caca graphical context. 🎨
• __extern int caca_refresh_display (caca_display_t *) — flushes pending changes and redraws the screen. 🔄
• __extern int caca_set_display_time (caca_display_t *, int) — sets the refresh delay. ⏱️
• __extern int caca_get_display_time (caca_display_t const *) — gets the display’s average rendering time. ⏳
• __extern int caca_get_display_width (caca_display_t const *) — gets the display width. 📏
• __extern int caca_get_display_height (caca_display_t const *) — gets the display height. 📐
• __extern int caca_set_display_title (caca_display_t *, char const *) — sets the display title. 🏷️
• __extern int caca_set_mouse (caca_display_t *, int) — shows or hides the mouse pointer. 🖱️
• __extern int caca_set_cursor (caca_display_t *, int) — shows or hides the cursor. 🖋️

🦋 DETAILED DESCRIPTION 🦋

These functions are the basic libcaca routines for display initialisation, system information retrieval and configuration. Literally the starter pack for making a display happen. ✨

🎀 FUNCTION DOCUMENTATION 🎀

💫 caca_create_display 💫

__extern caca_display_t * caca_create_display (caca_canvas_t * cv)

Okay so this one creates a graphical context using device-dependent features (ncurses for terminals, an X11 window, a DOS command window...) that attaches to a libcaca canvas. Everything that gets drawn in the libcaca canvas can then be displayed by the libcaca driver. It is giving “canvas goes public.” 👑

If no caca canvas is provided, a new one is created. Its handle can be retrieved using caca_get_canvas() and it is automatically destroyed when caca_free_display() is called.

Note: to achieve maximum Unicode compatibility, the driver initialisation code may temporarily change the program’s global LC_CTYPE locale using setlocale(). It is advised not to call LC_CTYPE-dependent functions from other threads during the call to caca_create_display(). The locale settings are restored when the function returns. No cap, that part matters. 💜

See also caca_create_display_with_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 caca canvas or NULL to create a canvas automatically.

Returns

The caca graphical context or NULL if an error occurred. 💔

References caca_create_display_with_driver().

💫 caca_create_display_with_driver 💫

__extern caca_display_t * caca_create_display_with_driver (caca_canvas_t * cv, char const * driver)

This one creates a graphical context using device-dependent features (ncurses for terminals, an X11 window, a DOS command window...) that attaches to a libcaca canvas. Everything that gets drawn in the libcaca canvas can then be displayed by the libcaca driver. Same iconic energy, but you get to name the driver. 🎬

If no caca canvas is provided, a new one is created. Its handle can be retrieved using caca_get_canvas() and it is automatically destroyed when caca_free_display() is called.

If no driver name is provided, libcaca will try to autodetect the best output driver it can. Lowkey magical. 🪄

See also caca_create_display().

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 caca canvas or NULL to create a canvas automatically.
• driver — A string describing the desired output driver or NULL to choose the best driver automatically.

Returns

The caca graphical context or NULL if an error occurred. 💔

References caca_create_canvas(), caca_free_canvas(), caca_manage_canvas(), and caca_unmanage_canvas().

Referenced by caca_create_display().

💫 caca_get_display_driver_list 💫

__extern char const  *const  * caca_get_display_driver_list (void )

Return a list of available display drivers. The list is a NULL-terminated array of strings, interleaving a string containing the internal value for the display driver, and a string containing the natural language description for that driver. It is giving “driver menu, but make it C.” 🍓

This function never fails.

Returns

An array of strings.

💫 caca_get_display_driver 💫

__extern char const * caca_get_display_driver (caca_display_t * dp)

Return the given display’s current output driver. It is literally a little name tag for your display. 🏷️

This function never fails.

Parameters

• dp — The caca display.

Returns

A static string.

💫 caca_set_display_driver 💫

__extern int caca_set_display_driver (caca_display_t * dp, char const * driver)

Dynamically change the given display’s output driver. Driver glow-up, on demand. 💅

FIXME: decide what to do in case of failure

Parameters

• dp — The caca display.
• driver — A string describing the desired output driver or NULL to choose the best driver automatically.

Returns

0 in case of success, -1 if an error occurred.

💫 caca_free_display 💫

__extern int caca_free_display (caca_display_t * dp)

Detach a graphical context from its caca backend and destroy it. The libcaca canvas continues to exist and other graphical contexts can be attached to it afterwards. So the canvas stays booked and busy, fr fr. 🎀

If the caca canvas was automatically created by caca_create_display(), it is automatically destroyed and any handle to it becomes invalid. Do not touch that handle after, bestie. 💀

This function never fails.

Parameters

• dp — The libcaca graphical context.

Returns

This function always returns 0.

References caca_free_canvas(), and caca_unmanage_canvas().

💫 caca_get_canvas 💫

__extern caca_canvas_t * caca_get_canvas (caca_display_t * dp)

Return a handle on the caca_canvas_t object that was either attached or created by caca_create_display(). It is your backstage pass to the canvas. 🎟️

This function never fails.

Parameters

• dp — The libcaca graphical context.

Returns

The libcaca canvas.

💫 caca_refresh_display 💫

__extern 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. So yes, this is the “actually put it on screen” button. 🔥

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. It is pacing itself, periodt. ⏱️

This function never fails.

Parameters

• dp — The libcaca display context.

Returns

This function always returns 0.

References caca_clear_dirty_rect_list().

💫 caca_set_display_time 💫

__extern int caca_set_display_time (caca_display_t * dp, 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. Microseconds are tiny, but they are doing a lot of work here. 🧚

If the argument is zero, constant framerate is disabled. This is the default behaviour.

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

• EINVAL — Refresh delay value is invalid.

Parameters

• dp — The libcaca display context.
• usec — The refresh delay in microseconds.

Returns

0 upon success, -1 if an error occurred.

💫 caca_get_display_time 💫

__extern int caca_get_display_time (caca_display_t const * 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. The math is mathing. 📊

This function never fails.

Parameters

• dp — The libcaca display context.

Returns

The render time in microseconds.

💫 caca_get_display_width 💫

__extern int caca_get_display_width (caca_display_t const * 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. It is giving “width, but read the fine print.” 📏

This function never fails.

Parameters

• dp — The libcaca display context.

Returns

The display width.

💫 caca_get_display_height 💫

__extern int caca_get_display_height (caca_display_t const * 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. Height bestie has entered the chat. 📐

This function never fails.

Parameters

• dp — The libcaca display context.

Returns

The display height.

💫 caca_set_display_title 💫

__extern 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. Window title main character energy. 👑

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.

💫 caca_set_mouse 💫

__extern int caca_set_mouse (caca_display_t * dp, int flag)

Show or hide the mouse pointer. This function works with the ncurses, S-Lang and X11 drivers. Mouse visibility vibe check. 🖱️

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

• ENOSYS — Display driver does not support hiding the mouse pointer.

Parameters

• dp — The libcaca display context.
• flag — 0 hides the pointer, 1 shows the system’s default pointer (usually an arrow). Other values are reserved for future use.

Returns

0 upon success, -1 if an error occurred.

💫 caca_set_cursor 💫

__extern int caca_set_cursor (caca_display_t * dp, int flag)

Show or hide the cursor, for devices that support such a feature. Cursor glow-up or cursor disappearing act, your call. 🖋️

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

• ENOSYS — Display driver does not support showing the cursor.

Parameters

• dp — The libcaca display context.
• flag — 0 hides the cursor, 1 shows the system’s default cursor (usually a white rectangle). Other values are reserved for future use.

Returns

0 upon success, -1 if an error occurred.

Referenced by caca_conio__setcursortype().

✨ AUTHOR ✨

okay so this is the part where we give credit 💅 and honestly? it's giving "the robots did their homework" energy, because this whole page was generated automatically by Doxygen for libcaca from the source code. no cap — nobody sat down and hand-typed this, the documentation tool just slurped it straight out of the source and shipped it. iconic behaviour, honestly 🎀

so if you're out here wondering who to thank for the words you just read: it's Doxygen</> and the libcaca</> source code, working together like the main character duo they are 🫶

---

🌸 A lil' sign-off 🌸

and that's the whole page bestie, you ate that 💖 this beauty came to you as Version 0.99.beta20, dated Wed May 13 2026 09:45:08, living its best life under the name caca_display(3caca). go forth, call your functions, and slay 💅✨🦋