Update API header documentation

Images, Document and Document Handlers.

2 files changed, 292 insertions, 8 deletions

diff --git a/include/mupdf/fitz/document.h b/include/mupdf/fitz/document.h
index 90b54b26..3769a795 100644
--- a/include/mupdf/fitz/document.h
+++ b/include/mupdf/fitz/document.h
@@ -27,17 +27,86 @@ typedef enum
 }
 fz_permission;
 
+/*
+	fz_document_drop_fn: Type for a function to be called when
+	the reference count for the fz_document drops to 0. The
+	implementation should release any resources held by the
+	document. The actual document pointer will be freed by the
+	caller.
+*/
 typedef void (fz_document_drop_fn)(fz_context *ctx, fz_document *doc);
+
+/*
+	fz_document_needs_password_fn: Type for a function to be
+	called to enquire whether the document needs a password
+	or not. See fz_needs_password for more information.
+*/
 typedef int (fz_document_needs_password_fn)(fz_context *ctx, fz_document *doc);
+
+/*
+	fz_document_authenticate_password_fn: Type for a function to be
+	called to attempt to authenticate a password. See
+	fz_authenticate_password for more information.
+*/
 typedef int (fz_document_authenticate_password_fn)(fz_context *ctx, fz_document *doc, const char *password);
+
+/*
+	fz_document_has_permission_fn: Type for a function to be
+	called to see if a document grants a certain permission. See
+	fz_document_has_permission for more information.
+*/
 typedef int (fz_document_has_permission_fn)(fz_context *ctx, fz_document *doc, fz_permission permission);
+
+/*
+	fz_document_load_outline_fn: Type for a function to be called to
+	load the outlines for a document. See fz_document_load_outline
+	for more information.
+*/
 typedef fz_outline *(fz_document_load_outline_fn)(fz_context *ctx, fz_document *doc);
+
+/*
+	fz_document_layout_fn: Type for a function to be called to lay
+	out a document. See fz_layout_document for more information.
+*/
 typedef void (fz_document_layout_fn)(fz_context *ctx, fz_document *doc, float w, float h, float em);
+
+/*
+	fz_document_resolve_link_fn: Type for a function to be called to
+	resolve an internal link to a page number. See fz_resolve_link
+	for more information.
+*/
 typedef int (fz_document_resolve_link_fn)(fz_context *ctx, fz_document *doc, const char *uri, float *xp, float *yp);
+
+/*
+	fz_document_count_pages_fn: Type for a function to be called to
+	count the number of pages in a document. See fz_count_pages for
+	more information.
+*/
 typedef int (fz_document_count_pages_fn)(fz_context *ctx, fz_document *doc);
+
+/*
+	fz_document_load_page_fn: Type for a function to load a given
+	page from a document. See fz_load_page for more information.
+*/
 typedef fz_page *(fz_document_load_page_fn)(fz_context *ctx, fz_document *doc, int number);
+
+/*
+	fz_document_lookup_metadata_fn: Type for a function to query
+	a documents metadata. See fz_lookup_metadata for more
+	information.
+*/
 typedef int (fz_document_lookup_metadata_fn)(fz_context *ctx, fz_document *doc, const char *key, char *buf, int size);
+
+/*
+	fz_document_make_bookmark_fn: Type for a function to make
+	a bookmark. See fz_make_bookmark for more information.
+*/
 typedef fz_bookmark (fz_document_make_bookmark_fn)(fz_context *ctx, fz_document *doc, int page);
+
+/*
+	fz_document_lookup_bookmark_fn: Type for a function to lookup
+	a bookmark. See fz_lookup_bookmark for more information.
+*/
 typedef int (fz_document_lookup_bookmark_fn)(fz_context *ctx, fz_document *doc, fz_bookmark mark);
 
 typedef fz_link *(fz_page_load_links_fn)(fz_context *ctx, fz_page *page);
@@ -92,7 +161,9 @@ struct fz_page_s
 
 /*
 	Structure definition is public so other classes can
-	derive from it. Do not access the members directly.
+	derive from it. Callers shoud not access the members
+	directly, though implementations will need initialize
+	functions directly.
 */
 struct fz_document_s
 {
@@ -113,8 +184,38 @@ struct fz_document_s
 	int is_reflowable;
 };
 
+/*
+	fz_document_open_fn: Function type to open a document from a
+	file.
+
+	filename: file to open
+
+	Pointer to opened document. Throws exception in case of error.
+*/
 typedef fz_document *(fz_document_open_fn)(fz_context *ctx, const char *filename);
+
+/*
+	fz_document_open_with_stream_fn: Function type to open a
+	document from a file.
+
+	stream: fz_stream to read document data from. Must be
+	seekable for formats that require it.
+
+	Pointer to opened document. Throws exception in case of error.
+*/
 typedef fz_document *(fz_document_open_with_stream_fn)(fz_context *ctx, fz_stream *stream);
+
+/*
+	fz_document_recognize_fn: Recognize a document type from
+	a magic string.
+
+	magic: string to recognise - typically a filename or mime
+	type.
+
+	Returns a number between 0 (not recognized) and 100
+	(fully recognized) based on how certain the recognizer
+	is that this is of the required type.
+*/
 typedef int (fz_document_recognize_fn)(fz_context *ctx, const char *magic);
 
 struct fz_document_handler_s
@@ -124,8 +225,19 @@ struct fz_document_handler_s
 	fz_document_open_with_stream_fn *open_with_stream;
 };
 
+/*
+	fz_register_document_handler: Register a handler
+	for a document type.
+
+	handler: The handler to register.
+*/
 void fz_register_document_handler(fz_context *ctx, const fz_document_handler *handler);
 
+/*
+	fz_register_document_handler: Register handlers
+	for all the standard document types supported in
+	this build.
+*/
 void fz_register_document_handlers(fz_context *ctx);
 
 /*
@@ -136,9 +248,7 @@ void fz_register_document_handlers(fz_context *ctx);
 	documents (without actually changing the file contents).
 
 	The returned fz_document is used when calling most other
-	document related functions. Note that it wraps the context, so
-	those functions implicitly can access the global state in
-	context.
+	document related functions.
 
 	filename: a path to a file as it would be given to open(2).
 */
diff --git a/include/mupdf/fitz/image.h b/include/mupdf/fitz/image.h
index 6ce71a14..7fe8a7f6 100644
--- a/include/mupdf/fitz/image.h
+++ b/include/mupdf/fitz/image.h
@@ -52,8 +52,9 @@ fz_pixmap *fz_get_pixmap_from_image(fz_context *ctx, fz_image *image, const fz_i
 void fz_drop_image(fz_context *ctx, fz_image *image);
 
 /*
-	fz_drop_image: Drop a reference to the base class of an
-	image (for internal use in derived image classes only).
+	fz_drop_image_base: Drop a reference to the base class
+	of an image (for internal use in derived image classes
+	only).
 
 	image: The image to drop a reference to.
 */
@@ -71,15 +72,157 @@ fz_image *fz_keep_image(fz_context *ctx, fz_image *image);
 fz_image *fz_keep_image_store_key(fz_context *ctx, fz_image *image);
 void fz_drop_image_store_key(fz_context *ctx, fz_image *image);
 
+/*
+	fz_drop_image_fn: Function type to destroy an images data
+	when it's reference count reaches zero.
+*/
 typedef void (fz_drop_image_fn)(fz_context *ctx, fz_image *image);
-typedef fz_pixmap *(fz_image_get_pixmap_fn)(fz_context *, fz_image *, fz_irect *, int, int, int *);
+
+/*
+	fz_get_pixmap_fn: Function type to get a decoded pixmap
+	for an image.
+
+	im: The image to decode.
+
+	subarea: NULL, or the subarea of the image required. Expressed
+	in terms of a rectangle in the original width/height of the
+	image. If non NULL, this should be updated by the function to
+	the actual subarea decoded - which must include the requested
+	area!
+
+	w, h: The actual width and height that the whole image would
+	need to be decoded to.
+
+	l2factor: On entry, the log 2 subsample factor required. If
+	possible the decode process can take care of (all or some) of
+	this subsampling, and must then update the value so the caller
+	knows what remains to be done.
+
+	Returns a reference to a decoded pixmap that satisfies the
+	requirements of the request.
+*/
+typedef fz_pixmap *(fz_image_get_pixmap_fn)(fz_context *ctx, fz_image *im, fz_irect *subarea, int w, int h, int *l2factor);
+
+/*
+	fz_image_get_size_fn: Function type to get the given storage
+	size for an image.
+
+	Returns the size in bytes used for a given image.
+*/
 typedef size_t (fz_image_get_size_fn)(fz_context *, fz_image *);
 
-fz_image *fz_new_image(fz_context *ctx, int w, int h, int bpc, fz_colorspace *colorspace, int xres, int yres, int interpolate, int imagemask, float *decode, int *colorkey, fz_image *mask, int size, fz_image_get_pixmap_fn *get, fz_image_get_size_fn *get_size, fz_drop_image_fn *drop);
+/*
+	fz_new_image_of_size: Internal function to make a new fz_image structure
+	for a derived class.
+
+	w,h: Width and height of the created image.
+
+	bpc: Bits per component.
+
+	colorspace: The colorspace (determines the number of components,
+	and any color conversions required while decoding).
+
+	xres, yres: The X and Y resolutions respectively.
+
+	interpolate: 1 if interpolation should be used when decoding
+	this image, 0 otherwise.
+
+	imagemask: 1 if this is an imagemask (i.e. transparent), 0
+	otherwise.
+
+	decode: NULL, or a pointer to to a decode array. The default
+	decode array is [0 1] (repeated n times, for n color components).
+
+	colorkey: NULL, or a pointer to a colorkey array. The default
+	colorkey array is [0 255] (repeatd n times, for n color
+	components).
+
+	mask: NULL, or another image to use as a mask for this one.
+	A new reference is taken to this image. Supplying a masked
+	image as a mask to another image is illegal!
+
+	size: The size of the required allocated structure (the size of
+	the derived structure).
+
+	get: The function to be called to obtain a decoded pixmap.
+
+	get_size: The function to be called to return the storage size
+	used by this image.
+
+	drop: The function to be called to dispose of this image once
+	the last reference is dropped.
+
+	Returns a pointer to an allocated structure of the required size,
+	with the first sizeof(fz_image) bytes initialised as appropriate
+	given the supplied parameters, and the other bytes set to zero.
+*/
+fz_image *fz_new_image_of_size(fz_context *ctx, int w, int h, int bpc, fz_colorspace *colorspace, int xres, int yres, int interpolate, int imagemask, float *decode, int *colorkey, fz_image *mask, int size, fz_image_get_pixmap_fn *get, fz_image_get_size_fn *get_size, fz_drop_image_fn *drop);
+
+#define fz_new_image(CTX,W,H,B,CS,X,Y,I,IM,D,C,M,T,G,S,Z) \
+	((T*)fz_new_image_of_size(CTX,W,H,B,CS,X,Y,I,IM,D,C,M,sizeof(T),G,S,Z))
+
+/*
+	fz_new_image_from_compressed_buffer: Create an image based on
+	the data in the supplied compressed buffer.
+
+	w,h: Width and height of the created image.
+
+	bpc: Bits per component.
+
+	colorspace: The colorspace (determines the number of components,
+	and any color conversions required while decoding).
+
+	xres, yres: The X and Y resolutions respectively.
+
+	interpolate: 1 if interpolation should be used when decoding
+	this image, 0 otherwise.
+
+	imagemask: 1 if this is an imagemask (i.e. transparent), 0
+	otherwise.
+
+	decode: NULL, or a pointer to to a decode array. The default
+	decode array is [0 1] (repeated n times, for n color components).
+
+	colorkey: NULL, or a pointer to a colorkey array. The default
+	colorkey array is [0 255] (repeatd n times, for n color
+	components).
+
+	buffer: Buffer of compressed data and compression parameters.
+	Ownership of this reference is passed in.
+
+	mask: NULL, or another image to use as a mask for this one.
+	A new reference is taken to this image. Supplying a masked
+	image as a mask to another image is illegal!
+*/
 fz_image *fz_new_image_from_compressed_buffer(fz_context *ctx, int w, int h, int bpc, fz_colorspace *colorspace, int xres, int yres, int interpolate, int imagemask, float *decode, int *colorkey, fz_compressed_buffer *buffer, fz_image *mask);
+
+/*
+	fz_new_image_from_pixmap: Create an image from the given
+	pixmap.
+
+	pixmap: The pixmap to base the image upon. A new reference
+	to this is taken.
+
+	mask: NULL, or another image to use as a mask for this one.
+	A new reference is taken to this image. Supplying a masked
+	image as a mask to another image is illegal!
+*/
 fz_image *fz_new_image_from_pixmap(fz_context *ctx, fz_pixmap *pixmap, fz_image *mask);
+
+/*
+	fz_new_image_from_buffer: Create a new image from a
+	buffer of data, inferring its type from the format
+	of the data.
+*/
 fz_image *fz_new_image_from_buffer(fz_context *ctx, fz_buffer *buffer);
+
+/*
+	fz_image_from_file: Create a new image from the contents
+	of a file, inferring its type from the format of the
+	data.
+*/
 fz_image *fz_new_image_from_file(fz_context *ctx, const char *path);
+
 void fz_drop_image_imp(fz_context *ctx, fz_storable *image);
 fz_pixmap *fz_decomp_image_from_stream(fz_context *ctx, fz_stream *stm, fz_compressed_image *image, fz_irect *subarea, int indexed, int l2factor);
 fz_pixmap *fz_expand_indexed_pixmap(fz_context *ctx, const fz_pixmap *src, int alpha);
@@ -134,13 +277,44 @@ void fz_load_pnm_info(fz_context *ctx, unsigned char *data, size_t size, int *w,
 int fz_load_tiff_subimage_count(fz_context *ctx, unsigned char *buf, size_t len);
 fz_pixmap *fz_load_tiff_subimage(fz_context *ctx, unsigned char *buf, size_t len, int subimage);
 
+/*
+	fz_image_resolution: Request the natural resolution
+	of an image.
+
+	xres, yres: Pointers to ints to be updated with the
+	natural resolution of an image (or a sensible default
+	if not encoded).
+*/
 void fz_image_resolution(fz_image *image, int *xres, int *yres);
 
 fz_pixmap *fz_compressed_image_tile(fz_context *ctx, fz_compressed_image *cimg);
 void fz_set_compressed_image_tile(fz_context *ctx, fz_compressed_image *cimg, fz_pixmap *pix);
+
+/*
+	fz_compressed_image_buffer: Retrieve the underlying compressed
+	data for an image.
+
+	Returns a pointer to the underlying data buffer for an image,
+	or NULL if this image is not based upon a compressed data
+	buffer.
+
+	This is not a reference counted structure, so no reference is
+	returned. Lifespan is limited to that of the image itself.
+*/
 fz_compressed_buffer *fz_compressed_image_buffer(fz_context *ctx, fz_image *image);
 void fz_set_compressed_image_buffer(fz_context *ctx, fz_compressed_image *cimg, fz_compressed_buffer *buf);
 
+/*
+	fz_pixmap_image_tile: Retried the underlying fz_pixmap
+	for an image.
+
+	Returns a pointer to the underlying fz_pixmap for an image,
+	or NULL if this image is not based upon an fz_pixmap.
+
+	No reference is returned. Lifespan is limited to that of
+	the image itself. If required, use fz_keep_pixmap to take
+	a reference to keep it longer.
+*/
 fz_pixmap *fz_pixmap_image_tile(fz_context *ctx, fz_pixmap_image *cimg);
 void fz_set_pixmap_image_tile(fz_context *ctx, fz_pixmap_image *cimg, fz_pixmap *pix);