Libsvgtiny
==========

http://www.netsurf-browser.org/projects/libsvgtiny/

Libsvgtiny is a library for parsing SVG files for display.

The overall idea of the library is to take some SVG as input, and
return a list of paths and texts which can be rendered easily. The
library does not do the actual rendering.

All supported SVG objects, for example circles, lines, and gradient
filled shapes, are converted to flat-filled paths or a fragment of
text, and all coordinates are converted, transformed etc. to pixels.

Libsvgtiny is Licensed under the MIT License,
http://opensource.org/licenses/mit-license.php

Written by James Bursa <james@netsurf-browser.org>.


SVG support
-----------

Libsvgtiny is initially aiming to implement SVG Tiny, as defined in
http://www.w3.org/TR/SVGMobile/.

SVG Tiny elements supported: defs, g, svg, circle, line, path, polygon,
polyline, rect, text

SVG Tiny elements not yet supported: desc, metadata, title, use, a,
switch, ellipse, image, font, font-face, font-face-name, font-face-src,
glyph, hkern, missing-glyph, animate, animateColor, animateMotion,
animateTransform, mpath, set, foreignObject

Additional elements supported: linearGradient, stop

Text support is incomplete.

The style attribute is supported.


Building libsvgtiny
-------------------

The library uses the Netsurf core buildsystem which must be available
(usually at the same level as the libsvg source)

The PREFIX variable can be used to perform builds which do not install
to global system paths.

You will require the following tools:

 - a C compiler (some parts of C99 support are required)
 - gperf

following additional libraries are required:

 - libwapcaplet
 - libdom
 - libcss

To compile libsvgtiny, use the command

  make

To install libsvgtiny into /usr/local, use

  make install

The VARIANT variable allows builds for "release" (the default) and "debug"
e.g.

  make VARIANT=debug


Testing libsvgtiny
------------------

The core buildsystem provides a test target which performs basic checks

  make test

For manual testing a svgtiny_display script is available which renders
an svg to a bitmap. This script uses the svgtiny_test program to
render an SVG to an imagemagic MVG. It requires that ImageMagick
convert is installed to convert the MVG into a bitmap.

Get an suitable SVG file, for example the tiger svg can be found in
the examples directory or downloaded [1]

Then use svgtiny_display to parse and render it:

  ./svgtiny_display tiger.svg
  ./svgtiny_display tiger.svg 2

The optional 2nd argument is a scale.


Using libsvgtiny
----------------

The interface is in the header svgtiny.h

  #include <svgtiny.h>

First create a svgtiny_diagram using svgtiny_create():

  struct svgtiny_diagram *diagram;
  diagram = svgtiny_create();

This will return a pointer to a new diagram, or NULL if there was not enough
memory.

SVGs are parsed from memory using svgtiny_parse():

  svgtiny_code code;
  code = svgtiny_parse(diagram, buffer, size, url, 1000, 1000);

The arguments are the pointer returned by svgtiny_create(), a buffer
containing the SVG data, the size of the SVG in bytes, the url that
the SVG came from, and the target viewport width and height in pixels.

The function returns svgtiny_OK if there were no problems, and diagram
is updated. The diagram can then be rendered by looping through the
array diagram->shape[0..diagram->shape_count]:

  for (unsigned int i = 0; i != diagram->shape_count; i++) {

Path shapes have a non-NULL path pointer. The path is an array of
floats of length path_length. The array contains segment type codes
followed by 0 to 3 pairs of coordinates (depending on the segment
type):

- svgtiny_PATH_MOVE x y
- svgtiny_PATH_CLOSE
- svgtiny_PATH_LINE x y
- svgtiny_PATH_BEZIER x1 y1 x2 y2 x3 y3

A path always starts with a MOVE.

The fill and stroke attributes give the colors of the path, or
svgtiny_TRANSPARENT if the path is not filled or stroked. Colors are
in 0xRRGGBB format (except when compiled for RISC OS). The macros
svgtiny_RED, svgtiny_GREEN, and svgtiny_BLUE can be used to extract
the components.

The width of the path is in stroke_width.

Text shapes have a NULL path pointer and a non-NULL text pointer. Text
is in UTF-8. The coordinates of the text are in text_x, text_y. Text
colors and stroke width are as for paths.

If memory runs out during parsing, svgtiny_parse() returns
svgtiny_OUT_OF_MEMORY, but the diagram is still valid up to the point
when memory was exhausted, and may safely be rendered.

If there is an error in the SVG (for example, an element is missing an
attribute required by the specification), svgtiny_SVG_ERROR is
returned, but the diagram is still valid up to the point of the
error. The error is recorded in diagram->error_message and the line
that caused it in diagram->error_line.

svgtiny_LIBDOM_ERROR indicates that parsing the XML failed. The
returned diagram will contain no shapes.

svgtiny_LIBCSS_ERROR indicates that something went wrong in
libcss. Either it failed to initialize, or it failed to parse
something within the SVG, or it failed un-initialize (free
resources). Except in the last case, the returned diagram will be
empty.

svgtiny_NOT_SVG means that the XML did not contain a top-level
<svg> element.

To free memory used by a diagram, use svgtiny_free():

  svgtiny_free(diagram);

For an example, see svgtiny_test.c.


[1] http://upload.wikimedia.org/wikipedia/commons/f/fd/Ghostscript_Tiger.svg