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