From 7944e8a06896097c9923c2c6659ff2ffa28c4191 Mon Sep 17 00:00:00 2001 From: James Bursa Date: Sun, 4 May 2008 01:59:15 +0000 Subject: [PATCH] Add an overview of the library. svn path=/trunk/libsvgtiny/; revision=4122 --- README | 149 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 README diff --git a/README b/README new file mode 100644 index 0000000..a728006 --- /dev/null +++ b/README @@ -0,0 +1,149 @@ +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 . + +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 +------------------- +You will require the following tools: + +- a C compiler (some parts of C99 support are required) +- gperf + +and the following libraries: + +- libxml2 + +To compile libsvgtiny, use the command + + make + +To install libsvgtiny into /usr/local, use + + make install + +To cross-compile for RISC OS, use + + make TARGET=riscos + make install TARGET=riscos + +Testing libsvgtiny +------------------ +The svgtiny_display script uses the library to render an SVG. It requires that +ImageMagick convert is installed. + +Get an SVG file, for example +http://www.croczilla.com/svg/samples/tiger/tiger.svg + +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 + +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_LIBXML_ERROR indicates that parsing the XML failed. The returned diagram +will contain no shapes. svgtiny_NOT_SVG means that the XML did not contain a +top-level element. + +To free memory used by a diagram, use svgtiny_free(): + + svgtiny_free(diagram); + +For an example, see svgtiny_test.c. + + + -- 2.44.2