Tutorial¶

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>
usingnamespacesvgpp;
classContext
{
public:
voidpath_move_to(doublex,doubley,tag::coordinate::absolute);
voidpath_line_to(doublex,doubley,tag::coordinate::absolute);
voidpath_cubic_bezier_to(
doublex1,doubley1,
doublex2,doubley2,
doublex,doubley,
tag::coordinate::absolute);
voidpath_quadratic_bezier_to(
doublex1,doubley1,
doublex,doubley,
tag::coordinate::absolute);
voidpath_elliptical_arc_to(
doublerx,doublery,doublex_axis_rotation,
boollarge_arc_flag,boolsweep_flag,
doublex,doubley,
tag::coordinate::absolute);
voidpath_close_subpath();
voidpath_exit();
voidon_enter_element(tag::element::any);
voidon_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
>::typeprocessed_elements_t;
voidloadSvg(xml_element_txml_root_element)
{
Contextcontext;
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:

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:

typedefrapidxml_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:

voidtransform_matrix(constboost::array<double,6>&matrix);
typedef
boost::mpl::insert<
traits::shapes_attributes_by_element,
tag::attribute::transform
>::typeprocessed_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>
>::typeprocessed_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:

typedefboost::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>
>::typeprocessed_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:

voidset_viewport(doubleviewport_x,doubleviewport_y,doubleviewport_width,doubleviewport_height);
voidset_viewbox_size(doubleviewbox_width,doubleviewbox_height);
voiddisable_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:

classBaseContext
{
public:
voidon_exit_element();
voidtransform_matrix(constboost::array<double,6>&matrix);
voidset_viewport(doubleviewport_x,doubleviewport_y,doubleviewport_width,doubleviewport_height);
voidset_viewbox_size(doubleviewbox_width,doubleviewbox_height);
voiddisable_rendering();
};
classShapeContext:publicBaseContext
{
public:
ShapeContext(BaseContextconst&parent);
voidpath_move_to(doublex,doubley,tag::coordinate::absolute);
/* ... other path methods ... */
};
structChildContextFactories
{
template<classParentContext,classElementTag,classEnable=void>
structapply
{
// Default definition handles "svg" and "g" elements
typedeffactory::context::on_stack<BaseContext>type;
};
};
// This specialization handles all shape elements (elements from traits::shape_elements sequence)
template<classElementTag>
structChildContextFactories::apply<BaseContext,ElementTag,
typenameboost::enable_if<boost::mpl::has_key<traits::shape_elements,ElementTag>>::type>
{
typedeffactory::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, and tag::attribute::xlink::href to the list of processed attributes (x, y, width and height already included through traits::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 to document_traversal_t::load_referenced_element<...>::load().

• Implement Viewport Policy requirement - svg and symbol context must have method:

  voidget_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:

voidmarker(marker_vertexv,doublex,doubley,doubledirectionality,unsignedmarker_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:

voidset(tag::attribute::stroke_width,doubleval);

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:

voidset(tag::attribute::stroke_width,doubleval);
voidset(tag::attribute::stroke,tag::value::none);
voidset(tag::attribute::stroke,tag::value::currentColor);
voidset(tag::attribute::stroke,color_tcolor,tag::skip_icc_color=tag::skip_icc_color());
template<classIRI>
voidset(tag::attribute::stroketag,IRIconst&iri);
template<classIRI>
voidset(tag::attribute::stroketag,tag::iri_fragment,IRIconst&fragment);
template<classIRI>
voidset(tag::attribute::stroketag,IRIconst&,tag::value::noneval);
template<classIRI>
voidset(tag::attribute::stroketag,tag::iri_fragment,IRIconst&fragment,tag::value::noneval);
template<classIRI>
voidset(tag::attribute::stroketag,IRIconst&,tag::value::currentColorval);
template<classIRI>
voidset(tag::attribute::stroketag,tag::iri_fragment,IRIconst&fragment,tag::value::currentColorval);
template<classIRI>
voidset(tag::attribute::stroketag,IRIconst&,color_tval,tag::skip_icc_color=tag::skip_icc_color());
template<classIRI>
voidset(tag::attribute::stroketag,tag::iri_fragment,IRIconst&fragment,color_tval,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.

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):

typedefboost::tuple<unsignedchar,unsignedchar,unsignedchar>color_t;

In this case we need our own Color Factory, that creates our custom color from components values, that was read from SVG:

structColorFactoryBase
{
typedefcolor_tcolor_type;
staticcolor_typecreate(unsignedcharr,unsignedcharg,unsignedcharb)
{
returncolor_t(r,g,b);
}
};
typedeffactory::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 from loadSvg 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 and BaseContext::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>>
  >/* ... */;
  

classBaseContext:publicStylableContext
{
public:
BaseContext(doubleresolutionDPI)
{
length_factory_.set_absolute_units_coefficient(resolutionDPI,tag::length_units::in());
}
/* ... */
// Viewport Events Policy
voidset_viewport(doubleviewport_x,doubleviewport_y,doubleviewport_width,doubleviewport_height)
{
length_factory_.set_viewport_size(viewport_width,viewport_height);
}
voidset_viewbox_size(doubleviewbox_width,doubleviewbox_height)
{
length_factory_.set_viewport_size(viewbox_width,viewbox_height);
}
// Length Policy interface
typedeffactory::length::unitless<>length_factory_type;
length_factory_typeconst&length_factory()const
{returnlength_factory_;}
private:
length_factory_typelength_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:

structAttributeTraversal:policy::attribute_traversal::default_policy
{
typedefboost::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 of BaseContext that will receive text element data. set_text method will be called by SVG++ to pass character data content of element:

  template<classRange>
  voidset_text(Rangeconst&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 elements processed_elements_t.