[Pixman] [PATCH v10 14/15] pixman-filter: Add description to pixman_filter_create_separable_convolution()

[spitzak at gmail.com]

From: Bill Spitzak <spitzak at gmail.com>

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

Signed-off-by: Bill Spitzak <spitzak at gmail.com>

Reviewed-by: Oded Gabbay <oded.gabbay at gmail.com>
---
 pixman/pixman-filter.c | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/pixman/pixman-filter.c b/pixman/pixman-filter.c
index 6e8024a..d795573 100644
--- a/pixman/pixman-filter.c
+++ b/pixman/pixman-filter.c
@@ -379,6 +379,51 @@ filter_width(pixman_kernel_t reconstruct, pixman_kernel_t sample,
 
 /* 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
+ *
+ * scale_x/y: amount to stretch the sample filter. Note that scale
+ * is the inverse of how the image is being scaled, if the image is
+ * being made smaller, the filter gets larger.
+ *
+ * reconstruct_x/y: filter that is not scaled.
+ *
+ * sample_x/y: filter that is scaled. Resoult 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 scale==1, but fewer are computed for larger scales and
+ * more for smaller scales.
+ *
+ * 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 scale < 1.0.
+ *
+ *  BOX.x - For scale < 1.0 this produces square pixels. For scale > 1.0 this
+ *          approaches IMPULSE.x as scale gets larger.
+ *
+ *  x.IMPULSE - Uses the reconstruct function only, scale is ignored.
+ *
+ *  BOX.BOX, LINEAR.IMPULSE, IMPULSE.LINEAR - at scale==1 these all match and
+ *              also produce same result as bilinear filtering.
+ *
+ *  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.LINEAR - At scale==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 - non-negative cubic. What some software calls "cubic interpolation".
+ *
+ *  IMPULSE.LANCZOS2 - Close to what a lot of other software calls "cubic interpolation"
+ *
+ *  IMPULSE.CUBIC - 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,
-- 
1.9.1