typedef struct fz_font_context fz_font_contexttypedef struct fz_hyph_context fz_hyph_contexttypedef struct fz_colorspace_context fz_colorspace_contexttypedef struct fz_style_context fz_style_contexttypedef struct fz_tuning_context fz_tuning_contexttypedef struct fz_store fz_storetypedef struct fz_glyph_cache fz_glyph_cachetypedef struct fz_document_handler_context fz_document_handler_contexttypedef struct fz_archive_handler_context fz_archive_handler_contexttypedef struct fz_output fz_outputtypedef struct fz_document fz_documentstruct fz_alloc_context
{
void *user;
void *(*malloc)(void *, size_t);
void *(*realloc)(void *, void *, size_t);
void (*free)(void *, void *);
}Allocator structure; holds callbacks and private data pointer.
Just treat these as a black box - pay no attention to the man behind the curtain.
These macros provide a simple exception handling system. Use them as follows:
fz_try(ctx)
...
fz_catch(ctx)
...or as:
fz_try(ctx)
...
fz_always(ctx)
...
fz_catch(ctx)
...Code within the fz_try() section can then throw exceptions using fz_throw() (or fz_vthrow()).
They are implemented with setjmp/longjmp, which can have unfortunate consequences for ‘losing’ local variable values on a throw. To avoid this we recommend calling ‘fz_var(variable)’ before the fz_try() for any local variable whose value may change within the fz_try() block and whose value will be required afterwards.
Do not call anything in the fz_always() section that can throw.
Any exception can be rethrown from the fz_catch() section using fz_rethrow() as long as there has been no intervening use of fz_try/fz_catch.
#define fz_var(var)Guard a local from losing changes when an exception throws. Must use this when a local is assigned a new value inside a try block, and is read outside the try block.
#define fz_try(ctx)#define fz_always(ctx)#define fz_catch(ctx)[[noreturn]] void
fz_throw (
fz_context *ctx,
int errcode,
const char *,
...
)Throw an exception.
This assumes an enclosing fz_try() block within the callstack.
[[noreturn]] void
fz_vthrow (
fz_context *ctx,
int errcode,
const char *,
va_list ap
)[[noreturn]] void
fz_rethrow (
fz_context *ctx
)Rethrow the last exception. Use this inside a fz_catch to propagate the error after cleanup.
void
fz_morph_error (
fz_context *ctx,
int fromcode,
int tocode
)Called within a catch block this modifies the current exception’s code. If it’s of type ‘fromcode’ it is modified to ‘tocode’. Typically used for ‘downgrading’ exception severity.
void
fz_warn (
fz_context *ctx,
const char *fmt,
...
)Log a warning.
This goes to the registered warning stream (stderr by default).
void
fz_vwarn (
fz_context *ctx,
const char *fmt,
va_list ap
)const char *
fz_caught_message (
fz_context *ctx
)Within an fz_catch() block, retrieve the formatted message string for the current exception.
This assumes no intervening use of fz_try/fz_catch.
int
fz_caught (
fz_context *ctx
)Within an fz_catch() block, retrieve the error code for the current exception.
This assumes no intervening use of fz_try/fz_catch.
int
fz_caught_errno (
fz_context *ctx
)Within an fz_catch() block, retrieve the errno code for the current SYSTEM exception.
Is undefined for non-SYSTEM errors.
void
fz_rethrow_if (
fz_context *ctx,
int errcode
)Within an fz_catch() block, rethrow the current exception if the errcode of the current exception matches.
This assumes no intervening use of fz_try/fz_catch.
void
fz_rethrow_unless (
fz_context *ctx,
int errcode
)void
fz_log_error_printf (
fz_context *ctx,
const char *fmt,
...
)Format an error message, and log it to the registered error stream (stderr by default).
void
fz_vlog_error_printf (
fz_context *ctx,
const char *fmt,
va_list ap
)void
fz_log_error (
fz_context *ctx,
const char *str
)Log a (preformatted) string to the registered error stream (stderr by default).
void
fz_report_error (
fz_context *ctx
)Report an error to the registered error callback.
void
fz_ignore_error (
fz_context *ctx
)Swallow an error and ignore it completely. This should only be called to signal that you’ve handled a TRYLATER or ABORT error,
const char *
fz_convert_error (
fz_context *ctx,
int *code
)Convert an error into another runtime exception. For use when converting an exception from Fitz to a language binding exception.
enum fz_error_type
{
FZ_ERROR_NONE,
FZ_ERROR_GENERIC,
FZ_ERROR_SYSTEM, // fatal out of memory or syscall error
FZ_ERROR_LIBRARY, // unclassified error from third-party library
FZ_ERROR_ARGUMENT, // invalid or out-of-range arguments to functions
FZ_ERROR_LIMIT, // failed because of resource or other hard limits
FZ_ERROR_UNSUPPORTED, // tried to use an unsupported feature
FZ_ERROR_FORMAT, // syntax or format errors that are unrecoverable
FZ_ERROR_SYNTAX, // syntax errors that should be diagnosed and ignored
// for internal use only
FZ_ERROR_TRYLATER, // try-later progressive loading signal
FZ_ERROR_ABORT, // user requested abort signal
FZ_ERROR_REPAIRED, // internal flag used when repairing a PDF to avoid cycles
}void
fz_flush_warnings (
fz_context *ctx
)Flush any repeated warnings.
Repeated warnings are buffered, counted and eventually printed along with the number of repetitions. Call fz_flush_warnings to force printing of the latest buffered warning and the number of repetitions, for example to make sure that all warnings are printed before exiting an application.
MuPDF is kept deliberately free of any knowledge of particular threading systems. As such, in order for safe multi-threaded operation, we rely on callbacks to client provided functions.
A client is expected to provide FZ_LOCK_MAX number of mutexes, and a function to lock/unlock each of them. These may be recursive mutexes, but do not have to be.
If a client does not intend to use multiple threads, then it may pass NULL instead of a lock structure.
In order to avoid deadlocks, we have one simple rule internally as to how we use locks: We can never take lock n when we already hold any lock i, where 0 <= i <= n. In order to verify this, we have some debugging code, that can be enabled by defining FITZ_DEBUG_LOCKING.
struct fz_locks_context
{
void *user;
void (*lock)(void *user, int lock);
void (*unlock)(void *user, int lock);
}enum fz_lock_id {
FZ_LOCK_ALLOC = 0,
FZ_LOCK_FREETYPE,
FZ_LOCK_GLYPHCACHE,
FZ_LOCK_MAX
}#define FITZ_DEBUG_LOCKINGWe turn on lock debugging automatically in Memento builds.
void
fz_assert_lock_held (
fz_context *ctx,
int lock
)void
fz_assert_lock_not_held (
fz_context *ctx,
int lock
)void
fz_lock_debug_lock (
fz_context *ctx,
int lock
)void
fz_lock_debug_unlock (
fz_context *ctx,
int lock
)#define fz_assert_lock_held(A,B)#define fz_assert_lock_not_held(A,B)#define fz_lock_debug_lock(A,B)#define fz_lock_debug_unlock(A,B)#define fz_new_context(alloc, locks, max_store)Allocate context containing global state.
The global state contains an exception stack, resource store, etc. Most functions in MuPDF take a context argument to be able to reference the global state. See fz_drop_context for freeing an allocated context.
May return NULL.
#define FZ_STORE_UNLIMITED 0Let the resource store grow unbounded. Given as max_store to fz_new_context.
#define FZ_STORE_DEFAULT (256 << 20)Specifies a reasonable upper bound on the size, for devices that are not memory constrained. Given as max_store to fz_new_context.
fz_context *
fz_clone_context (
fz_context *ctx
)Make a clone of an existing context.
This function is meant to be used in multi-threaded applications where each thread requires its own context, yet parts of the global state, for example caching, are shared.
May return NULL.
void
fz_drop_context (
fz_context *ctx
)Free a context and its global state.
The context and all of its global state is freed, and any buffered warnings are flushed (see fz_flush_warnings). If NULL is passed in nothing will happen.
Must not be called for a context that is being used in an active fz_try(), fz_always() or fz_catch() block.
void
fz_set_user_context (
fz_context *ctx,
void *user
)Set the user field in the context.
NULL initially, this field can be set to any opaque value required by the user. It is copied on clones.
void *
fz_user_context (
fz_context *ctx
)Read the user field from the context.
FIXME: Better not to expose fz_default_error_callback, and fz_default_warning callback and to allow ‘NULL’ to be used int fz_set_xxxx_callback to mean “defaults”.
FIXME: Do we need/want functions like fz_error_callback(ctx, message) to allow callers to inject stuff into the error/warning streams?
void
fz_default_error_callback (
void *user,
const char *message
)The default error callback. Declared publicly just so that the error callback can be set back to this after it has been overridden.
void
fz_default_warning_callback (
void *user,
const char *message
)The default warning callback. Declared publicly just so that the warning callback can be set back to this after it has been overridden.
typedef void (fz_error_cb)(void *user, const char *message)A callback called whenever an error message is generated. The user pointer passed to fz_set_error_callback() is passed along with the error message.
typedef void (fz_warning_cb)(void *user, const char *message)A callback called whenever a warning message is generated. The user pointer passed to fz_set_warning_callback() is passed along with the warning message.
void
fz_set_error_callback (
fz_context *ctx,
fz_error_cb *error_cb,
void *user
)Set the error callback. This will be called as part of the exception handling.
The callback must not throw exceptions!
fz_error_cb *
fz_error_callback (
fz_context *ctx,
void **user
)Retrieve the currently set error callback, or NULL if none has been set. Optionally, if user is non-NULL, the user pointer given when the warning callback was set is also passed back to the caller.
void
fz_set_warning_callback (
fz_context *ctx,
fz_warning_cb *warning_cb,
void *user
)Set the warning callback. This will be called as part of the exception handling.
The callback must not throw exceptions!
fz_warning_cb *
fz_warning_callback (
fz_context *ctx,
void **user
)Retrieve the currently set warning callback, or NULL if none has been set. Optionally, if user is non-NULL, the user pointer given when the warning callback was set is also passed back to the caller.
In order to tune MuPDF’s behaviour, certain functions can (optionally) be provided by callers.
typedef void (fz_tune_image_decode_fn)(void *arg, int w, int h, int l2factor, fz_irect *subarea)Given the width and height of an image, the subsample factor, and the subarea of the image actually required, the caller can decide whether to decode the whole image or just a subarea.
typedef int (fz_tune_image_scale_fn)(void *arg, int dst_w, int dst_h, int src_w, int src_h)Given the source width and height of image, together with the actual required width and height, decide whether we should use mitchell scaling.
Return 0 not to use the Mitchell scaler, 1 to use the Mitchell scaler. All other values reserved.
void
fz_tune_image_decode (
fz_context *ctx,
fz_tune_image_decode_fn *image_decode,
void *arg
)Set the tuning function to use for image decode.
void
fz_tune_image_scale (
fz_context *ctx,
fz_tune_image_scale_fn *image_scale,
void *arg
)Set the tuning function to use for image scaling.
enum fz_image_rendering_behavior
{
// We may box filter images down by a power of 2, before scaling
// accurately to get the final results. Rendering will be stable.
// This may be faster and may use less memory than 'QUALITY'
// rendering, for a (probably imperceptible) degradation of quality.
FZ_IMAGE_RENDERING_BALANCE = 0,
// We will never box filter images, and instead will always scale
// accurately. Rendering will be stable. This may be slower and
// may use more memory than 'HYBRID' rendering, for a (probably
// imperceptible) improvement in quality.
FZ_IMAGE_RENDERING_QUALITY = 1,
// We will box filter images down by a power of 2, before scaling
// accurately to get the final results. We will accept image
// tiles that have previously been box scaled and cached at higher
// quality than we need, thus saving us the decode again, at the
// cost of "rendering instability". i.e. the exact results of
// rendering may differ according to the order of rendering
// operations that have happened in the past. The quality
// differences here are rarely spotted, and very minor, but
// genuinely exist. In an interactive application, these are
// well within acceptability, but in an system where results are
// being compared pixel-by-pixel, this is probably best avoided.
FZ_IMAGE_RENDERING_SPEED = 2,
}Set the behavior for image rendering and resampling.
void
fz_tune_image_rendering (
fz_context *ctx,
enum fz_image_rendering_behavior behavior
)int
fz_aa_level (
fz_context *ctx
)Get the number of bits of antialiasing we are using (for graphics). Between 0 and 8.
void
fz_set_aa_level (
fz_context *ctx,
int bits
)Set the number of bits of antialiasing we should use (for both text and graphics).
int
fz_text_aa_level (
fz_context *ctx
)Get the number of bits of antialiasing we are using for text. Between 0 and 8.
void
fz_set_text_aa_level (
fz_context *ctx,
int bits
)Set the number of bits of antialiasing we should use for text.
int
fz_graphics_aa_level (
fz_context *ctx
)Get the number of bits of antialiasing we are using for graphics. Between 0 and 8.
void
fz_set_graphics_aa_level (
fz_context *ctx,
int bits
)Set the number of bits of antialiasing we should use for graphics.
float
fz_graphics_min_line_width (
fz_context *ctx
)Get the minimum line width to be used for stroked lines.
void
fz_set_graphics_min_line_width (
fz_context *ctx,
float min_line_width
)Set the minimum line width to be used for stroked lines.
const char *
fz_user_css (
fz_context *ctx
)Get the user stylesheet source text.
void
fz_set_user_css (
fz_context *ctx,
const char *text
)Set the user stylesheet source text for use with HTML and EPUB.
void
fz_load_user_css (
fz_context *ctx,
const char *filename
)Set the user stylesheet by loading the source from a file. If the file is missing, do nothing.
int
fz_use_document_css (
fz_context *ctx
)Return whether to respect document styles in HTML and EPUB.
void
fz_set_use_document_css (
fz_context *ctx,
int use
)Toggle whether to respect document styles in HTML and EPUB.
void
fz_enable_icc (
fz_context *ctx
)Enable icc profile based operation.
void
fz_disable_icc (
fz_context *ctx
)Disable icc profile based operation.
All calls to MuPDF’s allocator functions pass through to the underlying allocators passed in when the initial context is created, after locks are taken (using the supplied locking function) to ensure that only one thread at a time calls through.
If the underlying allocator fails, MuPDF attempts to make room for the allocation by evicting elements from the store, then retrying.
Any call to allocate may then result in several calls to the underlying allocator, and result in elements that are only referred to by the store being freed.
#define fz_malloc_struct(CTX, TYPE)Allocate memory for a structure, clear it, and tag the pointer for Memento.
Throws exception in the event of failure to allocate.
#define fz_malloc_struct_array(CTX, N, TYPE)Allocate memory for an array of structures, clear it, and tag the pointer for Memento.
Throws exception in the event of failure to allocate.
#define fz_malloc_array(CTX, COUNT, TYPE)Allocate uninitialized memory for an array of structures, and tag the pointer for Memento. Does NOT clear the memory!
Throws exception in the event of failure to allocate.
#define fz_realloc_array(CTX, OLD, COUNT, TYPE)void *
fz_malloc_array_imp (
fz_context *ctx,
size_t nmemb,
size_t size
)void *
fz_realloc_array_imp (
fz_context *ctx,
void *p,
size_t nmemb,
size_t size
)void *
fz_malloc (
fz_context *ctx,
size_t size
)Allocate uninitialized memory of a given size. Does NOT clear the memory!
May return NULL for size = 0.
Throws exception in the event of failure to allocate.
void *
fz_calloc (
fz_context *ctx,
size_t count,
size_t size
)Allocate array of memory of count entries of size bytes. Clears the memory to zero.
Throws exception in the event of failure to allocate.
void *
fz_realloc (
fz_context *ctx,
void *p,
size_t size
)Reallocates a block of memory to given size. Existing contents up to min(old_size,new_size) are maintained. The rest of the block is uninitialised.
fz_realloc(ctx, NULL, size) behaves like fz_malloc(ctx, size).
fz_realloc(ctx, p, 0); behaves like fz_free(ctx, p).
Throws exception in the event of failure to allocate.
void
fz_free (
fz_context *ctx,
void *p
)Free a previously allocated block of memory.
fz_free(ctx, NULL) does nothing.
Never throws exceptions.
#define fz_malloc_flexible(ctx, T, M, count)Flexible array member allocation helpers.
#define fz_realloc_flexible(ctx, p, T, M, count)#define fz_pool_alloc_flexible(ctx, pool, T, M, count)#define fz_sizeof_flexible(T, M, count)void *
fz_malloc_no_throw (
fz_context *ctx,
size_t size
)fz_malloc equivalent that returns NULL rather than throwing exceptions.
void *
fz_calloc_no_throw (
fz_context *ctx,
size_t count,
size_t size
)fz_calloc equivalent that returns NULL rather than throwing exceptions.
void *
fz_realloc_no_throw (
fz_context *ctx,
void *p,
size_t size
)fz_realloc equivalent that returns NULL rather than throwing exceptions.
void *
fz_malloc_aligned (
fz_context *ctx,
size_t size,
int align
)fz_malloc equivalent, except that the block is guaranteed aligned. Block must be freed later using fz_free_aligned.
void
fz_free_aligned (
fz_context *ctx,
void *p
)fz_free equivalent, for blocks allocated via fz_malloc_aligned.
char *
fz_strdup (
fz_context *ctx,
const char *s
)Portable strdup implementation, using fz allocators.
void
fz_memrnd (
fz_context *ctx,
uint8_t *block,
int len
)Fill block with len bytes of pseudo-randomness.
struct fz_string
{
int refs;
char str[FZ_FLEXIBLE_ARRAY];
}Reference counted malloced C strings.
fz_string *
fz_new_string (
fz_context *ctx,
const char *str
)Allocate a new string to hold a copy of str.
Returns with a refcount of 1.
fz_string *
fz_keep_string (
fz_context *ctx,
fz_string *str
)Take another reference to a string.
void
fz_drop_string (
fz_context *ctx,
fz_string *str
)Drop a reference to a string, freeing if the refcount reaches 0.
#define fz_cstring_from_string(A)Implementations exposed for speed, but considered private and subject to change at any time.
void
fz_var_imp (
void *
)fz_jmp_buf *
fz_push_try (
fz_context *ctx
)int
fz_do_try (
fz_context *ctx
)int
fz_do_always (
fz_context *ctx
)#define FZ_JMPBUF_ALIGN 32struct fz_error_stack_slot
{
fz_jmp_buf buffer;
int state, code;
char padding[FZ_JMPBUF_ALIGN-sizeof(int)*2];
}struct fz_error_context
{
fz_error_stack_slot *top;
fz_error_stack_slot stack[256];
fz_error_stack_slot padding;
fz_error_stack_slot *stack_base;
int errcode;
int errnum; /* errno for SYSTEM class errors */
void *print_user;
void (*print)(void *user, const char *message);
char message[256];
}struct fz_warn_context
{
void *print_user;
void (*print)(void *user, const char *message);
int count;
char message[256];
}struct fz_aa_context
{
int hscale;
int vscale;
int scale;
int bits;
int text_bits;
float min_line_width;
}enum fz_activity_reason
{
FZ_ACTIVITY_NEW_DOC = 0,
FZ_ACTIVITY_SHUTDOWN = 1
}typedef void (fz_activity_fn)(fz_context *ctx, void *opaque, fz_activity_reason reason, void *reason_arg)struct fz_activity_context
{
void *opaque;
fz_activity_fn *activity;
}void
fz_register_activity_logger (
fz_context *ctx,
fz_activity_fn *activity,
void *opaque
)struct fz_context
{
void *user;
/* If master points to itself, then we are the master context.
* If master is NULL, then we are the master context, but we have
* been destroyed. We exist just so the count of clones can live
* on. Otherwise master points to the master context from which
* we were cloned. */
fz_context *master;
/* The number of contexts in this family. 1 for this one, plus
* 1 for every context cloned (directly or indirectly) from it. */
int context_count;
/* Only the master version of this is used! */
int next_document_id;
fz_alloc_context alloc;
fz_locks_context locks;
fz_error_context error;
fz_warn_context warn;
fz_activity_context activity;
/* unshared contexts */
fz_aa_context aa;
fz_chacha20 seed;
#if FZ_ENABLE_ICC
int icc_enabled;
#endif
/* TODO: should these be unshared? */
fz_document_handler_context *handler;
fz_archive_handler_context *archive;
fz_style_context *style;
fz_tuning_context *tuning;
/* shared contexts */
fz_output *stddbg;
fz_font_context *font;
fz_hyph_context *hyph;
fz_colorspace_context *colorspace;
fz_store *store;
fz_glyph_cache *glyph_cache;
}fz_context *
fz_new_context_imp (
const fz_alloc_context *alloc,
const fz_locks_context *locks,
size_t max_store,
const char *version
)void
fz_lock (
fz_context *ctx,
int lock
)Lock one of the user supplied mutexes.
void
fz_unlock (
fz_context *ctx,
int lock
)Unlock one of the user supplied mutexes.
#define fz_keep_imp(C,P,R)Lock-safe reference counting functions
#define fz_keep_imp8(C,P,R)#define fz_keep_imp16(C,P,R)#define fz_keep_imp_locked(C,P,R)#define fz_keep_imp8_locked(C,P,R)#define fz_drop_imp(C,P,R)#define fz_drop_imp8(C,P,R)#define fz_drop_imp16(C,P,R)void *
fz_keep_imp_aux (
fz_context *ctx,
void *p,
int *refs
)void *
fz_keep_imp_locked_aux (
fz_context *ctx FZ_UNUSED,
void *p,
int *refs
)void *
fz_keep_imp8_locked_aux (
fz_context *ctx FZ_UNUSED,
void *p,
int8_t *refs
)void *
fz_keep_imp8_aux (
fz_context *ctx,
void *p,
int8_t *refs
)void *
fz_keep_imp16_aux (
fz_context *ctx,
void *p,
int16_t *refs
)int
fz_drop_imp_aux (
fz_context *ctx,
void *p,
int *refs
)int
fz_drop_imp8_aux (
fz_context *ctx,
void *p,
int8_t *refs
)int
fz_drop_imp16_aux (
fz_context *ctx,
void *p,
int16_t *refs
)