[cairo-commit] 2 commits - src/cairo-device.c src/cairo-surface-subsurface.c

[M. Joonas Pihlaja]

 src/cairo-device.c             |    6 ++++++
 src/cairo-surface-subsurface.c |    7 +++++++
 2 files changed, 13 insertions(+)

New commits:
commit 9f98ec6eb915204d59820cf57d32f347f9933517
Author: M Joonas Pihlaja <jpihlaja at cc.helsinki.fi>
Date:   Sun Aug 29 00:05:51 2010 +0300

    device: Refer the user to per-backend docs about devices.
    
    The exact semantics of the device API can't be spelled out
    out in the device API docs since the effects are so tied
    to the specific backend.  To use a particular device in
    practice the user should refer to the backend docs.

diff --git a/src/cairo-device.c b/src/cairo-device.c
index dac1b3b..15b0484 100644
--- a/src/cairo-device.c
+++ b/src/cairo-device.c
@@ -86,6 +86,12 @@
  *   cairo_device_release (device);
  * }
  * </programlisting></informalexample>
+ *
+ * <note><para>Please refer to the documentation of each backend for
+ * additional usage requirements, guarantees provided, and
+ * interactions with existing surface API of the device functions for
+ * surfaces of that type.
+ * </para></note>
  */
 
 static const cairo_device_t _nil_device = {
commit b0f65054b810d432238ff4986bee3f63e1fc46df
Author: M Joonas Pihlaja <jpihlaja at cc.helsinki.fi>
Date:   Sun Aug 29 00:03:07 2010 +0300

    subsurface: Add a note to the docs about usage restrictions.
    
    Make our assumptions about constructed subsurfaces explicit
    while we work out the correct semantics for the edge cases.

diff --git a/src/cairo-surface-subsurface.c b/src/cairo-surface-subsurface.c
index 96459a7..9b21fa6 100644
--- a/src/cairo-surface-subsurface.c
+++ b/src/cairo-surface-subsurface.c
@@ -486,6 +486,11 @@ static const cairo_surface_backend_t _cairo_surface_subsurface_backend = {
  * directly onto the parent surface, i.e. with no further backend allocations,
  * double buffering or copies.
  *
+ * <note><para>The semantics of subsurfaces have not been finalized yet
+ * unless the rectangle is in full device units, is contained within
+ * the extents of the target surface, and the target or subsurface's
+ * device transforms are not changed.</para></note>
+ *
  * Return value: a pointer to the newly allocated surface. The caller
  * owns the surface and should call cairo_surface_destroy() when done
  * with it.
@@ -493,6 +498,8 @@ static const cairo_surface_backend_t _cairo_surface_subsurface_backend = {
  * This function always returns a valid pointer, but it will return a
  * pointer to a "nil" surface if @other is already in an error state
  * or any other error occurs.
+ *
+ * Since: 1.10
  **/
 cairo_surface_t *
 cairo_surface_create_for_rectangle (cairo_surface_t *target,