ChafaSymbolMap: Chafa Reference Manual

## ChafaSymbolMap

ChafaSymbolMap — Describes a selection of textual symbols

## Functions

ChafaSymbolMap * | chafa_symbol_map_new ()
void | chafa_symbol_map_ref ()
void | chafa_symbol_map_unref ()
void | chafa_symbol_map_add_by_tags ()
void | chafa_symbol_map_remove_by_tags ()

## 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_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_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 |

## 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. |
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_ALL | Special value meaning all supported symbols. |

### ChafaSymbolMap

    typedef struct ChafaSymbolMap ChafaSymbolMap;