ChafaSymbolMap: Chafa Reference Manual

## ChafaSymbolMap ChafaSymbolMap — Describes a selection of textual symbols |

## Functions

ChafaSymbolMap * | chafa_symbol_map_new ()
ChafaSymbolMap * | chafa_symbol_map_copy ()
void | chafa_symbol_map_ref ()
void | chafa_symbol_map_unref ()
void | chafa_symbol_map_add_by_tags ()
void | chafa_symbol_map_add_by_range ()
void | chafa_symbol_map_remove_by_tags ()
void | chafa_symbol_map_remove_by_range ()
gboolean | chafa_symbol_map_apply_selectors ()
gboolean | chafa_symbol_map_get_allow_builtin_glyphs ()
void | chafa_symbol_map_set_allow_builtin_glyphs ()
gboolean | chafa_symbol_map_get_glyph ()
void | chafa_symbol_map_add_glyph ()

## Types and Values

#define | CHAFA_SYMBOL_WIDTH_PIXELS
#define | CHAFA_SYMBOL_HEIGHT_PIXELS
enum | ChafaSymbolTags
typedef | ChafaSymbolMap

## Description

A ChafaSymbolMap describes a selection of the supported textual symbols that can be used in building a printable output string from a ChafaCanvas.

To create a new ChafaSymbolMap, use `chafa_symbol_map_new()`. You can then add symbols to it using `chafa_symbol_map_add_by_tags()` before copying it into a ChafaCanvasConfig using `chafa_canvas_config_set_symbol_map()`.

Note that some symbols match multiple tags, so it makes sense to e.g. add symbols matching CHAFA_SYMBOL_TAG_BORDER and then removing symbols matching CHAFA_SYMBOL_TAG_DIAGONAL.

The number of available symbols is a significant factor in the speed of ChafaCanvas. For the fastest possible operation you could use a single symbol -- CHAFA_SYMBOL_TAG_VHALF works well by itself.

## Functions

### chafa_symbol_map_new ()

    ChafaSymbolMap *
    chafa_symbol_map_new (void);

Creates a new ChafaSymbolMap representing a set of Unicode symbols. The symbol map starts out empty.

#### Returns

The new symbol map

### chafa_symbol_map_copy ()

    ChafaSymbolMap *
    chafa_symbol_map_copy (const ChafaSymbolMap *symbol_map);

Creates a new ChafaSymbolMap that's a copy of `symbol_map` .

#### Parameters

symbol_map | A ChafaSymbolMap to copy. |

#### Returns

The new ChafaSymbolMap

### chafa_symbol_map_ref ()

    void
    chafa_symbol_map_ref (ChafaSymbolMap *symbol_map);

Adds a reference to `symbol_map` .

#### Parameters

symbol_map | Symbol map to add a reference to |

### chafa_symbol_map_unref ()

    void
    chafa_symbol_map_unref (ChafaSymbolMap *symbol_map);

Removes a reference from `symbol_map` . When remaining references drops to zero, the symbol map is freed and can no longer be used.

#### Parameters

symbol_map | Symbol map to remove a reference from |

### chafa_symbol_map_add_by_tags ()

    void
    chafa_symbol_map_add_by_tags (ChafaSymbolMap *symbol_map,
                                  ChafaSymbolTags tags);

Adds symbols matching the set of `tags` to `symbol_map` .

#### Parameters

symbol_map | Symbol map to add symbols to |
tags | Selector tags for symbols to add |

### chafa_symbol_map_add_by_range ()

    void
    chafa_symbol_map_add_by_range (ChafaSymbolMap *symbol_map,
                                   gunichar first,
                                   gunichar last);

Adds symbols in the code point range starting with `first` and ending with `last` to `symbol_map` .

#### Parameters

symbol_map | Symbol map to add symbols to |
first | First code point to add, inclusive |
last | Last code point to add, inclusive |

Since: 1.4

### chafa_symbol_map_remove_by_tags ()

    void
    chafa_symbol_map_remove_by_tags (ChafaSymbolMap *symbol_map,
                                     ChafaSymbolTags tags);

Removes symbols matching the set of `tags` from `symbol_map` .

#### Parameters

symbol_map | Symbol map to remove symbols from |
tags | Selector tags for symbols to remove |

### chafa_symbol_map_remove_by_range ()

    void
    chafa_symbol_map_remove_by_range (ChafaSymbolMap *symbol_map,
                                      gunichar first,
                                      gunichar last);

Removes symbols in the code point range starting with `first` and ending with `last` from `symbol_map` .

#### Parameters

symbol_map | Symbol map to remove symbols from |
first | First code point to remove, inclusive |
last | Last code point to remove, inclusive |

Since: 1.4

### chafa_symbol_map_apply_selectors ()

    gboolean
    chafa_symbol_map_apply_selectors (ChafaSymbolMap *symbol_map,
                                      const gchar *selectors,
                                      GError **error);

Parses a string consisting of symbol tags separated by [+-,] and applies the pattern to `symbol_map` . If the string begins with + or -, it's understood to be relative to the current set in `symbol_map` , otherwise the map is cleared first.

The symbol tags are string versions of ChafaSymbolTags, i.e. [all, none, space, solid, stipple, block, border, diagonal, dot, quad, half, hhalf, vhalf, braille, technical, geometric, ascii, extra].

Examples: "block,border" sets map to contain symbols matching either of those tags. "+block,border-dot,stipple" adds block and border symbols then removes dot and stipple symbols.

If there is a parse error, none of the changes are applied.

#### Parameters

symbol_map | Symbol map to apply selection to |
selectors | A string specifying selections |
error | Return location for an error, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` if there was a parse error

### chafa_symbol_map_get_allow_builtin_glyphs ()

    gboolean
    chafa_symbol_map_get_allow_builtin_glyphs
                                   (ChafaSymbolMap *symbol_map);

Queries whether a symbol map is allowed to use built-in glyphs for symbol selection. This can be turned off if you want to use your own glyphs exclusively (see `chafa_symbol_map_add_glyph()`).

Defaults to `TRUE`.

#### Parameters

symbol_map | A symbol map |

#### Returns

`TRUE` if built-in glyphs are allowed

Since: 1.4

### chafa_symbol_map_set_allow_builtin_glyphs ()

    void
    chafa_symbol_map_set_allow_builtin_glyphs
                                   (ChafaSymbolMap *symbol_map,
                                    gboolean use_builtin_glyphs);

Controls whether a symbol map is allowed to use built-in glyphs for symbol selection. This can be turned off if you want to use your own glyphs exclusively (see `chafa_symbol_map_add_glyph()`).

Defaults to `TRUE`.

#### Parameters

symbol_map | A symbol map |
use_builtin_glyphs | A boolean indicating whether to use built-in glyphs |

Since: 1.4

### chafa_symbol_map_get_glyph ()

    gboolean
    chafa_symbol_map_get_glyph (ChafaSymbolMap *symbol_map,
                                gunichar code_point,
                                ChafaPixelType pixel_format,
                                gpointer *pixels_out,
                                gint *width_out,
                                gint *height_out,
                                gint *rowstride_out);

Returns data for the glyph corresponding to `code_point` stored in `symbol_map` . Any of `pixels_out` , `width_out` , `height_out` and `rowstride_out` can be NULL, in which case the corresponding data is not retrieved.

If `pixels_out` is not NULL, a pointer to freshly allocated memory containing height * rowstride bytes in the pixel format specified by `pixel_format` will be stored at this address. It must be freed using `g_free()` when you're done with it.

Monochrome glyphs (the only kind currently supported) will be rendered as opaque white on a transparent black background (0xffffffff for inked pixels and 0x00000000 for uninked).

#### Parameters

symbol_map | A symbol map |
code_point | A Unicode code point |
pixel_format | Desired pixel format of `pixels_out` |
pixels_out | Storage for a pointer to exported glyph data |
width_out | Storage for width of glyph, in pixels |
height_out | Storage for height of glyph, in pixels |
rowstride_out | Storage for offset from start of one row to the next, in bytes |

Since: 1.12

### chafa_symbol_map_add_glyph ()

    void
    chafa_symbol_map_add_glyph (ChafaSymbolMap *symbol_map,
                                gunichar code_point,
                                ChafaPixelType pixel_format,
                                gpointer pixels,
                                gint width,
                                gint height,
                                gint rowstride);

Assigns a rendered glyph to a Unicode code point. This tells Chafa what the glyph looks like so the corresponding symbol can be used appropriately in output.

Assigned glyphs override built-in glyphs and any earlier glyph that may have been assigned to the same code point.

If the input is in a format with an alpha channel, the alpha channel will be used for the shape. If not, an average of the color channels will be used.

#### Parameters

symbol_map | A symbol map |
code_point | The Unicode code point for this glyph |
pixel_format | Glyph pixel format of `pixels` |
pixels | The glyph data |
width | Width of glyph, in pixels |
height | Height of glyph, in pixels |
rowstride | Offset from start of one row to the next, in bytes |

Since: 1.4

## Types and Values

### CHAFA_SYMBOL_WIDTH_PIXELS

    #define CHAFA_SYMBOL_WIDTH_PIXELS 8

The width of an internal symbol pixel matrix. If you are prescaling input graphics, you will get the best results when scaling to a multiple of this value.

### CHAFA_SYMBOL_HEIGHT_PIXELS

    #define CHAFA_SYMBOL_HEIGHT_PIXELS 8

The height of an internal symbol pixel matrix. If you are prescaling input graphics, you will get the best results when scaling to a multiple of this value.

### enum ChafaSymbolTags

#### Members

CHAFA_SYMBOL_TAG_NONE | Special value meaning no symbols. |
CHAFA_SYMBOL_TAG_SPACE | Space. |
CHAFA_SYMBOL_TAG_SOLID | Solid (inverse of space). |
CHAFA_SYMBOL_TAG_STIPPLE | Stipple symbols. |
CHAFA_SYMBOL_TAG_BLOCK | Block symbols. |
CHAFA_SYMBOL_TAG_BORDER | Border symbols. |
CHAFA_SYMBOL_TAG_DIAGONAL | Diagonal border symbols. |
CHAFA_SYMBOL_TAG_DOT | Symbols that look like isolated dots (excluding Braille). |
CHAFA_SYMBOL_TAG_QUAD | Quadrant block symbols. |
CHAFA_SYMBOL_TAG_HHALF | Horizontal half block symbols. |
CHAFA_SYMBOL_TAG_VHALF | Vertical half block symbols. |
CHAFA_SYMBOL_TAG_HALF | Joint set of horizontal and vertical halves. |
CHAFA_SYMBOL_TAG_INVERTED | Symbols that are the inverse of simpler symbols. When two symbols complement each other, only one will have this tag. |
CHAFA_SYMBOL_TAG_BRAILLE | Braille symbols. |
CHAFA_SYMBOL_TAG_TECHNICAL | Miscellaneous technical symbols. |
CHAFA_SYMBOL_TAG_GEOMETRIC | Geometric shapes. |
CHAFA_SYMBOL_TAG_ASCII | Printable ASCII characters. |
CHAFA_SYMBOL_TAG_ALPHA | Letters. |
CHAFA_SYMBOL_TAG_DIGIT | Digits. |
CHAFA_SYMBOL_TAG_ALNUM | Joint set of letters and digits. |
CHAFA_SYMBOL_TAG_NARROW | Characters that are one cell wide. |
CHAFA_SYMBOL_TAG_WIDE | Characters that are two cells wide. |
CHAFA_SYMBOL_TAG_AMBIGUOUS | Characters of uncertain width. Always excluded unless specifically asked for. |
CHAFA_SYMBOL_TAG_UGLY | Characters that are generally undesired or unlikely to render well. Always excluded unless specifically asked for. |
CHAFA_SYMBOL_TAG_LEGACY | Legacy computer symbols, including sextants, wedges and more. |
CHAFA_SYMBOL_TAG_SEXTANT | Sextant 2x3 mosaics. |
CHAFA_SYMBOL_TAG_WEDGE | Wedge shapes that align with sextants. |
CHAFA_SYMBOL_TAG_LATIN | Latin and Latin-like symbols (superset of ASCII). |
CHAFA_SYMBOL_TAG_IMPORTED | Symbols for which glyphs were imported with `chafa_symbol_map_add_glyph()`. |
CHAFA_SYMBOL_TAG_EXTRA | Symbols not in any other category. |
CHAFA_SYMBOL_TAG_BAD | Joint set of ugly and ambiguous characters. Always excluded unless specifically asked for. |
CHAFA_SYMBOL_TAG_ALL | Special value meaning all supported symbols. |

### ChafaSymbolMap

    typedef struct ChafaSymbolMap ChafaSymbolMap;