--- name: "cucul_dither" 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_dither" --- # cucul\_dither(3caca) ## NAME libcucul bitmap dithering - ### Functions \_\_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.* ## Detailed Description These functions provide high level routines for dither allocation and rendering. ## Function Documentation ### \_\_extern cucul\_dither\_t\* cucul\_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 **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: - • `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. ### \_\_extern int cucul\_set\_dither\_palette (cucul\_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. ### \_\_extern 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: - • `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. ### \_\_extern float cucul\_get\_dither\_brightness (cucul\_dither\_t const \* d) Get the brightness of the given dither object. This function never fails. **Parameters:** *d* Dither object. **Returns:** Brightness value. ### \_\_extern int cucul\_set\_dither\_gamma (cucul\_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. ### \_\_extern float cucul\_get\_dither\_gamma (cucul\_dither\_t const \* d) Get the gamma of the given dither object. This function never fails. **Parameters:** *d* Dither object. **Returns:** Gamma value. ### \_\_extern 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: - • `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. ### \_\_extern float cucul\_get\_dither\_contrast (cucul\_dither\_t const \* d) Get the contrast of the given dither object. This function never fails. **Parameters:** *d* Dither object. **Returns:** Contrast value. ### \_\_extern 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. - • `"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. ### \_\_extern 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. ### \_\_extern char const\* cucul\_get\_dither\_antialias (cucul\_dither\_t const \* d) Return the given dither's current antialiasing method. This function never fails. **Parameters:** *d* Dither object. **Returns:** A static string. ### \_\_extern 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: - • `"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:** *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. ### \_\_extern 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. ### \_\_extern char const\* cucul\_get\_dither\_color (cucul\_dither\_t const \* d) Return the given dither's current colour mode. This function never fails. **Parameters:** *d* Dither object. **Returns:** A static string. ### \_\_extern 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: - • `"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:** *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. ### \_\_extern 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. ### \_\_extern char const\* cucul\_get\_dither\_charset (cucul\_dither\_t const \* d) Return the given dither's current character set. This function never fails. **Parameters:** *d* Dither object. **Returns:** A static string. ### \_\_extern int cucul\_set\_dither\_algorithm (cucul\_dither\_t \* d, char const \* str) 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:** *d* Dither object. \ *str* A string describing the algorithm that needs to be used for the dithering. **Returns:** 0 in case of success, -1 if an error occurred. ### \_\_extern char const\* const\* cucul\_get\_dither\_algorithm\_list (cucul\_dither\_t const \* d) 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 cucul\_set\_dither\_dithering(), and a string containing the natural language description for that algorithm. This function never fails. **Parameters:** *d* Dither object. **Returns:** An array of strings. ### \_\_extern char const\* cucul\_get\_dither\_algorithm (cucul\_dither\_t const \* d) Return the given dither's current dithering algorithm. This function never fails. **Parameters:** *d* Dither object. **Returns:** A static string. ### \_\_extern 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. References CUCUL\_BLACK, cucul\_get\_attr(), cucul\_put\_char(), cucul\_set\_attr(), and cucul\_set\_color\_ansi(). ### \_\_extern 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.