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_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_build_ansi ()

    GString *
    chafa_canvas_build_ansi (ChafaCanvas *canvas);

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;