pixman-filter: Add description to pixman_filter_create_separable_convolution()

v9: Described arguments and more filter combinations, fixed some errors.

v11: Further correction, in particular replaced "scale" with "size"

Signed-off-by: Bill Spitzak <spitzak@gmail.com>
Acked-by: Oded Gabbay <oded.gabbay@redhat.com>

1 files changed, 51 insertions, 0 deletions

diff --git a/pixman/pixman-filter.c b/pixman/pixman-filter.c
index f582187a..2bf289a6 100644
--- a/pixman/pixman-filter.c
+++ b/pixman/pixman-filter.c
@@ -350,6 +350,57 @@ filter_width (pixman_kernel_t reconstruct, pixman_kernel_t sample, double size)
 
 /* Create the parameter list for a SEPARABLE_CONVOLUTION filter
  * with the given kernels and size parameters
+ *
+ * Returns pointer to the block of numbers
+ *
+ * n_values: pointer to integer to store size of the block
+ *
+ * size_x/y: amount to stretch the sample filter. The best value to
+ * use is the derivative of the sample location. This value is
+ * approximately 1/scale when scaling an image. If size < 1.0 then you
+ * will get square pixels as an image is enlarged, using 1.0 instead
+ * will get the more customary "blurry" enlargement.
+ *
+ * reconstruct_x/y: filter that is not resized.
+ *
+ * sample_x/y: filter that is resized. Result is convolved with reconstruct filter.
+ *
+ * subsample_bits_x/y: If positive there are 2^n subpixel positions computed for
+ * the filter. If negative then -n (rounded up to the next power of 2) positions
+ * are calculated when size==1, but fewer are computed for larger sizes and
+ * more for smaller sizes.
+ *
+ * Some interesting reconstruct.sample combinations:
+ *
+ *  IMPULSE.x - Uses the sample function only. This is what many other pieces of
+ *              software do. Does not work for size < 1.0, so you must pass
+ *              max(size, 1.0). Or use x.IMPULSE for size < 1.0.
+ *
+ *  x.IMPULSE - Same as IMPULSE.x at size==1, size is ignored.
+ *
+ *  LINEAR.IMPULSE - Same as the bilinear filter. At size==1 this is the exact
+ *                   same shape as BOX.BOX and IMPULSE.LINEAR, making it possible
+ *                   to do seamless transitions between these filters at size==1.
+ *
+ *  BOX.BOX - Produces a trapazoid-shape. Narrowest possible filter with antialiasing.
+ *            Matches a *lot* of other software, some call it "box", others call it
+ *            "linear".
+ *
+ *  BOX.x - For size < 1.0 this produces square pixels. For size > 1.0 this
+ *          approaches IMPULSE.x as size gets larger.
+ *
+ *  BOX.LINEAR - At size==1 this is what some software calls a Quadratic filter
+ *
+ *  IMPULSE.LINEAR - Some software calls this "linear" or "triangle". Not a good filter.
+ *
+ *  LINEAR.LINEAR - At size==1 this is what some software calls "cubic interpolation".
+ *
+ *  IMPULSE.LANCZOS2 - Close to what a lot of other software calls "cubic interpolation"
+ *
+ *  IMPULSE.CUBIC - A third thing often called "cubic interpolation", sometimes called
+ *                  "Mitchell" in other software.
+ *
+ *  IMPULSE.GAUSSIAN - Best removal of aliasing but usually considered too blurry
  */
 PIXMAN_EXPORT pixman_fixed_t *
 pixman_filter_create_separable_convolution (int             *n_values,