1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
|
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)
|
