ChafaCanvasConfig: Chafa Reference Manual

## ChafaCanvasConfig ChafaCanvasConfig — Describes a configuration for ChafaCanvas |

## Functions

ChafaCanvasConfig * | chafa_canvas_config_new ()
ChafaCanvasConfig * | chafa_canvas_config_copy ()
void | chafa_canvas_config_ref ()
void | chafa_canvas_config_unref ()
void | chafa_canvas_config_get_geometry ()
void | chafa_canvas_config_set_geometry ()
void | chafa_canvas_config_get_cell_geometry ()
void | chafa_canvas_config_set_cell_geometry ()
ChafaPixelMode | chafa_canvas_config_get_pixel_mode ()
void | chafa_canvas_config_set_pixel_mode ()
ChafaCanvasMode | chafa_canvas_config_get_canvas_mode ()
void | chafa_canvas_config_set_canvas_mode ()
ChafaColorExtractor | chafa_canvas_config_get_color_extractor ()
void | chafa_canvas_config_set_color_extractor ()
ChafaColorSpace | chafa_canvas_config_get_color_space ()
void | chafa_canvas_config_set_color_space ()
gboolean | chafa_canvas_config_get_preprocessing_enabled ()
void | chafa_canvas_config_set_preprocessing_enabled ()
const ChafaSymbolMap * | chafa_canvas_config_peek_symbol_map ()
void | chafa_canvas_config_set_symbol_map ()
const ChafaSymbolMap * | chafa_canvas_config_peek_fill_symbol_map ()
void | chafa_canvas_config_set_fill_symbol_map ()
gfloat | chafa_canvas_config_get_transparency_threshold ()
void | chafa_canvas_config_set_transparency_threshold ()
gboolean | chafa_canvas_config_get_fg_only_enabled ()
void | chafa_canvas_config_set_fg_only_enabled ()
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 ()
ChafaDitherMode | chafa_canvas_config_get_dither_mode ()
void | chafa_canvas_config_set_dither_mode ()
void | chafa_canvas_config_get_dither_grain_size ()
void | chafa_canvas_config_set_dither_grain_size ()
gfloat | chafa_canvas_config_get_dither_intensity ()
void | chafa_canvas_config_set_dither_intensity ()
ChafaOptimizations | chafa_canvas_config_get_optimizations ()
void | chafa_canvas_config_set_optimizations ()
ChafaPassthrough | chafa_canvas_config_get_passthrough ()
void | chafa_canvas_config_set_passthrough ()

## Types and Values

enum | ChafaPixelMode
enum | ChafaColorSpace
enum | ChafaCanvasMode
enum | ChafaDitherMode
enum | ChafaColorExtractor
enum | ChafaOptimizations
enum | ChafaPassthrough
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_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_cell_geometry ()

    void
    chafa_canvas_config_get_cell_geometry (const ChafaCanvasConfig *config,
                                           gint *cell_width_out,
                                           gint *cell_height_out);

Returns `config` 's cell width and height in pixels in the provided output locations.

#### Parameters

config | A ChafaCanvasConfig |
cell_width_out | Location to store cell width in, or `NULL` |
cell_height_out | Location to store cell height in, or `NULL` |

Since: 1.4

### chafa_canvas_config_set_cell_geometry ()

    void
    chafa_canvas_config_set_cell_geometry (ChafaCanvasConfig *config,
                                           gint cell_width,
                                           gint cell_height);

Sets `config` 's cell width and height in pixels to `cell_width` x `cell_height` .

#### Parameters

config | A ChafaCanvasConfig |
cell_width | Cell width in pixels |
cell_height | Cell height in pixels |

Since: 1.4

### chafa_canvas_config_get_pixel_mode ()

    ChafaPixelMode
    chafa_canvas_config_get_pixel_mode (const ChafaCanvasConfig *config);

Returns `config` 's ChafaPixelMode.

#### Parameters

config | A ChafaCanvasConfig |

#### Returns

The ChafaPixelMode. This determines how pixel graphics are rendered in the output.

Since: 1.4

### chafa_canvas_config_set_pixel_mode ()

    void
    chafa_canvas_config_set_pixel_mode (ChafaCanvasConfig *config,
                                        ChafaPixelMode pixel_mode);

Sets `config` 's stored ChafaPixelMode to `pixel_mode` . This determines how pixel graphics are rendered in the output.

#### Parameters

config | A ChafaCanvasConfig |
pixel_mode | A ChafaPixelMode |

Since: 1.4

### chafa_canvas_config_get_canvas_mode ()

    ChafaCanvasMode
    chafa_canvas_config_get_canvas_mode (const ChafaCanvasConfig *config);

Returns `config` 's ChafaCanvasMode. This determines how colors (and color control codes) are used in the output.

#### 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` . This determines how colors (and color control codes) are used in the output.

#### Parameters

config | A ChafaCanvasConfig |
mode | A ChafaCanvasMode |

### chafa_canvas_config_get_color_extractor ()

    ChafaColorExtractor
    chafa_canvas_config_get_color_extractor
                                   (const ChafaCanvasConfig *config);

Returns `config` 's ChafaColorExtractor. This determines how colors are approximated in character symbol output.

#### Parameters

config | A ChafaCanvasConfig |

#### Returns

The ChafaColorExtractor.

Since: 1.4

### chafa_canvas_config_set_color_extractor ()

    void
    chafa_canvas_config_set_color_extractor
                                   (ChafaCanvasConfig *config,
                                    ChafaColorExtractor color_extractor);

Sets `config` 's stored ChafaColorExtractor to `color_extractor` . This determines how colors are approximated in character symbol output.

#### Parameters

config | A ChafaCanvasConfig |
color_extractor | A ChafaColorExtractor |

Since: 1.4

### 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_only_enabled ()

    gboolean
    chafa_canvas_config_get_fg_only_enabled
                                   (const ChafaCanvasConfig *config);

Queries whether to use foreground colors only, leaving the background unmodified in the canvas output. This is relevant only when the ChafaPixelMode is set to CHAFA_PIXEL_MODE_SYMBOLS.

When this is set, the canvas will emit escape codes to set the foreground color only.

#### Parameters

config | A ChafaCanvasConfig |

#### Returns

`TRUE` if using foreground colors only, `FALSE` otherwise.

Since: 1.8

### chafa_canvas_config_set_fg_only_enabled ()

    void
    chafa_canvas_config_set_fg_only_enabled
                                   (ChafaCanvasConfig *config,
                                    gboolean fg_only_enabled);

Indicates whether to use foreground colors only, leaving the background unmodified in the canvas output. This is relevant only when the ChafaPixelMode is set to CHAFA_PIXEL_MODE_SYMBOLS.

When this is set, the canvas will emit escape codes to set the foreground color only.

#### Parameters

config | A ChafaCanvasConfig |
fg_only_enabled | Whether to use foreground colors only |

Since: 1.8

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

### chafa_canvas_config_get_dither_mode ()

    ChafaDitherMode
    chafa_canvas_config_get_dither_mode (const ChafaCanvasConfig *config);

Returns `config` 's ChafaDitherMode.

#### Parameters

config | A ChafaCanvasConfig |

#### Returns

The ChafaDitherMode.

Since: 1.2

### chafa_canvas_config_set_dither_mode ()

    void
    chafa_canvas_config_set_dither_mode (ChafaCanvasConfig *config,
                                         ChafaDitherMode dither_mode);

Sets `config` 's stored ChafaDitherMode to `dither_mode` .

#### Parameters

config | A ChafaCanvasConfig |
dither_mode | A ChafaDitherMode |

Since: 1.2

### chafa_canvas_config_get_dither_grain_size ()

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

Returns `config` 's dither grain size in `width_out` and `height_out` .

#### Parameters

config | A ChafaCanvasConfig |
width_out | Pointer to a location to store grain width |
height_out | Pointer to a location to store grain height |

Since: 1.2

### chafa_canvas_config_set_dither_grain_size ()

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

Sets `config` 's stored dither grain size to `width` by `height` pixels. These values can be 1, 2, 4 or 8. 8 corresponds to the size of an entire character cell. The default is 4 pixels by 4 pixels.

#### Parameters

config | A ChafaCanvasConfig |
width | The desired grain width (1, 2, 4 or 8) |
height | The desired grain height (1, 2, 4 or 8) |

Since: 1.2

### chafa_canvas_config_get_dither_intensity ()

    gfloat
    chafa_canvas_config_get_dither_intensity
                                   (const ChafaCanvasConfig *config);

Returns the relative intensity of the dithering pattern applied during image conversion. 1.0 is the default, corresponding to a moderate intensity.

#### Parameters

config | A ChafaCanvasConfig |

#### Returns

The relative dithering intensity

Since: 1.2

### chafa_canvas_config_set_dither_intensity ()

    void
    chafa_canvas_config_set_dither_intensity
                                   (ChafaCanvasConfig *config,
                                    gfloat intensity);

Sets `config` 's stored relative intensity of the dithering pattern applied during image conversion. 1.0 is the default, corresponding to a moderate intensity. Possible values range from 0.0 to infinity, but in practice, values above 10.0 are rarely useful.

#### Parameters

config | A ChafaCanvasConfig |
intensity | Desired relative dithering intensity |

Since: 1.2

### chafa_canvas_config_get_optimizations ()

    ChafaOptimizations
    chafa_canvas_config_get_optimizations (const ChafaCanvasConfig *config);

Returns `config` 's optimization flags. When enabled, these may produce more compact output at the cost of reduced compatibility and increased CPU use. Output quality is unaffected.

#### Parameters

config | A ChafaCanvasConfig |

#### Returns

The ChafaOptimizations flags.

Since: 1.6

### chafa_canvas_config_set_optimizations ()

    void
    chafa_canvas_config_set_optimizations (ChafaCanvasConfig *config,
                                           ChafaOptimizations optimizations);

Sets `config` 's stored optimization flags. When enabled, these may produce more compact output at the cost of reduced compatibility and increased CPU use. Output quality is unaffected.

#### Parameters

config | A ChafaCanvasConfig |
optimizations | A combination of ChafaOptimizations flags |

Since: 1.6

### chafa_canvas_config_get_passthrough ()

    ChafaPassthrough
    chafa_canvas_config_get_passthrough (const ChafaCanvasConfig *config);

Returns `config` 's ChafaPassthrough setting. This defaults to CHAFA_PASSTHROUGH_NONE.

Passthrough is needed to transmit certain escape codes to the outer terminal when running in an inner terminal environment like tmux. When enabled, this will happen automatically as needed, dictated by information contained in a ChafaTermInfo.

#### Parameters

config | A ChafaCanvasConfig |

#### Returns

The ChafaPassthrough setting

Since: 1.14

### chafa_canvas_config_set_passthrough ()

    void
    chafa_canvas_config_set_passthrough (ChafaCanvasConfig *config,
                                         ChafaPassthrough passthrough);

Indicates which passthrough mode to use. This defaults to CHAFA_PASSTHROUGH_NONE.

Passthrough is needed to transmit certain escape codes to the outer terminal when running in an inner terminal environment like tmux. When enabled, this will happen automatically as needed, dictated by information contained in a ChafaTermInfo.

#### Parameters

config | A ChafaCanvasConfig |
passthrough | A ChafaPassthrough value |

Since: 1.14

## Types and Values

### enum ChafaPixelMode

#### Members

CHAFA_PIXEL_MODE_SYMBOLS | Pixel data is approximated using character symbols ("ANSI art"). |
CHAFA_PIXEL_MODE_SIXELS | Pixel data is encoded as sixels. |
CHAFA_PIXEL_MODE_KITTY | Pixel data is encoded using the Kitty terminal protocol. |
CHAFA_PIXEL_MODE_ITERM2 | Pixel data is encoded using the iTerm2 terminal protocol. |
CHAFA_PIXEL_MODE_MAX | Last supported pixel mode plus one. |

### 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_INDEXED_8 | 8 colors, compatible with original ANSI X3.64. |
CHAFA_CANVAS_MODE_INDEXED_16_8 | 16 FG colors (8 of which enabled with bold/bright) and 8 BG colors. |
CHAFA_CANVAS_MODE_MAX | Last supported canvas mode plus one. |

### enum ChafaDitherMode

#### Members

CHAFA_DITHER_MODE_NONE | No dithering. |
CHAFA_DITHER_MODE_ORDERED | Ordered dithering (Bayer or similar). |
CHAFA_DITHER_MODE_DIFFUSION | Error diffusion dithering (Floyd-Steinberg or similar). |
CHAFA_DITHER_MODE_NOISE | Noise pattern dithering (blue noise or similar). |
CHAFA_DITHER_MODE_MAX | Last supported dither mode plus one. |

### enum ChafaColorExtractor

#### Members

CHAFA_COLOR_EXTRACTOR_AVERAGE | Use the average colors of each symbol's coverage area. |
CHAFA_COLOR_EXTRACTOR_MEDIAN | Use the median colors of each symbol's coverage area. |
CHAFA_COLOR_EXTRACTOR_MAX | Last supported color extractor plus one. |

### enum ChafaOptimizations

#### Members

CHAFA_OPTIMIZATION_REUSE_ATTRIBUTES | Suppress redundant SGR control sequences. |
CHAFA_OPTIMIZATION_SKIP_CELLS | Reserved for future use. |
CHAFA_OPTIMIZATION_REPEAT_CELLS | Use REP sequence to compress repeated runs of similar cells. |
CHAFA_OPTIMIZATION_NONE | All optimizations disabled. |
CHAFA_OPTIMIZATION_ALL | All optimizations enabled. |

### enum ChafaPassthrough

#### Members

CHAFA_PASSTHROUGH_NONE | No passthrough guards will be used. |
CHAFA_PASSTHROUGH_SCREEN | Passthrough guards for GNU Screen will be used. |
CHAFA_PASSTHROUGH_TMUX | Passthrough guards for tmux will be used. |
CHAFA_PASSTHROUGH_MAX | Last supported passthrough mode plus one. |

### ChafaCanvasConfig

    typedef struct ChafaCanvasConfig ChafaCanvasConfig;