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_set_placement ()
void | chafa_canvas_draw_all_pixels ()
GString * | chafa_canvas_print ()
void | chafa_canvas_print_rows ()
gchar ** | chafa_canvas_print_rows_strv ()
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_set_placement ()

    void
    chafa_canvas_set_placement (ChafaCanvas *canvas,
                                ChafaPlacement *placement);

Places `placement` on `canvas` , replacing the latter's content. The placement will cover the entire canvas.

The canvas will keep a reference to the placement until it is replaced or the canvas itself is freed.

#### Parameters

canvas | Canvas to place the placement on |
placement | Placement to place |

Since: 1.14

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

    void
    chafa_canvas_print_rows (ChafaCanvas *canvas,
                             ChafaTermInfo *term_info,
                             GString ***array_out,
                             gint *array_len_out);

Builds an array of UTF-8 strings made up of terminal control sequences and symbols representing the canvas' current contents. These can 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.

The array will be `NULL`-terminated. The element count does not include the terminator.

When the canvas' pixel mode is `CHAFA_PIXEL_MODE_SYMBOLS`, each element will hold the contents of exactly one symbol row. There will be no row separators, newlines or control sequences to reposition the cursor between rows. Row positioning is left to the caller.

In other pixel modes, there may be one or more strings, but the splitting criteria should not be relied on. They must be printed in sequence, exactly as they appear.

#### Parameters

canvas | The canvas to generate a printable representation of |
term_info | Terminal to format for, or `NULL` for fallback |
array_out | Pointer to storage for resulting array pointer |
array_len_out | Pointer to storage for array's element count, or `NULL` |

Since: 1.14

### chafa_canvas_print_rows_strv ()

    gchar **
    chafa_canvas_print_rows_strv (ChafaCanvas *canvas,
                                  ChafaTermInfo *term_info);

Builds an array of UTF-8 strings made up of terminal control sequences and symbols representing the canvas' current contents. These can 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.

The array will be `NULL`-terminated and can be freed with `g_strfreev()`.

When the canvas' pixel mode is `CHAFA_PIXEL_MODE_SYMBOLS`, each element will hold the contents of exactly one symbol row. There will be no row separators, newlines or control sequences to reposition the cursor between rows. Row positioning is left to the caller.

In other pixel modes, there may be one or more strings, but the splitting criteria should not be relied on. They must be printed in sequence, exactly as they appear.

#### Parameters

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

#### Returns

A `NULL`-terminated array of string pointers

Since: 1.14

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