More API tidying.

Make fz_clone_context copy existing AA settings.

Add accessor function for fz_bitmap.

Add more documentation for various functions/types.

8 files changed, 248 insertions, 61 deletions

diff --git a/apps/mudraw.c b/apps/mudraw.c
index 7c79b2fa..51a48539 100644
--- a/apps/mudraw.c
+++ b/apps/mudraw.c
@@ -251,7 +251,7 @@ static void drawpage(fz_context *ctx, fz_document *doc, int pagenum)
 				unsigned char digest[16];
 				int i;
 
-				fz_md5_pixmap(digest, pix);
+				fz_md5_pixmap(pix, digest);
 				printf(" ");
 				for (i = 0; i < 16; i++)
 					printf("%02x", digest[i]);
diff --git a/draw/draw_edge.c b/draw/draw_edge.c
index 74cd3aec..fa192bb8 100644
--- a/draw/draw_edge.c
+++ b/draw/draw_edge.c
@@ -41,6 +41,12 @@ void fz_new_aa_context(fz_context *ctx)
 #endif
 }
 
+void fz_copy_aa_context(fz_context *dst, fz_context *src)
+{
+	if (dst && src)
+		memcpy(dst, src, sizeof(*src));
+}
+
 void fz_free_aa_context(fz_context *ctx)
 {
 #ifndef AA_BITS
diff --git a/fitz/base_context.c b/fitz/base_context.c
index 7e3c0bdd..075a3d02 100644
--- a/fitz/base_context.c
+++ b/fitz/base_context.c
@@ -122,6 +122,8 @@ fz_clone_context_internal(fz_context *ctx)
 	if (ctx == NULL || ctx->alloc == NULL)
 		return NULL;
 	new_ctx = new_context_phase1(ctx->alloc, ctx->locks);
+	/* Inherit AA defaults from old context. */
+	fz_copy_aa_context(new_ctx, ctx);
 	new_ctx->store = fz_keep_store_context(ctx);
 	new_ctx->glyph_cache = fz_keep_glyph_cache(ctx);
 	new_ctx->font = fz_keep_font_context(ctx);
diff --git a/fitz/fitz-internal.h b/fitz/fitz-internal.h
index 04ce19e5..4c41564b 100644
--- a/fitz/fitz-internal.h
+++ b/fitz/fitz-internal.h
@@ -14,6 +14,7 @@ fz_context *fz_clone_context_internal(fz_context *ctx);
 
 void fz_new_aa_context(fz_context *ctx);
 void fz_free_aa_context(fz_context *ctx);
+void fz_copy_aa_context(fz_context *dst, fz_context *src);
 
 /* Default locks */
 extern fz_locks_context fz_locks_default;
@@ -510,15 +511,32 @@ enum { FZ_MAX_COLORS = 32 };
 int fz_find_blendmode(char *name);
 char *fz_blendmode_name(int blendmode);
 
+struct fz_bitmap_s
+{
+	int refs;
+	int w, h, stride, n;
+	unsigned char *samples;
+};
+
+fz_bitmap *fz_new_bitmap(fz_context *ctx, int w, int h, int n);
+
+void fz_bitmap_details(fz_bitmap *bitmap, int *w, int *h, int *n, int *stride);
+
+void fz_clear_bitmap(fz_context *ctx, fz_bitmap *bit);
+
 /*
-	fz_pixmap is an image XXX
+	Pixmaps represent a set of pixels for a 2 dimensional region of a
+	plane. Each pixel has n components per pixel, the last of which is
+	always alpha. The data is in premultiplied alpha when rendering, but
+	non-premultiplied for colorspace conversions and rescaling.
 
-	x, y: XXX
+	x, y: The minimum x and y coord of the region in pixels.
 
-	w, h: The width and height of the image in pixels.
+	w, h: The width and height of the region in pixels.
 
 	n: The number of color components in the image. Always
-	includes a separate alpha channel. XXX RGBA=4
+	includes a separate alpha channel. For mask images n=1, for greyscale
+	(plus alpha) images n=2, for rgb (plus alpha) images n=3.
 
 	interpolate: A boolean flag set to non-zero if the image
 	will be drawn using linear interpolation, or set to zero if
@@ -526,9 +544,13 @@ char *fz_blendmode_name(int blendmode);
 
 	xres, yres: Image resolution in dpi. Default is 96 dpi.
 
-	colorspace: XXX
+	colorspace: Pointer to a colorspace object describing the colorspace
+	the pixmap is in. If NULL, the image is a mask.
 
-	samples:
+	samples: A simple block of memory w * h * n bytes of memory in which
+	the components are stored. The first n bytes are components 0 to n-1
+	for the pixel at (x,y). Each successive n bytes gives another pixel
+	in scanline order. Subsequent scanlines follow on with no padding.
 
 	free_samples: Is zero when an application has provided its own
 	buffer for pixel data through fz_new_pixmap_with_rect_and_data.
@@ -546,6 +568,10 @@ struct fz_pixmap_s
 	int free_samples;
 };
 
+fz_pixmap *fz_new_pixmap_with_data(fz_context *ctx, fz_colorspace *colorspace, int w, int h, unsigned char *samples);
+
+fz_pixmap *fz_new_pixmap_with_rect_and_data(fz_context *ctx, fz_colorspace *colorspace, fz_bbox bbox, unsigned char *samples);
+
 void fz_free_pixmap_imp(fz_context *ctx, fz_storable *pix);
 
 void fz_clear_pixmap_rect_with_value(fz_context *ctx, fz_pixmap *pix, int value, fz_bbox r);
@@ -863,6 +889,8 @@ void fz_flatten_dash_path(fz_gel *gel, fz_path *path, fz_stroke_state *stroke, f
  * The device interface.
  */
 
+fz_device *fz_new_draw_device_type3(fz_context *ctx, fz_pixmap *dest);
+
 enum
 {
 	/* Hints */
diff --git a/fitz/fitz.h b/fitz/fitz.h
index 2b432e13..849b07a8 100644
--- a/fitz/fitz.h
+++ b/fitz/fitz.h
@@ -1084,19 +1084,65 @@ fz_buffer *fz_read_all(fz_stream *stm, int initial);
 */
 typedef struct fz_bitmap_s fz_bitmap;
 
-struct fz_bitmap_s
-{
-	int refs;
-	int w, h, stride, n;
-	unsigned char *samples;
-};
+/*
+	fz_keep_bitmap: Take a reference to a bitmap.
+
+	bit: The bitmap to increment the reference for.
 
-fz_bitmap *fz_new_bitmap(fz_context *ctx, int w, int h, int n);
+	Returns bit. Does not throw exceptions.
+*/
 fz_bitmap *fz_keep_bitmap(fz_context *ctx, fz_bitmap *bit);
-void fz_clear_bitmap(fz_context *ctx, fz_bitmap *bit);
+
+/*
+	fz_drop_bitmap: Drop a reference and free a bitmap.
+
+	Decrement the reference count for the bitmap. When no
+	references remain the pixmap will be freed.
+
+	Does not throw exceptions.
+*/
 void fz_drop_bitmap(fz_context *ctx, fz_bitmap *bit);
 
 /*
+	An fz_colorspace object represents an abstract colorspace. While
+	this should be treated as a black box by callers of the library at
+	this stage, know that it encapsulates knowledge of how to convert
+	colors to and from the colorspace, any lookup tables generated, the
+	number of components in the colorspace etc.
+*/
+typedef struct fz_colorspace_s fz_colorspace;
+
+/*
+	fz_find_device_colorspace: Find a standard colorspace based upon
+	it's name.
+*/
+fz_colorspace *fz_find_device_colorspace(char *name);
+
+/*
+	fz_device_gray: Abstract colorspace representing device specific
+	gray.
+*/
+extern fz_colorspace *fz_device_gray;
+
+/*
+	fz_device_rgb: Abstract colorspace representing device specific
+	rgb.
+*/
+extern fz_colorspace *fz_device_rgb;
+
+/*
+	fz_device_bgr: Abstract colorspace representing device specific
+	bgr.
+*/
+extern fz_colorspace *fz_device_bgr;
+
+/*
+	fz_device_cmyk: Abstract colorspace representing device specific
+	CMYK.
+*/
+extern fz_colorspace *fz_device_cmyk;
+
+/*
 	Pixmaps represent a set of pixels for a 2 dimensional region of a
 	plane. Each pixel has n components per pixel, the last of which is
 	always alpha. The data is in premultiplied alpha when rendering, but
@@ -1104,11 +1150,27 @@ void fz_drop_bitmap(fz_context *ctx, fz_bitmap *bit);
 */
 typedef struct fz_pixmap_s fz_pixmap;
 
-typedef struct fz_colorspace_s fz_colorspace;
+/*
+	fz_bound_pixmap: Return a bounding box for a pixmap.
 
+	Returns an exact bounding box for the supplied pixmap.
+*/
 fz_bbox fz_bound_pixmap(fz_pixmap *pix);
 
-fz_pixmap *fz_new_pixmap(fz_context *ctx, fz_colorspace *, int w, int h);
+/*
+	fz_new_pixmap: Create a new pixmap, with it's origin at (0,0)
+
+	cs: The colorspace to use for the pixmap, or NULL for an alpha
+	plane/mask.
+
+	w: The width of the pixmap (in pixels)
+
+	h: The height of the pixmap (in pixels)
+
+	Returns a pointer to the new pixmap. Throws exception on failure to
+	allocate.
+*/
+fz_pixmap *fz_new_pixmap(fz_context *ctx, fz_colorspace *cs, int w, int h);
 
 /*
 	fz_new_pixmap_with_rect: Create a pixmap of a given size,
@@ -1126,17 +1188,6 @@ fz_pixmap *fz_new_pixmap(fz_context *ctx, fz_colorspace *, int w, int h);
 */
 fz_pixmap *fz_new_pixmap_with_rect(fz_context *ctx, fz_colorspace *colorspace, fz_bbox bbox);
 
-fz_pixmap *fz_new_pixmap_with_data(fz_context *ctx, fz_colorspace *colorspace, int w, int h, unsigned char *samples);
-
-/*
-	fz_keep_pixmap: Take a reference to a pixmap.
-
-	pix: The pixmap to increment the reference for.
-
-	Returns pix. Does not throw exceptions.
-*/
-fz_pixmap *fz_new_pixmap_with_rect_and_data(fz_context *ctx, fz_colorspace *colorspace, fz_bbox bbox, unsigned char *samples);
-
 /*
 	fz_keep_pixmap: Take a reference to a pixmap.
 
@@ -1178,9 +1229,9 @@ int fz_pixmap_components(fz_context *ctx, fz_pixmap *pix);
 unsigned char *fz_pixmap_pixels(fz_context *ctx, fz_pixmap *pix);
 
 /*
-	fz_clear_pixmap_with_value: Clears a pixmap with the given value
+	fz_clear_pixmap_with_value: Clears a pixmap with the given value.
 
-	pix: Pixmap obtained from fz_new_pixmap*.
+	pix: The pixmap to clear.
 
 	value: Values in the range 0 to 255 are valid. Each component
 	sample for each pixel in the pixmap will be set to this value,
@@ -1190,17 +1241,106 @@ unsigned char *fz_pixmap_pixels(fz_context *ctx, fz_pixmap *pix);
 */
 void fz_clear_pixmap_with_value(fz_context *ctx, fz_pixmap *pix, int value);
 
+/*
+	fz_clear_pixmap_with_value: Sets all components (including alpha) of
+	all pixels in a pixmap to 0.
+
+	pix: The pixmap to clear.
+
+	Does not throw exceptions.
+*/
 void fz_clear_pixmap(fz_context *ctx, fz_pixmap *pix);
+
+/*
+	fz_invert_pixmap: Invert all the pixels in a pixmap. All components
+	of all pixels are inverted (except alpha, which is unchanged).
+
+	Does not throw exceptions.
+*/
 void fz_invert_pixmap(fz_context *ctx, fz_pixmap *pix);
+
+/*
+	fz_invert_pixmap: Invert all the pixels in a given rectangle of a
+	pixmap. All components of all pixels in the rectangle are inverted
+	(except alpha, which is unchanged).
+
+	Does not throw exceptions.
+*/
 void fz_invert_pixmap_rect(fz_pixmap *image, fz_bbox rect);
+
+/*
+	fz_gamma_pixmap: Apply gamma correction to a pixmap. All components
+	of all pixels are modified (except alpha, which is unchanged).
+
+	gamma: The gamma value to apply; 1.0 for no change.
+
+	Does not throw exceptions.
+*/
 void fz_gamma_pixmap(fz_context *ctx, fz_pixmap *pix, float gamma);
+
+/*
+	fz_unmultiply_pixmap: Convert a pixmap from premultiplied to
+	non-premultiplied format.
+
+	Does not throw exceptions.
+*/
 void fz_unmultiply_pixmap(fz_context *ctx, fz_pixmap *pix);
+
+/*
+	fz_convert_pixmap: Convert from one pixmap to another (assumed to be
+	the same size, but possibly with a different colorspace).
+
+	src: the source pixmap.
+
+	dst: the destination pixmap.
+*/
+void fz_convert_pixmap(fz_context *ctx, fz_pixmap *src, fz_pixmap *dst);
+
+/*
+	fz_save_pixmap: Save a pixmap out.
+
+	name: The prefix for the name of the pixmap. The pixmap will be saved
+	as "name.png" if the pixmap is RGB or Greyscale, "name.pam" otherwise.
+
+	rgb: If non zero, the pixmap is converted to rgb (if possible) before
+	saving.
+*/
 void fz_save_pixmap(fz_context *ctx, fz_pixmap *img, char *name, int rgb);
+
+/*
+	fz_write_pnm: Save a pixmap as a pnm
+
+	filename: The filename to save as (including extension).
+*/
 void fz_write_pnm(fz_context *ctx, fz_pixmap *pixmap, char *filename);
+
+/*
+	fz_write_pam: Save a pixmap as a pam
+
+	filename: The filename to save as (including extension).
+*/
 void fz_write_pam(fz_context *ctx, fz_pixmap *pixmap, char *filename, int savealpha);
+
+/*
+	fz_write_png: Save a pixmap as a png
+
+	filename: The filename to save as (including extension).
+*/
 void fz_write_png(fz_context *ctx, fz_pixmap *pixmap, char *filename, int savealpha);
+
+/*
+	fz_write_pbm: Save a bitmap as a pbm
+
+	filename: The filename to save as (including extension).
+*/
 void fz_write_pbm(fz_context *ctx, fz_bitmap *bitmap, char *filename);
-void fz_md5_pixmap(unsigned char digest[16], fz_pixmap *pixmap);
+
+/*
+	fz_md5_pixmap: Return the md5 digest for a pixmap
+
+	filename: The filename to save as (including extension).
+*/
+void fz_md5_pixmap(fz_pixmap *pixmap, unsigned char digest[16]);
 
 /*
 	Images are storable objects from which we can obtain fz_pixmaps.
@@ -1266,37 +1406,24 @@ typedef struct fz_halftone_s fz_halftone;
 fz_bitmap *fz_halftone_pixmap(fz_context *ctx, fz_pixmap *pix, fz_halftone *ht);
 
 /*
-	Colorspace resources.
-*/
-
-void fz_convert_pixmap(fz_context *ctx, fz_pixmap *src, fz_pixmap *dst);
-
-fz_colorspace *fz_find_device_colorspace(char *name);
-
-/*
-	fz_device_gray: XXX
+	An abstract font handle. Currently there are no public API functions
+	for handling these.
 */
-extern fz_colorspace *fz_device_gray;
-
-/*
-	fz_device_rgb: XXX
-*/
-extern fz_colorspace *fz_device_rgb;
-
-/*
-	fz_device_bgr: XXX
-*/
-extern fz_colorspace *fz_device_bgr;
+typedef struct fz_font_s fz_font;
 
 /*
-	fz_device_cmyk: XXX
+	The different format handlers (pdf, xps etc) interpret pages to a
+	device. These devices can then process the stream of calls they
+	recieve in various ways:
+		The trace device outputs debugging information for the calls.
+		The draw device will render them.
+		The list device stores them in a list to play back later.
+		The text device performs text extraction and searching.
+		The bbox device calculates the bounding box for the page.
+	Other devices can (and will) be written in future.
 */
-extern fz_colorspace *fz_device_cmyk;
-
 typedef struct fz_device_s fz_device;
 
-typedef struct fz_font_s fz_font;
-
 /*
 	fz_free_device: Free a devices of any type and its resources.
 */
@@ -1305,8 +1432,6 @@ void fz_free_device(fz_device *dev);
 /*
 	fz_new_trace_device: Create a device to print a debug trace of
 	all device calls.
-
-	XXX
 */
 fz_device *fz_new_trace_device(fz_context *ctx);
 
@@ -1330,8 +1455,6 @@ fz_device *fz_new_bbox_device(fz_context *ctx, fz_bbox *bboxp);
 */
 fz_device *fz_new_draw_device(fz_context *ctx, fz_pixmap *dest);
 
-fz_device *fz_new_draw_device_type3(fz_context *ctx, fz_pixmap *dest);
-
 /*
 	Text extraction device
 */
diff --git a/fitz/image_md5.c b/fitz/image_md5.c
index c82c7066..86ba0a12 100644
--- a/fitz/image_md5.c
+++ b/fitz/image_md5.c
@@ -1,6 +1,6 @@
 #include "fitz-internal.h"
 
-void fz_md5_pixmap(unsigned char digest[16], fz_pixmap *pix)
+void fz_md5_pixmap(fz_pixmap *pix, unsigned char digest[16])
 {
 	fz_md5 md5;
 
diff --git a/fitz/res_bitmap.c b/fitz/res_bitmap.c
index 62cdd8ca..25e88187 100644
--- a/fitz/res_bitmap.c
+++ b/fitz/res_bitmap.c
@@ -95,3 +95,27 @@ unsigned char *fz_pixmap_pixels(fz_context *ctx, fz_pixmap *pix)
 		return NULL;
 	return pix->samples;
 }
+
+void fz_bitmap_details(fz_bitmap *bit, int *w, int *h, int *n, int *stride)
+{
+	if (!bit)
+	{
+		if (w)
+			*w = 0;
+		if (h)
+			*h = 0;
+		if (n)
+			*n = 0;
+		if (stride)
+			*stride = 0;
+		return;
+	}
+	if (w)
+		*w = bit->w;
+	if (h)
+		*h = bit->h;
+	if (n)
+		*n = bit->n;
+	if (stride)
+		*w = bit->stride;
+}
diff --git a/scripts/cmapdump.c b/scripts/cmapdump.c
index 3e1230ad..53247339 100644
--- a/scripts/cmapdump.c
+++ b/scripts/cmapdump.c
@@ -181,6 +181,10 @@ void fz_free_aa_context(fz_context *ctx)
 {
 }
 
+void fz_copy_aa_context(fz_context *dst, fz_context *src)
+{
+}
+
 void *fz_keep_storable(fz_context *ctx, fz_storable *s)
 {
 	return s;