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