Adding upstream version 1.2.2.upstream/1.2.2upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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)