libcucul canvas drawing


Defines
#define	CUCUL_MAGIC_FULLWIDTH 0x000ffffe
Functions
__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.

Detailed Description

These functions provide low-level character printing routines and higher level graphics functions.

Define Documentation

#define CUCUL_MAGIC_FULLWIDTH 0x000ffffe

Used to indicate that the previous character was a fullwidth glyph.

Referenced by cucul_blit(), cucul_flip(), cucul_put_attr(), cucul_put_char(), and cucul_rotate_180().

Function Documentation

__extern int cucul_gotoxy	(	cucul_canvas_t *	cv,
		int	x,
		int	y
	)

Put the cursor at the given coordinates. Functions making use of the cursor will use the new values. Setting the cursor position outside the canvas is legal but the cursor will not be shown.

This function never fails.

Parameters:

	cv	A handle to the libcucul canvas.
	x	X cursor coordinate.
	y	Y cursor coordinate.

Returns:: This function always returns 0.

__extern int cucul_get_cursor_x ( cucul_canvas_t const * cv )

Retrieve the X coordinate of the cursor's position.

This function never fails.

Parameters:

cv

A handle to the libcucul canvas.

Returns:: The cursor's X coordinate.

__extern int cucul_get_cursor_y ( cucul_canvas_t const * cv )

Retrieve the Y coordinate of the cursor's position.

This function never fails.

Parameters:

cv

A handle to the libcucul canvas.

Returns:: The cursor's Y coordinate.

__extern int cucul_put_char	(	cucul_canvas_t *	cv,
		int	x,
		int	y,
		uint32_t	ch
	)

Print an ASCII or Unicode character at the given coordinates, using the default foreground and background colour values.

If the coordinates are outside the canvas boundaries, nothing is printed. If a fullwidth Unicode character gets overwritten, its remaining visible parts are replaced with spaces. If the canvas' boundaries would split the fullwidth character in two, a space is printed instead.

The behaviour when printing non-printable characters or invalid UTF-32 characters is undefined. To print a sequence of bytes forming an UTF-8 character instead of an UTF-32 character, use the cucul_put_str() function.

This function never fails.

Parameters:

	cv	A handle to the libcucul canvas.
	x	X coordinate.
	y	Y coordinate.
	ch	The character to print.

Returns:: This function always returns 0.

References CUCUL_MAGIC_FULLWIDTH, and cucul_utf32_is_fullwidth().

Referenced by cucul_dither_bitmap(), cucul_draw_cp437_box(), cucul_draw_thin_box(), cucul_fill_box(), cucul_fill_triangle(), and cucul_put_str().

__extern uint32_t cucul_get_char	(	cucul_canvas_t const *	cv,
		int	x,
		int	y
	)

Get the ASCII or Unicode value of the character at the given coordinates. If the value is less or equal to 127 (0x7f), the character can be printed as ASCII. Otherise, it must be handled as a UTF-32 value.

If the coordinates are outside the canvas boundaries, a space (0x20) is returned.

A special exception is when CUCUL_MAGIC_FULLWIDTH is returned. This value is guaranteed not to be a valid Unicode character, and indicates that the character at the left of the requested one is a fullwidth character.

This function never fails.

Parameters:

	cv	A handle to the libcucul canvas.
	x	X coordinate.
	y	Y coordinate.

Returns:: This function always returns 0.

__extern int cucul_put_str	(	cucul_canvas_t *	cv,
		int	x,
		int	y,
		char const *	s
	)

Print an UTF-8 string at the given coordinates, using the default foreground and background values. The coordinates may be outside the canvas boundaries (eg. a negative Y coordinate) and the string will be cropped accordingly if it is too long.

See cucul_put_char() for more information on how fullwidth characters are handled when overwriting each other or at the canvas' boundaries.

This function never fails.

Parameters:

	cv	A handle to the libcucul canvas.
	x	X coordinate.
	y	Y coordinate.
	s	The string to print.

Returns:: This function always returns 0.

References cucul_put_char(), cucul_utf32_is_fullwidth(), and cucul_utf8_to_utf32().

Referenced by cucul_printf().

__extern uint32_t cucul_get_attr	(	cucul_canvas_t const *	cv,
		int	x,
		int	y
	)

Get the internal libcucul attribute value of the character at the given coordinates. The attribute value has 32 significant bits, organised as follows from MSB to LSB:

3 bits for the background alpha
4 bits for the background red component
4 bits for the background green component
3 bits for the background blue component
3 bits for the foreground alpha
4 bits for the foreground red component
4 bits for the foreground green component
3 bits for the foreground blue component
4 bits for the bold, italics, underline and blink flags

If the coordinates are outside the canvas boundaries, the current attribute is returned.

This function never fails.

Parameters:

	cv	A handle to the libcucul canvas.
	x	X coordinate.
	y	Y coordinate.

Returns:: The requested attribute.

Referenced by cucul_dither_bitmap().

__extern int cucul_set_attr	(	cucul_canvas_t *	cv,
		uint32_t	attr
	)

Set the default character attribute for drawing. Attributes define foreground and background colour, transparency, bold, italics and underline styles, as well as blink. String functions such as caca_printf() and graphical primitive functions such as caca_draw_line() will use this attribute.

The value of attr is either:

a 32-bit integer as returned by cucul_get_attr(), in which case it also contains colour information,
a combination (bitwise OR) of style values (CUCUL_UNDERLINE, CUCUL_BLINK, CUCUL_BOLD and CUCUL_ITALICS), in which case setting the attribute does not modify the current colour information.

To retrieve the current attribute value, use cucul_get_attr(-1,-1).

This function never fails.

Parameters:

	cv	A handle to the libcucul canvas.
	attr	The requested attribute value.

Returns:: This function always returns 0.

Referenced by cucul_dither_bitmap().

__extern int cucul_put_attr	(	cucul_canvas_t *	cv,
		int	x,
		int	y,
		uint32_t	attr
	)

Set the character attribute, without changing the character's value. If the character at the given coordinates is a fullwidth character, both cells' attributes are replaced.

The value of attr is either:

a 32-bit integer as returned by cucul_get_attr(), in which case it also contains colour information,
a combination (bitwise OR) of style values (CUCUL_UNDERLINE, CUCUL_BLINK, CUCUL_BOLD and CUCUL_ITALICS), in which case setting the attribute does not modify the current colour information.

This function never fails.

Parameters:

	cv	A handle to the libcucul canvas.
	x	X coordinate.
	y	Y coordinate.
	attr	The requested attribute value.

Returns:: This function always returns 0.

References CUCUL_MAGIC_FULLWIDTH.

__extern int cucul_set_color_ansi	(	cucul_canvas_t *	cv,
		uint8_t	fg,
		uint8_t	bg
	)

Set the default ANSI colour pair for text drawing. String functions such as caca_printf() and graphical primitive functions such as caca_draw_line() will use these attributes.

Color values are those defined in cucul.h, such as CUCUL_RED or CUCUL_TRANSPARENT.

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

EINVAL At least one of the colour values is invalid.

Parameters:

	cv	A handle to the libcucul canvas.
	fg	The requested ANSI foreground colour.
	bg	The requested ANSI background colour.

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

Referenced by cucul_create_canvas(), and cucul_dither_bitmap().

__extern int cucul_set_color_argb	(	cucul_canvas_t *	cv,
		uint16_t	fg,
		uint16_t	bg
	)

Set the default ARGB colour pair for text drawing. String functions such as caca_printf() and graphical primitive functions such as caca_draw_line() will use these attributes.

Colors are 16-bit ARGB values, each component being coded on 4 bits. For instance, 0xf088 is solid dark cyan (A=15 R=0 G=8 B=8), and 0x8fff is white with 50% alpha (A=8 R=15 G=15 B=15).

This function never fails.

Parameters:

	cv	A handle to the libcucul canvas.
	fg	The requested ARGB foreground colour.
	bg	The requested ARGB background colour.

Returns:: This function always returns 0.

__extern int cucul_printf	(	cucul_canvas_t *	cv,
		int	x,
		int	y,
		char const *	format,
			...
	)

Format a string at the given coordinates, using the default foreground and background values. The coordinates may be outside the canvas boundaries (eg. a negative Y coordinate) and the string will be cropped accordingly if it is too long. The syntax of the format string is the same as for the C printf() function.

This function never fails.

Parameters:

	cv	A handle to the libcucul canvas.
	x	X coordinate.
	y	Y coordinate.
	format	The format string to print.
	...	Arguments to the format string.

Returns:: This function always returns 0.

References cucul_put_str().

__extern int cucul_clear_canvas ( cucul_canvas_t * cv )

Clear the canvas using the current foreground and background colours.

This function never fails.

Parameters:

cv

The canvas to clear.

Returns:: This function always returns 0.

__extern int cucul_set_canvas_handle	(	cucul_canvas_t *	cv,
		int	x,
		int	y
	)

Set the canvas' handle. Blitting functions will use the handle value to put the canvas at the proper coordinates.

This function never fails.

Parameters:

	cv	A handle to the libcucul canvas.
	x	X handle coordinate.
	y	Y handle coordinate.

Returns:: This function always returns 0.

__extern int cucul_get_canvas_handle_x ( cucul_canvas_t const * cv )

Retrieve the X coordinate of the canvas' handle.

This function never fails.

Parameters:

cv

A handle to the libcucul canvas.

Returns:: The canvas' handle's X coordinate.

__extern int cucul_get_canvas_handle_y ( cucul_canvas_t const * cv )

Retrieve the Y coordinate of the canvas' handle.

This function never fails.

Parameters:

cv

A handle to the libcucul canvas.

Returns:: The canvas' handle's Y coordinate.

__extern int cucul_blit	(	cucul_canvas_t *	dst,
		int	x,
		int	y,
		cucul_canvas_t const *	src,
		cucul_canvas_t const *	mask
	)

Blit a canvas onto another one at the given coordinates. An optional mask canvas can be used.

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

EINVAL A mask was specified but the mask size and source canvas size do not match.

Parameters:

	dst	The destination canvas.
	x	X coordinate.
	y	Y coordinate.
	src	The source canvas.
	mask	The mask canvas.

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

References CUCUL_MAGIC_FULLWIDTH.

Referenced by cucul_set_canvas_boundaries().

__extern int cucul_set_canvas_boundaries	(	cucul_canvas_t *	cv,
		int	x,
		int	y,
		int	w,
		int	h
	)

Set new boundaries for a canvas. This function can be used to crop a canvas, to expand it or for combinations of both actions. All frames are affected by this function.

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

EINVAL Specified width or height is invalid.
EBUSY The canvas is in use by a display driver and cannot be resized.
ENOMEM Not enough memory for the requested canvas size. If this happens, the canvas handle becomes invalid and should not be used.

Parameters:

	cv	The canvas to crop.
	x	X coordinate of the top-left corner.
	y	Y coordinate of the top-left corner.
	w	The width of the cropped area.
	h	The height of the cropped area.

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

References cucul_blit(), cucul_create_canvas(), cucul_create_frame(), cucul_get_frame_count(), and cucul_set_frame().

libcucul canvas drawing

Defines

Functions

Detailed Description

Define Documentation

Function Documentation