caca_primitives(3caca)

📦
version 0.99.beta20 · 13 versions
, in opensuse-leap 16.0

💅 caca_primitives(3caca) — libcaca primitives drawing ✨

Okay bestie, so this page lives in the libcaca manual (section 3caca), and it's literally the ✨drawing era✨ of libcaca. Lines, boxes, triangles, ellipses — all the shapes, all rendered as characters on a canvas. No cap, this is the fun one. 🎨

🌸 NAME 🌸

caca_primitives — libcaca primitives drawing. That's it, that's the whole vibe. 💅

🦋 SYNOPSIS 🦋

🎀 Topics 🎀

  • libcaca canvas frame handling

🎀 Functions 🎀

  • __extern int caca_draw_line (caca_canvas_t *, int, int, int, int, uint32_t) — Draw a line on the canvas using the given character.
  • __extern int caca_draw_polyline (caca_canvas_t *, int const x[], int const y[], int, uint32_t) — Draw a polyline.
  • __extern int caca_draw_thin_line (caca_canvas_t *, int, int, int, int) — Draw a thin line on the canvas, using ASCII art.
  • __extern int caca_draw_thin_polyline (caca_canvas_t *, int const x[], int const y[], int) — Draw an ASCII art thin polyline.
  • __extern int caca_draw_circle (caca_canvas_t *, int, int, int, uint32_t) — Draw a circle on the canvas using the given character.
  • __extern int caca_draw_ellipse (caca_canvas_t *, int, int, int, int, uint32_t) — Draw an ellipse on the canvas using the given character.
  • __extern int caca_draw_thin_ellipse (caca_canvas_t *, int, int, int, int) — Draw a thin ellipse on the canvas.
  • __extern int caca_fill_ellipse (caca_canvas_t *, int, int, int, int, uint32_t) — Fill an ellipse on the canvas using the given character.
  • __extern int caca_draw_box (caca_canvas_t *, int, int, int, int, uint32_t) — Draw a box on the canvas using the given character.
  • __extern int caca_draw_thin_box (caca_canvas_t *, int, int, int, int) — Draw a thin box on the canvas.
  • __extern int caca_draw_cp437_box (caca_canvas_t *, int, int, int, int) — Draw a box on the canvas using CP437 characters.
  • __extern int caca_fill_box (caca_canvas_t *, int, int, int, int, uint32_t) — Fill a box on the canvas using the given character.
  • __extern int caca_draw_triangle (caca_canvas_t *, int, int, int, int, int, int, uint32_t) — Draw a triangle on the canvas using the given character.
  • __extern int caca_draw_thin_triangle (caca_canvas_t *, int, int, int, int, int, int) — Draw a thin triangle on the canvas.
  • __extern int caca_fill_triangle (caca_canvas_t *, int, int, int, int, int, int, uint32_t) — Fill a triangle on the canvas using the given character.
  • __extern int caca_fill_triangle_textured (caca_canvas_t *cv, int coords[6], caca_canvas_t *tex, float uv[6]) — Fill a triangle on the canvas using an arbitrary-sized texture.

🌈 DETAILED DESCRIPTION 🌈

These functions are the whole primitive drawing moment — the roster of routines for lines, boxes, triangles and ellipses. Simple as that, and honestly? Iconic. 🫶

👑 FUNCTION DOCUMENTATION 👑

💜 __extern int caca_draw_line (caca_canvas_t * cv, int x1, int y1, int x2, int y2, uint32_t ch)

This function never fails. Like, ever. It ate and left no crumbs. 💀

Parameters

  • cv — The handle to the libcaca canvas.
  • x1 — X coordinate of the first point.
  • y1 — Y coordinate of the first point.
  • x2 — X coordinate of the second point.
  • y2 — Y coordinate of the second point.
  • ch — UTF-32 character to be used to draw the line.

Returns

This function always returns 0.

Referenced by caca_draw_box(), caca_draw_triangle(), and caca_fill_ellipse().

💜 __extern int caca_draw_polyline (caca_canvas_t * cv, int const x[], int const y[], int n, uint32_t ch)

Draws a polyline on the canvas using the given character and coordinate arrays. Lowkey important detail: the first and last points are not connected, so if you want a polygon you gotta specify the starting point again at the end of the list. 🌀

This function never fails.

Parameters

  • cv — The handle to the libcaca canvas.
  • x — Array of X coordinates. Must have n + 1 elements.
  • y — Array of Y coordinates. Must have n + 1 elements.
  • n — Number of lines to draw.
  • ch — UTF-32 character to be used to draw the lines.

Returns

This function always returns 0.

💜 __extern int caca_draw_thin_line (caca_canvas_t * cv, int x1, int y1, int x2, int y2)

This function never fails. Slay.

Parameters

  • cv — The handle to the libcaca canvas.
  • x1 — X coordinate of the first point.
  • y1 — Y coordinate of the first point.
  • x2 — X coordinate of the second point.
  • y2 — Y coordinate of the second point.

Returns

This function always returns 0.

Referenced by caca_draw_thin_triangle().

💜 __extern int caca_draw_thin_polyline (caca_canvas_t * cv, int const x[], int const y[], int n)

Draws a thin polyline on the canvas using the given coordinate arrays, with ASCII art energy 🎀. Same deal as the regular polyline: first and last points are not connected, so to draw a polygon you need to specify the starting point at the end of the list too.

This function never fails.

Parameters

  • cv — The handle to the libcaca canvas.
  • x — Array of X coordinates. Must have n + 1 elements.
  • y — Array of Y coordinates. Must have n + 1 elements.
  • n — Number of lines to draw.

Returns

This function always returns 0.

💜 __extern int caca_draw_circle (caca_canvas_t * cv, int x, int y, int r, uint32_t ch)

This function never fails. ⭕

Parameters

  • cv — The handle to the libcaca canvas.
  • x — Center X coordinate.
  • y — Center Y coordinate.
  • r — Circle radius.
  • ch — UTF-32 character to be used to draw the circle outline.

Returns

This function always returns 0.

💜 __extern int caca_draw_ellipse (caca_canvas_t * cv, int xo, int yo, int a, int b, uint32_t ch)

This function never fails.

Parameters

  • cv — The handle to the libcaca canvas.
  • xo — Center X coordinate.
  • yo — Center Y coordinate.
  • a — Ellipse X radius.
  • b — Ellipse Y radius.
  • ch — UTF-32 character to be used to draw the ellipse outline.

Returns

This function always returns 0.

💜 __extern int caca_draw_thin_ellipse (caca_canvas_t * cv, int xo, int yo, int a, int b)

This function never fails.

Parameters

  • cv — The handle to the libcaca canvas.
  • xo — Center X coordinate.
  • yo — Center Y coordinate.
  • a — Ellipse X radius.
  • b — Ellipse Y radius.

Returns

This function always returns 0.

💜 __extern int caca_fill_ellipse (caca_canvas_t * cv, int xo, int yo, int a, int b, uint32_t ch)

This function never fails.

Parameters

  • cv — The handle to the libcaca canvas.
  • xo — Center X coordinate.
  • yo — Center Y coordinate.
  • a — Ellipse X radius.
  • b — Ellipse Y radius.
  • ch — UTF-32 character to be used to fill the ellipse.

Returns

This function always returns 0.

References caca_draw_line().

💜 __extern int caca_draw_box (caca_canvas_t * cv, int x, int y, int w, int h, uint32_t ch)

This function never fails. 📦

Parameters

  • cv — The handle to the libcaca canvas.
  • x — X coordinate of the upper-left corner of the box.
  • y — Y coordinate of the upper-left corner of the box.
  • w — Width of the box.
  • h — Height of the box.
  • ch — UTF-32 character to be used to draw the box.

Returns

This function always returns 0.

References caca_draw_line().

💜 __extern int caca_draw_thin_box (caca_canvas_t * cv, int x, int y, int w, int h)

This function never fails.

Parameters

  • cv — The handle to the libcaca canvas.
  • x — X coordinate of the upper-left corner of the box.
  • y — Y coordinate of the upper-left corner of the box.
  • w — Width of the box.
  • h — Height of the box.

Returns

This function always returns 0.

💜 __extern int caca_draw_cp437_box (caca_canvas_t * cv, int x, int y, int w, int h)

This function never fails. Retro CP437 box-drawing energy, we love to see it. 🕹️

Parameters

  • cv — The handle to the libcaca canvas.
  • x — X coordinate of the upper-left corner of the box.
  • y — Y coordinate of the upper-left corner of the box.
  • w — Width of the box.
  • h — Height of the box.

Returns

This function always returns 0.

💜 __extern int caca_fill_box (caca_canvas_t * cv, int x, int y, int w, int h, uint32_t ch)

This function never fails.

Parameters

  • cv — The handle to the libcaca canvas.
  • x — X coordinate of the upper-left corner of the box.
  • y — Y coordinate of the upper-left corner of the box.
  • w — Width of the box.
  • h — Height of the box.
  • ch — UTF-32 character to be used to draw the box.

Returns

This function always returns 0.

References caca_add_dirty_rect(), and caca_put_char().

Referenced by caca_conio_clreol().

💜 __extern int caca_draw_triangle (caca_canvas_t * cv, int x1, int y1, int x2, int y2, int x3, int y3, uint32_t ch)

This function never fails. 🔺

Parameters

  • cv — The handle to the libcaca canvas.
  • x1 — X coordinate of the first point.
  • y1 — Y coordinate of the first point.
  • x2 — X coordinate of the second point.
  • y2 — Y coordinate of the second point.
  • x3 — X coordinate of the third point.
  • y3 — Y coordinate of the third point.
  • ch — UTF-32 character to be used to draw the triangle outline.

Returns

This function always returns 0.

References caca_draw_line().

💜 __extern int caca_draw_thin_triangle (caca_canvas_t * cv, int x1, int y1, int x2, int y2, int x3, int y3)

This function never fails.

Parameters

  • cv — The handle to the libcaca canvas.
  • x1 — X coordinate of the first point.
  • y1 — Y coordinate of the first point.
  • x2 — X coordinate of the second point.
  • y2 — Y coordinate of the second point.
  • x3 — X coordinate of the third point.
  • y3 — Y coordinate of the third point.

Returns

This function always returns 0.

References caca_draw_thin_line().

💜 __extern int caca_fill_triangle (caca_canvas_t * cv, int x1, int y1, int x2, int y2, int x3, int y3, uint32_t ch)

This function never fails.

Parameters

  • cv — The handle to the libcaca canvas.
  • x1 — X coordinate of the first point.
  • y1 — Y coordinate of the first point.
  • x2 — X coordinate of the second point.
  • y2 — Y coordinate of the second point.
  • x3 — X coordinate of the third point.
  • y3 — Y coordinate of the third point.
  • ch — UTF-32 character to be used to fill the triangle.

Returns

This function always returns 0.

References caca_fill_triangle(), and caca_put_char().

Referenced by caca_fill_triangle().

Not a typo, bestie — it really does reference itself and get referenced by itself. The docs said it, so we're repeating it exactly. 🫡

💜 __extern int caca_fill_triangle_textured (caca_canvas_t * cv, int coords[6], caca_canvas_t * tex, float uv[6])

Okay so this one is the exception to the "never fails" era 😭 — it fails if one or both the canvas are missing.

Parameters

  • cv — The handle to the libcaca canvas.
  • coords — The coordinates of the triangle (3{x,y})
  • tex — The handle of the canvas texture.
  • uv — The coordinates of the texture (3{u,v})

Returns

This function return 0 if ok, -1 if canvas or texture are missing.

🧚 AUTHOR 🧚

Generated automatically by Doxygen for libcaca from the source code.

Mwah 💋 — that's the whole page, and it's Version 0.99.beta20, dated Wed May 13 2026 09:45:08. Go draw some triangles, bestie. 🎀🦋✨

📦 where this page comes from