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 accomodate 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			feBlend
NR_FILTER_COLORMATRIX		feColorMatrix
NR_FILTER_COMPONENTTRANSFER	feComponentTransfer
NR_FILTER_COMPOSITE		feComposite
NR_FILTER_CONVOLVEMATRIX	feConvolveMatrix
NR_FILTER_DIFFUSELIGHTING	feDiffuseLighting
NR_FILTER_DISPLACEMENTMAP	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 &lenght)
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 overriden with configuration 
file parameter options.filtertest)
