diff options
Diffstat (limited to 'doc/nr-filter-interface.txt')
| -rw-r--r-- | doc/nr-filter-interface.txt | 229 |
1 files changed, 229 insertions, 0 deletions
diff --git a/doc/nr-filter-interface.txt b/doc/nr-filter-interface.txt new file mode 100644 index 0000000..012accf --- /dev/null +++ b/doc/nr-filter-interface.txt @@ -0,0 +1,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) |