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.

1 files changed, 7 insertions, 0 deletions

diff --git a/src/cairo-surface-subsurface.c b/src/cairo-surface-subsurface.c
index 96459a78..9b21fa65 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,