Using Chafa in your application: Chafa Reference Manual

Using Chafa in your application

Using Chafa in your application — How to use Chafa

Compiling your application

To compile an application using Chafa, you need to tell the compiler where to find the Chafa header files and libraries. This is done with the pkg-config utility.

The following interactive shell session demonstrates how pkg-config is used (the actual output on your system may be different):

$ pkg-config --cflags chafa
-I/usr/include/chafa -I/usr/include/glib-2.0 -I/usr/lib64/glib-2.0/include
$ pkg-config --libs chafa
-lm -lchafa -lglib-2.0

See the pkg-config website for more information about pkg-config.

The simplest way to compile a program is to use the command substitution feature of the shell. If you enclose a command in backticks (not single quotes), then its output will be substituted into the command line before execution. So to compile Hello, World program using Chafa you would type the following:

$ cc hello.c `pkg-config --cflags --libs chafa` -o hello

Note that the name of the file must come before the other options (such as pkg-config), or else you may get an error from the linker.

When using Chafa in your program, you only need to include the toplevel header chafa.h.

An example

The following program turns a 3x3 red X stored in a const array into an ANSI string and prints it to stdout. It can be compiled as described in the previous section and run without arguments.

Note that it will output UTF-8 regardless of the current locale.

#include <chafa.h>
#include <stdio.h>

#define PIX_WIDTH 3
#define PIX_HEIGHT 3
#define N_CHANNELS 4

int
main (int argc, char *argv [])
{
    const guint8 pixels [PIX_WIDTH * PIX_HEIGHT * N_CHANNELS] =
    {
        0xff, 0x00, 0x00, 0xff, 0x00, 0x00, 0x00, 0xff, 0xff, 0x00, 0x00, 0xff,
        0x00, 0x00, 0x00, 0xff, 0xff, 0x00, 0x00, 0xff, 0x00, 0x00, 0x00, 0xff,
        0xff, 0x00, 0x00, 0xff, 0x00, 0x00, 0x00, 0xff, 0xff, 0x00, 0x00, 0xff
    };
    ChafaSymbolMap *symbol_map;
    ChafaCanvasConfig *config;
    ChafaCanvas *canvas;
    GString *gs;

    /* Specify the symbols we want */
    symbol_map = chafa_symbol_map_new ();
    chafa_symbol_map_add_by_tags (symbol_map, CHAFA_SYMBOL_TAG_ALL);

    /* Set up a configuration with the symbols and the canvas size in characters */
    config = chafa_canvas_config_new ();
    chafa_canvas_config_set_geometry (config, 23, 12);
    chafa_canvas_config_set_symbol_map (config, symbol_map);

    /* Create canvas */
    canvas = chafa_canvas_new (config);

    /* Draw pixels and build ANSI string */
    chafa_canvas_draw_all_pixels (canvas,
                                  CHAFA_PIXEL_RGBA8_UNASSOCIATED,
                                  pixels,
                                  PIX_WIDTH,
                                  PIX_HEIGHT,
                                  PIX_WIDTH * N_CHANNELS);
    gs = chafa_canvas_build_ansi (canvas);

    /* Print the string */
    fwrite (gs->str, sizeof (char), gs->len, stdout);
    fputc ('\n', stdout);

    /* Free resources */
    g_string_free (gs, TRUE);
    chafa_canvas_unref (canvas);
    chafa_canvas_config_unref (config);
    chafa_symbol_map_unref (symbol_map);

    return 0;
}