ChafaCanvasConfig: Chafa Reference Manual

## ChafaCanvasConfig

ChafaCanvasConfig — Describes a configuration for ChafaCanvas

## Functions

ChafaCanvasConfig * | chafa_canvas_config_new ()
void | chafa_canvas_config_ref ()
void | chafa_canvas_config_unref ()
void | chafa_canvas_config_get_geometry ()
void | chafa_canvas_config_set_geometry ()
ChafaCanvasMode | chafa_canvas_config_get_canvas_mode ()
void | chafa_canvas_config_set_canvas_mode ()
ChafaColorSpace | chafa_canvas_config_get_color_space ()
void | chafa_canvas_config_set_color_space ()
const ChafaSymbolMap * | chafa_canvas_config_peek_symbol_map ()
void | chafa_canvas_config_set_symbol_map ()
gfloat | chafa_canvas_config_get_transparency_threshold ()
void | chafa_canvas_config_set_transparency_threshold ()
guint32 | chafa_canvas_config_get_fg_color ()
void | chafa_canvas_config_set_fg_color ()
guint32 | chafa_canvas_config_get_bg_color ()
void | chafa_canvas_config_set_bg_color ()
gfloat | chafa_canvas_config_get_work_factor ()
void | chafa_canvas_config_set_work_factor ()

## Types and Values

enum | ChafaColorSpace
enum | ChafaCanvasMode
typedef | ChafaCanvasConfig

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