]> gitweb.michael.orlitzky.com - libsvgtiny.git/blob - README
src/svgtiny.c: remove old misleading libcss comments
[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
62 To compile libsvgtiny, use the command
63
64 make
65
66 To install libsvgtiny into /usr/local, use
67
68 make install
69
70 The VARIANT variable allows builds for "release" (the default) and "debug"
71 e.g.
72
73 make VARIANT=debug
74
75
76 Testing libsvgtiny
77 ------------------
78
79 The core buildsystem provides a test target which performs basic checks
80
81 make test
82
83 For manual testing a svgtiny_display script is available which renders
84 an svg to a bitmap. This script uses the svgtiny_test program to
85 render an SVG to an imagemagic MVG. It requires that ImageMagick
86 convert is installed to convert the MVG into a bitmap.
87
88 Get an suitable SVG file, for example the tiger svg can be found in
89 the examples directory or downloaded [1]
90
91 Then use svgtiny_display to parse and render it:
92
93 ./svgtiny_display tiger.svg
94 ./svgtiny_display tiger.svg 2
95
96 The optional 2nd argument is a scale.
97
98
99 Using libsvgtiny
100 ----------------
101
102 The interface is in the header svgtiny.h
103
104 #include <svgtiny.h>
105
106 First create a svgtiny_diagram using svgtiny_create():
107
108 struct svgtiny_diagram *diagram;
109 diagram = svgtiny_create();
110
111 This will return a pointer to a new diagram, or NULL if there was not enough
112 memory.
113
114 SVGs are parsed from memory using svgtiny_parse():
115
116 svgtiny_code code;
117 code = svgtiny_parse(diagram, buffer, size, url, 1000, 1000);
118
119 The arguments are the pointer returned by svgtiny_create(), a buffer
120 containing the SVG data, the size of the SVG in bytes, the url that
121 the SVG came from, and the target viewport width and height in pixels.
122
123 The function returns svgtiny_OK if there were no problems, and diagram
124 is updated. The diagram can then be rendered by looping through the
125 array diagram->shape[0..diagram->shape_count]:
126
127 for (unsigned int i = 0; i != diagram->shape_count; i++) {
128
129 Path shapes have a non-NULL path pointer. The path is an array of
130 floats of length path_length. The array contains segment type codes
131 followed by 0 to 3 pairs of coordinates (depending on the segment
132 type):
133
134 - svgtiny_PATH_MOVE x y
135 - svgtiny_PATH_CLOSE
136 - svgtiny_PATH_LINE x y
137 - svgtiny_PATH_BEZIER x1 y1 x2 y2 x3 y3
138
139 A path always starts with a MOVE.
140
141 The fill and stroke attributes give the colors of the path, or
142 svgtiny_TRANSPARENT if the path is not filled or stroked. Colors are
143 in 0xRRGGBB format (except when compiled for RISC OS). The macros
144 svgtiny_RED, svgtiny_GREEN, and svgtiny_BLUE can be used to extract
145 the components.
146
147 The width of the path is in stroke_width.
148
149 Text shapes have a NULL path pointer and a non-NULL text pointer. Text
150 is in UTF-8. The coordinates of the text are in text_x, text_y. Text
151 colors and stroke width are as for paths.
152
153 If memory runs out during parsing, svgtiny_parse() returns
154 svgtiny_OUT_OF_MEMORY, but the diagram is still valid up to the point
155 when memory was exhausted, and may safely be rendered.
156
157 If there is an error in the SVG (for example, an element is missing an
158 attribute required by the specification), svgtiny_SVG_ERROR is
159 returned, but the diagram is still valid up to the point of the
160 error. The error is recorded in diagram->error_message and the line
161 that caused it in diagram->error_line.
162
163 svgtiny_LIBDOM_ERROR indicates that parsing the XML failed. The
164 returned diagram will contain no shapes. svgtiny_NOT_SVG means that
165 the XML did not contain a top-level <svg> element.
166
167 To free memory used by a diagram, use svgtiny_free():
168
169 svgtiny_free(diagram);
170
171 For an example, see svgtiny_test.c.
172
173
174 [1] http://upload.wikimedia.org/wikipedia/commons/f/fd/Ghostscript_Tiger.svg