libcaca  0.99.beta19
About: libcaca is a graphics library that outputs text instead of pixels, so that it can work on older video cards or text terminals (something like an advanced AAlib library).
  Fossies Dox: libcaca-0.99.beta19.tar.gz  ("inofficial" and yet experimental doxygen-generated source code documentation)  

libcaca bitmap dithering

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

Functions

caca_dither_tcaca_create_dither (int, int, int, int, uint32_t, uint32_t, uint32_t, uint32_t)
 Create an internal dither object. More...
 
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. More...
 
int caca_set_dither_brightness (caca_dither_t *, float)
 Set the brightness of a dither object. More...
 
float caca_get_dither_brightness (caca_dither_t const *)
 Get the brightness of a dither object. More...
 
int caca_set_dither_gamma (caca_dither_t *, float)
 Set the gamma of a dither object. More...
 
float caca_get_dither_gamma (caca_dither_t const *)
 Get the gamma of a dither object. More...
 
int caca_set_dither_contrast (caca_dither_t *, float)
 Set the contrast of a dither object. More...
 
float caca_get_dither_contrast (caca_dither_t const *)
 Get the contrast of a dither object. More...
 
int caca_set_dither_antialias (caca_dither_t *, char const *)
 Set dither antialiasing. More...
 
const char *const * caca_get_dither_antialias_list (caca_dither_t const *)
 Get available antialiasing methods. More...
 
const char * caca_get_dither_antialias (caca_dither_t const *)
 Get current antialiasing method. More...
 
int caca_set_dither_color (caca_dither_t *, char const *)
 Choose colours used for dithering. More...
 
const char *const * caca_get_dither_color_list (caca_dither_t const *)
 Get available colour modes. More...
 
const char * caca_get_dither_color (caca_dither_t const *)
 Get current colour mode. More...
 
int caca_set_dither_charset (caca_dither_t *, char const *)
 Choose characters used for dithering. More...
 
const char *const * caca_get_dither_charset_list (caca_dither_t const *)
 Get available dither character sets. More...
 
const char * caca_get_dither_charset (caca_dither_t const *)
 Get current character set. More...
 
int caca_set_dither_algorithm (caca_dither_t *, char const *)
 Set dithering algorithm. More...
 
const char *const * caca_get_dither_algorithm_list (caca_dither_t const *)
 Get dithering algorithms. More...
 
const char * caca_get_dither_algorithm (caca_dither_t const *)
 Get current dithering algorithm. More...
 
int caca_dither_bitmap (caca_canvas_t *, int, int, int, int, caca_dither_t const *, void const *)
 Dither a bitmap on the canvas. More...
 
int caca_free_dither (caca_dither_t *)
 Free the memory associated with a dither. More...
 

Detailed Description

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

Function Documentation

◆ caca_create_dither()

caca_dither_t * caca_create_dither ( int  ,
int  ,
int  ,
int  ,
uint32_t  ,
uint32_t  ,
uint32_t  ,
uint32_t   
)

Create an internal dither object.

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
bppBitmap depth in bits per pixel.
wBitmap width in pixels.
hBitmap height in pixels.
pitchBitmap pitch in bytes.
rmaskBitmask for red values.
gmaskBitmask for green values.
bmaskBitmask for blue values.
amaskBitmask for alpha values.
Returns
Dither object upon success, NULL if an error occurred.

Definition at line 261 of file dither.c.

References aleft, algo_name, amask, antialias, antialias_name, aright, ascii_glyphs, bleft, blue, bmask, bpp, bright, brightness, color, COLOR_MODE_FULL16, color_name, contrast, gamma, gammatab, get_dither, get_fstein_dither(), gleft, glyph_count, glyph_name, glyphs, gmask, green, gright, h, has_alpha, has_palette, increment_dither, increment_fstein_dither(), init_dither, init_fstein_dither(), init_lookup(), invert, lookup_initialised, mask2shift(), pitch, red, rleft, rmask, rright, seterrno, and w.

Referenced by __caca0_create_bitmap(), Dither::Dither(), dither_initialize(), initialize(), Java_org_zoy_caca_Dither_createDither(), load_image(), metaballs(), moire(), plasma(), and rotozoom().

◆ caca_dither_bitmap()

int caca_dither_bitmap ( caca_canvas_t cv,
int  x,
int  y,
int  w,
int  h,
caca_dither_t const *  d,
void const *  pixels 
)

Dither a bitmap on the canvas.

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
cvA handle to the libcaca canvas.
xX coordinate of the upper-left corner of the drawing area.
yY coordinate of the upper-left corner of the drawing area.
wWidth of the drawing area.
hHeight of the drawing area.
dDither object to be drawn.
pixelsBitmap's pixels.
Returns
This function always returns 0.

Definition at line 940 of file dither.c.

References antialias, CACA_BLACK, caca_get_attr(), caca_put_char(), caca_set_attr(), caca_set_color_ansi(), color, COLOR_MODE_FULL16, COLOR_MODE_FULLGRAY, cv, get_dither, get_rgba_default(), glyph_count, glyphs, h, has_alpha, caca_canvas::height, increment_dither, init_dither, init_fstein_dither(), invert, pitch, rgb_palette, rgb_weight, sq(), w, caca_canvas::width, x, and y.

Referenced by Dither::Bitmap(), dither_bitmap(), drawfire(), Java_org_zoy_caca_Canvas_canvasDitherBitmap(), main(), metaballs(), moire(), plasma(), and rotozoom().

◆ caca_free_dither()

int caca_free_dither ( caca_dither_t )

Free the memory associated with a dither.

Free the memory allocated by caca_create_dither().

This function never fails.

Parameters
dDither object.
Returns
This function always returns 0.

Definition at line 1209 of file dither.c.

Referenced by __caca0_free_bitmap(), dither_free(), Java_org_zoy_caca_Dither_freeDither(), metaballs(), moire(), plasma(), rotozoom(), unload_image(), and Dither::~Dither().

◆ caca_get_dither_algorithm()

const char * caca_get_dither_algorithm ( caca_dither_t const *  )

Get current dithering algorithm.

Return the given dither's current dithering algorithm.

This function never fails.

Parameters
dDither object.
Returns
A static string.

Definition at line 919 of file dither.c.

References algo_name.

Referenced by Java_org_zoy_caca_Dither_getDitherAlgorithm(), and main().

◆ caca_get_dither_algorithm_list()

const char *const * caca_get_dither_algorithm_list ( caca_dither_t const *  )

Get dithering algorithms.

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

This function never fails.

Parameters
dDither object.
Returns
An array of strings.

Definition at line 894 of file dither.c.

Referenced by cucul_get_dither_mode_list(), Dither::getModeList(), Java_org_zoy_caca_Dither_getDitherAlgorithmList(), main(), and usage().

◆ caca_get_dither_antialias()

const char * caca_get_dither_antialias ( caca_dither_t const *  )

Get current antialiasing method.

Return the given dither's current antialiasing method.

This function never fails.

Parameters
dDither object.
Returns
A static string.

Definition at line 600 of file dither.c.

References antialias_name.

Referenced by Java_org_zoy_caca_Dither_getDitherAntiAliasing().

◆ caca_get_dither_antialias_list()

const char *const * caca_get_dither_antialias_list ( caca_dither_t const *  )

Get available antialiasing methods.

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
dDither object.
Returns
An array of strings.

Definition at line 579 of file dither.c.

Referenced by Dither::getAntialiasList(), and Java_org_zoy_caca_Dither_getDitherAntiAliasingList().

◆ caca_get_dither_brightness()

float caca_get_dither_brightness ( caca_dither_t const *  )

Get the brightness of a dither object.

Get the brightness of the given dither object.

This function never fails.

Parameters
dDither object.
Returns
Brightness value.

Definition at line 438 of file dither.c.

References brightness.

Referenced by Java_org_zoy_caca_Dither_getDitherBrightness().

◆ caca_get_dither_charset()

const char * caca_get_dither_charset ( caca_dither_t const *  )

Get current character set.

Return the given dither's current character set.

This function never fails.

Parameters
dDither object.
Returns
A static string.

Definition at line 803 of file dither.c.

References glyph_name.

Referenced by Java_org_zoy_caca_Dither_getDitherCharset().

◆ caca_get_dither_charset_list()

const char *const * caca_get_dither_charset_list ( caca_dither_t const *  )

Get available dither character sets.

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 caca_set_dither_charset(), and a string containing the natural language description for that character set.

This function never fails.

Parameters
dDither object.
Returns
An array of strings.

Definition at line 781 of file dither.c.

Referenced by Dither::getCharsetList().

◆ caca_get_dither_color()

const char * caca_get_dither_color ( caca_dither_t const *  )

Get current colour mode.

Return the given dither's current colour mode.

This function never fails.

Parameters
dDither object.
Returns
A static string.

Definition at line 714 of file dither.c.

References color_name.

Referenced by Java_org_zoy_caca_Dither_getDitherColor().

◆ caca_get_dither_color_list()

const char *const * caca_get_dither_color_list ( caca_dither_t const *  )

Get available colour modes.

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 caca_set_dither_color(), and a string containing the natural language description for that colour mode.

This function never fails.

Parameters
dDither object.
Returns
An array of strings.

Definition at line 688 of file dither.c.

Referenced by Dither::getColorList(), Java_org_zoy_caca_Dither_getDitherCharsetList(), and Java_org_zoy_caca_Dither_getDitherColorList().

◆ caca_get_dither_contrast()

float caca_get_dither_contrast ( caca_dither_t const *  )

Get the contrast of a dither object.

Get the contrast of the given dither object.

This function never fails.

Parameters
dDither object.
Returns
Contrast value.

Definition at line 523 of file dither.c.

References contrast.

Referenced by Java_org_zoy_caca_Dither_getDitherContrast().

◆ caca_get_dither_gamma()

float caca_get_dither_gamma ( caca_dither_t const *  )

Get the gamma of a dither object.

Get the gamma of the given dither object.

This function never fails.

Parameters
dDither object.
Returns
Gamma value.

Definition at line 490 of file dither.c.

References gamma.

Referenced by cucul_set_dither_invert(), and Java_org_zoy_caca_Dither_getDitherGamma().

◆ caca_set_dither_algorithm()

int caca_set_dither_algorithm ( caca_dither_t ,
char const *   
)

Set dithering algorithm.

Tell the renderer which dithering algorithm 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:

  • "none": no dithering is used, the nearest matching colour is used.
  • "ordered2": use a 2x2 Bayer matrix for dithering.
  • "ordered4": use a 4x4 Bayer matrix for dithering.
  • "ordered8": use a 8x8 Bayer matrix for dithering.
  • "random": use random dithering.
  • "fstein": use Floyd-Steinberg dithering. This is the default value.

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

  • EINVAL Unknown dithering mode.
Parameters
dDither object.
strA string describing the algorithm that needs to be used for the dithering.
Returns
0 in case of success, -1 if an error occurred.

Definition at line 828 of file dither.c.

References algo_name, get_dither, get_fstein_dither(), get_no_dither(), get_ordered2_dither(), get_ordered4_dither(), get_ordered8_dither(), get_random_dither(), increment_dither, increment_fstein_dither(), increment_no_dither(), increment_ordered2_dither(), increment_ordered4_dither(), increment_ordered8_dither(), increment_random_dither(), init_dither, init_fstein_dither(), init_no_dither(), init_ordered2_dither(), init_ordered4_dither(), init_ordered8_dither(), init_random_dither(), seterrno, and strcasecmp.

Referenced by __caca0_create_bitmap(), __caca0_set_feature(), cucul_set_dither_mode(), Java_org_zoy_caca_Dither_setDitherAlgorithm(), main(), and Dither::setMode().

◆ caca_set_dither_antialias()

int caca_set_dither_antialias ( caca_dither_t ,
char const *   
)

Set dither antialiasing.

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
dDither object.
strA string describing the antialiasing method that will be used for the dithering.
Returns
0 in case of success, -1 if an error occurred.

Definition at line 544 of file dither.c.

References antialias, antialias_name, seterrno, and strcasecmp.

Referenced by __caca0_create_bitmap(), __caca0_set_feature(), Java_org_zoy_caca_Dither_setDitherAntiAliasing(), and Dither::setAntialias().

◆ caca_set_dither_brightness()

int caca_set_dither_brightness ( caca_dither_t ,
float   
)

Set the brightness of a dither object.

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
dDither object.
brightnessbrightness value.
Returns
0 in case of success, -1 if an error occurred.

Definition at line 421 of file dither.c.

References brightness.

Referenced by Java_org_zoy_caca_Dither_setDitherBrightness(), main(), and Dither::setBrightness().

◆ caca_set_dither_charset()

int caca_set_dither_charset ( caca_dither_t ,
char const *   
)

Choose characters used for dithering.

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

  • "ascii" or "default": use only ASCII characters. This is the default value.
  • "shades": use Unicode characters "U+2591 LIGHT SHADE", "U+2592 MEDIUM SHADE" and "U+2593 DARK SHADE". These characters are also present in the CP437 codepage available on DOS and VGA.
  • "blocks": use Unicode quarter-cell block combinations. These characters are only found in the Unicode set.

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

  • EINVAL Invalid character set.
Parameters
dDither object.
strA string describing the characters that need to be used for the dithering.
Returns
0 in case of success, -1 if an error occurred.

Definition at line 739 of file dither.c.

References ascii_glyphs, blocks_glyphs, glyph_count, glyph_name, glyphs, seterrno, shades_glyphs, and strcasecmp.

Referenced by Java_org_zoy_caca_Dither_setDitherCharset(), and Dither::setCharset().

◆ caca_set_dither_color()

int caca_set_dither_color ( caca_dither_t ,
char const *   
)

Choose colours used for dithering.

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. This is the default value.

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

  • EINVAL Invalid colour set.
Parameters
dDither object.
strA string describing the colour set that will be used for the dithering.
Returns
0 in case of success, -1 if an error occurred.

Definition at line 628 of file dither.c.

References color, COLOR_MODE_16, COLOR_MODE_8, COLOR_MODE_FULL16, COLOR_MODE_FULL8, COLOR_MODE_FULLGRAY, COLOR_MODE_GRAY, COLOR_MODE_MONO, color_name, seterrno, and strcasecmp.

Referenced by __caca0_create_bitmap(), __caca0_set_feature(), Java_org_zoy_caca_Dither_setDitherColor(), and Dither::setColor().

◆ caca_set_dither_contrast()

int caca_set_dither_contrast ( caca_dither_t ,
float   
)

Set the contrast of a dither object.

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
dDither object.
contrastcontrast value.
Returns
0 in case of success, -1 if an error occurred.

Definition at line 506 of file dither.c.

References contrast.

Referenced by Java_org_zoy_caca_Dither_setDitherContrast(), main(), and Dither::setContrast().

◆ caca_set_dither_gamma()

int caca_set_dither_gamma ( caca_dither_t ,
float   
)

Set the gamma of a dither object.

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
dDither object.
gammaGamma value.
Returns
0 in case of success, -1 if an error occurred.

Definition at line 455 of file dither.c.

References gamma, gammapow(), gammatab, invert, and seterrno.

Referenced by cucul_set_dither_invert(), Java_org_zoy_caca_Dither_setDitherGamma(), main(), set_gamma(), and Dither::setGamma().

◆ caca_set_dither_palette()

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.

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
dDither object.
redArray of 256 red values.
greenArray of 256 green values.
blueArray of 256 blue values.
alphaArray of 256 alpha values.
Returns
0 in case of success, -1 if an error occurred.

Definition at line 372 of file dither.c.

References alpha, blue, bpp, green, has_alpha, red, and seterrno.

Referenced by initialize(), Java_org_zoy_caca_Dither_setDitherPalette(), load_image(), metaballs(), moire(), plasma(), set_dither_palette(), and Dither::setPalette().