doc/nr-filter-interface.txt

   1 Public interface for NR::Filter and NR::FilterPrimitive
   2
   3 Constructors
   4 ============
   5
   6 Filter::Filter()
   7 Creates a new filter with space for one filter element
   8
   9 Filter::Filter(int n)
  10 Creates a new filter with space for n filter elements. If number of filter
  11 elements is known beforehand, it's better to use this constructor.
  12
  13
  14 Managing filter primitives
  15 ==========================
  16
  17 FilterPrimitive * Filter::add_primitive(FilterPrimitiveType type)
  18 Creates a new filter primitive under this filter object.
  19 New primitive is placed so that it will be executed after all filter
  20 primitives defined beforehand for this filter object.
  21 Should this filter not have enough space for a new primitive, the filter
  22 is enlarged to accomodate the new filter element. It may be enlarged by more
  23 that one element.
  24 Returns a pointer to the filter primitive created.
  25 Returns NULL, if type is not valid filter primitive type or filter primitive
  26 of such type cannot be created.
  27
  28 void Filter::clear_primitives()
  29 Removes all filter primitives from this filter.
  30 All pointers to filter primitives inside this filter should be considered
  31 invalid after calling this function.
  32
  33 FilterPrimitive * Filter::replace_primitive(FilterPrimitive *target,
  34                                             FilterPrimitiveType type)
  35 Replaces filter primitive pointed by 'target' with a new filter primitive of
  36 type 'type'
  37 If 'target' does not correspond to any primitive inside this filter OR
  38 'type' is not a valid filter primitive type OR
  39 filter primitive of such type cannot be created,
  40 this function returns NULL and doesn't change the internal state of this
  41 filter.
  42 Otherwise, a new filter primitive is created. Any pointers to filter primitive
  43 'target' should be considered invalid. A pointer to the newly created
  44 primitive is returned.
  45
  46
  47 Filter primitive types
  48 ======================
  49
  50 enum FilterPrimitiveType is declared in display/nr-filter-types.h
  51
  52 Enumeration value               Corresponding filter primitive
  53 NR_FILTER_BLEND                 feBlend
  54 NR_FILTER_COLORMATRIX           feColorMatrix
  55 NR_FILTER_COMPONENTTRANSFER     feComponentTransfer
  56 NR_FILTER_COMPOSITE             feComposite
  57 NR_FILTER_CONVOLVEMATRIX        feConvolveMatrix
  58 NR_FILTER_DIFFUSELIGHTING       feDiffuseLighting
  59 NR_FILTER_DISPLACEMENTMAP       feDisplacementMap
  60 NR_FILTER_FLOOD                 feFlood
  61 NR_FILTER_GAUSSIANBLUR          feGaussianBlur
  62 NR_FILTER_IMAGE                 feImage
  63 NR_FILTER_MERGE                 feMerge
  64 NR_FILTER_MORPHOLOGY            feMorphology
  65 NR_FILTER_OFFSET                feOffset
  66 NR_FILTER_SPECULARLIGHTING      feSpecularLighting
  67 NR_FILTER_TILE                  feTile
  68 NR_FILTER_TURBULENCE            feTurbulence
  69
  70
  71 Setting inputs and outputs for filter primitives
  72 ================================================
  73
  74 Each filter primitive can take one or more images as inputs and produces
  75 a single image as output. In NR::Filter these are managed as image slots.
  76 Every slot can hold one image.
  77
  78 There are two types of slots: pre-defined and user defined. Pre-defined
  79 slots may only be used as inputs, while user defined slots may be used as
  80 both inputs and outputs. User defined slots are numbered from 0 upwards,
  81 pre-defined slots are numbered with the following constants:
  82
  83 Constant name                   Corresponding SVG input name
  84 NR_FILTER_SOURCEGRAPHIC         SourceGraphic
  85 NR_FILTER_SOURCEALPHA           SourceAlpha
  86 NR_FILTER_BACKGROUNDIMAGE       BackgroundImage
  87 NR_FILTER_BACKGROUNDALPHA       BackgroundAlpha
  88 NR_FILTER_FILLPAINT             FillPaint
  89 NR_FILTER_SOURCEPAINT           SourcePaint
  90 (defined in display/nr-filter-types.h)
  91
  92 Any user defined slot used as input must be the output of some previous
  93 filter primitive. Other than that, user defined input slots do not need to be
  94 used in any particular order.
  95
  96 void FilterPrimitive::set_input(int slot)
  97 Sets the input slot number 'slot' to be used as input in rendering filter
  98 primitive 'primitive'
  99 For filter primitive types accepting more than one input, this sets the
 100 first input.
 101 If any of the required input slots is not set, the output of previous filter
 102 primitive is used, or SourceGraphic if this is the first primitive for this
 103 filter.
 104
 105 void FilterPrimitive::set_input(int input, int slot)
 106 Sets the input slot number 'slot' to be user as input number 'input' in
 107 rendering filter primitive 'primitive'
 108 First input for a filter primitive is number 0. For primitives with attributes
 109 'in' and 'in2', these are numbered 0 and 1, respectively.
 110 If any of required input slots for a filter is not set, the output of
 111 previous filter primitive is used, or SourceGraphic if this is the first
 112 filter primitive for this filter.
 113
 114 void FilterPrimitive::set_output(int slot)
 115 Sets the slot number 'slot' to be used as output from filter primitive
 116 'primitive'
 117 If output slot for a filter element is not set, one of the unused image
 118 slots is used.
 119 It is an error to specify a pre-defined slot as 'slot'. Such call does
 120 not have any effect to the state of filter or its primitives.
 121
 122 void Filter::set_output(int slot)
 123 Sets the slot number 'slot' to be used as result from this filter.
 124 If output is not set, the output from last filter primitive is used as
 125 output from the filter.
 126 It is an error to specify a pre-defined slot as 'slot'. Such call does
 127 not have any effect to the state of filter or its primitives.
 128
 129
 130 Functions for reading filter state
 131 ==================================
 132
 133 int Filter::get_enlarge(Matrix const &m)
 134 Returns the amount of pixels the rendering area should be enlarged
 135 to prevent visual artefacts when filter needs to read pixels that
 136 are outside its output area (e.g. gaussian blur)
 137
 138 void Fiter::bbox_enlarge(NRRectL &bbox)
 139 Given an object bounding box, this function enlarges it so that it
 140 contains the filter effect area
 141
 142
 143 Filter effects region and filter primitive subregion
 144 ====================================================
 145
 146 void Filter::set_x(SVGLength &lenght)
 147 void FilterPrimitive::set_x(SVGLength &length)
 148
 149 void Filter::set_y(SVGLength &length)
 150 void FilterPrimitive::set_y(SVGLength &length)
 151
 152 void Filter::set_width(SVGLength &length)
 153 void FilterPrimitive::set_width(SVGLength &length)
 154
 155 void Filter::set_height(SVGLength &length)
 156 void FilterPrimitive::set_width(SVGLength &length)
 157
 158 These functions set the parameters for filter effects region and filter
 159 primitive subregion.
 160 Passing an unset length (length._set == false) results in no changes to
 161 filter state.
 162 Filter will not hold any references to the passed SVGLength object after
 163 function returns.
 164 If any of these parameters does not get set - either because function
 165 for setting that is not called, or it is called with an unset length -
 166 the default value, as defined in SVG standard, for that parameter is
 167 used instead.
 168
 169 void Filter::set_region(SVGLength &x, SVGLength &y,
 170                         SVGLength &width, SVGLength &height)
 171 void FilterPrimitive::set_region(SVGLength &x, SVGLength &y,
 172                                  SVGLength &width, SVGLength &height)
 173
 174 This is shorthand for calling set_x(x), set_y(y), set_width(width) and
 175 set_height(height). The result is as if those four functions had been
 176 called separately.
 177
 178 void Filter::reset_region()
 179 void FilterPrimitive::reset_region()
 180
 181 Resets the filter effects region or filter primitive subregion to its
 182 default value as defined in SVG standard.
 183
 184 void Filter::set_resolution(double x_pixels)
 185
 186 Sets the width of intermediate images in pixels. If not set, suitable
 187 resolution is determined automatically. If x_pixels is less than zero,
 188 calling this function results in no changes to filter state.
 189
 190 void Filter::set_resolution(double x_pixels, double y_pixels)
 191
 192 Sets the width and height of intermediate images in pixels. If not set,
 193 suitable resolution is determined automatically. If either parameter is
 194 less than zero, calling this function results in no changes to filter
 195 state.
 196
 197 void Filter::reset_resolution()
 198
 199 Resets the filter resolution to its default value, i.e. automatically
 200 determined.
 201
 202 void Filter::set_filter_units(SPFilterUnits unit)
 203 void Filter::set_primitive_units(SPFilterUnits unit)
 204
 205 Set the filterUnits and primitiveUnits -properteries, respectively. If
 206 not set, the default values are used: objectBoundingBox for filterUnits
 207 and userSpaceOnUse for primitiveUnits. If the parameter value is not a
 208 valid enumeration value from SPFilterUnits, no changes to filter state
 209 are made.
 210
 211
 212 Parameters specific to some filter primitive type
 213 =================================================
 214
 215 Gaussian blur
 216 -------------
 217
 218 void FilterGaussian::set_deviation(double deviation)
 219 void FilterGaussian::set_deviation(double x, double y)
 220
 221 Set the standard deviation value for gaussian blur. One-parameter
 222 version sets deviation along both axis to same value, two-parameter
 223 version allows setting deviation along x- and y-axis separately.
 224 Passing either of these functions a negative value, NaN or infinity is
 225 considered an error and no changes to filter state are made. If not set,
 226 default value of zero is used, which means the filter results in
 227 transparent black image.
 228 (NB: as for now, the default value can be overriden with configuration
 229 file parameter options.filtertest)