[cairo-commit] pycairo/doc/reference mattributes.rst, 1.2, 1.3 surfaces.rst, 1.4, 1.5

[Steve Chaplin]

Committed by: stevech1097

Update of /cvs/cairo/pycairo/doc/reference
In directory kemper:/tmp/cvs-serv4014/doc/reference

Modified Files:
	mattributes.rst surfaces.rst 
Log Message:
'SC'

Index: mattributes.rst
===================================================================
RCS file: /cvs/cairo/pycairo/doc/reference/mattributes.rst,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- mattributes.rst	12 Feb 2009 09:04:29 -0000	1.2
+++ mattributes.rst	3 Mar 2009 12:40:23 -0000	1.3
@@ -154,6 +154,7 @@
 
  These attributes specify variants of a font face based on their slant.
 
+.. _mattributes_format:
 .. attribute:: cairo.FORMAT_ARGB32
    	       cairo.FORMAT_RGB24
    	       cairo.FORMAT_A8

Index: surfaces.rst
===================================================================
RCS file: /cvs/cairo/pycairo/doc/reference/surfaces.rst,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- surfaces.rst	12 Feb 2009 09:04:29 -0000	1.4
+++ surfaces.rst	3 Mar 2009 12:40:24 -0000	1.5
@@ -211,24 +211,59 @@
 class ImageSurface(:class:`Surface`)
 ====================================
 
-.. class:: ImageSurface
+A *cairo.ImageSurface* provides the ability to render to memory buffers either
+allocated by cairo or by the calling code. The supported image formats are
+those defined in :ref:`FORMAT attributes <mattributes_format>`.
 
-.. comment
- C : surface = cairo_image_surface_create (format, width, height);
+.. class:: ImageSurface(format, width, height)
+
+   :param format: format of pixels in the surface to create
+   :param width: width of the surface, in pixels
+   :param height: height of the surface, in pixels
+   :returns: a new *ImageSurface*
+   :raises: *MemoryError* in case of no memory
+
+   Creates an *ImageSurface* of the specified format and dimensions. Initially
+   the surface contents are all 0. (Specifically, within each pixel, each
+   color or alpha channel belonging to format will be 0. The contents of bits
+   within a pixel, but not belonging to the given format are undefined).
+
+   .. method:: create_for_data(data, format, width, height, stride)
+
+      :param data: a writable Python buffer object
+      :param format: the format of pixels in the buffer
+      :param width: the width of the image to be stored in the buffer
+      :param height: the height of the image to be stored in the buffer
+      :param stride: the number of bytes between the start of rows in the buffer as allocated. This value should always be computed by :meth:`.format_stride_for_width` before allocating the data buffer.
+      :returns: a new *ImageSurface*
+      :raises: *MemoryError* in case of no memory.
+
+               :class:`cairo.Error` in case of invalid *stride* value.
+
+      Creates an *ImageSurface* for the provided pixel data. The initial
+      contents of buffer will be used as the initial image contents; you must
+      explicitly clear the buffer, using, for example, cairo_rectangle() and
+      cairo_fill() if you want it cleared.
+
+      Note that the *stride* may be larger than width*bytes_per_pixel to
+      provide proper alignment for each pixel and row. This alignment is
+      required to allow high-performance rendering within cairo. The correct
+      way to obtain a legal stride value is to call
+      :meth:`.format_stride_for_width` with the desired format and maximum
+      image width value, and use the resulting stride value to allocate the
+      data and to create the *ImageSurface*. See
+      :meth:`.format_stride_for_width` for example code.
+
+
+   .. method:: create_from_png()
+   .. comment
      surface = cairo_image_surface_create_from_png (filename);
      surface = cairo_image_surface_create_from_png_stream (read_func, closure);
-     surface = cairo_image_surface_create_for_data (data, format, w, h, stride)
 
- Py: surface = cairo.ImageSurface (format, width, height)
      surface = cairo.ImageSurface.create_from_png (f)
        where 'f' is a filename, a file object, or a file-like object
-     surface = cairo.ImageSurface.create_for_data (data, format, w, h, stride)
-       where 'data' if a writable Python buffer object
-..
-
-   .. method:: create_for_data()
+   ..
 
-   .. method:: create_from_png()
 
    .. method:: format_stride_for_width()
 
@@ -238,10 +273,10 @@
 
    .. method:: get_height()
 
-   .. method:: get_width()
-
    .. method:: get_stride()
 
+   .. method:: get_width()
+
 
 class PDFSurface(:class:`Surface`)
 ==================================