README

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