doc: Add documentation for cairo_raster_source_pattern

Signed-off-by: Chris Wilson <chris@chris-wilson.co.uk>

3 files changed, 241 insertions, 0 deletions

diff --git a/doc/public/cairo-sections.txt b/doc/public/cairo-sections.txt
index d38e53ae..0af32f0a 100644
--- a/doc/public/cairo-sections.txt
+++ b/doc/public/cairo-sections.txt
@@ -323,6 +323,26 @@ cairo_pattern_get_user_data
 </SECTION>
 
 <SECTION>
+<FILE>cairo-raster-source</FILE>
+cairo_pattern_create_raster_source
+cairo_raster_source_pattern_set_callback_data
+cairo_raster_source_pattern_get_callback_data
+cairo_raster_source_pattern_set_acquire
+cairo_raster_source_pattern_get_acquire
+cairo_raster_source_pattern_set_snapshot
+cairo_raster_source_pattern_get_snapshot
+cairo_raster_source_pattern_set_copy
+cairo_raster_source_pattern_get_copy
+cairo_raster_source_pattern_set_finish
+cairo_raster_source_pattern_get_finish
+cairo_raster_source_acquire_func_t
+cairo_raster_source_release_func_t
+cairo_raster_source_snapshot_func_t
+cairo_raster_source_copy_func_t
+cairo_raster_source_finish_func_t
+</SECTION>
+
+<SECTION>
 <FILE>cairo-matrix</FILE>
 cairo_matrix_t
 cairo_matrix_init
diff --git a/src/cairo-raster-source-pattern.c b/src/cairo-raster-source-pattern.c
index 40031f79..940b297a 100644
--- a/src/cairo-raster-source-pattern.c
+++ b/src/cairo-raster-source-pattern.c
@@ -38,6 +38,29 @@
 #include "cairo-error-private.h"
 #include "cairo-pattern-private.h"
 
+/**
+ * SECTION:cairo-raster-source
+ * @Title: Raster Sources
+ * @Short_Description: Supplying arbitrary image data
+ * @See_Also: #cairo_pattern_t
+ *
+ * The raster source provides the ability to supply arbitrary pixel data
+ * whilst rendering. The pixels are queried at the time of rasterisation
+ * by means of user callback functions, allowing for the ultimate
+ * flexibility. For example, in handling compressed image sources, you
+ * may keep a MRU cache of decompressed images and decompress sources on the
+ * fly and discard old ones to conserve memory.
+ *
+ * For the raster source to be effective, you must at least specify
+ * the acquire and release callbacks which are used to retrieve the pixel
+ * data for the region of interest and demark when it can be freed afterwards.
+ * Other callbacks are provided for when the pattern is copied temporarily
+ * during rasterisation, or more permanently as a snapshot in order to keep
+ * the pixel data available for printing.
+ *
+ * Since: 1.12
+ **/
+
 cairo_surface_t *
 _cairo_raster_source_pattern_acquire (const cairo_pattern_t *abstract_pattern,
 				      cairo_surface_t *target,
@@ -112,6 +135,27 @@ _cairo_raster_source_pattern_finish (cairo_pattern_t *abstract_pattern)
     pattern->finish (&pattern->base, pattern->user_data);
 }
 
+/* Public interface */
+
+/**
+ * cairo_pattern_create_raster_source:
+ * @user_data: the user data to be passed to all callbacks
+ * @content: content type for the pixel data that will be returned. Knowing
+ * the content type ahead of time is used for analysing the operation and
+ * picking the appropriate rendering path.
+ * @width: maximum size of the sample area
+ * @height: maximum size of the sample area
+ *
+ * Creates a new user pattern for providing pixel data.
+ *
+ * Use the setter functions to associate callbacks with the returned
+ * pattern.  The only mandatory callback is acquire.
+ *
+ * Return value: a newly created #cairo_pattern_t. Free with
+ *  cairo_pattern_destroy() when you are done using it.
+ *
+ * Since: 1.12
+ **/
 cairo_pattern_t *
 cairo_pattern_create_raster_source (void *user_data,
 				    cairo_content_t content,
@@ -147,6 +191,15 @@ cairo_pattern_create_raster_source (void *user_data,
     return &pattern->base;
 }
 
+/**
+ * cairo_raster_source_pattern_set_callback_data:
+ * @pattern: the pattern to update
+ * @data: the user data to be passed to all callbacks
+ *
+ * Updates the user data that is provided to all callbacks.
+ *
+ * Since: 1.12
+ **/
 void
 cairo_raster_source_pattern_set_callback_data (cairo_pattern_t *abstract_pattern,
 					       void *data)
@@ -160,6 +213,14 @@ cairo_raster_source_pattern_set_callback_data (cairo_pattern_t *abstract_pattern
     pattern->user_data = data;
 }
 
+/**
+ * cairo_raster_source_pattern_get_callback_data:
+ * @pattern: the pattern to update
+ *
+ * Queries the current user data.
+ *
+ * Since: 1.12
+ **/
 void *
 cairo_raster_source_pattern_get_callback_data (cairo_pattern_t *abstract_pattern)
 {
@@ -172,6 +233,25 @@ cairo_raster_source_pattern_get_callback_data (cairo_pattern_t *abstract_pattern
     return pattern->user_data;
 }
 
+/**
+ * cairo_raster_source_pattern_set_acquire:
+ * @pattern: the pattern to update
+ * @acquire: acquire callback
+ * @release: release callback
+ *
+ * Specifies the callbacks used to generate the image surface for a rendering
+ * operation (acquire) and the function used to cleanup that surface afterwards.
+ *
+ * The @acquire callback should create a surface (preferably an image
+ * surface created to match the target using
+ * cairo_surface_create_similar_image()) that defines at least the region
+ * of interest specified by extents. The surface is allowed to be the entire
+ * sample area, but if it does contain a subsection of the sample area,
+ * the surface extents should be provided by setting the device offset (along
+ * with its width and height) using cairo_surface_set_device_offset().
+ *
+ * Since: 1.12
+ **/
 void
 cairo_raster_source_pattern_set_acquire (cairo_pattern_t *abstract_pattern,
 					 cairo_raster_source_acquire_func_t acquire,
@@ -187,6 +267,16 @@ cairo_raster_source_pattern_set_acquire (cairo_pattern_t *abstract_pattern,
     pattern->release = release;
 }
 
+/**
+ * cairo_raster_source_pattern_get_acquire:
+ * @pattern: the pattern to query
+ * @acquire: return value for the current acquire callback
+ * @release: return value for the current release callback
+ *
+ * Queries the current acquire and release callbacks.
+ *
+ * Since: 1.12
+ **/
 void
 cairo_raster_source_pattern_get_acquire (cairo_pattern_t *abstract_pattern,
 					 cairo_raster_source_acquire_func_t *acquire,
@@ -204,6 +294,17 @@ cairo_raster_source_pattern_get_acquire (cairo_pattern_t *abstract_pattern,
 	*release = pattern->release;
 }
 
+/**
+ * cairo_raster_source_pattern_set_snapshot:
+ * @pattern: the pattern to update
+ * @snapshot: snapshot callback
+ *
+ * Sets the callback that will be used whenever a snapshot is taken of the
+ * pattern, that is whenever the current contents of the pattern should be
+ * preserved for later use. This is typically invoked whilst printing.
+ *
+ * Since: 1.12
+ **/
 void
 cairo_raster_source_pattern_set_snapshot (cairo_pattern_t *abstract_pattern,
 					  cairo_raster_source_snapshot_func_t snapshot)
@@ -217,6 +318,16 @@ cairo_raster_source_pattern_set_snapshot (cairo_pattern_t *abstract_pattern,
     pattern->snapshot = snapshot;
 }
 
+/**
+ * cairo_raster_source_pattern_get_snapshot:
+ * @pattern: the pattern to query
+ *
+ * Queries the current snapshot callback.
+ *
+ * Return value: the current snapshot callback
+ *
+ * Since: 1.12
+ **/
 cairo_raster_source_snapshot_func_t
 cairo_raster_source_pattern_get_snapshot (cairo_pattern_t *abstract_pattern)
 {
@@ -229,6 +340,16 @@ cairo_raster_source_pattern_get_snapshot (cairo_pattern_t *abstract_pattern)
     return pattern->snapshot;
 }
 
+/**
+ * cairo_raster_source_pattern_set_copy:
+ * @pattern: the pattern to update
+ * @copy: the copy callback
+ *
+ * Updates the copy callback which is used whenever a temporary copy of the
+ * pattern is taken.
+ *
+ * Since: 1.12
+ **/
 void
 cairo_raster_source_pattern_set_copy (cairo_pattern_t *abstract_pattern,
 				      cairo_raster_source_copy_func_t copy)
@@ -242,6 +363,16 @@ cairo_raster_source_pattern_set_copy (cairo_pattern_t *abstract_pattern,
     pattern->copy = copy;
 }
 
+/**
+ * cairo_raster_source_pattern_get_copy:
+ * @pattern: the pattern to query
+ *
+ * Queries the current copy callback.
+ *
+ * Return value: the current copy callback
+ *
+ * Since: 1.12
+ **/
 cairo_raster_source_copy_func_t
 cairo_raster_source_pattern_get_copy (cairo_pattern_t *abstract_pattern)
 {
@@ -254,6 +385,16 @@ cairo_raster_source_pattern_get_copy (cairo_pattern_t *abstract_pattern)
     return pattern->copy;
 }
 
+/**
+ * cairo_raster_source_pattern_set_finish:
+ * @pattern: the pattern to update
+ * @finish: the finish callback
+ *
+ * Updates the finish callback which is used whenever a pattern (or a copy
+ * thereof) will no longer be used.
+ *
+ * Since: 1.12
+ **/
 void
 cairo_raster_source_pattern_set_finish (cairo_pattern_t *abstract_pattern,
 					cairo_raster_source_finish_func_t finish)
@@ -267,6 +408,16 @@ cairo_raster_source_pattern_set_finish (cairo_pattern_t *abstract_pattern,
     pattern->finish = finish;
 }
 
+/**
+ * cairo_raster_source_pattern_get_finish:
+ * @pattern: the pattern to query
+ *
+ * Queries the current finish callback.
+ *
+ * Return value: the current finish callback
+ *
+ * Since: 1.12
+ **/
 cairo_raster_source_finish_func_t
 cairo_raster_source_pattern_get_finish (cairo_pattern_t *abstract_pattern)
 {
diff --git a/src/cairo.h b/src/cairo.h
index 438abfc7..2b575c9e 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -2479,26 +2479,96 @@ cairo_recording_surface_get_extents (cairo_surface_t *surface,
 
 /* raster-source pattern (callback) functions */
 
+/**
+ * cairo_raster_source_acquire_func_t:
+ * @pattern: the pattern being rendered from
+ * @callback_data: the user data supplied during creation
+ * @target: the rendering target surface
+ * @extents: rectangular region of interest in pixels in sample space
+ *
+ * #cairo_raster_source_acquire_func_t is the type of function which is
+ * called when a pattern is being rendered from. It should create a surface
+ * that provides the pixel data for the region of interest as defined by
+ * extents, though the surface itself does not have to be limited to that
+ * area. For convenience the surface should probably be of image type,
+ * created with cairo_surface_create_similar_image() for the target (which
+ * enables the number of copies to be reduced during transfer to the
+ * device). Anothjr option, might be to return a similar surface to the
+ * target for explicit handling by the application of a set of cached sources
+ * on the device. The region of sample data provided should be defined using
+ * cairo_surface_set_device_offset() to specify the top-left corner of the
+ * sample data (along with width and height of the surface).
+ *
+ * Returns: a #cairo_surface_t
+ *
+ * Since: 1.12
+ **/
 typedef cairo_surface_t *
 (*cairo_raster_source_acquire_func_t) (cairo_pattern_t *pattern,
 				       void *callback_data,
 				       cairo_surface_t *target,
 				       const cairo_rectangle_int_t *extents);
 
+/**
+ * cairo_raster_source_release_func_t:
+ * @pattern: the pattern being rendered from
+ * @callback_data: the user data supplied during creation
+ * @surface: the surface created during acquire
+ *
+ * #cairo_raster_source_release_func_t is the type of function which is
+ * called when the pixel data is no longer being access by the pattern
+ * for the rendering operation. Typically this function will simply
+ * destroy the surface created during acquire.
+ *
+ * Since: 1.12
+ **/
 typedef void
 (*cairo_raster_source_release_func_t) (cairo_pattern_t *pattern,
 				       void *callback_data,
 				       cairo_surface_t *surface);
 
+/**
+ * cairo_raster_source_snapshot_func_t:
+ * @pattern: the pattern being rendered from
+ * @callback_data: the user data supplied during creation
+ *
+ * #cairo_raster_source_release_func_t is the type of function which is
+ * called when the pixel data needs to be preserved for later use
+ * during printing. This pattern will be accessed again later, and it
+ * is expected to provide the pixel data that was current at the time
+ * of snapshotting.
+ *
+ * Since: 1.12
+ **/
 typedef cairo_status_t
 (*cairo_raster_source_snapshot_func_t) (cairo_pattern_t *pattern,
 					void *callback_data);
 
+/**
+ * cairo_raster_source_copy_func_t:
+ * @pattern: the pattern being rendered from
+ * @callback_data: the user data supplied during creation
+ *
+ * #cairo_raster_source_copy_func_t is the type of function which is
+ * called when the pattern gets copied as a normal part of rendering.
+ *
+ * Since: 1.12
+ **/
 typedef cairo_status_t
 (*cairo_raster_source_copy_func_t) (cairo_pattern_t *pattern,
 				    void *callback_data,
 				    const cairo_pattern_t *other);
 
+/**
+ * cairo_raster_source_finish_func_t:
+ * @pattern: the pattern being rendered from
+ * @callback_data: the user data supplied during creation
+ *
+ * #cairo_raster_source_copy_func_t is the type of function which is
+ * called when the pattern (or a copy thereof) is no longer required.
+ *
+ * Since: 1.12
+ **/
 typedef void
 (*cairo_raster_source_finish_func_t) (cairo_pattern_t *pattern,
 				      void *callback_data);