1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<refentry id="chafa-using" revision="04 Jan 2024">
<refmeta>
<refentrytitle>Using Chafa in your application</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>Chafa Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Using Chafa in your application</refname>
<refpurpose>How to use Chafa</refpurpose>
</refnamediv>
<refsect1>
<title>Compiling your application</title>
<para>
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
<application>pkg-config</application> utility.
</para>
<para>
The following interactive shell session demonstrates how
<application>pkg-config</application> is used (the actual output on
your system may be different):
<programlisting>
$ 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
</programlisting>
</para>
<para>
See the <ulink url="http://www.freedesktop.org/wiki/Software/pkg-config">pkg-config website</ulink>
for more information about <application>pkg-config</application>.
</para>
<para>
The simplest way to compile a program is to use the command
substitution feature of the shell. If you enclose a command in
backticks (<emphasis>not single quotes</emphasis>), 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:
<programlisting>
$ cc hello.c `pkg-config --cflags --libs chafa` -o hello
</programlisting>
</para>
<note><para>
Note that the name of the file must come before the other options
(such as <emphasis>pkg-config</emphasis>), or else you may get an
error from the linker.
</para></note>
<para>
When using Chafa in your program, you only need to include the toplevel
header <filename>chafa.h</filename>.
</para>
</refsect1>
<refsect1>
<title>An example</title>
<para>
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.
</para>
<para>
Note that it will output UTF-8 regardless of the current locale.
</para>
<programlisting>
#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, 40, 20);
chafa_canvas_config_set_symbol_map (config, symbol_map);
/* Create canvas */
canvas = chafa_canvas_new (config);
/* Draw pixels to canvas */
chafa_canvas_draw_all_pixels (canvas,
CHAFA_PIXEL_RGBA8_UNASSOCIATED,
pixels,
PIX_WIDTH,
PIX_HEIGHT,
PIX_WIDTH * N_CHANNELS);
/* Generate a string that will show the canvas contents on a terminal */
gs = chafa_canvas_print (canvas, NULL);
/* 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;
}
</programlisting>
</refsect1>
</refentry>
|
