? pixman.h
? src/.cairo-pattern.c.swp
? src/.cairo-surface.c.swp
Index: src/cairo-pattern.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo-pattern.c,v
retrieving revision 1.65
diff -p -u -7 -r1.65 cairo-pattern.c
--- src/cairo-pattern.c	30 Aug 2005 17:42:17 -0000	1.65
+++ src/cairo-pattern.c	7 Oct 2005 21:22:11 -0000
@@ -1514,14 +1514,52 @@ _cairo_pattern_release_surface (cairo_pa
     }
     else
     {
 	cairo_surface_destroy (surface);
     }
 }
 
+/**
+ * _cairo_pattern_acquire_surfaces:
+ * @src: Source pattern
+ * @mask: Mask pattern. Can be null.
+ * @dst: Destination surface
+ * @src_x: X coordinate of the source rectangle, in the source pattern's
+ *         coordinate system
+ * @src_y: Y coordinate of the source rectangle, in the source pattern's
+ *         coordinate system
+ * @mask_x: X coordinate of upper-left corner of the mask area
+ *         (in device coordinates)
+ * @mask_y: Y coordinate of upper-left corner of the mask area
+ *         (in device coordinates)
+ * @width: Width of the area to composite upon (device coords)
+ * @height: Height of the area to composite upon (device coords)
+ * @src_out: Source surface for compositing
+ * @mask_out: Mask surface for compositing; can be null.
+ * @src_attributes: Attributes for the source surface.
+ * @mask_attributes: Attributes for the mask surface.
+ *
+ * Acquires surfaces for a pattern. This can be used each time a surface
+ * backend wants to implement a composite operation for a pattern.
+ *
+ * The returned surfaces match the result of dst->clone_similar (if
+ * available). The returned surfaces should then be treated like a surface
+ * pattern with attributes as specified in src_attributes and mask_attributes.
+ *
+ * The offsets in the returned attributes are to be added to the x/y
+ * parameters passed in to this function.
+ *
+ * attr->acquired and attr->extra can be ignored; they are only used by
+ * _cairo_pattern_release_surface.
+ *
+ * The returned matrix will not be an integer translation; it will be the
+ * identity matrix or a more complex transformation than an integer translate.
+ *
+ * Returned surfaces must be freed using _cairo_pattern_release_surface.
+ **/
 cairo_int_status_t
 _cairo_pattern_acquire_surfaces (cairo_pattern_t	    *src,
 				 cairo_pattern_t	    *mask,
 				 cairo_surface_t	    *dst,
 				 int			    src_x,
 				 int			    src_y,
 				 int			    mask_x,
Index: src/cairo-surface.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo-surface.c,v
retrieving revision 1.101
diff -p -u -7 -r1.101 cairo-surface.c
--- src/cairo-surface.c	29 Sep 2005 17:09:59 -0000	1.101
+++ src/cairo-surface.c	7 Oct 2005 21:22:11 -0000
@@ -804,14 +804,55 @@ _fallback_composite (cairo_operator_t	op
 						   dst_y - state.image_rect.y,
 						   width, height);
     _fallback_fini (&state);
 
     return status;
 }
 
+/**
+ * @operator: Cairo operator used for the compositing operation
+ * @src: A source pattern to composite upon the destination surface
+ * @mask: A mask to clip the drawing operation to
+ * @dst: Destination surface
+ * @src_x: X coordinate of the source rectangle, in the source pattern's
+ *         coordinate system
+ * @src_y: Y coordinate of the source rectangle, in the source pattern's
+ *         coordinate system
+ * @mask_x: X coordinate of the mask rectangle, in the mask pattern's
+ *         coordinate system
+ * @mask_y: X coordinate of the mask rectangle, in the mask pattern's
+ *         coordinate system
+ * @dst_x: X coordinate of the mask rectangle, in the destination surface's
+ *         coordinate system
+ * @dst_Y: Y coordinate of the mask rectangle, in the destination surface's
+ *         coordinate system
+ * @width: Width of the destination rectangle, in the destination surface's
+ *         coordinate system
+ * @height: Height of the destination rectangle, in the destination surface's
+ *          coordinate system
+ *
+ * Composites a pattern onto a surface.
+ * The compositing process works like this:
+ * - The patterns should be transformed according to the pattern matrix
+ *   using the filter from attr->filter
+ * - src_x/mask_x and src_y/mask_y are used as the upperleft corner of the
+ *   source/mask rect, in the coordinate space of their respective patterns
+ * - The surface should be composited to the resulting area, taking the extend
+ *   attribute into account, at the position indicated by dst_x/dst_y (as
+ *   passed to the composite functions), clipped to the width/height indicated
+ *   by the width/height parameter.
+ *
+ * If the mask repeat is none, pixels outside the mask are not changed (i.e.
+ * the mask rect is used as a clip rect in this case). The same goes for the
+ * source.
+ *
+ * A null mask is treated as a fully-opaque mask of infinite dimensions.
+ *
+ * See also _cairo_pattern_acquire_surfaces.
+ **/
 cairo_status_t
 _cairo_surface_composite (cairo_operator_t	operator,
 			  cairo_pattern_t	*src,
 			  cairo_pattern_t	*mask,
 			  cairo_surface_t	*dst,
 			  int			src_x,
 			  int			src_y,
Index: src/cairo-xcb-surface.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo-xcb-surface.c,v
retrieving revision 1.47
diff -p -u -7 -r1.47 cairo-xcb-surface.c
--- src/cairo-xcb-surface.c	10 Aug 2005 21:30:15 -0000	1.47
+++ src/cairo-xcb-surface.c	7 Oct 2005 21:22:15 -0000
@@ -317,41 +317,41 @@ _CAIRO_MASK_FORMAT (cairo_format_masks_t
     case 32:
 	if (masks->alpha_mask == 0xff000000 &&
 	    masks->red_mask == 0x00ff0000 &&
 	    masks->green_mask == 0x0000ff00 &&
 	    masks->blue_mask == 0x000000ff)
 	{
 	    *format = CAIRO_FORMAT_ARGB32;
-	    return 1;
+	    return TRUE;
 	}
 	if (masks->alpha_mask == 0x00000000 &&
 	    masks->red_mask == 0x00ff0000 &&
 	    masks->green_mask == 0x0000ff00 &&
 	    masks->blue_mask == 0x000000ff)
 	{
 	    *format = CAIRO_FORMAT_RGB24;
-	    return 1;
+	    return TRUE;
 	}
 	break;
     case 8:
 	if (masks->alpha_mask == 0xff)
 	{
 	    *format = CAIRO_FORMAT_A8;
-	    return 1;
+	    return TRUE;
 	}
 	break;
     case 1:
 	if (masks->alpha_mask == 0x1)
 	{
 	    *format = CAIRO_FORMAT_A1;
-	    return 1;
+	    return TRUE;
 	}
 	break;
     }
-    return 0;
+    return FALSE;
 }
 
 static cairo_status_t
 _get_image_surface (cairo_xcb_surface_t    *surface,
 		    cairo_rectangle_t      *interest_rect,
 		    cairo_image_surface_t **image_out,
 		    cairo_rectangle_t      *image_rect)
Index: src/cairoint.h
===================================================================
RCS file: /cvs/cairo/cairo/src/cairoint.h,v
retrieving revision 1.211
diff -p -u -7 -r1.211 cairoint.h
--- src/cairoint.h	19 Sep 2005 21:24:00 -0000	1.211
+++ src/cairoint.h	7 Oct 2005 21:22:15 -0000
@@ -746,28 +746,32 @@ typedef struct _cairo_format_masks {
     unsigned long green_mask;
     unsigned long blue_mask;
 } cairo_format_masks_t;
 
 struct _cairo_surface {
     const cairo_surface_backend_t *backend;
 
+    // All data members here are interpreted by cairo-surface.c and can be
+    // ignored by backend implementors. Especially, device_*_offset is added
+    // before the backend functions are called; similarly, the caller of the
+    // clip functions sets the clip serials.
     unsigned int ref_count;
     cairo_status_t status;
     cairo_bool_t finished;
     cairo_user_data_array_t user_data;
 
     double device_x_offset;
     double device_y_offset;
     double device_x_scale;
     double device_y_scale;
 
     /*
      * Each time a clip region is modified, it gets the next value in this
      * sequence.  This means that clip regions for this surface are uniquely
-     * identified andupdates to the clip can be readily identified
+     * identified and updates to the clip can be readily identified
      */
     unsigned int next_clip_serial;
     /*
      * The serial number of the current clip.  This is set when
      * the surface clipping is set.  The gstate can then cheaply
      * check whether the surface clipping is already correct before
      * performing a rendering operation.
@@ -898,14 +902,16 @@ typedef union {
 
 typedef struct _cairo_surface_attributes {
     cairo_matrix_t matrix;
     cairo_extend_t extend;
     cairo_filter_t filter;
     int		   x_offset;
     int		   y_offset;
+
+    /* private: */
     cairo_bool_t   acquired;
     void	   *extra;
 } cairo_surface_attributes_t;
 
 typedef struct _cairo_traps {
     cairo_trapezoid_t *traps;
     int num_traps;