init commit

2026-02-10 14:45:18 +08:00
parent a530a79566
commit 5ce88674da
142 changed files with 12394 additions and 4280 deletions
--- a/include/mupdf/fitz/device.h
+++ b/include/mupdf/fitz/device.h
@@ -1,19 +1,40 @@
+// Copyright (C) 2004-2023 Artifex Software, Inc.
+//
+// This file is part of MuPDF.
+//
+// MuPDF is free software: you can redistribute it and/or modify it under the
+// terms of the GNU Affero General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option)
+// any later version.
+//
+// MuPDF is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+// FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+// details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with MuPDF. If not, see <https://www.gnu.org/licenses/agpl-3.0.en.html>
+//
+// Alternative licensing terms are available from the licensor.
+// For commercial licensing, see <https://www.artifex.com/> or contact
+// Artifex Software, Inc., 39 Mesa Street, Suite 108A, San Francisco,
+// CA 94129, USA, for further information.
+
 #ifndef MUPDF_FITZ_DEVICE_H
 #define MUPDF_FITZ_DEVICE_H

 #include "mupdf/fitz/system.h"
 #include "mupdf/fitz/context.h"
 #include "mupdf/fitz/geometry.h"
-#include "mupdf/fitz/colorspace.h"
 #include "mupdf/fitz/image.h"
 #include "mupdf/fitz/shade.h"
 #include "mupdf/fitz/path.h"
 #include "mupdf/fitz/text.h"

-/*
-	The different format handlers (pdf, xps etc) interpret pages to a
-	device. These devices can then process the stream of calls they
-	receive in various ways:
+/**
+	The different format handlers (pdf, xps etc) interpret pages to
+	a device. These devices can then process the stream of calls
+	they receive 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.
@@ -21,7 +42,7 @@
 		The bbox device calculates the bounding box for the page.
 	Other devices can (and will) be written in the future.
 */
-typedef struct fz_device_s fz_device;
+typedef struct fz_device fz_device;

 enum
 {
@@ -37,9 +58,10 @@ enum
 	FZ_DEVFLAG_LINEJOIN_UNDEFINED = 256,
 	FZ_DEVFLAG_MITERLIMIT_UNDEFINED = 512,
 	FZ_DEVFLAG_LINEWIDTH_UNDEFINED = 1024,
-	/* Arguably we should have a bit for the dash pattern itself being
-	 * undefined, but that causes problems; do we assume that it should
-	 * always be set to non-dashing at the start of every glyph? */
+	/* Arguably we should have a bit for the dash pattern itself
+	 * being undefined, but that causes problems; do we assume that
+	 * it should always be set to non-dashing at the start of every
+	 * glyph? */
 	FZ_DEVFLAG_BBOX_DEFINED = 2048,
 	FZ_DEVFLAG_GRIDFIT_AS_TILED = 4096,
 };
@@ -72,12 +94,201 @@ enum
 	FZ_BLEND_KNOCKOUT = 32
 };

+/**
+	Map from (case sensitive) blend mode string to enumeration.
+*/
 int fz_lookup_blendmode(const char *name);
-char *fz_blendmode_name(int blendmode);

-typedef struct fz_device_container_stack_s fz_device_container_stack;
+/**
+	Map from enumeration to blend mode string.

-struct fz_device_s
+	The string is static, with arbitrary lifespan.
+*/
+const char *fz_blendmode_name(int blendmode);
+
+/*
+	Generic function type.
+
+	Different function implementations will derive from this.
+*/
+typedef struct fz_function fz_function;
+
+typedef void (fz_function_eval_fn)(fz_context *, fz_function *, const float *, float *);
+
+enum
+{
+	FZ_FUNCTION_MAX_N = FZ_MAX_COLORS,
+	FZ_FUNCTION_MAX_M = FZ_MAX_COLORS
+};
+
+struct fz_function
+{
+	fz_storable storable;
+	size_t size;
+	int m;					/* number of input values */
+	int n;					/* number of output values */
+
+	fz_function_eval_fn *eval;
+};
+
+fz_function *fz_new_function_of_size(fz_context *ctx, int size, size_t size2, int m, int n, fz_function_eval_fn *eval, fz_store_drop_fn *drop);
+
+#define fz_new_derived_function(CTX,TYPE,SIZE,M,N,EVAL,DROP) \
+	((TYPE*)Memento_label(fz_new_function_of_size(CTX,sizeof(TYPE),SIZE,M,N,EVAL,DROP), #TYPE))
+
+/*
+	Evaluate a function.
+
+	Input vector = (in[0], ..., in[inlen-1])
+	Output vector = (out[0], ..., out[outlen-1])
+
+	If inlen or outlen do not match that expected by the function, this
+	routine will truncate or extend the input/output (with 0's) as
+	required.
+*/
+void fz_eval_function(fz_context *ctx, fz_function *func, const float *in, int inlen, float *out, int outlen);
+
+/*
+	Keep a function reference.
+*/
+fz_function *fz_keep_function(fz_context *ctx, fz_function *func);
+
+/*
+	Drop a function reference.
+*/
+void fz_drop_function(fz_context *ctx, fz_function *func);
+
+/*
+	Function size
+*/
+size_t fz_function_size(fz_context *ctx, fz_function *func);
+
+/**
+	The device structure is public to allow devices to be
+	implemented outside of fitz.
+
+	Device methods should always be called using e.g.
+	fz_fill_path(ctx, dev, ...) rather than
+	dev->fill_path(ctx, dev, ...)
+*/
+
+/**
+	Devices can keep track of containers (clips/masks/groups/tiles)
+	as they go to save callers having to do it.
+*/
+typedef struct
+{
+	fz_rect scissor;
+	int type;
+	int user;
+} fz_device_container_stack;
+
+enum
+{
+	fz_device_container_stack_is_clip,
+	fz_device_container_stack_is_mask,
+	fz_device_container_stack_is_group,
+	fz_device_container_stack_is_tile,
+};
+
+/* Structure types */
+typedef enum
+{
+	FZ_STRUCTURE_INVALID = -1,
+
+	/* Grouping elements (PDF 1.7 - Table 10.20) */
+	FZ_STRUCTURE_DOCUMENT,
+	FZ_STRUCTURE_PART,
+	FZ_STRUCTURE_ART,
+	FZ_STRUCTURE_SECT,
+	FZ_STRUCTURE_DIV,
+	FZ_STRUCTURE_BLOCKQUOTE,
+	FZ_STRUCTURE_CAPTION,
+	FZ_STRUCTURE_TOC,
+	FZ_STRUCTURE_TOCI,
+	FZ_STRUCTURE_INDEX,
+	FZ_STRUCTURE_NONSTRUCT,
+	FZ_STRUCTURE_PRIVATE,
+	/* Grouping elements (PDF 2.0 - Table 364) */
+	FZ_STRUCTURE_DOCUMENTFRAGMENT,
+	/* Grouping elements (PDF 2.0 - Table 365) */
+	FZ_STRUCTURE_ASIDE,
+	/* Grouping elements (PDF 2.0 - Table 366) */
+	FZ_STRUCTURE_TITLE,
+	FZ_STRUCTURE_FENOTE,
+	/* Grouping elements (PDF 2.0 - Table 367) */
+	FZ_STRUCTURE_SUB,
+
+	/* Paragraphlike elements (PDF 1.7 - Table 10.21) */
+	FZ_STRUCTURE_P,
+	FZ_STRUCTURE_H,
+	FZ_STRUCTURE_H1,
+	FZ_STRUCTURE_H2,
+	FZ_STRUCTURE_H3,
+	FZ_STRUCTURE_H4,
+	FZ_STRUCTURE_H5,
+	FZ_STRUCTURE_H6,
+
+	/* List elements (PDF 1.7 - Table 10.23) */
+	FZ_STRUCTURE_LIST,
+	FZ_STRUCTURE_LISTITEM,
+	FZ_STRUCTURE_LABEL,
+	FZ_STRUCTURE_LISTBODY,
+
+	/* Table elements (PDF 1.7 - Table 10.24) */
+	FZ_STRUCTURE_TABLE,
+	FZ_STRUCTURE_TR,
+	FZ_STRUCTURE_TH,
+	FZ_STRUCTURE_TD,
+	FZ_STRUCTURE_THEAD,
+	FZ_STRUCTURE_TBODY,
+	FZ_STRUCTURE_TFOOT,
+
+	/* Inline elements (PDF 1.7 - Table 10.25) */
+	FZ_STRUCTURE_SPAN,
+	FZ_STRUCTURE_QUOTE,
+	FZ_STRUCTURE_NOTE,
+	FZ_STRUCTURE_REFERENCE,
+	FZ_STRUCTURE_BIBENTRY,
+	FZ_STRUCTURE_CODE,
+	FZ_STRUCTURE_LINK,
+	FZ_STRUCTURE_ANNOT,
+	/* Inline elements (PDF 2.0 - Table 368) */
+	FZ_STRUCTURE_EM,
+	FZ_STRUCTURE_STRONG,
+
+	/* Ruby inline element (PDF 1.7 - Table 10.26) */
+	FZ_STRUCTURE_RUBY,
+	FZ_STRUCTURE_RB,
+	FZ_STRUCTURE_RT,
+	FZ_STRUCTURE_RP,
+
+	/* Warichu inline element (PDF 1.7 - Table 10.26) */
+	FZ_STRUCTURE_WARICHU,
+	FZ_STRUCTURE_WT,
+	FZ_STRUCTURE_WP,
+
+	/* Illustration elements (PDF 1.7 - Table 10.27) */
+	FZ_STRUCTURE_FIGURE,
+	FZ_STRUCTURE_FORMULA,
+	FZ_STRUCTURE_FORM,
+
+	/* Artifact structure type (PDF 2.0 - Table 375) */
+	FZ_STRUCTURE_ARTIFACT
+} fz_structure;
+
+const char *fz_structure_to_string(fz_structure type);
+fz_structure fz_structure_from_string(const char *str);
+
+typedef enum
+{
+	FZ_METATEXT_ACTUALTEXT,
+	FZ_METATEXT_ALT,
+	FZ_METATEXT_ABBREVIATION,
+	FZ_METATEXT_TITLE
+} fz_metatext;
+
+struct fz_device
 {
 	int refs;
 	int hints;
@@ -86,30 +297,30 @@ struct fz_device_s
 	void (*close_device)(fz_context *, fz_device *);
 	void (*drop_device)(fz_context *, fz_device *);

-	void (*fill_path)(fz_context *, fz_device *, const fz_path *, int even_odd, const fz_matrix *, fz_colorspace *, const float *color, float alpha, const fz_color_params *);
-	void (*stroke_path)(fz_context *, fz_device *, const fz_path *, const fz_stroke_state *, const fz_matrix *, fz_colorspace *, const float *color, float alpha, const fz_color_params *);
-	void (*clip_path)(fz_context *, fz_device *, const fz_path *, int even_odd, const fz_matrix *, const fz_rect *scissor);
-	void (*clip_stroke_path)(fz_context *, fz_device *, const fz_path *, const fz_stroke_state *, const fz_matrix *, const fz_rect *scissor);
+	void (*fill_path)(fz_context *, fz_device *, const fz_path *, int even_odd, fz_matrix, fz_colorspace *, const float *color, float alpha, fz_color_params );
+	void (*stroke_path)(fz_context *, fz_device *, const fz_path *, const fz_stroke_state *, fz_matrix, fz_colorspace *, const float *color, float alpha, fz_color_params );
+	void (*clip_path)(fz_context *, fz_device *, const fz_path *, int even_odd, fz_matrix, fz_rect scissor);
+	void (*clip_stroke_path)(fz_context *, fz_device *, const fz_path *, const fz_stroke_state *, fz_matrix, fz_rect scissor);

-	void (*fill_text)(fz_context *, fz_device *, const fz_text *, const fz_matrix *, fz_colorspace *, const float *color, float alpha, const fz_color_params *);
-	void (*stroke_text)(fz_context *, fz_device *, const fz_text *, const fz_stroke_state *, const fz_matrix *, fz_colorspace *, const float *color, float alpha, const fz_color_params *);
-	void (*clip_text)(fz_context *, fz_device *, const fz_text *, const fz_matrix *, const fz_rect *scissor);
-	void (*clip_stroke_text)(fz_context *, fz_device *, const fz_text *, const fz_stroke_state *, const fz_matrix *, const fz_rect *scissor);
-	void (*ignore_text)(fz_context *, fz_device *, const fz_text *, const fz_matrix *);
+	void (*fill_text)(fz_context *, fz_device *, const fz_text *, fz_matrix, fz_colorspace *, const float *color, float alpha, fz_color_params );
+	void (*stroke_text)(fz_context *, fz_device *, const fz_text *, const fz_stroke_state *, fz_matrix, fz_colorspace *, const float *color, float alpha, fz_color_params );
+	void (*clip_text)(fz_context *, fz_device *, const fz_text *, fz_matrix, fz_rect scissor);
+	void (*clip_stroke_text)(fz_context *, fz_device *, const fz_text *, const fz_stroke_state *, fz_matrix, fz_rect scissor);
+	void (*ignore_text)(fz_context *, fz_device *, const fz_text *, fz_matrix );

-	void (*fill_shade)(fz_context *, fz_device *, fz_shade *shd, const fz_matrix *ctm, float alpha, const fz_color_params *color_params);
-	void (*fill_image)(fz_context *, fz_device *, fz_image *img, const fz_matrix *ctm, float alpha, const fz_color_params *color_params);
-	void (*fill_image_mask)(fz_context *, fz_device *, fz_image *img, const fz_matrix *ctm, fz_colorspace *, const float *color, float alpha, const fz_color_params *color_params);
-	void (*clip_image_mask)(fz_context *, fz_device *, fz_image *img, const fz_matrix *ctm, const fz_rect *scissor);
+	void (*fill_shade)(fz_context *, fz_device *, fz_shade *shd, fz_matrix ctm, float alpha, fz_color_params color_params);
+	void (*fill_image)(fz_context *, fz_device *, fz_image *img, fz_matrix ctm, float alpha, fz_color_params color_params);
+	void (*fill_image_mask)(fz_context *, fz_device *, fz_image *img, fz_matrix ctm, fz_colorspace *, const float *color, float alpha, fz_color_params color_params);
+	void (*clip_image_mask)(fz_context *, fz_device *, fz_image *img, fz_matrix ctm, fz_rect scissor);

 	void (*pop_clip)(fz_context *, fz_device *);

-	void (*begin_mask)(fz_context *, fz_device *, const fz_rect *, int luminosity, fz_colorspace *, const float *bc, const fz_color_params *);
-	void (*end_mask)(fz_context *, fz_device *);
-	void (*begin_group)(fz_context *, fz_device *, const fz_rect *, fz_colorspace *cs, int isolated, int knockout, int blendmode, float alpha);
+	void (*begin_mask)(fz_context *, fz_device *, fz_rect area, int luminosity, fz_colorspace *, const float *bc, fz_color_params );
+	void (*end_mask)(fz_context *, fz_device *, fz_function *fn);
+	void (*begin_group)(fz_context *, fz_device *, fz_rect area, fz_colorspace *cs, int isolated, int knockout, int blendmode, float alpha);
 	void (*end_group)(fz_context *, fz_device *);

-	int (*begin_tile)(fz_context *, fz_device *, const fz_rect *area, const fz_rect *view, float xstep, float ystep, const fz_matrix *ctm, int id);
+	int (*begin_tile)(fz_context *, fz_device *, fz_rect area, fz_rect view, float xstep, float ystep, fz_matrix ctm, int id);
 	void (*end_tile)(fz_context *, fz_device *);

 	void (*render_flags)(fz_context *, fz_device *, int set, int clear);
@@ -118,95 +329,117 @@ struct fz_device_s
 	void (*begin_layer)(fz_context *, fz_device *, const char *layer_name);
 	void (*end_layer)(fz_context *, fz_device *);

-	fz_rect d1_rect;
+	void (*begin_structure)(fz_context *, fz_device *, fz_structure standard, const char *raw, int idx);
+	void (*end_structure)(fz_context *, fz_device *);

-	int error_depth;
-	char errmess[256];
+	void (*begin_metatext)(fz_context *, fz_device *, fz_metatext meta, const char *text);
+	void (*end_metatext)(fz_context *, fz_device *);
+
+	fz_rect d1_rect;

 	int container_len;
 	int container_cap;
 	fz_device_container_stack *container;
 };

-void fz_fill_path(fz_context *ctx, fz_device *dev, const fz_path *path, int even_odd, const fz_matrix *ctm, fz_colorspace *colorspace, const float *color, float alpha, const fz_color_params *color_params);
-void fz_stroke_path(fz_context *ctx, fz_device *dev, const fz_path *path, const fz_stroke_state *stroke, const fz_matrix *ctm, fz_colorspace *colorspace, const float *color, float alpha, const fz_color_params *color_params);
-void fz_clip_path(fz_context *ctx, fz_device *dev, const fz_path *path, int even_odd, const fz_matrix *ctm, const fz_rect *scissor);
-void fz_clip_stroke_path(fz_context *ctx, fz_device *dev, const fz_path *path, const fz_stroke_state *stroke, const fz_matrix *ctm, const fz_rect *scissor);
-void fz_fill_text(fz_context *ctx, fz_device *dev, const fz_text *text, const fz_matrix *ctm, fz_colorspace *colorspace, const float *color, float alpha, const fz_color_params *color_params);
-void fz_stroke_text(fz_context *ctx, fz_device *dev, const fz_text *text, const fz_stroke_state *stroke, const fz_matrix *ctm, fz_colorspace *colorspace, const float *color, float alpha, const fz_color_params *color_params);
-void fz_clip_text(fz_context *ctx, fz_device *dev, const fz_text *text, const fz_matrix *ctm, const fz_rect *scissor);
-void fz_clip_stroke_text(fz_context *ctx, fz_device *dev, const fz_text *text, const fz_stroke_state *stroke, const fz_matrix *ctm, const fz_rect *scissor);
-void fz_ignore_text(fz_context *ctx, fz_device *dev, const fz_text *text, const fz_matrix *ctm);
+/**
+	Device calls; graphics primitives and containers.
+*/
+void fz_fill_path(fz_context *ctx, fz_device *dev, const fz_path *path, int even_odd, fz_matrix ctm, fz_colorspace *colorspace, const float *color, float alpha, fz_color_params color_params);
+void fz_stroke_path(fz_context *ctx, fz_device *dev, const fz_path *path, const fz_stroke_state *stroke, fz_matrix ctm, fz_colorspace *colorspace, const float *color, float alpha, fz_color_params color_params);
+void fz_clip_path(fz_context *ctx, fz_device *dev, const fz_path *path, int even_odd, fz_matrix ctm, fz_rect scissor);
+void fz_clip_stroke_path(fz_context *ctx, fz_device *dev, const fz_path *path, const fz_stroke_state *stroke, fz_matrix ctm, fz_rect scissor);
+void fz_fill_text(fz_context *ctx, fz_device *dev, const fz_text *text, fz_matrix ctm, fz_colorspace *colorspace, const float *color, float alpha, fz_color_params color_params);
+void fz_stroke_text(fz_context *ctx, fz_device *dev, const fz_text *text, const fz_stroke_state *stroke, fz_matrix ctm, fz_colorspace *colorspace, const float *color, float alpha, fz_color_params color_params);
+void fz_clip_text(fz_context *ctx, fz_device *dev, const fz_text *text, fz_matrix ctm, fz_rect scissor);
+void fz_clip_stroke_text(fz_context *ctx, fz_device *dev, const fz_text *text, const fz_stroke_state *stroke, fz_matrix ctm, fz_rect scissor);
+void fz_ignore_text(fz_context *ctx, fz_device *dev, const fz_text *text, fz_matrix ctm);
 void fz_pop_clip(fz_context *ctx, fz_device *dev);
-void fz_fill_shade(fz_context *ctx, fz_device *dev, fz_shade *shade, const fz_matrix *ctm, float alpha, const fz_color_params *color_params);
-void fz_fill_image(fz_context *ctx, fz_device *dev, fz_image *image, const fz_matrix *ctm, float alpha, const fz_color_params *color_params);
-void fz_fill_image_mask(fz_context *ctx, fz_device *dev, fz_image *image, const fz_matrix *ctm, fz_colorspace *colorspace, const float *color, float alpha, const fz_color_params *color_params);
-void fz_clip_image_mask(fz_context *ctx, fz_device *dev, fz_image *image, const fz_matrix *ctm, const fz_rect *scissor);
-void fz_begin_mask(fz_context *ctx, fz_device *dev, const fz_rect *area, int luminosity, fz_colorspace *colorspace, const float *bc, const fz_color_params *color_params);
+void fz_fill_shade(fz_context *ctx, fz_device *dev, fz_shade *shade, fz_matrix ctm, float alpha, fz_color_params color_params);
+void fz_fill_image(fz_context *ctx, fz_device *dev, fz_image *image, fz_matrix ctm, float alpha, fz_color_params color_params);
+void fz_fill_image_mask(fz_context *ctx, fz_device *dev, fz_image *image, fz_matrix ctm, fz_colorspace *colorspace, const float *color, float alpha, fz_color_params color_params);
+void fz_clip_image_mask(fz_context *ctx, fz_device *dev, fz_image *image, fz_matrix ctm, fz_rect scissor);
+void fz_begin_mask(fz_context *ctx, fz_device *dev, fz_rect area, int luminosity, fz_colorspace *colorspace, const float *bc, fz_color_params color_params);
 void fz_end_mask(fz_context *ctx, fz_device *dev);
-void fz_begin_group(fz_context *ctx, fz_device *dev, const fz_rect *area, fz_colorspace *cs, int isolated, int knockout, int blendmode, float alpha);
+void fz_end_mask_tr(fz_context *ctx, fz_device *dev, fz_function *fn);
+void fz_begin_group(fz_context *ctx, fz_device *dev, fz_rect area, fz_colorspace *cs, int isolated, int knockout, int blendmode, float alpha);
 void fz_end_group(fz_context *ctx, fz_device *dev);
-void fz_begin_tile(fz_context *ctx, fz_device *dev, const fz_rect *area, const fz_rect *view, float xstep, float ystep, const fz_matrix *ctm);
-int fz_begin_tile_id(fz_context *ctx, fz_device *dev, const fz_rect *area, const fz_rect *view, float xstep, float ystep, const fz_matrix *ctm, int id);
+void fz_begin_tile(fz_context *ctx, fz_device *dev, fz_rect area, fz_rect view, float xstep, float ystep, fz_matrix ctm);
+int fz_begin_tile_id(fz_context *ctx, fz_device *dev, fz_rect area, fz_rect view, float xstep, float ystep, fz_matrix ctm, int id);
 void fz_end_tile(fz_context *ctx, fz_device *dev);
 void fz_render_flags(fz_context *ctx, fz_device *dev, int set, int clear);
 void fz_set_default_colorspaces(fz_context *ctx, fz_device *dev, fz_default_colorspaces *default_cs);
 void fz_begin_layer(fz_context *ctx, fz_device *dev, const char *layer_name);
 void fz_end_layer(fz_context *ctx, fz_device *dev);
-fz_device *fz_new_device_of_size(fz_context *ctx, int size);
+void fz_begin_structure(fz_context *ctx, fz_device *dev, fz_structure standard, const char *raw, int idx);
+void fz_end_structure(fz_context *ctx, fz_device *dev);
+void fz_begin_metatext(fz_context *ctx, fz_device *dev, fz_metatext meta, const char *text);
+void fz_end_metatext(fz_context *ctx, fz_device *dev);

+/**
+	Devices are created by calls to device implementations, for
+	instance: foo_new_device(). These will be implemented by calling
+	fz_new_derived_device(ctx, foo_device) where foo_device is a
+	structure "derived from" fz_device, for instance
+	typedef struct { fz_device base;  ...extras...} foo_device;
+*/
+fz_device *fz_new_device_of_size(fz_context *ctx, int size);
 #define fz_new_derived_device(CTX, TYPE) \
 	((TYPE *)Memento_label(fz_new_device_of_size(ctx,sizeof(TYPE)),#TYPE))

-/*
-	fz_close_device: Signal the end of input, and flush any buffered output.
-	This is NOT called implicitly on fz_drop_device.
+/**
+	Signal the end of input, and flush any buffered output.
+	This is NOT called implicitly on fz_drop_device. This
+	may throw exceptions.
 */
 void fz_close_device(fz_context *ctx, fz_device *dev);

-/*
-	fz_drop_device: Free a device of any type and its resources.
+/**
+	Reduce the reference count on a device. When the reference count
+	reaches zero, the device and its resources will be freed.
 	Don't forget to call fz_close_device before dropping the device,
 	or you may get incomplete output!
+
+	Never throws exceptions.
 */
 void fz_drop_device(fz_context *ctx, fz_device *dev);

+/**
+	Increment the reference count for a device. Returns the same
+	pointer.
+
+	Never throws exceptions.
+*/
 fz_device *fz_keep_device(fz_context *ctx, fz_device *dev);

-/*
-	fz_enable_device_hints : Enable hints in a device.
-
-	hints: mask of hints to enable.
+/**
+	Enable (set) hint bits within the hint bitfield for a device.
 */
 void fz_enable_device_hints(fz_context *ctx, fz_device *dev, int hints);

-/*
-	fz_disable_device_hints : Disable hints in a device.
-
-	hints: mask of hints to disable.
+/**
+	Disable (clear) hint bits within the hint bitfield for a device.
 */
 void fz_disable_device_hints(fz_context *ctx, fz_device *dev, int hints);

-/*
+/**
 	Find current scissor region as tracked by the device.
 */
-const fz_rect *fz_device_current_scissor(fz_context *ctx, fz_device *dev);
+fz_rect fz_device_current_scissor(fz_context *ctx, fz_device *dev);

 enum
 {
 	/* Hints */
 	FZ_DONT_INTERPOLATE_IMAGES = 1,
-	FZ_MAINTAIN_CONTAINER_STACK = 2,
-	FZ_NO_CACHE = 4,
+	FZ_NO_CACHE = 2,
+	FZ_DONT_DECODE_IMAGES = 4
 };

-/*
+/**
 	Cookie support - simple communication channel between app/library.
 */

-typedef struct fz_cookie_s fz_cookie;
-
-/*
+/**
 	Provide two-way communication between application and library.
 	Intended for multi-threaded applications where one thread is
 	rendering pages and another thread wants to read progress
@@ -242,33 +475,30 @@ typedef struct fz_cookie_s fz_cookie;

 	errors: count of errors during current rendering.

-	incomplete_ok: If this is set to 1 by the caller, then TRYLATER
-	errors are swallowed as they occur, setting the 'incomplete' flag.
-	Rendering continues as much as possible ignoring errors. The caller
-	is expected to check the 'incomplete' flag at the end to see if the
-	rendering may be considered final or not.
-
-	incomplete: Initially should be set to 0. Will be set to non-zero
-	if a TRYLATER error is thrown during rendering and the incomplete_ok
-	flag is set.
+	incomplete: Initially should be set to 0. Will be set to
+	non-zero if a TRYLATER error is thrown during rendering.
 */
-struct fz_cookie_s
+typedef struct
 {
 	int abort;
 	int progress;
-	int progress_max; /* -1 for unknown */
+	size_t progress_max; /* (size_t)-1 for unknown */
 	int errors;
-	int incomplete_ok;
 	int incomplete;
-};
+} fz_cookie;

-/*
-	fz_new_trace_device: Create a device to print a debug trace of all device calls.
+/**
+	Create a device to print a debug trace of all device calls.
 */
 fz_device *fz_new_trace_device(fz_context *ctx, fz_output *out);

-/*
-	fz_new_bbox_device: Create a device to compute the bounding
+/**
+	Create a device to output raw information.
+*/
+fz_device *fz_new_xmltext_device(fz_context *ctx, fz_output *out);
+
+/**
+	Create a device to compute the bounding
 	box of all marks on a page.

 	The returned bounding box will be the union of all bounding
@@ -276,8 +506,8 @@ fz_device *fz_new_trace_device(fz_context *ctx, fz_output *out);
 */
 fz_device *fz_new_bbox_device(fz_context *ctx, fz_rect *rectp);

-/*
-	fz_new_test_device: Create a device to test for features.
+/**
+	Create a device to test for features.

 	Currently only tests for the presence of non-grayscale colors.

@@ -315,8 +545,8 @@ enum
 	FZ_TEST_OPT_SHADINGS = 2
 };

-/*
-	fz_new_draw_device: Create a device to draw on a pixmap.
+/**
+	Create a device to draw on a pixmap.

 	dest: Target pixmap for the draw device. See fz_new_pixmap*
 	for how to obtain a pixmap. The pixmap is not cleared by the
@@ -324,12 +554,13 @@ enum
 	calling fz_new_draw_device. Free the device by calling
 	fz_drop_device.

-	transform: Transform from user space in points to device space in pixels.
+	transform: Transform from user space in points to device space
+	in pixels.
 */
-fz_device *fz_new_draw_device(fz_context *ctx, const fz_matrix *transform, fz_pixmap *dest);
+fz_device *fz_new_draw_device(fz_context *ctx, fz_matrix transform, fz_pixmap *dest);

-/*
-	fz_new_draw_device_with_bbox: Create a device to draw on a pixmap.
+/**
+	Create a device to draw on a pixmap.

 	dest: Target pixmap for the draw device. See fz_new_pixmap*
 	for how to obtain a pixmap. The pixmap is not cleared by the
@@ -337,15 +568,16 @@ fz_device *fz_new_draw_device(fz_context *ctx, const fz_matrix *transform, fz_pi
 	calling fz_new_draw_device. Free the device by calling
 	fz_drop_device.

-	transform: Transform from user space in points to device space in pixels.
+	transform: Transform from user space in points to device space
+	in pixels.

 	clip: Bounding box to restrict any marking operations of the
 	draw device.
 */
-fz_device *fz_new_draw_device_with_bbox(fz_context *ctx, const fz_matrix *transform, fz_pixmap *dest, const fz_irect *clip);
+fz_device *fz_new_draw_device_with_bbox(fz_context *ctx, fz_matrix transform, fz_pixmap *dest, const fz_irect *clip);

-/*
-	fz_new_draw_device_with_proof: Create a device to draw on a pixmap.
+/**
+	Create a device to draw on a pixmap.

 	dest: Target pixmap for the draw device. See fz_new_pixmap*
 	for how to obtain a pixmap. The pixmap is not cleared by the
@@ -353,15 +585,16 @@ fz_device *fz_new_draw_device_with_bbox(fz_context *ctx, const fz_matrix *transf
 	calling fz_new_draw_device. Free the device by calling
 	fz_drop_device.

-	transform: Transform from user space in points to device space in pixels.
+	transform: Transform from user space in points to device space
+	in pixels.

 	proof_cs: Intermediate color space to map though when mapping to
 	color space defined by pixmap.
 */
-fz_device *fz_new_draw_device_with_proof(fz_context *ctx, const fz_matrix *transform, fz_pixmap *dest, fz_colorspace *proof_cs);
+fz_device *fz_new_draw_device_with_proof(fz_context *ctx, fz_matrix transform, fz_pixmap *dest, fz_colorspace *proof_cs);

-/*
-	fz_new_draw_device_with_bbox_proof: Create a device to draw on a pixmap.
+/**
+	Create a device to draw on a pixmap.

 	dest: Target pixmap for the draw device. See fz_new_pixmap*
 	for how to obtain a pixmap. The pixmap is not cleared by the
@@ -369,23 +602,24 @@ fz_device *fz_new_draw_device_with_proof(fz_context *ctx, const fz_matrix *trans
 	calling fz_new_draw_device. Free the device by calling
 	fz_drop_device.

-	transform: Transform from user space in points to device space in pixels.
+	transform: Transform from user space in points to device space
+	in pixels.

 	clip: Bounding box to restrict any marking operations of the
 	draw device.

-	proof_cs: Color space to render to prior to mapping to color space defined by pixmap.
+	proof_cs: Color space to render to prior to mapping to color
+	space defined by pixmap.
 */
-fz_device *fz_new_draw_device_with_bbox_proof(fz_context *ctx, const fz_matrix *transform, fz_pixmap *dest, const fz_irect *clip, fz_colorspace *cs);
+fz_device *fz_new_draw_device_with_bbox_proof(fz_context *ctx, fz_matrix transform, fz_pixmap *dest, const fz_irect *clip, fz_colorspace *cs);

-fz_device *fz_new_draw_device_type3(fz_context *ctx, const fz_matrix *transform, fz_pixmap *dest);
+fz_device *fz_new_draw_device_type3(fz_context *ctx, fz_matrix transform, fz_pixmap *dest);

-/*
-	struct fz_draw_options: Options for creating a pixmap and draw device.
+/**
+	struct fz_draw_options: Options for creating a pixmap and draw
+	device.
 */
-typedef struct fz_draw_options_s fz_draw_options;
-
-struct fz_draw_options_s
+typedef struct
 {
 	int rotate;
 	int x_resolution;
@@ -396,22 +630,25 @@ struct fz_draw_options_s
 	int alpha;
 	int graphics;
 	int text;
-};
+} fz_draw_options;

-extern const char *fz_draw_options_usage;
+FZ_DATA extern const char *fz_draw_options_usage;

-/*
-	fz_parse_draw_options: Parse draw device options from a comma separated key-value string.
+/**
+	Parse draw device options from a comma separated key-value string.
 */
 fz_draw_options *fz_parse_draw_options(fz_context *ctx, fz_draw_options *options, const char *string);

-/*
-	fz_new_draw_device_with_options: Create a new pixmap and draw device, using the specified options.
+/**
+	Create a new pixmap and draw device, using the specified options.
+
+	options: Options to configure the draw device, and choose the
+	resolution and colorspace.

-	options: Options to configure the draw device, and choose the resolution and colorspace.
 	mediabox: The bounds of the page in points.
+
 	pixmap: An out parameter containing the newly created pixmap.
 */
-fz_device *fz_new_draw_device_with_options(fz_context *ctx, const fz_draw_options *options, const fz_rect *mediabox, fz_pixmap **pixmap);
+fz_device *fz_new_draw_device_with_options(fz_context *ctx, const fz_draw_options *options, fz_rect mediabox, fz_pixmap **pixmap);

 #endif