1Guile-Cairo README
2Last updated 1 October 2018.
3
4
5About Guile-Cairo
6=================
7
8Guile-Cairo wraps the Cairo graphics library for Guile Scheme.
9
10
11A pasteable introduction to using Guile-Cairo
12=============================================
13
14;; Paste this into your guile interpreter!
15
16;; This wrapset defines a module `(cairo)'
17
18(use-modules (cairo))
19
20;; Cairo procedures all start with `cairo-'
21
22(cairo-version-string)
23;; => "1.14.8"
24
25;; For most useful things, you have to make a surface first
26
27(define surf (cairo-image-surface-create 'argb32 140 100))
28
29;; Given a surface, you can create a cairo context, and start drawing
30
31(define cr (cairo-create surf))
32
33;; You then need to make a source
34
35(cairo-select-font-face cr "Bitstream Vera Sans" 'normal 'normal)
36(cairo-scale cr 100 100)
37(define pat (cairo-pattern-create-linear 0 0 1 1))
38(cairo-pattern-add-color-stop-rgba pat 1 1 0 0 1)
39(cairo-pattern-add-color-stop-rgba pat 0 0 0 1 1)
40(cairo-set-source cr pat)
41
42;; Then you make your mask
43
44(cairo-set-font-size cr 0.4)
45(cairo-move-to cr 0.0 0.6)
46(cairo-show-text cr "(cairo)")
47
48;; Finally you can write the surface out to a file if you want
49
50(cairo-surface-write-to-png surf "/tmp/guile-cairo.png")
51
52;; Functions that write out to files always take the filename as their
53;; last argument, which is optional. If you leave it out, guile-cairo
54;; will write to the current output port. So this is another way of
55;; doing the same thing:
56
57(with-output-to-file "/tmp/guile-cairo.png"
58  (lambda () (cairo-surface-write-to-png surf)))
59
60;; Enumerated types are represented as symbols. The available set of
61;; symbols for any given type can be retrieved at runtime
62
63(cairo-format-get-values)
64;; => (argb32 rgb24 a8 a1)
65
66;; That's it!
67
68
69Notes
70=====
71
72Guile-Cairo wraps almost all of Cairo's procedures. Notable exceptions
73include functions that read or write from streams instead of files and
74raw access to image data.
75
76Guile-Cairo wraps all of Cairo's types. As mentioned above, enumerated
77values are represented by symbols, but functions accept integers as
78well. Struct types like cairo_rectangle_t are represented as vectors.
79Constructors of the form cairo-make-rectangle are provided, as well as
80accessors like cairo-rectangle:x.
81
82
83Using Guile-Cairo's C interface
84===============================
85
86These days Cairo forms a part of many software stacks; its types are
87seen in the APIs of a number of other libraries. Guile-Cairo provides an
88interface to represent all cairo C types as scheme values.
89
90To build against this library in your C program, first you will need to
91get the CFLAGS and LDFLAGS to link against libguile-cairo. Autoconf
92users should use:
93
94PKG_CHECK_MODULES(GUILE_CAIRO, guile-cairo >= 1.3.0)
95AC_SUBST(GUILE_CAIRO_CFLAGS)
96AC_SUBST(GUILE_CAIRO_LDFLAGS)
97
98In your C files you should then:
99
100  #include <guile-cairo.h>
101
102The type wrapping functions are all in the form scm_to_TYPE and
103scm_from_TYPE, where TYPE could be cairo_surface, for example. For
104vector types there is also scm_fill_TYPE, which expects you to have an
105already-allocated structure to fill. Additionally there are
106scm_take_TYPE functions that will take ownership of the pointer in
107question, for example for constructors and for non-refcounted opaque
108objects like cairo_font_options_t.
109
110
111Known bugs
112==================
113
114[https://bugs.freedesktop.org/show_bug.cgi?id=30510] Reported by CK Jester-Young
115
116The documentation for cairo-pdf-surface-create specifies the arguments as
117(filename width-in-points height-in-points). In actuality, it's (sx sy
118[filename]), where an unspecified filename means the output is sent to the
119current output port.
120
121This bug hasn't been fixed because of inability to regenerate the
122documentation. Any help in this sense is appreciated. Please have a look at
123
124- doc/README
125- commit 8e73e952f8797159719b770fafecbdcb6f87152c
126- https://lists.gnu.org/archive/html/guile-user/2018-08/msg00117.html
127
128
129Copying Guile-Cairo
130===================
131
132Distribution of Guile-Cairo is under the LGPL. See the COPYING file for
133more information.
134
135
136Contact info
137============
138
139  Mailing List: guile-user@gnu.org
140  Homepage:     http://www.non-gnu.org/guile-cairo/
141  Download:     http://www.non-gnu.org/guile-cairo/download/
142
143
144Build dependencies
145==================
146
147* Guile 1.8.0 or newer
148  http://www.gnu.org/software/guile/
149* Cairo 1.10.0 or newer
150  http://cairographics.org/
151* guile-lib 0.1.6 or newer (only for `make check')
152  https://www.nongnu.org/guile-lib
153
154See 'Known bugs' in this file and doc/README if you wish to rebuild the
155documentation.
156
157Installation quickstart
158=======================
159
160Install using the standard autotools incantation:
161  ./configure --prefix=/opt/guile-cairo && make && make install.
162
163Build from CVS or Arch using ./autogen.sh --prefix=/opt/guile-cairo && make.
164
165You can run without installing, just run './env guile'.
166
167
168Copying this file
169=================
170
171Copyright (C) 2007,2011 Andy Wingo <wingo pobox.com>
172
173Copying and distribution of this file, with or without modification, are
174permitted in any medium without royalty provided the copyright notice
175and this notice are preserved.
176