]> gitweb.michael.orlitzky.com - libsvgtiny.git/blob - README
src/svgtiny_css.c: implement node_has_attribute_equal() select handler
[libsvgtiny.git] / README
1 Libsvgtiny
2 ==========
3
4 http://www.netsurf-browser.org/projects/libsvgtiny/
5
6 Libsvgtiny is a library for parsing SVG files for display.
7
8 The overall idea of the library is to take some SVG as input, and
9 return a list of paths and texts which can be rendered easily. The
10 library does not do the actual rendering.
11
12 All supported SVG objects, for example circles, lines, and gradient
13 filled shapes, are converted to flat-filled paths or a fragment of
14 text, and all coordinates are converted, transformed etc. to pixels.
15
16 Libsvgtiny is Licensed under the MIT License,
17 http://opensource.org/licenses/mit-license.php
18
19 Written by James Bursa <james@netsurf-browser.org>.
20
21
22 SVG support
23 -----------
24
25 Libsvgtiny is initially aiming to implement SVG Tiny, as defined in
26 http://www.w3.org/TR/SVGMobile/.
27
28 SVG Tiny elements supported: defs, g, svg, circle, line, path, polygon,
29 polyline, rect, text
30
31 SVG Tiny elements not yet supported: desc, metadata, title, use, a,
32 switch, ellipse, image, font, font-face, font-face-name, font-face-src,
33 glyph, hkern, missing-glyph, animate, animateColor, animateMotion,
34 animateTransform, mpath, set, foreignObject
35
36 Additional elements supported: linearGradient, stop
37
38 Text support is incomplete.
39
40 The style attribute is supported.
41
42
43 Building libsvgtiny
44 -------------------
45
46 The library uses the Netsurf core buildsystem which must be available
47 (usually at the same level as the libsvg source)
48
49 The PREFIX variable can be used to perform builds which do not install
50 to global system paths.
51
52 You will require the following tools:
53
54 - a C compiler (some parts of C99 support are required)
55 - gperf
56
57 following additional libraries are required:
58
59 - libwapcaplet
60 - libdom
61 - libcss
62
63 To compile libsvgtiny, use the command
64
65 make
66
67 To install libsvgtiny into /usr/local, use
68
69 make install
70
71 The VARIANT variable allows builds for "release" (the default) and "debug"
72 e.g.
73
74 make VARIANT=debug
75
76
77 Testing libsvgtiny
78 ------------------
79
80 The core buildsystem provides a test target which performs basic checks
81
82 make test
83
84 For manual testing a svgtiny_display script is available which renders
85 an svg to a bitmap. This script uses the svgtiny_test program to
86 render an SVG to an imagemagic MVG. It requires that ImageMagick
87 convert is installed to convert the MVG into a bitmap.
88
89 Get an suitable SVG file, for example the tiger svg can be found in
90 the examples directory or downloaded [1]
91
92 Then use svgtiny_display to parse and render it:
93
94 ./svgtiny_display tiger.svg
95 ./svgtiny_display tiger.svg 2
96
97 The optional 2nd argument is a scale.
98
99
100 Using libsvgtiny
101 ----------------
102
103 The interface is in the header svgtiny.h
104
105 #include <svgtiny.h>
106
107 First create a svgtiny_diagram using svgtiny_create():
108
109 struct svgtiny_diagram *diagram;
110 diagram = svgtiny_create();
111
112 This will return a pointer to a new diagram, or NULL if there was not enough
113 memory.
114
115 SVGs are parsed from memory using svgtiny_parse():
116
117 svgtiny_code code;
118 code = svgtiny_parse(diagram, buffer, size, url, 1000, 1000);
119
120 The arguments are the pointer returned by svgtiny_create(), a buffer
121 containing the SVG data, the size of the SVG in bytes, the url that
122 the SVG came from, and the target viewport width and height in pixels.
123
124 The function returns svgtiny_OK if there were no problems, and diagram
125 is updated. The diagram can then be rendered by looping through the
126 array diagram->shape[0..diagram->shape_count]:
127
128 for (unsigned int i = 0; i != diagram->shape_count; i++) {
129
130 Path shapes have a non-NULL path pointer. The path is an array of
131 floats of length path_length. The array contains segment type codes
132 followed by 0 to 3 pairs of coordinates (depending on the segment
133 type):
134
135 - svgtiny_PATH_MOVE x y
136 - svgtiny_PATH_CLOSE
137 - svgtiny_PATH_LINE x y
138 - svgtiny_PATH_BEZIER x1 y1 x2 y2 x3 y3
139
140 A path always starts with a MOVE.
141
142 The fill and stroke attributes give the colors of the path, or
143 svgtiny_TRANSPARENT if the path is not filled or stroked. Colors are
144 in 0xRRGGBB format (except when compiled for RISC OS). The macros
145 svgtiny_RED, svgtiny_GREEN, and svgtiny_BLUE can be used to extract
146 the components.
147
148 The width of the path is in stroke_width.
149
150 Text shapes have a NULL path pointer and a non-NULL text pointer. Text
151 is in UTF-8. The coordinates of the text are in text_x, text_y. Text
152 colors and stroke width are as for paths.
153
154 If memory runs out during parsing, svgtiny_parse() returns
155 svgtiny_OUT_OF_MEMORY, but the diagram is still valid up to the point
156 when memory was exhausted, and may safely be rendered.
157
158 If there is an error in the SVG (for example, an element is missing an
159 attribute required by the specification), svgtiny_SVG_ERROR is
160 returned, but the diagram is still valid up to the point of the
161 error. The error is recorded in diagram->error_message and the line
162 that caused it in diagram->error_line.
163
164 svgtiny_LIBDOM_ERROR indicates that parsing the XML failed. The
165 returned diagram will contain no shapes.
166
167 svgtiny_LIBCSS_ERROR indicates that something went wrong in
168 libcss. Either it failed to initialize, or it failed to parse
169 something within the SVG, or it failed un-initialize (free
170 resources). Except in the last case, the returned diagram will be
171 empty.
172
173 svgtiny_NOT_SVG means that the XML did not contain a top-level
174 <svg> element.
175
176 To free memory used by a diagram, use svgtiny_free():
177
178 svgtiny_free(diagram);
179
180 For an example, see svgtiny_test.c.
181
182
183 [1] http://upload.wikimedia.org/wikipedia/commons/f/fd/Ghostscript_Tiger.svg