---
name: "cucul.h"
section: "3caca"
platform: "linux"
package: "libcucul-dev"
version: "0.99.beta14-1"
release: "Debian 5.0 (Lenny)"
platforms: ["linux"]
url: "https://new.carta.tech/cucul.h"
---

# cucul.h(3caca)

The libcucul public header.

## NAME

cucul.h - The *libcucul* public header.

## SYNOPSIS

### Defines

\#define **CUCUL\_API\_VERSION\_1**\
 \#define **CUCUL\_BLACK**   0x00\
 \#define **CUCUL\_BLUE**   0x01\
 \#define **CUCUL\_GREEN**   0x02\
 \#define **CUCUL\_CYAN**   0x03\
 \#define **CUCUL\_RED**   0x04\
 \#define **CUCUL\_MAGENTA**   0x05\
 \#define **CUCUL\_BROWN**   0x06\
 \#define **CUCUL\_LIGHTGRAY**   0x07\
 \#define **CUCUL\_DARKGRAY**   0x08\
 \#define **CUCUL\_LIGHTBLUE**   0x09\
 \#define **CUCUL\_LIGHTGREEN**   0x0a\
 \#define **CUCUL\_LIGHTCYAN**   0x0b\
 \#define **CUCUL\_LIGHTRED**   0x0c\
 \#define **CUCUL\_LIGHTMAGENTA**   0x0d\
 \#define **CUCUL\_YELLOW**   0x0e\
 \#define **CUCUL\_WHITE**   0x0f\
 \#define **CUCUL\_DEFAULT**   0x10\
 \#define **CUCUL\_TRANSPARENT**   0x20\
 \#define **CUCUL\_BOLD**   0x01\
 \#define **CUCUL\_ITALICS**   0x02\
 \#define **CUCUL\_UNDERLINE**   0x04\
 \#define **CUCUL\_BLINK**   0x08\
 \#define **CUCUL\_MAGIC\_FULLWIDTH**   0x000ffffe\

### Typedefs

typedef struct cucul\_canvas **cucul\_canvas\_t**\
 typedef struct cucul\_dither **cucul\_dither\_t**\
 typedef struct cucul\_font **cucul\_font\_t**\
 typedef struct cucul\_file **cucul\_file\_t**\

### Functions

\_\_extern **cucul\_canvas\_t** \* **cucul\_create\_canvas** (int, int)\
 *Initialise a libcucul canvas.*  \_\_extern int **cucul\_manage\_canvas** (**cucul\_canvas\_t** \*, int(\*)(void \*), void \*)\
 *Manage a canvas.*  \_\_extern int **cucul\_unmanage\_canvas** (**cucul\_canvas\_t** \*, int(\*)(void \*), void \*)\
 *Unmanage a canvas.*  \_\_extern int **cucul\_set\_canvas\_size** (**cucul\_canvas\_t** \*, int, int)\
 *Resize a canvas.*  \_\_extern int **cucul\_get\_canvas\_width** (**cucul\_canvas\_t** const \*)\
 *Get the canvas width.*  \_\_extern int **cucul\_get\_canvas\_height** (**cucul\_canvas\_t** const \*)\
 *Get the canvas height.*  \_\_extern uint8\_t const \* **cucul\_get\_canvas\_chars** (**cucul\_canvas\_t** const \*)\
 *Get the canvas character array.*  \_\_extern uint8\_t const \* **cucul\_get\_canvas\_attrs** (**cucul\_canvas\_t** const \*)\
 *Get the canvas attribute array.*  \_\_extern int **cucul\_free\_canvas** (**cucul\_canvas\_t** \*)\
 *Uninitialise libcucul.*  \_\_extern int **cucul\_rand** (int, int)\
 *Generate a random integer within a range.*  \_\_extern char const \* **cucul\_get\_version** (void)\
 *Return the libcucul version.*  \_\_extern int **cucul\_gotoxy** (**cucul\_canvas\_t** \*, int, int)\
 *Set cursor position.*  \_\_extern int **cucul\_get\_cursor\_x** (**cucul\_canvas\_t** const \*)\
 *Get X cursor position.*  \_\_extern int **cucul\_get\_cursor\_y** (**cucul\_canvas\_t** const \*)\
 *Get Y cursor position.*  \_\_extern int **cucul\_put\_char** (**cucul\_canvas\_t** \*, int, int, uint32\_t)\
 *Print an ASCII or Unicode character.*  \_\_extern uint32\_t **cucul\_get\_char** (**cucul\_canvas\_t** const \*, int, int)\
 *Get the Unicode character at the given coordinates.*  \_\_extern int **cucul\_put\_str** (**cucul\_canvas\_t** \*, int, int, char const \*)\
 *Print a string.*  \_\_extern uint32\_t **cucul\_get\_attr** (**cucul\_canvas\_t** const \*, int, int)\
 *Get the text attribute at the given coordinates.*  \_\_extern int **cucul\_set\_attr** (**cucul\_canvas\_t** \*, uint32\_t)\
 *Set the default character attribute.*  \_\_extern int **cucul\_put\_attr** (**cucul\_canvas\_t** \*, int, int, uint32\_t)\
 *Set the character attribute at the given coordinates.*  \_\_extern int **cucul\_set\_color\_ansi** (**cucul\_canvas\_t** \*, uint8\_t, uint8\_t)\
 *Set the default colour pair for text (ANSI version).*  \_\_extern int **cucul\_set\_color\_argb** (**cucul\_canvas\_t** \*, uint16\_t, uint16\_t)\
 *Set the default colour pair for text (truecolor version).*  \_\_extern int **cucul\_printf** (**cucul\_canvas\_t** \*, int, int, char const \*,...)\
 *Print a formated string.*  \_\_extern int **cucul\_clear\_canvas** (**cucul\_canvas\_t** \*)\
 *Clear the canvas.*  \_\_extern int **cucul\_set\_canvas\_handle** (**cucul\_canvas\_t** \*, int, int)\
 *Set cursor handle.*  \_\_extern int **cucul\_get\_canvas\_handle\_x** (**cucul\_canvas\_t** const \*)\
 *Get X handle position.*  \_\_extern int **cucul\_get\_canvas\_handle\_y** (**cucul\_canvas\_t** const \*)\
 *Get Y handle position.*  \_\_extern int **cucul\_blit** (**cucul\_canvas\_t** \*, int, int, **cucul\_canvas\_t** const \*, **cucul\_canvas\_t** const \*)\
 *Blit a canvas onto another one.*  \_\_extern int **cucul\_set\_canvas\_boundaries** (**cucul\_canvas\_t** \*, int, int, int, int)\
 *Set a canvas' new boundaries.*  \_\_extern int **cucul\_invert** (**cucul\_canvas\_t** \*)\
 *Invert a canvas' colours.*  \_\_extern int **cucul\_flip** (**cucul\_canvas\_t** \*)\
 *Flip a canvas horizontally.*  \_\_extern int **cucul\_flop** (**cucul\_canvas\_t** \*)\
 *Flip a canvas vertically.*  \_\_extern int **cucul\_rotate\_180** (**cucul\_canvas\_t** \*)\
 *Rotate a canvas.*  \_\_extern int **cucul\_rotate\_left** (**cucul\_canvas\_t** \*)\
 *Rotate a canvas, 90 degrees counterclockwise.*  \_\_extern int **cucul\_rotate\_right** (**cucul\_canvas\_t** \*)\
 *Rotate a canvas, 90 degrees counterclockwise.*  \_\_extern int **cucul\_stretch\_left** (**cucul\_canvas\_t** \*)\
 *Rotate and stretch a canvas, 90 degrees counterclockwise.*  \_\_extern int **cucul\_stretch\_right** (**cucul\_canvas\_t** \*)\
 *Rotate and stretch a canvas, 90 degrees clockwise.*  \_\_extern uint8\_t **cucul\_attr\_to\_ansi** (uint32\_t)\
 *Get DOS ANSI information from attribute.*  \_\_extern uint8\_t **cucul\_attr\_to\_ansi\_fg** (uint32\_t)\
 *Get ANSI foreground information from attribute.*  \_\_extern uint8\_t **cucul\_attr\_to\_ansi\_bg** (uint32\_t)\
 *Get ANSI background information from attribute.*  \_\_extern uint16\_t **cucul\_attr\_to\_rgb12\_fg** (uint32\_t)\
 *Get 12-bit RGB foreground information from attribute.*  \_\_extern uint16\_t **cucul\_attr\_to\_rgb12\_bg** (uint32\_t)\
 *Get 12-bit RGB background information from attribute.*  \_\_extern void **cucul\_attr\_to\_argb64** (uint32\_t, uint8\_t\[8\])\
 *Get 64-bit ARGB information from attribute.*  \_\_extern uint32\_t **cucul\_utf8\_to\_utf32** (char const \*, size\_t \*)\
 *Convert a UTF-8 character to UTF-32.*  \_\_extern size\_t **cucul\_utf32\_to\_utf8** (char \*, uint32\_t)\
 *Convert a UTF-32 character to UTF-8.*  \_\_extern uint8\_t **cucul\_utf32\_to\_cp437** (uint32\_t)\
 *Convert a UTF-32 character to CP437.*  \_\_extern uint32\_t **cucul\_cp437\_to\_utf32** (uint8\_t)\
 *Convert a CP437 character to UTF-32.*  \_\_extern char **cucul\_utf32\_to\_ascii** (uint32\_t)\
 *Convert a UTF-32 character to ASCII.*  \_\_extern int **cucul\_utf32\_is\_fullwidth** (uint32\_t)\
 *Tell whether a UTF-32 character is fullwidth.*  \_\_extern int **cucul\_draw\_line** (**cucul\_canvas\_t** \*, int, int, int, int, uint32\_t)\
 *Draw a line on the canvas using the given character.*  \_\_extern int **cucul\_draw\_polyline** (**cucul\_canvas\_t** \*, int const x\[\], int const y\[\], int, uint32\_t)\
 *Draw a polyline.*  \_\_extern int **cucul\_draw\_thin\_line** (**cucul\_canvas\_t** \*, int, int, int, int)\
 *Draw a thin line on the canvas, using ASCII art.*  \_\_extern int **cucul\_draw\_thin\_polyline** (**cucul\_canvas\_t** \*, int const x\[\], int const y\[\], int)\
 *Draw an ASCII art thin polyline.*  \_\_extern int **cucul\_draw\_circle** (**cucul\_canvas\_t** \*, int, int, int, uint32\_t)\
 *Draw a circle on the canvas using the given character.*  \_\_extern int **cucul\_draw\_ellipse** (**cucul\_canvas\_t** \*, int, int, int, int, uint32\_t)\
 *Draw an ellipse on the canvas using the given character.*  \_\_extern int **cucul\_draw\_thin\_ellipse** (**cucul\_canvas\_t** \*, int, int, int, int)\
 *Draw a thin ellipse on the canvas.*  \_\_extern int **cucul\_fill\_ellipse** (**cucul\_canvas\_t** \*, int, int, int, int, uint32\_t)\
 *Fill an ellipse on the canvas using the given character.*  \_\_extern int **cucul\_draw\_box** (**cucul\_canvas\_t** \*, int, int, int, int, uint32\_t)\
 *Draw a box on the canvas using the given character.*  \_\_extern int **cucul\_draw\_thin\_box** (**cucul\_canvas\_t** \*, int, int, int, int)\
 *Draw a thin box on the canvas.*  \_\_extern int **cucul\_draw\_cp437\_box** (**cucul\_canvas\_t** \*, int, int, int, int)\
 *Draw a box on the canvas using CP437 characters.*  \_\_extern int **cucul\_fill\_box** (**cucul\_canvas\_t** \*, int, int, int, int, uint32\_t)\
 *Fill a box on the canvas using the given character.*  \_\_extern int **cucul\_draw\_triangle** (**cucul\_canvas\_t** \*, int, int, int, int, int, int, uint32\_t)\
 *Draw a triangle on the canvas using the given character.*  \_\_extern int **cucul\_draw\_thin\_triangle** (**cucul\_canvas\_t** \*, int, int, int, int, int, int)\
 *Draw a thin triangle on the canvas.*  \_\_extern int **cucul\_fill\_triangle** (**cucul\_canvas\_t** \*, int, int, int, int, int, int, uint32\_t)\
 *Fill a triangle on the canvas using the given character.*  \_\_extern int **cucul\_get\_frame\_count** (**cucul\_canvas\_t** const \*)\
 *Get the number of frames in a canvas.*  \_\_extern int **cucul\_set\_frame** (**cucul\_canvas\_t** \*, int)\
 *Activate a given canvas frame.*  \_\_extern char const \* **cucul\_get\_frame\_name** (**cucul\_canvas\_t** const \*)\
 *Get the current frame's name.*  \_\_extern int **cucul\_set\_frame\_name** (**cucul\_canvas\_t** \*, char const \*)\
 *Set the current frame's name.*  \_\_extern int **cucul\_create\_frame** (**cucul\_canvas\_t** \*, int)\
 *Add a frame to a canvas.*  \_\_extern int **cucul\_free\_frame** (**cucul\_canvas\_t** \*, int)\
 *Remove a frame from a canvas.*  \_\_extern **cucul\_dither\_t** \* **cucul\_create\_dither** (int, int, int, int, uint32\_t, uint32\_t, uint32\_t, uint32\_t)\
 *Create an internal dither object.*  \_\_extern int **cucul\_set\_dither\_palette** (**cucul\_dither\_t** \*, uint32\_t r\[\], uint32\_t g\[\], uint32\_t b\[\], uint32\_t a\[\])\
 *Set the palette of an 8bpp dither object.*  \_\_extern int **cucul\_set\_dither\_brightness** (**cucul\_dither\_t** \*, float)\
 *Set the brightness of a dither object.*  \_\_extern float **cucul\_get\_dither\_brightness** (**cucul\_dither\_t** const \*)\
 *Get the brightness of a dither object.*  \_\_extern int **cucul\_set\_dither\_gamma** (**cucul\_dither\_t** \*, float)\
 *Set the gamma of a dither object.*  \_\_extern float **cucul\_get\_dither\_gamma** (**cucul\_dither\_t** const \*)\
 *Get the gamma of a dither object.*  \_\_extern int **cucul\_set\_dither\_contrast** (**cucul\_dither\_t** \*, float)\
 *Set the contrast of a dither object.*  \_\_extern float **cucul\_get\_dither\_contrast** (**cucul\_dither\_t** const \*)\
 *Get the contrast of a dither object.*  \_\_extern int **cucul\_set\_dither\_antialias** (**cucul\_dither\_t** \*, char const \*)\
 *Set dither antialiasing.*  \_\_extern char const \*const \* **cucul\_get\_dither\_antialias\_list** (**cucul\_dither\_t** const \*)\
 *Get available antialiasing methods.*  \_\_extern char const \* **cucul\_get\_dither\_antialias** (**cucul\_dither\_t** const \*)\
 *Get current antialiasing method.*  \_\_extern int **cucul\_set\_dither\_color** (**cucul\_dither\_t** \*, char const \*)\
 *Choose colours used for dithering.*  \_\_extern char const \*const \* **cucul\_get\_dither\_color\_list** (**cucul\_dither\_t** const \*)\
 *Get available colour modes.*  \_\_extern char const \* **cucul\_get\_dither\_color** (**cucul\_dither\_t** const \*)\
 *Get current colour mode.*  \_\_extern int **cucul\_set\_dither\_charset** (**cucul\_dither\_t** \*, char const \*)\
 *Choose characters used for dithering.*  \_\_extern char const \*const \* **cucul\_get\_dither\_charset\_list** (**cucul\_dither\_t** const \*)\
 *Get available dither character sets.*  \_\_extern char const \* **cucul\_get\_dither\_charset** (**cucul\_dither\_t** const \*)\
 *Get current character set.*  \_\_extern int **cucul\_set\_dither\_algorithm** (**cucul\_dither\_t** \*, char const \*)\
 *Set dithering algorithm.*  \_\_extern char const \*const \* **cucul\_get\_dither\_algorithm\_list** (**cucul\_dither\_t** const \*)\
 *Get dithering algorithms.*  \_\_extern char const \* **cucul\_get\_dither\_algorithm** (**cucul\_dither\_t** const \*)\
 *Get current dithering algorithm.*  \_\_extern int **cucul\_dither\_bitmap** (**cucul\_canvas\_t** \*, int, int, int, int, **cucul\_dither\_t** const \*, void \*)\
 *Dither a bitmap on the canvas.*  \_\_extern int **cucul\_free\_dither** (**cucul\_dither\_t** \*)\
 *Free the memory associated with a dither.*  \_\_extern **cucul\_font\_t** \* **cucul\_load\_font** (void const \*, size\_t)\
 *Load a font from memory for future use.*  \_\_extern char const \*const \* **cucul\_get\_font\_list** (void)\
 *Get available builtin fonts.*  \_\_extern int **cucul\_get\_font\_width** (**cucul\_font\_t** const \*)\
 *Get a font's standard glyph width.*  \_\_extern int **cucul\_get\_font\_height** (**cucul\_font\_t** const \*)\
 *Get a font's standard glyph height.*  \_\_extern uint32\_t const \* **cucul\_get\_font\_blocks** (**cucul\_font\_t** const \*)\
 *Get a font's list of supported glyphs.*  \_\_extern int **cucul\_render\_canvas** (**cucul\_canvas\_t** const \*, **cucul\_font\_t** const \*, void \*, int, int, int)\
 *Render the canvas onto an image buffer.*  \_\_extern int **cucul\_free\_font** (**cucul\_font\_t** \*)\
 *Free a font structure.*  \_\_extern int **cucul\_canvas\_set\_figfont** (**cucul\_canvas\_t** \*, char const \*)\
 \_\_extern int **cucul\_put\_figchar** (**cucul\_canvas\_t** \*, uint32\_t)\
 \_\_extern int **cucul\_flush\_figlet** (**cucul\_canvas\_t** \*)\
 \_\_extern **cucul\_file\_t** \* **cucul\_file\_open** (char const \*, const char \*)\
 \_\_extern int **cucul\_file\_close** (**cucul\_file\_t** \*)\
 \_\_extern uint64\_t **cucul\_file\_tell** (**cucul\_file\_t** \*)\
 \_\_extern size\_t **cucul\_file\_read** (**cucul\_file\_t** \*, void \*, size\_t)\
 \_\_extern size\_t **cucul\_file\_write** (**cucul\_file\_t** \*, const void \*, size\_t)\
 \_\_extern char \* **cucul\_file\_gets** (**cucul\_file\_t** \*, char \*, int)\
 \_\_extern int **cucul\_file\_eof** (**cucul\_file\_t** \*)\
 \_\_extern ssize\_t **cucul\_import\_memory** (**cucul\_canvas\_t** \*, void const \*, size\_t, char const \*)\
 *Import a memory buffer into a canvas.*  \_\_extern ssize\_t **cucul\_import\_file** (**cucul\_canvas\_t** \*, char const \*, char const \*)\
 *Import a file into a canvas.*  \_\_extern char const \*const \* **cucul\_get\_import\_list** (void)\
 *Get available import formats.*  \_\_extern void \* **cucul\_export\_memory** (**cucul\_canvas\_t** const \*, char const \*, size\_t \*)\
 *Export a canvas into a foreign format.*  \_\_extern char const \*const \* **cucul\_get\_export\_list** (void)\
 *Get available export formats.*

## Detailed Description

**Version:**

$Id$

**Author:**

Sam Hocevar \<sam@zoy.org\> This header contains the public types and functions that applications using *libcucul* may use.

## Define Documentation

### #define CUCUL\_API\_VERSION\_1

libcucul API version

## Typedef Documentation

### typedef struct cucul\_canvas cucul\_canvas\_t

*libcucul* canvas

### typedef struct cucul\_dither cucul\_dither\_t

dither structure

### typedef struct cucul\_font cucul\_font\_t

font structure

### typedef struct cucul\_file cucul\_file\_t

file handle structure

## Author

Generated automatically by Doxygen for libcaca from the source code.