Filter effects internals

The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

This page describes the internal workings of Inkscape Filter effects subsystem.

Overview

From Filter effects viewpoint, Inkscape is essentially three-tiered system. The tiers are XML representation, SVG document and SVG renderer.

XML representation level is merely an representation of XML tree of the document. It contains XML nodes, which have attributes, content, children etc. At this level these nodes and whatever content they have, don't have any special meaning. Inkscape XML representation layer could be used for any type of XML document, not just SVG.

SVG document layer builds upon the XML layer. This layer gives meaning to XML node names, node attributes, node content etc. Mostly, nodes are handled by different classes depending on the name of the node. For example, nodes named feOffset are handled by SPFeOffset class, which resides in src/sp-feoffset.*

Main tasks for SVG document layer are reading essential parameters from XML tree, parsing parameter values read from XML tree, writing out internal state to XML node and initializing SVG renderer classes.

SVG renderer produces bitmap images from the SVG graphics. Again, there are own classes for most different node names. For example, feOffset node is handled by NR::FilterOffset class, which resides in src/display/nr-filter-offset.*

Note that Inkscape uses two types of classes here: SVG document layer uses GTK style classes, which don't make use of C++ object oriented programming functionality, but are usable in plain C. SVG renderer in turn uses C++ classes.

Filters in document layer

In document layer, the classes responsible for filter effects are SPFilter, SPFilterPrimitive and it's subclasses. Each of SPFilterPrimitive's subclasses handles one type of filter primitive. There is also related code in SPItem, SPStyle, NRArenaShape, NRArenaGroup and NRArenaImage.

Reading parameters from XML tree

The build method of a filter primitive class should read all possible parameters, that are special for that filter primitive. For example, sp_feOffset_build calls sp_object_read_attr for parameters dx and dy. Any parameters that are common for all filter primitives, should be read in build-method for SPFilterPrimitive, which is superclass for all filter primitive classes.

Note that the build method doesn't need to make any attempt to handle any contents, the read attributes may have. It is handled by the set-method, which is described in next paragraph.

Parsing parameters read from XML tree

When the parameters in XML tree are modified or read by build method, the set method for corresponding document layer object gets called. This method receives the name and content of the parameter and should set object's internal state according to these values.

Writing out XML nodes

The write function in filter primitive class should write the relevant parts of object's internal state to given node. Note that many filter primitives don't do this, but instead just duplicate the contents of their XML node. For some examples how do do this right, see sp-shape.cpp or sp-filter.cpp.

Initializing SVG renderer classes

Each filter primitive class should have build_renderer method, which will add correct type of filter primitive to the filter renderer object and give correct settings for created filter primitive.

SPItem

Filter renderer uses item bounding box for its calculations, this information is set in sp_item_update in sp-item.cpp.

Also in this file contains sp_item_write_transform, which handles transforming items. Some transformations, like scaling a rectangle, can be done by embedding transform into object's properteries (i.e. changing rectangle width and height) instead of writing out normal transformation. If an item has a filter set, this might give odd behaviour, so this method checks for set filters before embedding transforms.

SPStyle

Filter effect applied to an object can be considered as a part of object style and in Inkscape codebase it is a natural place to handle such object property.

SPStyle can locate the filter referenced by an SVG item, and provides a pointer to corresponding SPFilter object.

NRArenaShape, -Group and -Image

While these are renderer level classes, they contain filtering code, that interfaces document level and renderer level.

Here, in set_style method for each class, if the SVG item references some filter, the corresponding SPFilter is fetched from SPStyle and a NR::Filter object is constructed from it.

Specifically, the set_style method calls sp_filter_build_renderer, which will initialize the filter renderer (NR::Filter object).