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

[Oded Gabbay]

On Fri, Feb 5, 2016 at 9:49 AM,  <spitzak at gmail.com> wrote:
> From: Bill Spitzak <spitzak at gmail.com>
>
> 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 at gmail.com>
> ---
>  pixman/pixman-filter.c | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 50 insertions(+)
>
> diff --git a/pixman/pixman-filter.c b/pixman/pixman-filter.c
> index e57b154..b23d348 100644
> --- a/pixman/pixman-filter.c
> +++ b/pixman/pixman-filter.c
> @@ -379,6 +379,56 @@ subsample_bits (int subsample_bits, 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.
> + *
> + *  x.IMPULSE - Uses the reconstruct function only, size is ignored. This is
> + *              what many pieces of software do for size < 1.0.
> + *
> + *  LINEAR.IMPULSE - Same as the bilinear filter
> + *
> + *  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". At size==1 this matches LINEAR.IMPULSE, IMPULSE.LINEAR, and
> + *            the bilinear filter, allowing transitions at those points.
> + *
> + *  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,
> --
> 1.9.1
>
> _______________________________________________
> Pixman mailing list
> Pixman at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/pixman

Acked-by: Oded Gabbay <oded.gabbay at redhat.com>