ChafaCanvasConfig

ChafaCanvasConfig — Describes a configuration for ChafaCanvas

Functions

Types and Values

Description

A ChafaCanvasConfig describes a set of parameters for ChafaCanvas, such as its geometry, color space and other output characteristics.

To create a new ChafaCanvasConfig, use chafa_canvas_config_new(). You can then modify it using its setters, e.g. chafa_canvas_config_set_canvas_mode() before assigning it to a new ChafaCanvas with chafa_canvas_new().

Note that it is not possible to change a canvas' configuration after the canvas is created.

Functions

chafa_canvas_config_new ()

ChafaCanvasConfig *
chafa_canvas_config_new (void);

Creates a new ChafaCanvasConfig with default settings. This object can later be used in the creation of a ChafaCanvas.

Returns

The new ChafaCanvasConfig


chafa_canvas_config_copy ()

ChafaCanvasConfig *
chafa_canvas_config_copy (const ChafaCanvasConfig *config);

Creates a new ChafaCanvasConfig that's a copy of config .

Parameters

config

A ChafaSymbolMap to copy.

 

Returns

The new ChafaCanvasConfig


chafa_canvas_config_ref ()

void
chafa_canvas_config_ref (ChafaCanvasConfig *config);

Adds a reference to config .

Parameters

config

ChafaCanvasConfig to add a reference to.

 

chafa_canvas_config_unref ()

void
chafa_canvas_config_unref (ChafaCanvasConfig *config);

Removes a reference from config .

Parameters

config

ChafaCanvasConfig to remove a reference from.

 

chafa_canvas_config_get_geometry ()

void
chafa_canvas_config_get_geometry (const ChafaCanvasConfig *config,
                                  gint *width_out,
                                  gint *height_out);

Returns config 's width and height in character cells in the provided output locations.

Parameters

config

A ChafaCanvasConfig

 

width_out

Location to store width in, or NULL

 

height_out

Location to store height in, or NULL

 

chafa_canvas_config_set_geometry ()

void
chafa_canvas_config_set_geometry (ChafaCanvasConfig *config,
                                  gint width,
                                  gint height);

Sets config 's width and height in character cells to width x height .

Parameters

config

A ChafaCanvasConfig

 

width

Width in character cells

 

height

Height in character cells

 

chafa_canvas_config_get_canvas_mode ()

ChafaCanvasMode
chafa_canvas_config_get_canvas_mode (const ChafaCanvasConfig *config);

Returns config 's ChafaCanvasMode.

Parameters

config

A ChafaCanvasConfig

 

Returns

The ChafaCanvasMode.


chafa_canvas_config_set_canvas_mode ()

void
chafa_canvas_config_set_canvas_mode (ChafaCanvasConfig *config,
                                     ChafaCanvasMode mode);

Sets config 's stored ChafaCanvasMode to mode .

Parameters

config

A ChafaCanvasConfig

 

mode

A ChafaCanvasMode

 

chafa_canvas_config_get_color_space ()

ChafaColorSpace
chafa_canvas_config_get_color_space (const ChafaCanvasConfig *config);

Returns config 's ChafaColorSpace.

Parameters

config

A ChafaCanvasConfig

 

Returns

The ChafaColorSpace.


chafa_canvas_config_set_color_space ()

void
chafa_canvas_config_set_color_space (ChafaCanvasConfig *config,
                                     ChafaColorSpace color_space);

Sets config 's stored ChafaColorSpace to color_space .

Parameters

config

A ChafaCanvasConfig

 

color_space

A ChafaColorSpace

 

chafa_canvas_config_get_preprocessing_enabled ()

gboolean
chafa_canvas_config_get_preprocessing_enabled
                               (const ChafaCanvasConfig *config);

Queries whether automatic image preprocessing is enabled. This allows Chafa to boost contrast and saturation in an attempt to improve legibility. The type of preprocessing applied (if any) depends on the canvas mode.

Parameters

config

A ChafaCanvasConfig

 

Returns

Whether automatic preprocessing is enabled


chafa_canvas_config_set_preprocessing_enabled ()

void
chafa_canvas_config_set_preprocessing_enabled
                               (ChafaCanvasConfig *config,
                                gboolean preprocessing_enabled);

Indicates whether automatic image preprocessing should be enabled. This allows Chafa to boost contrast and saturation in an attempt to improve legibility. The type of preprocessing applied (if any) depends on the canvas mode.

Parameters

config

A ChafaCanvasConfig

 

preprocessing_enabled

Whether automatic preprocessing should be enabled

 

chafa_canvas_config_peek_symbol_map ()

const ChafaSymbolMap *
chafa_canvas_config_peek_symbol_map (const ChafaCanvasConfig *config);

Returns a pointer to the symbol map belonging to config . This can be inspected using the ChafaSymbolMap getter functions, but not changed.

Parameters

config

A ChafaCanvasConfig

 

Returns

A pointer to the config's immutable symbol map


chafa_canvas_config_set_symbol_map ()

void
chafa_canvas_config_set_symbol_map (ChafaCanvasConfig *config,
                                    const ChafaSymbolMap *symbol_map);

Assigns a copy of symbol_map to config .

Parameters

config

A ChafaCanvasConfig

 

symbol_map

A ChafaSymbolMap

 

chafa_canvas_config_peek_fill_symbol_map ()

const ChafaSymbolMap *
chafa_canvas_config_peek_fill_symbol_map
                               (const ChafaCanvasConfig *config);

Returns a pointer to the fill symbol map belonging to config . This can be inspected using the ChafaSymbolMap getter functions, but not changed.

Fill symbols are assigned according to their overall foreground to background coverage, disregarding shape.

Parameters

config

A ChafaCanvasConfig

 

Returns

A pointer to the config's immutable fill symbol map


chafa_canvas_config_set_fill_symbol_map ()

void
chafa_canvas_config_set_fill_symbol_map
                               (ChafaCanvasConfig *config,
                                const ChafaSymbolMap *fill_symbol_map);

Assigns a copy of fill_symbol_map to config .

Parameters

config

A ChafaCanvasConfig

 

fill_symbol_map

A ChafaSymbolMap

 

chafa_canvas_config_get_transparency_threshold ()

gfloat
chafa_canvas_config_get_transparency_threshold
                               (const ChafaCanvasConfig *config);

Returns the threshold above which full transparency will be used.

Parameters

config

A ChafaCanvasConfig

 

Returns

The transparency threshold [0.0 - 1.0]


chafa_canvas_config_set_transparency_threshold ()

void
chafa_canvas_config_set_transparency_threshold
                               (ChafaCanvasConfig *config,
                                gfloat alpha_threshold);

Sets the threshold above which full transparency will be used.

Parameters

config

A ChafaCanvasConfig

 

alpha_threshold

The transparency threshold [0.0 - 1.0].

 

chafa_canvas_config_get_fg_color ()

guint32
chafa_canvas_config_get_fg_color (const ChafaCanvasConfig *config);

Gets the assumed foreground color of the output device. This is used to determine how to apply the foreground pen in FGBG modes.

Parameters

config

A ChafaCanvasConfig

 

Returns

Foreground color as packed RGB triplet


chafa_canvas_config_set_fg_color ()

void
chafa_canvas_config_set_fg_color (ChafaCanvasConfig *config,
                                  guint32 fg_color_packed_rgb);

Sets the assumed foreground color of the output device. This is used to determine how to apply the foreground pen in FGBG modes.

Parameters

config

A ChafaCanvasConfig

 

fg_color_packed_rgb

Foreground color as packed RGB triplet

 

chafa_canvas_config_get_bg_color ()

guint32
chafa_canvas_config_get_bg_color (const ChafaCanvasConfig *config);

Gets the assumed background color of the output device. This is used to determine how to apply the background pen in FGBG modes.

Parameters

config

A ChafaCanvasConfig

 

Returns

Background color as packed RGB triplet


chafa_canvas_config_set_bg_color ()

void
chafa_canvas_config_set_bg_color (ChafaCanvasConfig *config,
                                  guint32 bg_color_packed_rgb);

Sets the assumed background color of the output device. This is used to determine how to apply the background and transparency pens in FGBG modes, and will also be substituted for partial transparency.

Parameters

config

A ChafaCanvasConfig

 

bg_color_packed_rgb

Background color as packed RGB triplet

 

chafa_canvas_config_get_work_factor ()

gfloat
chafa_canvas_config_get_work_factor (const ChafaCanvasConfig *config);

Gets the work/quality tradeoff factor. A higher value means more time and memory will be spent towards a higher quality output.

Parameters

config

A ChafaCanvasConfig

 

Returns

The work factor [0.0 - 1.0]


chafa_canvas_config_set_work_factor ()

void
chafa_canvas_config_set_work_factor (ChafaCanvasConfig *config,
                                     gfloat work_factor);

Sets the work/quality tradeoff factor. A higher value means more time and memory will be spent towards a higher quality output.

Parameters

config

A ChafaCanvasConfig

 

work_factor

Work factor [0.0 - 1.0]

 

Types and Values

enum ChafaColorSpace

Members

CHAFA_COLOR_SPACE_RGB

RGB color space. Fast but imprecise.

 

CHAFA_COLOR_SPACE_DIN99D

DIN99d color space. Slower, but good perceptual color precision.

 

CHAFA_COLOR_SPACE_MAX

Last supported color space plus one.

 

enum ChafaCanvasMode

Members

CHAFA_CANVAS_MODE_TRUECOLOR

Truecolor.

 

CHAFA_CANVAS_MODE_INDEXED_256

256 colors.

 

CHAFA_CANVAS_MODE_INDEXED_240

256 colors, but avoid using the lower 16 whose values vary between terminal environments.

 

CHAFA_CANVAS_MODE_INDEXED_16

16 colors using the aixterm ANSI extension.

 

CHAFA_CANVAS_MODE_FGBG_BGFG

Default foreground and background colors, plus inversion.

 

CHAFA_CANVAS_MODE_FGBG

Default foreground and background colors. No ANSI codes will be used.

 

CHAFA_CANVAS_MODE_MAX

Last supported canvas mode plus one.

 

ChafaCanvasConfig

typedef struct ChafaCanvasConfig ChafaCanvasConfig;