better draw docs

add a caching discussion to the start of draw

see https://github.com/jcupitt/libvips/issues/411

TODO

@@ -4,8 +4,10 @@
 
   get 254 for white, some rounding problem
 
-- I like the new int mask creator in reducev, can we use it in vips2mask as
-  well?
+- I like the new int mask creator in reducev, can we use it in im_vips2imask()
+  as well?
+
+  what about making the int masks for the interpolators?
 
 - try SEQ_UNBUFFERED on jpg source, get out of order error?
 

libvips/deprecated/im_vips2mask.c

@@ -200,7 +200,7 @@ im_vips2imask( IMAGE *in, const char *filename )
 	 * brightness between input and output? We want the same ratio for the
 	 * int version, if we can.
 	 *
-	 * Imaging an input image where every pixel is 1, what will the output
+	 * Imagine an input image where every pixel is 1, what will the output
 	 * be?
 	 */
 	double_result = 0;

libvips/draw/draw.c

@@ -54,8 +54,24 @@
  * These operations directly modify the image. They do not thread, on 32-bit
  * machines they will be limited to 2GB images, and a little care needs to be
  * taken if you use them as part of an image pipeline. 
- *
  * They are mostly supposed to be useful for paintbox-style programs.
+ *
+ * libvips operations are all functional: they take zero or more existing input 
+ * images and generate zero or more new output images. Images are
+ * never altered, you always create new images. This means libvips can cache
+ * and thread very agressively.
+ *
+ * The downside is that creating entirely fresh images each time can be very
+ * slow. libvips has a range of tricks to avoid these problems, but there are
+ * still times when you really have to be able to modify an image. An example
+ * might be drawing a curved line from a set of straight line segments: if you
+ * need to draw 1,000 straight lines, a 1,000 operation-deep pipeline is going
+ * to be a slow way to do it. This is where the draw operations come in.
+ *
+ * To use these operations, take a copy of the image you want to modify, to
+ * ensure that no one else is using it, then call a series of draw operations.
+ * Once you are done drawing, return to normal use of vips operations. Any time
+ * you want to start drawing again, you'll need to copy again. 
  */
 
 /**