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

[Bryce Harrington]

 src/cairo-surface.c |   10 ++++++++++
 1 file changed, 10 insertions(+)

New commits:
commit 2d89cbb30e276cec57a893d4f0d45428858e5e8d
Author: jimmyfrasche <soapboxcicero at gmail.com>
Date:   Sun May 25 20:22:16 2014 -0700

    Add more info to cairo_surface_set_mime_data docs.
    
    Explains how to use cairo_surface_set_mime_data so that the image always
    gets used even if the MIME data cannot be.
    
    Signed-off-by: jimmyfrasche <soapboxcicero at gmail.com>

diff --git a/src/cairo-surface.c b/src/cairo-surface.c
index b8109f3..84e912d 100644
--- a/src/cairo-surface.c
+++ b/src/cairo-surface.c
@@ -1293,6 +1293,16 @@ _cairo_mime_data_destroy (void *ptr)
  * discarded if you draw on the surface afterwards. Use this function
  * with care.
  *
+ * Even if a backend supports a MIME type, that does not mean cairo
+ * will always be able to use the attached MIME data. For example, if
+ * the backend does not natively support the compositing operation used
+ * to apply the MIME data to the backend. In that case, the MIME data
+ * will be ignored. Therefore, to apply an image in all cases, it is best
+ * to create an image surface which contains the decoded image data and
+ * then attach the MIME data to that. This ensures the image will always
+ * be used while still allowing the MIME data to be used whenever
+ * possible.
+ *
  * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY if a
  * slot could not be allocated for the user data.
  *