libcaca bitmap dithering

Modules
	libcaca character font handling

Functions
__extern caca_dither_t *	caca_create_dither (int, int, int, int, uint32_t, uint32_t, uint32_t, uint32_t)
	Create an internal dither object.
__extern int	caca_set_dither_palette (caca_dither_t *, uint32_t r[], uint32_t g[], uint32_t b[], uint32_t a[])
	Set the palette of an 8bpp dither object.
__extern int	caca_set_dither_brightness (caca_dither_t *, float)
	Set the brightness of a dither object.
__extern float	caca_get_dither_brightness (caca_dither_t const *)
	Get the brightness of a dither object.
__extern int	caca_set_dither_gamma (caca_dither_t *, float)
	Set the gamma of a dither object.
__extern float	caca_get_dither_gamma (caca_dither_t const *)
	Get the gamma of a dither object.
__extern int	caca_set_dither_contrast (caca_dither_t *, float)
	Set the contrast of a dither object.
__extern float	caca_get_dither_contrast (caca_dither_t const *)
	Get the contrast of a dither object.
__extern int	caca_set_dither_antialias (caca_dither_t *, char const *)
	Set dither antialiasing.
__extern char const *const *	caca_get_dither_antialias_list (caca_dither_t const *)
	Get available antialiasing methods.
__extern char const *	caca_get_dither_antialias (caca_dither_t const *)
	Get current antialiasing method.
__extern int	caca_set_dither_color (caca_dither_t *, char const *)
	Choose colours used for dithering.
__extern char const *const *	caca_get_dither_color_list (caca_dither_t const *)
	Get available colour modes.
__extern char const *	caca_get_dither_color (caca_dither_t const *)
	Get current colour mode.
__extern int	caca_set_dither_charset (caca_dither_t *, char const *)
	Choose characters used for dithering.
__extern char const *const *	caca_get_dither_charset_list (caca_dither_t const *)
	Get available dither character sets.
__extern char const *	caca_get_dither_charset (caca_dither_t const *)
	Get current character set.
__extern int	caca_set_dither_algorithm (caca_dither_t *, char const *)
	Set dithering algorithm.
__extern char const *const *	caca_get_dither_algorithm_list (caca_dither_t const *)
	Get dithering algorithms.
__extern char const *	caca_get_dither_algorithm (caca_dither_t const *)
	Get current dithering algorithm.
__extern int	caca_dither_bitmap (caca_canvas_t *, int, int, int, int, caca_dither_t const *, void const *)
	Dither a bitmap on the canvas.
__extern int	caca_free_dither (caca_dither_t *)
	Free the memory associated with a dither.

Detailed Description

These functions provide high level routines for dither allocation and rendering.

Function Documentation

caca_create_dither()

__extern caca_dither_t * caca_create_dither	(	int	bpp,
		int	w,
		int	h,
		int	pitch,
		uint32_t	rmask,
		uint32_t	gmask,
		uint32_t	bmask,
		uint32_t	amask
	)

Create a dither structure from its coordinates (depth, width, height and pitch) and pixel mask values. If the depth is 8 bits per pixel, the mask values are ignored and the colour palette should be set using the caca_set_dither_palette() function. For depths greater than 8 bits per pixel, a zero alpha mask causes the alpha values to be ignored.

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

• EINVAL Requested width, height, pitch or bits per pixel value was invalid.
• ENOMEM Not enough memory to allocate dither structure.

Parameters

bpp	Bitmap depth in bits per pixel.
w	Bitmap width in pixels.
h	Bitmap height in pixels.
pitch	Bitmap pitch in bytes.
rmask	Bitmask for red values.
gmask	Bitmask for green values.
bmask	Bitmask for blue values.
amask	Bitmask for alpha values.

Returns

Dither object upon success, NULL if an error occurred.

caca_set_dither_palette()

__extern int caca_set_dither_palette	(	caca_dither_t *	d,
		uint32_t	red[],
		uint32_t	green[],
		uint32_t	blue[],
		uint32_t	alpha[]
	)

Set the palette of an 8 bits per pixel bitmap. Values should be between 0 and 4095 (0xfff).

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

• EINVAL Dither bits per pixel value is not 8, or one of the pixel values was outside the range 0 - 4095.

Parameters

d	Dither object.
red	Array of 256 red values.
green	Array of 256 green values.
blue	Array of 256 blue values.
alpha	Array of 256 alpha values.

Returns

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

caca_set_dither_brightness()

__extern int caca_set_dither_brightness	(	caca_dither_t *	d,
		float	brightness
	)

Set the brightness of dither.

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

• EINVAL Brightness value was out of range.

Parameters

d	Dither object.
brightness	brightness value.

Returns

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

caca_get_dither_brightness()

__extern float caca_get_dither_brightness

(

caca_dither_t const *

d

)

Get the brightness of the given dither object.

This function never fails.

Parameters

d	Dither object.

Returns

Brightness value.

caca_set_dither_gamma()

__extern int caca_set_dither_gamma	(	caca_dither_t *	d,
		float	gamma
	)

Set the gamma of the given dither object. A negative value causes colour inversion.

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

• EINVAL Gamma value was out of range.

Parameters

d	Dither object.
gamma	Gamma value.

Returns

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

caca_get_dither_gamma()

__extern float caca_get_dither_gamma

(

caca_dither_t const *

d

)

Get the gamma of the given dither object.

This function never fails.

Parameters

d	Dither object.

Returns

Gamma value.

caca_set_dither_contrast()

__extern int caca_set_dither_contrast	(	caca_dither_t *	d,
		float	contrast
	)

Set the contrast of dither.

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

• EINVAL Contrast value was out of range.

Parameters

d	Dither object.
contrast	contrast value.

Returns

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

caca_get_dither_contrast()

__extern float caca_get_dither_contrast

(

caca_dither_t const *

d

)

Get the contrast of the given dither object.

This function never fails.

Parameters

d	Dither object.

Returns

Contrast value.

caca_set_dither_antialias()

__extern int caca_set_dither_antialias	(	caca_dither_t *	d,
		char const *	str
	)

Tell the renderer whether to antialias the dither. Antialiasing smoothens the rendered image and avoids the commonly seen staircase effect.

• "none": no antialiasing.
• "prefilter" or "default": simple prefilter antialiasing. This is the default value.

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

• EINVAL Invalid antialiasing mode.

Parameters

d	Dither object.
str	A string describing the antialiasing method that will be used for the dithering.

Returns

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

caca_get_dither_antialias_list()

__extern char const *const * caca_get_dither_antialias_list

(

caca_dither_t const *

d

)

Return a list of available antialiasing methods for a given dither. The list is a NULL-terminated array of strings, interleaving a string containing the internal value for the antialiasing method to be used with caca_set_dither_antialias(), and a string containing the natural language description for that antialiasing method.

This function never fails.

Parameters

d	Dither object.

Returns

An array of strings.

caca_get_dither_antialias()

__extern char const * caca_get_dither_antialias

(

caca_dither_t const *

d

)

Return the given dither's current antialiasing method.

This function never fails.

Parameters

d	Dither object.

Returns

A static string.

caca_set_dither_color()

__extern int caca_set_dither_color	(	caca_dither_t *	d,
		char const *	str
	)

Tell the renderer which colours should be used to render the bitmap. Valid values for str are:

• "mono": use light gray on a black background.
• "gray": use white and two shades of gray on a black background.
• "8": use the 8 ANSI colours on a black background.
• "16": use the 16 ANSI colours on a black background.
• "fullgray": use black, white and two shades of gray for both the characters and the background.
• "full8": use the 8 ANSI colours for both the characters and the background.
• "full16" or "default": use the 16 ANSI colours for both the characters and the background. T