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

  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 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> >
  > /* ... */;
  

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 of BaseContext 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 elements processed_elements_t.