Tutorial¶
This tutorial introduces SVG++ features by adding them one-by-one into some sample application.
All SVG++ headers may be included through this one:
#include <svgpp/svgpp.hpp>
All SVG++ code is placed in svgpp
namespace. We’ll import the entire namespace in our sample.
Handling Shapes Geometry¶
Basic pattern of SVG++ usage: call document_traversal::load_document
method, passing XML element and context to it.
Library will call methods of context, passing the parsed data.
#include <svgpp/svgpp.hpp>
using namespace svgpp;
class Context
{
public:
void path_move_to(double x, double y, tag::coordinate::absolute);
void path_line_to(double x, double y, tag::coordinate::absolute);
void path_cubic_bezier_to(
double x1, double y1,
double x2, double y2,
double x, double y,
tag::coordinate::absolute);
void path_quadratic_bezier_to(
double x1, double y1,
double x, double y,
tag::coordinate::absolute);
void path_elliptical_arc_to(
double rx, double ry, double x_axis_rotation,
bool large_arc_flag, bool sweep_flag,
double x, double y,
tag::coordinate::absolute);
void path_close_subpath();
void path_exit();
void on_enter_element(tag::element::any);
void on_exit_element();
};
typedef
boost::mpl::set<
// SVG Structural Elements
tag::element::svg,
tag::element::g,
// SVG Shape Elements
tag::element::circle,
tag::element::ellipse,
tag::element::line,
tag::element::path,
tag::element::polygon,
tag::element::polyline,
tag::element::rect
>::type processed_elements_t;
void loadSvg(xml_element_t xml_root_element)
{
Context context;
document_traversal<
processed_elements<processed_elements_t>,
processed_attributes<traits::shapes_attributes_by_element>
>::load_document(xml_root_element, context);
}
document_traversal is a facade that provides access to most library capabilities.
In most cases only some subset of SVG elements is needed, so we pass
named template parameter processed_elements
to document_traversal
template class. In our case it is processed_elements_t
-
boost::mpl::set
that combines traits::shape_elements
(enumerates SVG
shapes) with svg and g elements.
SVG++ references SVG element types by tags.
We choose SVG attributes subset and pass it as
processed_attributes parameter.
traits::shapes_attributes_by_element
contains attributes, that describe geometry of all shapes
({x, y, width, height, rx and ry} for rect, {d} for path etc.).
In this sample the same context instance is used for all SVG elements.
Context::on_enter_element(element_tag)
is called when moving to child SVG element, type
of child element passed as tag in the only argument (tag::element::any
is a base class for all element tags).
on_exit_element()
is called when processing of child element is finished:
XML element | Call to context |
---|---|
<svg> |
on_enter_element(tag::element::svg()) |
<rect |
on_enter_element(tag::element::rect()) |
x="100" y="200" |
|
/> |
on_exit_element() |
<g> |
on_enter_element(tag::element::g()) |
<rect |
on_enter_element(tag::element::rect()) |
x="300" y="100" |
|
/> |
on_exit_element() |
</g> |
on_exit_element() |
</svg> |
on_exit_element() |
Calls like path_XXXX
except path_exit
correspond to SVG
path data commands.
path_exit
is called after path data attribute was parsed.
SVG++ by default (see Path Policy for details):
- converts relative coordinates to absolute ones;
- commands for horizontal and vertical lines (H, h, V, v) converts to calls to
path_line_to
with two coordinates; - shorthand/smooth curveto and shorthand/smooth quadratic Bézier curveto replaces with calls with full parameters list.
SVG++ by default converts basic shapes to path (see Basic Shapes Policy for details).
XML Parser¶
We didn’t declared xml_element_t
yet.
Let’s use RapidXML NS library (it is a clone of
RapidXML with namespace handling added) that comes with SVG++
in the third_party/rapidxml_ns/rapidxml_ns.hpp
file. It’s a single header library, so we just need to point to its header:
#include <rapidxml_ns/rapidxml_ns.hpp>
Then we must include SVG++ policy for chosen XML parser:
#include <svgpp/policy/xml/rapidxml_ns.hpp>
XML policy headers don’t include parser header because their location and names may differ. The programmer must include appropriate XML parser header herself before including policy header.
Setting appropriate XML element type for RapidXML NS parser:
typedef rapidxml_ns::xml_node<> const * xml_element_t;
You can find the full cpp file here: src/samples/sample01a.cpp.
Handling Transformations¶
Just add tag::attribute::transform
to processed_attributes
list and transform_matrix
method to Context
class:
void transform_matrix(const boost::array<double, 6> & matrix);
typedef
boost::mpl::insert<
traits::shapes_attributes_by_element,
tag::attribute::transform
>::type processed_attributes_t;
/* ... */
document_traversal<
processed_elements<processed_elements_t>,
processed_attributes<processed_attributes_t>
>::load_document(xml_root_element, context);
Passed matrix
array [a b c d e f]
correspond to this matrix:

The default SVG++ behavior is to join all transformations in transform
attribute into single affine transformation matrix.
Source file: src/samples/sample01b.cpp.
Handling Viewports¶
The svg element may be used inside SVG document to establish a new viewport.
To process new viewport coordinate system and new user coordinate system
several attributes must be processed (x, y, width, height, preserveAspectRatio, viewbox).
SVG++ will do it itself if we set policy::viewport::as_transform
Viewport Policy
document_traversal<
processed_elements<processed_elements_t>,
processed_attributes<processed_attributes_t>,
viewport_policy<policy::viewport::as_transform>
>::load_document(xml_root_element, context);
we also must append viewport attributes to the list of processed attributes:
typedef
boost::mpl::fold<
boost::mpl::protect<
boost::mpl::joint_view<
traits::shapes_attributes_by_element,
traits::viewport_attributes
>
>,
boost::mpl::set<
tag::attribute::transform
>::type,
boost::mpl::insert<boost::mpl::_1, boost::mpl::_2>
>::type processed_attributes_t;
Please note that this cryptic code just merges predefined sequences traits::shapes_attributes_by_element
and traits::viewport_attributes
with tag::attribute::transform
attribute into single MPL sequence
equivalent to the following:
typedef boost::mpl::set<
// Transform attribute
tag::attribute::transform,
// Viewport attributes
tag::attribute::x,
tag::attribute::y,
tag::attribute::width,
tag::attribute::height,
tag::attribute::viewBox,
tag::attribute::preserveAspectRatio,
// Shape attributes for each shape element
boost::mpl::pair<tag::element::path, tag::attribute::d>,
boost::mpl::pair<tag::element::rect, tag::attribute::x>,
boost::mpl::pair<tag::element::rect, tag::attribute::y>,
boost::mpl::pair<tag::element::rect, tag::attribute::width>,
boost::mpl::pair<tag::element::rect, tag::attribute::height>,
boost::mpl::pair<tag::element::rect, tag::attribute::rx>,
boost::mpl::pair<tag::element::rect, tag::attribute::ry>,
boost::mpl::pair<tag::element::circle, tag::attribute::cx>,
boost::mpl::pair<tag::element::circle, tag::attribute::cy>,
boost::mpl::pair<tag::element::circle, tag::attribute::r>,
boost::mpl::pair<tag::element::ellipse, tag::attribute::cx>,
boost::mpl::pair<tag::element::ellipse, tag::attribute::cy>,
boost::mpl::pair<tag::element::ellipse, tag::attribute::rx>,
boost::mpl::pair<tag::element::ellipse, tag::attribute::ry>,
boost::mpl::pair<tag::element::line, tag::attribute::x1>,
boost::mpl::pair<tag::element::line, tag::attribute::y1>,
boost::mpl::pair<tag::element::line, tag::attribute::x2>,
boost::mpl::pair<tag::element::line, tag::attribute::y2>,
boost::mpl::pair<tag::element::polyline, tag::attribute::points>,
boost::mpl::pair<tag::element::polygon, tag::attribute::points>
>::type processed_attributes_t;
Now SVG++ will call the existing method transform_matrix
to set new user coordinate system.
And we must add some methods that will be passed with information about new viewport:
void set_viewport(double viewport_x, double viewport_y, double viewport_width, double viewport_height);
void set_viewbox_size(double viewbox_width, double viewbox_height);
void disable_rendering();
The full cpp file for this step can be found here: src/samples/sample01c.cpp.
Creating Contexts¶
Until now only one instance of context object was used for entire SVG document tree.
It is convenient to create context instance on stack for each SVG element processed.
This behavior is controlled by context factories, passed by context_factories
parameter of document_traversal
template class.
Context factories is a Metafunction Class that receives parent context type and child element tag as parameters and returns context factory type.
This sample application processes structural elements (svg and g) and shape elements (path, rect, circle etc).
For the structural elements only transform attribute is processed, and for the shape elements - transform and attributes
describing shape. So we can divide Context
context class for BaseContext
and ShapeContext
subclass:
class BaseContext
{
public:
void on_exit_element();
void transform_matrix(const boost::array<double, 6> & matrix);
void set_viewport(double viewport_x, double viewport_y, double viewport_width, double viewport_height);
void set_viewbox_size(double viewbox_width, double viewbox_height);
void disable_rendering();
};
class ShapeContext: public BaseContext
{
public:
ShapeContext(BaseContext const & parent);
void path_move_to(double x, double y, tag::coordinate::absolute);
/* ... other path methods ... */
};
struct ChildContextFactories
{
template<class ParentContext, class ElementTag, class Enable = void>
struct apply
{
// Default definition handles "svg" and "g" elements
typedef factory::context::on_stack<BaseContext> type;
};
};
// This specialization handles all shape elements (elements from traits::shape_elements sequence)
template<class ElementTag>
struct ChildContextFactories::apply<BaseContext, ElementTag,
typename boost::enable_if<boost::mpl::has_key<traits::shape_elements, ElementTag> >::type>
{
typedef factory::context::on_stack<ShapeContext> type;
};
factory::context::on_stack<ChildContext>
factory creates context object ChildContext
, passing reference
to parent context in ChildContext
constructor.
Lifetime of context object - until processing of element content (child elements and text nodes) is finished.
on_exit_element()
is called right before object destruction.
ChildContextFactories
is passed to document_traversal
:
document_traversal<
/* ... */
context_factories<ChildContextFactories>
>::load_document(xml_root_element, context);
Source file: src/samples/sample01d.cpp.
The use Element Support¶
The use element is used to include/draw other SVG element. If use references svg or symbol, then new viewport and user coordinate system are established.
To add support for use in our sample we:
Add
tag::element::use_
to the list of processed elements, andtag::attribute::xlink::href
to the list of processed attributes (x, y, width and height already included throughtraits::viewport_attributes
).Create context class
UseContext
to be used for use element, that will collect x, y, width, height and xlink:href attributes values.After processing all use element attributes (in method
UseContext::on_exit_element()
), look inside document for element with given id and load it with call todocument_traversal_t::load_referenced_element<...>::load()
.Implement Viewport Policy requirement - svg and symbol context must have method:
void get_reference_viewport_size(double & width, double & height);that returns size of the viewport set in referenced use element. One of possible variant is creation of new context
ReferencedSymbolOrSvgContext
.
Full implementation is in file: src/samples/sample01e.cpp.
Calculating Marker Positions¶
SVG++ may solve complex task of calculating orientations of markers with attribute orient=”auto”. Let’s set Markers Policy that enables this option:
document_traversal<
/* ... */
markers_policy<policy::markers::calculate_always>
> /* ... */
Then add Marker Events method to ShapeContext
:
void marker(marker_vertex v, double x, double y, double directionality, unsigned marker_index);
The sample (src/samples/sample01f.cpp) just shows how to get marker positions. To implement full marker support we also need to process marker, marker-start, marker-mid and marker-end properties and process marker element (similar to processing of use element). Demo application may give some idea about this.
Processing of stroke and stroke-width Properties¶
Adding stroke-width property processing is trivial - just add
tag::attribute::stroke_width
to the list of processed attributes, and add method,
that receives value, to the context class:
void set(tag::attribute::stroke_width, double val);
Property stroke has complex type <paint>:
<paint>: none |
currentColor |
<color> [<icccolor>] |
<funciri> [ none | currentColor | <color> [<icccolor>] ] |
inherit
that is why so many methods are required to receive all possible values of the property:
void set(tag::attribute::stroke_width, double val);
void set(tag::attribute::stroke, tag::value::none);
void set(tag::attribute::stroke, tag::value::currentColor);
void set(tag::attribute::stroke, color_t color, tag::skip_icc_color = tag::skip_icc_color());
template<class IRI>
void set(tag::attribute::stroke tag, IRI const & iri);
template<class IRI>
void set(tag::attribute::stroke tag, tag::iri_fragment, IRI const & fragment);
template<class IRI>
void set(tag::attribute::stroke tag, IRI const &, tag::value::none val);
template<class IRI>
void set(tag::attribute::stroke tag, tag::iri_fragment, IRI const & fragment, tag::value::none val);
template<class IRI>
void set(tag::attribute::stroke tag, IRI const &, tag::value::currentColor val);
template<class IRI>
void set(tag::attribute::stroke tag, tag::iri_fragment, IRI const & fragment, tag::value::currentColor val);
template<class IRI>
void set(tag::attribute::stroke tag, IRI const &, color_t val, tag::skip_icc_color = tag::skip_icc_color());
template<class IRI>
void set(tag::attribute::stroke tag, tag::iri_fragment, IRI const & fragment, color_t val, tag::skip_icc_color = tag::skip_icc_color());
Default IRI Policy is used that distinguishes absolute IRIs and local IRI references to fragments in same SVG document.
Source code: src/samples/sample01g.cpp.
Note
svgpp_parser_impl.cpp
file was added to the project and a couple of macros was added at the start of the sample01g.cpp
to get around Visual C++ 2015 “compiler out of memory” problem.
See description of this solution.
Custom Color Factory¶
Suppose that default SVG++ color presentation as 8 bit per channel RGB value packed in int
doesn’t suit our needs.
We prefer to use some custom type, e.g. boost::tuple
(same as C++11 std::tuple
):
typedef boost::tuple<unsigned char, unsigned char, unsigned char> color_t;
In this case we need our own Color Factory, that creates our custom color from components values, that was read from SVG:
struct ColorFactoryBase
{
typedef color_t color_type;
static color_type create(unsigned char r, unsigned char g, unsigned char b)
{
return color_t(r, g, b);
}
};
typedef factory::color::percentage_adapter<ColorFactoryBase> ColorFactory;
document_traversal<
/* ... */
color_factory<ColorFactory>
> /* ... */
Usage of factory::color::percentage_adapter
frees us from implementing
create_from_percent
method in our Color Factory.
Source file: src/samples/sample01h.cpp.
Correct Length Handling¶
On next step (src/samples/sample01i.cpp) of sample evolution we will add correct handling of length, that takes in account device resolution (dpi) and changes of viewport size by svg and symbol elements, that affects lengths, which are set in percent. So we:
Add to
BaseContext
class constructor that receives device resolution in dpi (this constructor is only called by ourselves fromloadSvg
function).Add
length_factory_
field and access function.length_factory_
settings (resolution, viewport size) will be passed to child contexts in copy constructor.In
BaseContext::set_viewport
andBaseContext::set_viewbox_size
methods pass viewport size to the Length Factory.Set Length Policy, that will ask
BaseContext
class for Length Factory instance:document_traversal< /* ... */ length_policy<policy::length::forward_to_method<BaseContext> > > /* ... */;
class BaseContext: public StylableContext
{
public:
BaseContext(double resolutionDPI)
{
length_factory_.set_absolute_units_coefficient(resolutionDPI, tag::length_units::in());
}
/* ... */
// Viewport Events Policy
void set_viewport(double viewport_x, double viewport_y, double viewport_width, double viewport_height)
{
length_factory_.set_viewport_size(viewport_width, viewport_height);
}
void set_viewbox_size(double viewbox_width, double viewbox_height)
{
length_factory_.set_viewport_size(viewbox_width, viewbox_height);
}
// Length Policy interface
typedef factory::length::unitless<> length_factory_type;
length_factory_type const & length_factory() const
{ return length_factory_; }
private:
length_factory_type length_factory_;
};
According to SVG Specification, the size of the new viewport affects attributes of element that establish new viewport (except x, y, width and height attributes). As our Length Factory converts lengths to numbers immediately, we need to pass new viewport size to Length Factory before processing other attributes. To do so we will use get_priority_attributes_by_element parameter of Attribute Traversal Policy:
struct AttributeTraversal: policy::attribute_traversal::default_policy
{
typedef boost::mpl::if_<
// If element is 'svg' or 'symbol'...
boost::mpl::has_key<
boost::mpl::set<
tag::element::svg,
tag::element::symbol
>,
boost::mpl::_1
>,
boost::mpl::vector<
// ... load viewport-related attributes first ...
tag::attribute::x,
tag::attribute::y,
tag::attribute::width,
tag::attribute::height,
tag::attribute::viewBox,
tag::attribute::preserveAspectRatio,
// ... notify library, that all viewport attributes that are present was loaded.
// It will result in call to BaseContext::set_viewport and BaseContext::set_viewbox_size
notify_context<tag::event::after_viewport_attributes>
>::type,
boost::mpl::empty_sequence
> get_priority_attributes_by_element;
};
document_traversal<
/* ... */
attribute_traversal_policy<AttributeTraversal>
> /* ... */;
Now we are sure that BaseContext::set_viewport
(and BaseContext::set_viewbox_size
)
will be called before other attributes are processed.
Text Handling¶
On the next step (src/samples/sample01j.cpp) we will implement basic handling of text elements:
Create new
TextContext
child ofBaseContext
that will receive text element data.set_text
method will be called by SVG++ to pass character data content of element:template<class Range> void set_text(Range const & text) { text_content_.append(boost::begin(text), boost::end(text)); }Add specialization of ChildContextFactories class that will create
TextContext
class for text elements (tag::element::text
).Add
tag::element::text
to the list of processed elementsprocessed_elements_t
.