ChafaCanvas: Chafa Reference Manual

## ChafaCanvas ChafaCanvas — A canvas that renders to text |

## Functions

ChafaCanvas * | chafa_canvas_new ()
ChafaCanvas * | chafa_canvas_new_similar ()
void | chafa_canvas_ref ()
void | chafa_canvas_unref ()
const ChafaCanvasConfig * | chafa_canvas_peek_config ()
void | chafa_canvas_draw_all_pixels ()
GString * | chafa_canvas_print ()
gunichar | chafa_canvas_get_char_at ()
gint | chafa_canvas_set_char_at ()
void | chafa_canvas_get_colors_at ()
void | chafa_canvas_set_colors_at ()
void | chafa_canvas_get_raw_colors_at ()
void | chafa_canvas_set_raw_colors_at ()
GString * | chafa_canvas_build_ansi ()
void | chafa_canvas_set_contents_rgba8 ()

## Types and Values

typedef | ChafaCanvas

## Description

A ChafaCanvas is a canvas that can render its contents as text strings.

To create a new ChafaCanvas, use `chafa_canvas_new()`. If you want to specify any parameters, like the geometry, color space and so on, you must create a ChafaCanvasConfig first.

You can draw an image to the canvas using `chafa_canvas_draw_all_pixels()` and create an ANSI text (or sixel) representation of the canvas' current contents using `chafa_canvas_build_ansi()`.

## Functions

### chafa_canvas_new ()

    ChafaCanvas *
    chafa_canvas_new (const ChafaCanvasConfig *config);

Creates a new canvas with the specified configuration. The canvas makes a private copy of the configuration, so it will not be affected by subsequent changes.

#### Parameters

config | Configuration to use or `NULL` for hardcoded defaults |

#### Returns

The new canvas

### chafa_canvas_new_similar ()

    ChafaCanvas *
    chafa_canvas_new_similar (ChafaCanvas *orig);

Creates a new canvas configured similarly to `orig` .

#### Parameters

orig | Canvas to copy configuration from |

#### Returns

The new canvas

### chafa_canvas_ref ()

    void
    chafa_canvas_ref (ChafaCanvas *canvas);

Adds a reference to `canvas` .

#### Parameters

canvas | Canvas to add a reference to |

### chafa_canvas_unref ()

    void
    chafa_canvas_unref (ChafaCanvas *canvas);

Removes a reference from `canvas` . When remaining references drops to zero, the canvas is freed and can no longer be used.

#### Parameters

canvas | Canvas to remove a reference from |

### chafa_canvas_peek_config ()

    const ChafaCanvasConfig *
    chafa_canvas_peek_config (ChafaCanvas *canvas);

Returns a pointer to the configuration belonging to `canvas` . This can be inspected using the ChafaCanvasConfig getter functions, but not changed.

#### Parameters

canvas | Canvas whose configuration to inspect |

#### Returns

A pointer to the canvas' immutable configuration

### chafa_canvas_draw_all_pixels ()

    void
    chafa_canvas_draw_all_pixels (ChafaCanvas *canvas,
                                  ChafaPixelType src_pixel_type,
                                  const guint8 *src_pixels,
                                  gint src_width,
                                  gint src_height,
                                  gint src_rowstride);

Replaces pixel data of `canvas` with a copy of that found at `src_pixels` , which must be in one of the formats supported by ChafaPixelType.

#### Parameters

canvas | Canvas whose pixel data to replace |
src_pixel_type | Pixel format of `src_pixels` |
src_pixels | Pointer to the start of source pixel memory |
src_width | Width in pixels of source pixel data |
src_height | Height in pixels of source pixel data |
src_rowstride | Number of bytes between the start of each pixel row |

Since: 1.2

### chafa_canvas_print ()

    GString *
    chafa_canvas_print (ChafaCanvas *canvas,
                        ChafaTermInfo *term_info);

Builds a UTF-8 string of terminal control sequences and symbols representing the canvas' current contents. This can e.g. be printed to a terminal. The exact choice of escape sequences and symbols, dimensions, etc. is determined by the configuration assigned to `canvas` on its creation.

All output lines except for the last one will end in a newline.

#### Parameters

canvas | The canvas to generate a printable representation of |
term_info | Terminal to format for, or `NULL` for fallback |

#### Returns

A UTF-8 string of terminal control sequences and symbols

Since: 1.6

### chafa_canvas_get_char_at ()

    gunichar
    chafa_canvas_get_char_at (ChafaCanvas *canvas,
                              gint x,
                              gint y);

Returns the character at cell (x, y). The coordinates are zero-indexed. For double-width characters, the leftmost cell will contain the character and the rightmost cell will contain 0.

#### Parameters

canvas | The canvas to inspect |
x | Column of character cell to inspect |
y | Row of character cell to inspect |

#### Returns

The character at (x, y)

Since: 1.8

### chafa_canvas_set_char_at ()

    gint
    chafa_canvas_set_char_at (ChafaCanvas *canvas,
                              gint x,
                              gint y,
                              gunichar c);

Sets the character at cell (x, y). The coordinates are zero-indexed. For double-width characters, the leftmost cell must contain the character and the cell to the right of it will automatically be set to 0.

If the character is a nonprintable or zero-width, no change will be made.

#### Parameters

canvas | The canvas to manipulate |
x | Column of character cell to manipulate |
y | Row of character cell to manipulate |
c | The character value to store |

#### Returns

The number of cells output (0, 1 or 2)

Since: 1.8

### chafa_canvas_get_colors_at ()

    void
    chafa_canvas_get_colors_at (ChafaCanvas *canvas,
                                gint x,
                                gint y,
                                gint *fg_out,
                                gint *bg_out);

Gets the colors at cell (x, y). The coordinates are zero-indexed. For double-width characters, both cells will contain the same colors.

The colors will be -1 for transparency, packed 8bpc RGB otherwise, i.e. 0x00RRGGBB hex.

If the canvas is in an indexed mode, palette lookups will be made for you.

#### Parameters

canvas | The canvas to inspect |
x | Column of character cell to inspect |
y | Row of character cell to inspect |
fg_out | Storage for foreground color |
bg_out | Storage for background color |

Since: 1.8

### chafa_canvas_set_colors_at ()

    void
    chafa_canvas_set_colors_at (ChafaCanvas *canvas,
                                gint x,
                                gint y,
                                gint fg,
                                gint bg);

Sets the colors at cell (x, y). The coordinates are zero-indexed. For double-width characters, both cells will be set to the same color.

The colors must be -1 for transparency, packed 8bpc RGB otherwise, i.e. 0x00RRGGBB hex.

If the canvas is in an indexed mode, palette lookups will be made for you.

#### Parameters

canvas | The canvas to manipulate |
x | Column of character cell to manipulate |
y | Row of character cell to manipulate |
fg | Foreground color |
bg | Background color |

Since: 1.8

### chafa_canvas_get_raw_colors_at ()

    void
    chafa_canvas_get_raw_colors_at (ChafaCanvas *canvas,
                                    gint x,
                                    gint y,
                                    gint *fg_out,
                                    gint *bg_out);

Gets the colors at cell (x, y). The coordinates are zero-indexed. For double-width characters, both cells will contain the same colors.

The colors will be -1 for transparency, packed 8bpc RGB, i.e. 0x00RRGGBB hex in truecolor mode, or the raw pen value (0-255) in indexed modes.

It's the caller's responsibility to handle the color values correctly according to the canvas mode (truecolor or indexed).

#### Parameters

canvas | The canvas to inspect |
x | Column of character cell to inspect |
y | Row of character cell to inspect |
fg_out | Storage for foreground color |
bg_out | Storage for background color |

Since: 1.8

### chafa_canvas_set_raw_colors_at ()

    void
    chafa_canvas_set_raw_colors_at (ChafaCanvas *canvas,
                                    gint x,
                                    gint y,
                                    gint fg,
                                    gint bg);

Sets the colors at cell (x, y). The coordinates are zero-indexed. For double-width characters, both cells will be set to the same color.

The colors must be -1 for transparency, packed 8bpc RGB, i.e. 0x00RRGGBB hex in truecolor mode, or the raw pen value (0-255) in indexed modes.

It's the caller's responsibility to handle the color values correctly according to the canvas mode (truecolor or indexed).

#### Parameters

canvas | The canvas to manipulate |
x | Column of character cell to manipulate |
y | Row of character cell to manipulate |
fg | Foreground color |
bg | Background color |

Since: 1.8

### chafa_canvas_build_ansi ()

    GString *
    chafa_canvas_build_ansi (ChafaCanvas *canvas);

`chafa_canvas_build_ansi` has been deprecated since version 1.6 and should not be used in newly-written code.

Use `chafa_canvas_print()` instead.

Builds a UTF-8 string of ANSI sequences and symbols representing the canvas' current contents. This can e.g. be printed to a terminal. The exact choice of escape sequences and symbols, dimensions, etc. is determined by the configuration assigned to `canvas` on its creation.

All output lines except for the last one will end in a newline.

#### Parameters

canvas | The canvas to generate an ANSI character representation of |

#### Returns

A UTF-8 string of ANSI sequences and symbols

### chafa_canvas_set_contents_rgba8 ()

    void
    chafa_canvas_set_contents_rgba8 (ChafaCanvas *canvas,
                                     const guint8 *src_pixels,
                                     gint src_width,
                                     gint src_height,
                                     gint src_rowstride);

`chafa_canvas_set_contents_rgba8` has been deprecated since version 1.2 and should not be used in newly-written code.

Use `chafa_canvas_draw_all_pixels()` instead.

Replaces pixel data of `canvas` with a copy of that found at `src_pixels` . The source data must be in packed 8-bits-per-channel RGBA format. The alpha value is expressed as opacity (0xff is opaque) and is not premultiplied.

#### Parameters

canvas | Canvas whose pixel data to replace |
src_pixels | Pointer to the start of source pixel memory |
src_width | Width in pixels of source pixel data |
src_height | Height in pixels of source pixel data |
src_rowstride | Number of bytes between the start of each pixel row |

## Types and Values

### ChafaCanvas

    typedef struct ChafaCanvas ChafaCanvas;