doc: Add links to flush() and mark_dirty() in direct access functions

cairo_image_get_data() and other direct access functions are often
misused by applications because they don't call cairo_surface_flush()
and/or cairo_surface_mark_dirty() around the code which accesses the
surface data directly.

Although this information is already available in the description of
the cairo_surface_t type, adding a reminder about it in the direct
access functions should make it easier to use them correctly.

3 files changed, 18 insertions, 0 deletions

diff --git a/src/cairo-image-surface.c b/src/cairo-image-surface.c
index 7820f571..6082215f 100644
--- a/src/cairo-image-surface.c
+++ b/src/cairo-image-surface.c
@@ -524,6 +524,11 @@ slim_hidden_def (cairo_image_surface_create_for_data);
  * Get a pointer to the data of the image surface, for direct
  * inspection or modification.
  *
+ * A call to cairo_surface_flush() is required before accessing the
+ * pixel data to ensure that all pending drawing operations are
+ * finished. A call to cairo_surface_mark_dirty() is required after
+ * the data is modified.
+ *
  * Return value: a pointer to the image data of this surface or %NULL
  * if @surface is not an image surface, or if cairo_surface_finish()
  * has been called.
diff --git a/src/cairo-quartz-surface.c b/src/cairo-quartz-surface.c
index c5fbe033..06dd1287 100644
--- a/src/cairo-quartz-surface.c
+++ b/src/cairo-quartz-surface.c
@@ -2714,6 +2714,13 @@ cairo_quartz_surface_create (cairo_format_t format,
  * Returns the CGContextRef that the given Quartz surface is backed
  * by.
  *
+ * A call to cairo_surface_flush() is required before using the
+ * CGContextRef to ensure that all pending drawing operations are
+ * finished and to restore any temporary modification cairo has made
+ * to its state. A call to cairo_surface_mark_dirty() is required
+ * after the state or the content of the CGContextRef has been
+ * modified.
+ *
  * Return value: the CGContextRef for the given surface.
  *
  * Since: 1.4
diff --git a/src/cairo-win32-surface.c b/src/cairo-win32-surface.c
index c335d978..da8acca0 100644
--- a/src/cairo-win32-surface.c
+++ b/src/cairo-win32-surface.c
@@ -1849,6 +1849,12 @@ _cairo_surface_is_win32 (cairo_surface_t *surface)
  * Returns the HDC associated with this surface, or %NULL if none.
  * Also returns %NULL if the surface is not a win32 surface.
  *
+ * A call to cairo_surface_flush() is required before using the HDC to
+ * ensure that all pending drawing operations are finished and to
+ * restore any temporary modification cairo has made to its state. A
+ * call to cairo_surface_mark_dirty() is required after the state or
+ * the content of the HDC has been modified.
+ *
  * Return value: HDC or %NULL if no HDC available.
  *
  * Since: 1.2