update docs for new Python stuff

ChangeLog

@@ -22,6 +22,7 @@
 - command-line IMAGVEC input could segv with non-vips image output
 - added .tobuffer()/.frombuffer(), .tostring()/.fromstring() to Python binding
 - add PIL_mode_from_vips () and vips_from_PIL_mode () utility functions
+- update docs for new Python stuff
 
 25/1/08 started 7.14.0
 - bump all version numbers for new stable

doc/src/cppintro.tex

@@ -64,23 +64,26 @@ invert: VIPS error: im_open:
 #include <vips/vips>
 
 int
-main( int argc, char **argv )
+main (int argc, char **argv)
 {
-        if( argc != 3 ) {
+  if (argc != 3)
-                std::cerr << "usage: " << argv[0] << " infile outfile\n";
+    {
-                exit( 1 );
+      std::cerr << "usage: " << argv[0] << " infile outfile\n";
-        }
+      exit (1);
+    }
 
-        try {
+  try
-                vips::VImage fred( argv[1] );
+  {
+    vips::VImage fred (argv[1]);
 
-                fred.invert().write( argv[2] );
+    fred.invert ().write (argv[2]);
-        }
+  }
-        catch( vips::VError e ) {
+  catch (vips::VError e)
-                e.perror( argv[0] );
+  {
-        }
+    e.perror (argv[0]);
+  }
 
-        return( 0 );
+  return (0);
 }
 \end{verbatim}
 \caption{\texttt{invert} program in C++}

doc/src/vimage.tex

@@ -70,6 +70,37 @@ from an \verb+IMAGE+.
 In both these two cases, the VIPS C++ API does not assume responsibility
 for the resouces: it's up to you to make sure the buffer is freed.
 
+The Python interface adds the usual \verb+frombuffer+ and
+\verb+fromstring+ methods. 
+
+\begin{verbatim}
+VImage.fromstring (string, 
+  width, height, bands, format) -> 
+  VImage
+\end{verbatim}
+
+\begin{verbatim}
+VImage.frombuffer (buffer, 
+  width, height, bands, format) -> 
+  VImage
+\end{verbatim}
+
+\noindent
+Use \verb+fromstring+ to avoid worries about object lifetime, but you'll see a
+lot of copies and high memory use. Use \verb+frombuffer+ for speed, but you
+have to manage object lifetime yourself.
+
+They are useful for moving images into VIPS from other image processing
+libraries. There's also a utility function, \verb+vips_from_PIL_mode+, which
+turns a PIL mode into a VIPS band, format, type triple.
+
+\begin{verbatim}
+VImage.vips_from_PIL_mode (mode) -> 
+  (bands, format, type) 
+\end{verbatim}
+
+See also \verb+tobuffer+ and \verb+tostring+ below.
+
 \subsection{File conversion}
 
 VIPS can read and write a number of different file formats. Information about
@@ -160,6 +191,26 @@ void *data() const;
 \noindent
 This can be very slow and use huge amounts of RAM.
 
+The Python interface adds \verb+tobuffer+ and \verb+tostring+. These
+operations call \verb+data()+ to generate the image pixels and then either
+copy it and return the copy as a string, or wrap the pixels up as a Python
+buffer object.
+
+Use \verb+tostring+ to avoid worries about object lifetime, but you'll see a
+lot of copies and high memory use. Use \verb+tobuffer+ for speed, but you
+have to manage object lifetime yourself.
+
+They are useful for moving images from VIPS into other image processing
+libraries. There's also a utility function, \verb+PIL_mode_from_vips+, which
+makes a PIL mode from a VIPS image.
+
+\begin{verbatim}
+VImage.PIL_mode_from_vips (vips-image) -> 
+  mode
+\end{verbatim}
+
+See also \verb+frombuffer+ and \verb+fromstring+ above.
+
 Finally, two projection functions give access to the filename and history
 fields maintained by the VIPS IO system.