doc: Clarify when the device scale is inherited and when it isn'tHEADmaster

In short, cairo_surface_create_similar inherits it, while
cairo_surface_create_similar_image doesn't. It wasn't obvious without
reading the code or explicitly checking the device scale of the new
surface.

Fixes: https://bugs.freedesktop.org/show_bug.cgi?id=99094

Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>

1 files changed, 8 insertions, 5 deletions

diff --git a/src/cairo-surface.c b/src/cairo-surface.c
index f56e0f81c..fc5f876d7 100644
--- a/src/cairo-surface.c
+++ b/src/cairo-surface.c
@@ -466,10 +466,11 @@ _cairo_surface_copy_similar_properties (cairo_surface_t *surface,
  *
  * Create a new surface that is as compatible as possible with an
  * existing surface. For example the new surface will have the same
- * fallback resolution and font options as @other. Generally, the new
- * surface will also use the same backend as @other, unless that is
- * not possible for some reason. The type of the returned surface may
- * be examined with cairo_surface_get_type().
+ * device scale, fallback resolution and font options as
+ * @other. Generally, the new surface will also use the same backend
+ * as @other, unless that is not possible for some reason. The type of
+ * the returned surface may be examined with
+ * cairo_surface_get_type().
  *
  * Initially the surface contents are all 0 (transparent if contents
  * have transparency, black otherwise.)
@@ -556,7 +557,9 @@ cairo_surface_create_similar (cairo_surface_t  *other,
  *
  * Create a new image surface that is as compatible as possible for uploading
  * to and the use in conjunction with an existing surface. However, this surface
- * can still be used like any normal image surface.
+ * can still be used like any normal image surface. Unlike
+ * cairo_surface_create_similar() the new image surface won't inherit
+ * the device scale from @other.
  *
  * Initially the surface contents are all 0 (transparent if contents
  * have transparency, black otherwise.)