caca_frame(3caca)

🎀 caca_frame — libcaca canvas frame handling 🎀

ok so this is the caca_frame page from the libcaca manual (section 3caca, bestie 💅) and it's literally all about handling frames inside a canvas. yes. frames. like layers. we love a layered queen 👑

---

✨ SYNOPSIS ✨

🦋 Topics

• libcaca bitmap dithering

🌸 Functions

• __extern int caca_get_frame_count (caca_canvas_t const *) — Get the number of frames in a canvas.
• __extern int caca_set_frame (caca_canvas_t *, int) — Activate a given canvas frame.
• __extern char const * caca_get_frame_name (caca_canvas_t const *) — Get the current frame's name.
• __extern int caca_set_frame_name (caca_canvas_t *, char const *) — Set the current frame's name.
• __extern int caca_create_frame (caca_canvas_t *, int) — Add a frame to a canvas.
• __extern int caca_free_frame (caca_canvas_t *, int) — Remove a frame from a canvas.

---

💜 Detailed Description

ok so these functions are the high level routines for canvas frame insertion, removal, copying etc. that's the whole vibe. insert, remove, copy. iconic behaviour, no notes 🫶

---

👑 Function Documentation 👑

🌈 __extern int caca_get_frame_count (caca_canvas_t const * cv)

Returns the current canvas' frame count. that's it. that's the function 💖

This function never fails. like, ever. she's reliable.

Parameters

• cv — A libcaca canvas

Returns

• The frame count

Referenced by caca_set_canvas_boundaries().

---

⭐ __extern int caca_set_frame (caca_canvas_t * cv, int id)

Sets the active canvas frame. every drawing operation after this one gets performed on that frame 🎨 The current painting context set by caca_set_attr() is inherited — yes, inherited, we love a hand-me-down.

If the frame index is outside the canvas' frame range, nothing happens. literally nothing. silence. 💀

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

• EINVAL — Requested frame is out of range.

Parameters

• cv — A libcaca canvas
• id — The canvas frame to activate

Returns

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

References caca_add_dirty_rect().

Referenced by caca_set_canvas_boundaries().

---

🧚 __extern char const * caca_get_frame_name (caca_canvas_t const * cv)

Returns the current frame's name 🏷️ The returned string is valid until the frame is deleted or caca_set_frame_name() is called to change the frame name again — so like, don't go holding onto it forever, bestie, it's giving "borrowed, not gifted" 🙈

This function never fails.

Parameters

• cv — A libcaca canvas.

Returns

• The current frame's name.

---

🌸 __extern int caca_set_frame_name (caca_canvas_t * cv, char const * name)

Sets the current frame's name ✨ Fun fact: upon creation, a frame has a default name of "frame#xxxxxxxx" where xxxxxxxx is a self-incrementing hexadecimal number. so she comes pre-named, but you can absolutely rename her.

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

• ENOMEM — Not enough memory to allocate new frame.

Parameters

• cv — A libcaca canvas.
• name — The name to give to the current frame.

Returns

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

---

🍓 __extern int caca_create_frame (caca_canvas_t * cv, int id)

Creates a new frame within the given canvas 🆕 Its contents and attributes are copied from the currently active frame — so it's a whole clone situation, main character duplicating herself.

The frame index indicates where the frame should be inserted. Valid values range from 0 to the current canvas frame count. If the frame index is greater than or equals the current canvas frame count, the new frame is appended at the end of the canvas. If the frame index is less than zero, the new frame is inserted at index 0. so like: too big = end, negative = front. no in-between drama 💅

The active frame does not change, but its index may be renumbered due to the insertion. so watch out, her number might shift and that's not her fault.

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

• ENOMEM — Not enough memory to allocate new frame.

Parameters

• cv — A libcaca canvas
• id — The index where to insert the new frame

Returns

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

Referenced by caca_set_canvas_boundaries().

---

🔥 __extern int caca_free_frame (caca_canvas_t * cv, int id)

Deletes a frame from a given canvas. goodbye frame, you had a good run 😭

The frame index indicates the frame to delete. Valid values range from 0 to the current canvas frame count minus 1. If the frame index is greater than or equals the current canvas frame count, the last frame is deleted. yes, it just nukes the last one. chaotic but that's the rule.

If the active frame is deleted, frame 0 becomes the new active frame. Otherwise, the active frame does not change, but its index may be renumbered due to the deletion. again with the renumbering, she's always going through something.

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

• EINVAL — Requested frame is out of range, or attempt to delete the last frame of the canvas.

⚠️ okay important: trying to delete the last frame of the canvas is an error (EINVAL). can't have zero frames, bestie, the canvas would be empty and honestly kind of nothing.

Parameters

• cv — A libcaca canvas
• id — The index of the frame to delete

Returns

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

References caca_add_dirty_rect().

---

💖 Author

Generated automatically by Doxygen for libcaca from the source code. (not a human, not a vibe, just doxygen doing doxygen things)

---

and that's the whole page, bestie 🫶 this one's from libcaca version 0.99.beta20, dated Wed May 13 2026 09:45:08, and it's filed under caca_frame(3caca) for all your frame-handling needs. go forth and slay those frames ✨🎀💜