libcucul bitmap dithering


Functions

cucul_dither_tcucul_create_dither (unsigned int, unsigned int, unsigned int, unsigned int, unsigned long int, unsigned long int, unsigned long int, unsigned long int)
 Create an internal dither object.
int cucul_set_dither_palette (cucul_dither_t *, unsigned int r[], unsigned int g[], unsigned int b[], unsigned int a[])
 Set the palette of an 8bpp dither object.
int cucul_set_dither_brightness (cucul_dither_t *, float)
 Set the brightness of a dither object.
int cucul_set_dither_gamma (cucul_dither_t *, float)
 Set the gamma of a dither object.
int cucul_set_dither_contrast (cucul_dither_t *, float)
 Set the contrast of a dither object.
int cucul_set_dither_invert (cucul_dither_t *, int)
 Invert colors of dither.
int cucul_set_dither_antialias (cucul_dither_t *, char const *)
 Set dither antialiasing.
char const *const * cucul_get_dither_antialias_list (cucul_dither_t const *)
 Get available antialiasing methods.
int cucul_set_dither_color (cucul_dither_t *, char const *)
 Choose colours used for dithering.
char const *const * cucul_get_dither_color_list (cucul_dither_t const *)
 Get available colour modes.
int cucul_set_dither_charset (cucul_dither_t *, char const *)
 Choose characters used for dithering.
char const *const * cucul_get_dither_charset_list (cucul_dither_t const *)
 Get available dither character sets.
int cucul_set_dither_mode (cucul_dither_t *, char const *)
 Set dithering method.
char const *const * cucul_get_dither_mode_list (cucul_dither_t const *)
 Get dithering methods.
int cucul_dither_bitmap (cucul_canvas_t *, int, int, int, int, cucul_dither_t const *, void *)
 Dither a bitmap on the canvas.
int cucul_free_dither (cucul_dither_t *)
 Free the memory associated with a dither.

Detailed Description

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

Function Documentation

cucul_dither_t* cucul_create_dither ( unsigned int  bpp,
unsigned int  w,
unsigned int  h,
unsigned int  pitch,
unsigned long int  rmask,
unsigned long int  gmask,
unsigned long int  bmask,
unsigned long int  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 cucul_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:

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.

int cucul_set_dither_palette ( cucul_dither_t d,
unsigned int  red[],
unsigned int  green[],
unsigned int  blue[],
unsigned int  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:

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.

int cucul_set_dither_brightness ( cucul_dither_t d,
float  brightness 
)

Set the brightness of dither.

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

Parameters:
d Dither object.
brightness brightness value.
Returns:
0 in case of success, -1 if an error occurred.

int cucul_set_dither_gamma ( cucul_dither_t d,
float  gamma 
)

Set the gamma of dither.

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

Parameters:
d Dither object.
gamma Gamma value.
Returns:
0 in case of success, -1 if an error occurred.

int cucul_set_dither_contrast ( cucul_dither_t d,
float  contrast 
)

Set the contrast of dither.

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

Parameters:
d Dither object.
contrast contrast value.
Returns:
0 in case of success, -1 if an error occurred.

int cucul_set_dither_invert ( cucul_dither_t d,
int  value 
)

Invert colors of dither.

This function never fails.

Parameters:
d Dither object.
value 0 for normal behaviour, 1 for invert
Returns:
This function always returns 0.

int cucul_set_dither_antialias ( cucul_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.

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

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.

char const* const* cucul_get_dither_antialias_list ( cucul_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 cucul_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.

int cucul_set_dither_color ( cucul_dither_t d,
char const *  str 
)

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

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

Parameters:
d Dither object.
str A string describing the colour set that will be used for the dithering.
Returns:
0 in case of success, -1 if an error occurred.

char const* const* cucul_get_dither_color_list ( cucul_dither_t const *  d  ) 

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

This function never fails.

Parameters:
d Dither object.
Returns:
An array of strings.

int cucul_set_dither_charset ( cucul_dither_t d,
char const *  str 
)

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

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

Parameters:
d Dither object.
str A string describing the characters that need to be used for the dithering.
Returns:
0 in case of success, -1 if an error occurred.

char const* const* cucul_get_dither_charset_list ( cucul_dither_t const *  d  ) 

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

This function never fails.

Parameters:
d Dither object.
Returns:
An array of strings.

int cucul_set_dither_mode ( cucul_dither_t d,
char const *  str 
)

Tell the renderer which dithering method should be used. Dithering is necessary because the picture being rendered has usually far more colours than the available palette. Valid values for str are:

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

Parameters:
d Dither object.
str A string describing the method that needs to be used for the dithering.
Returns:
0 in case of success, -1 if an error occurred.

char const* const* cucul_get_dither_mode_list ( cucul_dither_t const *  d  ) 

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

This function never fails.

Parameters:
d Dither object.
Returns:
An array of strings.

int cucul_dither_bitmap ( cucul_canvas_t cv,
int  x,
int  y,
int  w,
int  h,
cucul_dither_t const *  d,
void *  pixels 
)

Dither a bitmap at the given coordinates. The dither can be of any size and will be stretched to the text area.

This function never fails.

Parameters:
cv A handle to the libcucul canvas.
x X coordinate of the upper-left corner of the drawing area.
y Y coordinate of the upper-left corner of the drawing area.
w Width of the drawing area.
h Height of the drawing area.
d Dither object to be drawn.
pixels Bitmap's pixels.
Returns:
This function always returns 0.

int cucul_free_dither ( cucul_dither_t d  ) 

Free the memory allocated by cucul_create_dither().

This function never fails.

Parameters:
d Dither object.
Returns:
This function always returns 0.