Add API comments for fz_shade.

1 files changed, 93 insertions, 0 deletions

diff --git a/include/mupdf/fitz/shade.h b/include/mupdf/fitz/shade.h
index 56adea5b..59ff7b97 100644
--- a/include/mupdf/fitz/shade.h
+++ b/include/mupdf/fitz/shade.h
@@ -72,11 +72,56 @@ struct fz_shade_s
 	fz_compressed_buffer *buffer;
 };
 
+/*
+	fz_keep_shade: Add a reference to an fz_shade.
+
+	shade: The reference to keep.
+
+	Returns shade.
+*/
 fz_shade *fz_keep_shade(fz_context *ctx, fz_shade *shade);
+
+/*
+	fz_drop_shade: Drop a reference to an fz_shade.
+
+	shade: The reference to drop. If this is the last
+	reference, shade will be destroyed.
+*/
 void fz_drop_shade(fz_context *ctx, fz_shade *shade);
+
+/*
+	fz_drop_shade_imp: Internal function to destroy a
+	shade. Only exposed for use with the fz_store.
+
+	shade: The reference to destroy.
+*/
 void fz_drop_shade_imp(fz_context *ctx, fz_storable *shade);
 
+/*
+	fz_bound_shade: Bound a given shading.
+
+	shade: The shade to bound.
+
+	ctm: The transform to apply to the shade before bounding.
+
+	r: Pointer to storage to put the bounds in.
+
+	Returns r, updated to contain the bounds for the shading.
+*/
 fz_rect *fz_bound_shade(fz_context *ctx, fz_shade *shade, const fz_matrix *ctm, fz_rect *r);
+
+/*
+	fz_paint_shade: Render a shade to a given pixmap.
+
+	shade: The shade to paint.
+
+	ctm: The transform to apply.
+
+	dest: The pixmap to render into.
+
+	bbox: Pointer to a bounding box to limit the rendering
+	of the shade.
+*/
 void fz_paint_shade(fz_context *ctx, fz_shade *shade, const fz_matrix *ctm, fz_pixmap *dest, const fz_irect *bbox);
 
 /*
@@ -90,12 +135,60 @@ struct fz_vertex_s
 	float c[FZ_MAX_COLORS];
 };
 
+/*
+	fz_mesh_prepare_fn: Callback function type for use with
+	fz_process_mesh.
+
+	arg: Opaque pointer from fz_process_mesh caller.
+
+	v: Pointer to a fz_vertex structure to populate.
+
+	c: Pointer to an array of floats to use to populate v.
+*/
 typedef void (fz_mesh_prepare_fn)(fz_context *ctx, void *arg, fz_vertex *v, const float *c);
+
+/*
+	fz_mesh_process_fn: Callback function type for use with
+	fz_process_mesh.
+
+	arg: Opaque pointer from fz_process_mesh caller.
+
+	av, bv, cv: Pointers to a fz_vertex structure describing
+	the corner locations and colors of a triangle to be
+	filled.
+*/
 typedef void (fz_mesh_process_fn)(fz_context *ctx, void *arg, fz_vertex *av, fz_vertex *bv, fz_vertex *cv);
 
+/*
+	fz_process_mesh: Process a mesh, using supplied callback
+	functions.
+
+	shade: The shade to process.
+
+	ctm: The transform to use
+
+	prepare: Callback function to 'prepare' each vertex.
+	This function is passed an array of floats, and populates
+	an fz_vertex structure.
+
+	process: This function is passed 3 pointers to vertex
+	structures, and actually performs the processing (typically
+	filling the area between the vertexes).
+
+	process_arg: An opaque argument passed through from caller
+	to callback functions.
+*/
 void fz_process_mesh(fz_context *ctx, fz_shade *shade, const fz_matrix *ctm,
 			fz_mesh_prepare_fn *prepare, fz_mesh_process_fn *process, void *process_arg);
 
+/*
+	fz_print_shade: Output a textual representation of
+	a shading.
+
+	out: The stream to output to.
+
+	shade: The shade to dump information about.
+*/
 void fz_print_shade(fz_context *ctx, fz_output *out, fz_shade *shade);
 
 #endif