[cairo-commit] src/cairo-xcb-connection.c src/cairo-xcb-surface.c

[Uli Schlachter]

 src/cairo-xcb-connection.c |   26 ++++++++++++++++
 src/cairo-xcb-surface.c    |   70 ++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 95 insertions(+), 1 deletion(-)

New commits:
commit 00b1eac4b0df7a169ce0796850ed7a17bef69416
Author: Uli Schlachter <psychon at znc.in>
Date:   Wed Jan 26 21:10:59 2011 +0100

    xcb: Document all public functions
    
    These docs are based upon cairo-xlib and the existing documentations for
    cairo_xcb_surface_create_with_xrender_format.
    
    Signed-off-by: Uli Schlachter <psychon at znc.in>

diff --git a/src/cairo-xcb-connection.c b/src/cairo-xcb-connection.c
index 73f70b1..8098337 100644
--- a/src/cairo-xcb-connection.c
+++ b/src/cairo-xcb-connection.c
@@ -792,6 +792,19 @@ _cairo_xcb_connection_get_xid (cairo_xcb_connection_t *connection)
 
 /* public (debug) interface */
 
+/**
+ * cairo_xcb_device_debug_cap_xshm_version:
+ * @device: a #cairo_device_t for the XCB backend
+ * @major_version: major version to restrict to
+ * @minor_version: minor version to restrict to
+ *
+ * Restricts all future XCB surfaces for this devices to the specified version
+ * of the SHM extension. This function exists solely for debugging purpose.
+ * It let's you find out how cairo would behave with an older version of
+ * the SHM extension.
+ *
+ * Use the special values -1 and -1 for disabling the SHM extension.
+ **/
 void
 cairo_xcb_device_debug_cap_xshm_version (cairo_device_t *device,
                                          int major_version,
@@ -811,6 +824,19 @@ cairo_xcb_device_debug_cap_xshm_version (cairo_device_t *device,
     }
 }
 
+/**
+ * cairo_xcb_device_debug_cap_xrender_version:
+ * @device: a #cairo_device_t for the XCB backend
+ * @major_version: major version to restrict to
+ * @minor_version: minor version to restrict to
+ *
+ * Restricts all future XCB surfaces for this devices to the specified version
+ * of the RENDER extension. This function exists solely for debugging purpose.
+ * It let's you find out how cairo would behave with an older version of
+ * the RENDER extension.
+ *
+ * Use the special values -1 and -1 for disabling the RENDER extension.
+ **/
 void
 cairo_xcb_device_debug_cap_xrender_version (cairo_device_t *device,
                                             int major_version,
diff --git a/src/cairo-xcb-surface.c b/src/cairo-xcb-surface.c
index 6b45e8b..33e42ce 100644
--- a/src/cairo-xcb-surface.c
+++ b/src/cairo-xcb-surface.c
@@ -74,6 +74,13 @@ slim_hidden_proto (cairo_xcb_surface_create_with_xrender_format);
  * extension if it is available.
  */
 
+/**
+ * CAIRO_HAS_XCB_SURFACE:
+ *
+ * Defined if the xcb surface backend is available.
+ * This macro can be used to conditionally compile backend-specific code.
+ */
+
 #if CAIRO_HAS_XCB_SHM_FUNCTIONS
 static cairo_status_t
 _cairo_xcb_surface_create_similar_shm (cairo_xcb_surface_t *other,
@@ -1131,6 +1138,37 @@ _cairo_xcb_screen_from_visual (xcb_connection_t *connection,
     return NULL;
 }
 
+/**
+ * cairo_xcb_surface_create:
+ * @xcb_connection: an XCB connection
+ * @drawable: an XCB drawable
+ * @visual: the visual to use for drawing to @drawable. The depth
+ *          of the visual must match the depth of the drawable.
+ *          Currently, only TrueColor visuals are fully supported.
+ * @width: the current width of @drawable
+ * @height: the current height of @drawable
+ *
+ * Creates an XCB surface that draws to the given drawable.
+ * The way that colors are represented in the drawable is specified
+ * by the provided visual.
+ *
+ * Note: If @drawable is a Window, then the function
+ * cairo_xcb_surface_set_size() must be called whenever the size of the
+ * window changes.
+ *
+ * When @drawable is a Window containing child windows then drawing to
+ * the created surface will be clipped by those child windows.  When
+ * the created surface is used as a source, the contents of the
+ * children will be included.
+ *
+ * Return value: a pointer to the newly created surface. The caller
+ * owns the surface and should call cairo_surface_destroy() when done
+ * with it.
+ *
+ * This function always returns a valid pointer, but it will return a
+ * pointer to a "nil" surface if an error such as out of memory
+ * occurs. You can use cairo_surface_status() to check for this.
+ **/
 cairo_surface_t *
 cairo_xcb_surface_create (xcb_connection_t  *xcb_connection,
 			  xcb_drawable_t     drawable,
@@ -1191,6 +1229,25 @@ cairo_xcb_surface_create (xcb_connection_t  *xcb_connection,
 slim_hidden_def (cairo_xcb_surface_create);
 #endif
 
+/**
+ * cairo_xcb_surface_create_for_bitmap:
+ * @xcb_connection: an XCB connection
+ * @xcb_screen: the XCB screen associated with @bitmap
+ * @bitmap: an XCB drawable (a Pixmap with depth 1)
+ * @width: the current width of @drawable
+ * @height: the current height of @drawable
+ *
+ * Creates an XCB surface that draws to the given bitmap.
+ * This will be drawn to as a %CAIRO_FORMAT_A1 object.
+ *
+ * Return value: a pointer to the newly created surface. The caller
+ * owns the surface and should call cairo_surface_destroy() when done
+ * with it.
+ *
+ * This function always returns a valid pointer, but it will return a
+ * pointer to a "nil" surface if an error such as out of memory
+ * occurs. You can use cairo_surface_status() to check for this.
+ **/
 cairo_surface_t *
 cairo_xcb_surface_create_for_bitmap (xcb_connection_t	*xcb_connection,
 				     xcb_screen_t	*xcb_screen,
@@ -1237,7 +1294,18 @@ slim_hidden_def (cairo_xcb_surface_create_for_bitmap);
  * cairo_xcb_surface_set_size() must be called whenever the size of the
  * window changes.
  *
- * Return value: the newly created surface.
+ * When @drawable is a Window containing child windows then drawing to
+ * the created surface will be clipped by those child windows.  When
+ * the created surface is used as a source, the contents of the
+ * children will be included.
+ *
+ * Return value: a pointer to the newly created surface. The caller
+ * owns the surface and should call cairo_surface_destroy() when done
+ * with it.
+ *
+ * This function always returns a valid pointer, but it will return a
+ * pointer to a "nil" surface if an error such as out of memory
+ * occurs. You can use cairo_surface_status() to check for this.
  **/
 cairo_surface_t *
 cairo_xcb_surface_create_with_xrender_format (xcb_connection_t	    *xcb_connection,