---
name: "caca_primitives"
section: "3caca"
platform: "linux"
package: "libcaca"
version: "0.99.beta20-7"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/caca_primitives"
---

# caca\_primitives(3caca)

libcaca primitives drawing

## NAME

caca\_primitives - libcaca primitives drawing

## 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 provide routines for primitive drawing, such as lines, boxes, triangles and ellipses.

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

**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)

Draw a polyline on the canvas using the given character and coordinate arrays. The first and last points are not connected, hence in order to draw a polygon you need to specify the starting point at the end of the list as well.

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.

**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)

Draw a thin polyline on the canvas using the given coordinate arrays and with ASCII art. The first and last points are not connected, so in order to draw a polygon you need to specify the starting point at the end of the list as well.

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.

**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()**.

### \_\_extern int caca\_fill\_triangle\_textured (caca\_canvas\_t \* cv, int coords\[6\], caca\_canvas\_t \* tex, float uv\[6\])

This function 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.