229 lines
8.7 KiB
Text
229 lines
8.7 KiB
Text
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 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 Filter::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)
|