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)