From 5e58187902827d842f68ec589da4acd79fca4c35 Mon Sep 17 00:00:00 2001
From: John Cupitt <jcupitt@gmail.com>
Date: Mon, 4 Jul 2016 10:18:39 +0100
Subject: [PATCH] improve docs

---
 libvips/convolution/conv.c        | 17 +++++++++++------
 libvips/convolution/convi.c       | 22 ++++++++++++++--------
 libvips/convolution/im_aconvsep.c |  4 ++--
 3 files changed, 27 insertions(+), 16 deletions(-)

diff --git a/libvips/convolution/conv.c b/libvips/convolution/conv.c
index ffc64099..a4326edc 100644
--- a/libvips/convolution/conv.c
+++ b/libvips/convolution/conv.c
@@ -182,17 +182,22 @@ vips_conv_init( VipsConv *conv )
  * Convolution. 
  *
  * Perform a convolution of @in with @mask.
- * Each output pixel is
- * calculated as sigma[i]{pixel[i] * mask[i]} / scale + offset, where scale
- * and offset are part of @mask. 
+ * Each output pixel is calculated as:
+ *
+ * |[
+ * sigma[i]{pixel[i] * mask[i]} / scale + offset
+ * ]|
+ *
+ * where scale and offset are part of @mask. 
  *
  * If @precision is #VIPS_PRECISION_INTEGER then the convolution is performed
  * with integer arithmetic and the output image 
  * always has the same #VipsBandFormat as the input image. 
  *
- * Convolutions on unsigned 8-bit images are calculated with the 
- * processor's vector unit, if possible. Disable this with `--vips-novector` or 
- * `VIPS_NOVECTOR`.
+ * For #VIPS_FORMAT_UCHAR images, vips_conv() uses a fast vector path based on
+ * fixed-point arithmetic. This can produce slightly different results. 
+ * Disable the vector path with `--vips-novector` or `VIPS_NOVECTOR` or
+ * vips_vector_set_enabled().
  *
  * If @precision is #VIPS_PRECISION_FLOAT then the convolution is performed
  * with floating-point arithmetic. The output image 
diff --git a/libvips/convolution/convi.c b/libvips/convolution/convi.c
index 557d3919..39ae5952 100644
--- a/libvips/convolution/convi.c
+++ b/libvips/convolution/convi.c
@@ -1030,16 +1030,22 @@ vips_convi_init( VipsConvi *convi )
  * @mask: convolve with this mask
  * @...: %NULL-terminated list of optional named arguments
  *
- * Convolution. This is a low-level operation, see vips_conv() for something
- * more convenient. 
+ * Integer convolution. This is a low-level operation, see vips_conv() for 
+ * something more convenient. 
  *
- * Perform a convolution of @in with @mask.
- * Each output pixel is
- * calculated as rint(sigma[i]{pixel[i] * mask[i]} / scale) + offset, where 
- * scale and offset are part of @mask. 
+ * @mask is converted to an integer mask with rint() of each element, rint of
+ * scale and rint of offset. Each output pixel is then calculated as 
  *
- * The convolution is performed with integer arithmetic. The output image 
- * always has the same #VipsBandFormat as the input image. 
+ * |[
+ * sigma[i]{pixel[i] * mask[i]} / scale + offset
+ * ]|
+ *
+ * The output image always has the same #VipsBandFormat as the input image. 
+ *
+ * For #VIPS_FORMAT_UCHAR images, vips_convi() uses a fast vector path based on
+ * fixed-point arithmetic. This can produce slightly different results. 
+ * Disable the vector path with `--vips-novector` or `VIPS_NOVECTOR` or
+ * vips_vector_set_enabled().
  *
  * See also: vips_conv().
  *
diff --git a/libvips/convolution/im_aconvsep.c b/libvips/convolution/im_aconvsep.c
index 4bc0a810..9af49350 100644
--- a/libvips/convolution/im_aconvsep.c
+++ b/libvips/convolution/im_aconvsep.c
@@ -56,13 +56,13 @@
  */
 
 /* Show sample pixels as they are transformed.
-#define DEBUG_PIXELS
  */
+#define DEBUG_PIXELS
 
 /*
+ */
 #define DEBUG
 #define VIPS_DEBUG
- */
 
 #ifdef HAVE_CONFIG_H
 #include <config.h>