Public interface for NR::Filter and NR::FilterPrimitive

Constructors
============

Filter::Filter()
Creates a new filter with space for one filter element

Filter::Filter(int n)
Creates a new filter with space for n filter elements. If number of filter
elements is known beforehand, it's better to use this constructor.

Managing filter primitives

==========================

FilterPrimitive * Filter::add_primitive(FilterPrimitiveType type)

Creates a new filter primitive under this filter object.
New primitive is placed so that it will be executed after all filter
primitives defined beforehand for this filter object.
Should this filter not have enough space for a new primitive, the filter
is enlarged to accommodate the new filter element. It may be enlarged by more
that one element.
Returns a pointer to the filter primitive created.
Returns NULL, if type is not valid filter primitive type or filter primitive
of such type cannot be created.

void Filter::clear_primitives()
Removes all filter primitives from this filter.
All pointers to filter primitives inside this filter should be considered
invalid after calling this function.

FilterPrimitive * Filter::replace_primitive(FilterPrimitive *target,

FilterPrimitiveType type)
Replaces filter primitive pointed by 'target' with a new filter primitive of
type 'type'
If 'target' does not correspond to any primitive inside this filter OR
'type' is not a valid filter primitive type OR
filter primitive of such type cannot be created,
this function returns NULL and doesn't change the internal state of this
filter.
Otherwise, a new filter primitive is created. Any pointers to filter primitive
'target' should be considered invalid. A pointer to the newly created
primitive is returned.

Filter primitive types

======================

enum FilterPrimitiveType is declared in display/nr-filter-types.h

Enumeration value Corresponding filter primitive

NR_FILTER_BLEND
NR_FILTER_COLORMATRIX
NR_FILTER_COMPONENTTRANSFER
NR_FILTER_COMPOSITE
NR_FILTER_CONVOLVEMATRIX
NR_FILTER_DIFFUSELIGHTING
NR_FILTER_DISPLACEMENTMAP
feBlend
feColorMatrix
feComponentTransfer
feComposite
feConvolveMatrix
feDiffuseLighting
feDisplacementMap
NR_FILTER_FLOOD feFlood
NR_FILTER_GAUSSIANBLUR feGaussianBlur
NR_FILTER_IMAGE feImage
NR_FILTER_MERGE feMerge
NR_FILTER_MORPHOLOGY feMorphology
NR_FILTER_OFFSET feOffset
NR_FILTER_SPECULARLIGHTING feSpecularLighting
NR_FILTER_TILE feTile
NR_FILTER_TURBULENCE feTurbulence

Setting inputs and outputs for filter primitives

================================================

Each filter primitive can take one or more images as inputs and produces
a single image as output. In NR::Filter these are managed as image slots.
Every slot can hold one image.

There are two types of slots: pre-defined and user defined. Pre-defined
slots may only be used as inputs, while user defined slots may be used as
both inputs and outputs. User defined slots are numbered from 0 upwards,
pre-defined slots are numbered with the following constants:

Constant name Corresponding SVG input name

NR_FILTER_SOURCEGRAPHIC SourceGraphic
NR_FILTER_SOURCEALPHA SourceAlpha
NR_FILTER_BACKGROUNDIMAGE BackgroundImage
NR_FILTER_BACKGROUNDALPHA BackgroundAlpha
NR_FILTER_FILLPAINT FillPaint
NR_FILTER_SOURCEPAINT SourcePaint
(defined in display/nr-filter-types.h)

Any user defined slot used as input must be the output of some previous
filter primitive. Other than that, user defined input slots do not need to be
used in any particular order.

void FilterPrimitive::set_input(int slot)

Sets the input slot number 'slot' to be used as input in rendering filter
primitive 'primitive'
For filter primitive types accepting more than one input, this sets the
first input.
If any of the required input slots is not set, the output of previous filter
primitive is used, or SourceGraphic if this is the first primitive for this
filter.

void FilterPrimitive::set_input(int input, int slot)

Sets the input slot number 'slot' to be user as input number 'input' in
rendering filter primitive 'primitive'
First input for a filter primitive is number 0. For primitives with attributes
'in' and 'in2', these are numbered 0 and 1, respectively.
If any of required input slots for a filter is not set, the output of
previous filter primitive is used, or SourceGraphic if this is the first
filter primitive for this filter.

void FilterPrimitive::set_output(int slot)

Sets the slot number 'slot' to be used as output from filter primitive
'primitive'
If output slot for a filter element is not set, one of the unused image
slots is used.
It is an error to specify a pre-defined slot as 'slot'. Such call does
not have any effect to the state of filter or its primitives.

void Filter::set_output(int slot)

Sets the slot number 'slot' to be used as result from this filter.
If output is not set, the output from last filter primitive is used as
output from the filter.
It is an error to specify a pre-defined slot as 'slot'. Such call does
not have any effect to the state of filter or its primitives.

Functions for reading filter state

==================================

int Filter::get_enlarge(Matrix const &m)

Returns the amount of pixels the rendering area should be enlarged
to prevent visual artefacts when filter needs to read pixels that
are outside its output area (e.g. gaussian blur)

void Fiter::bbox_enlarge(NRRectL &bbox)

Given an object bounding box, this function enlarges it so that it
contains the filter effect area

Filter effects region and filter primitive subregion

====================================================

void Filter::set_x(SVGLength &length)

void FilterPrimitive::set_x(SVGLength &length)

void Filter::set_y(SVGLength &length)

void FilterPrimitive::set_y(SVGLength &length)

void Filter::set_width(SVGLength &length)

void FilterPrimitive::set_width(SVGLength &length)

void Filter::set_height(SVGLength &length)

void FilterPrimitive::set_width(SVGLength &length)

These functions set the parameters for filter effects region and filter
primitive subregion.
Passing an unset length (length._set == false) results in no changes to
filter state.
Filter will not hold any references to the passed SVGLength object after
function returns.
If any of these parameters does not get set - either because function
for setting that is not called, or it is called with an unset length -
the default value, as defined in SVG standard, for that parameter is
used instead.

void Filter::set_region(SVGLength &x, SVGLength &y,

SVGLength &width, SVGLength &height)
void FilterPrimitive::set_region(SVGLength &x, SVGLength &y,
SVGLength &width, SVGLength &height)

This is shorthand for calling set_x(x), set_y(y), set_width(width) and

set_height(height). The result is as if those four functions had been
called separately.
void Filter::reset_region()
void FilterPrimitive::reset_region()

Resets the filter effects region or filter primitive subregion to its

default value as defined in SVG standard.

void Filter::set_resolution(double x_pixels)

Sets the width of intermediate images in pixels. If not set, suitable

resolution is determined automatically. If x_pixels is less than zero,
calling this function results in no changes to filter state.

void Filter::set_resolution(double x_pixels, double y_pixels)

Sets the width and height of intermediate images in pixels. If not set,
suitable resolution is determined automatically. If either parameter is
less than zero, calling this function results in no changes to filter
state.

void Filter::reset_resolution()

Resets the filter resolution to its default value, i.e. automatically

determined.

void Filter::set_filter_units(SPFilterUnits unit)

void Filter::set_primitive_units(SPFilterUnits unit)

Set the filterUnits and primitiveUnits -properteries, respectively. If

not set, the default values are used: objectBoundingBox for filterUnits
and userSpaceOnUse for primitiveUnits. If the parameter value is not a
valid enumeration value from SPFilterUnits, no changes to filter state
are made.

Parameters specific to some filter primitive type

=================================================

Gaussian blur
-------------

void FilterGaussian::set_deviation(double deviation)

void FilterGaussian::set_deviation(double x, double y)

Set the standard deviation value for gaussian blur. One-parameter

version sets deviation along both axis to same value, two-parameter
version allows setting deviation along x- and y-axis separately.
Passing either of these functions a negative value, NaN or infinity is
considered an error and no changes to filter state are made. If not set,
default value of zero is used, which means the filter results in
transparent black image.
(NB: as for now, the default value can be overridden with configuration
file parameter options.filtertest)