better support for drawing operations

much more mem efficient for repeated draws

doc updates too

TODO

@@ -8,8 +8,6 @@
 
 - why don't we get gtk-doc expansions in the leading chapters? we turn them on
 
-- note we automatically copy modified args in Vips.py
-
 - does cplusplus need to hide deprecated args and operations?
 
 - test other cpp arg types

doc/reference/using-python.xml

@@ -99,7 +99,7 @@ im = im.similarity(scale = 0.9, interpolate = Vips.Interpolate.new("bicubic"))
   </refsect1>
 
   <refsect1 id="python-basics">
-    <title><code>pyvips8</code> Basics</title>
+    <title><code>pyvips8</code> basics</title>
     <para>
       The Python interface comes in two main parts. First, the C source code 
       to libvips has been marked up with special comments describing the 
@@ -291,6 +291,30 @@ help(image.add)
     </para>
   </refsect1>
 
+  <refsect1 id="python-modify">
+    <title>Draw operations</title>
+    <para>
+      Paint operations like <code>draw_circle</code> and <code>draw_line</code> 
+      modify their input image. This makes them hard to use with the rest of 
+      libvips: you need to be very careful about the order in which operations 
+      execute or you can get nasty crashes.
+    </para>
+
+    <para>
+      The wrapper spots operations of this type and makes a private copy of 
+      the image in memory before calling the operation. This stops crashes, 
+      but it does make it inefficient. If you draw 100 lines on an image, 
+      for example, you'll copy the image 100 times. The wrapper does make sure 
+      that memory is recycled where possible, so you won't have 100 copies in 
+      memory. At least you can execute these operations. 
+    </para>
+
+    <para>
+      If you want to avoid the copies, you'll need to call drawing 
+      operations yourself. 
+    </para>
+  </refsect1>
+
   <refsect1 id="python-overloads">
     <title>Overloads</title>
     <para>

python/Vips.py

@@ -136,7 +136,12 @@ class Argument:
 
         # MODIFY input images need to be copied before assigning them
         if self.flags & Vips.ArgumentFlags.MODIFY:
-            value = value.copy()
+            # don't use .copy(): we want to make a new pipeline with no
+            # reference back to the old stuff ... this way we can free the
+            # previous image earlier
+            new_image = Vips.Image.new_memory()
+            value.write(new_image)
+            value = new_image
 
         logging.debug('assigning %s' % self.prop.value_type)