ChafaSymbolMap

ChafaSymbolMap — Describes a selection of textual symbols

Functions

Types and Values

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;