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_contents_rgba8 ()
GString * | chafa_canvas_build_ansi ()

## 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_set_contents_rgba8()` and create an ANSI text 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 | Canvas configuration to use for this canvas |

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

    void
    chafa_canvas_set_contents_rgba8 (ChafaCanvas *canvas,
                                     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` . 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 |

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

## Types and Values

### ChafaCanvas

    typedef struct ChafaCanvas ChafaCanvas;