Almost all functions in the MuPDF library take a
fz_context structure as their first argument. The context
is used for many things; primarily it holds the exception stack for our
setjmp based exception handling. It also holds various
caches and auxiliary contexts for font rendering and color
management.
Here is the code to create a Fitz context. The first two arguments are used if you need to use a custom memory allocator, and the third argument is a hint to much memory the various caches should be allowed to grow. The limit is only a soft limit. We may exceed it, but will start clearing out stale data to try to stay below the limit when possible. Setting it to a lower value will prevent the caches from growing out of hand if you are tight on memory.
#include <mupdf/fitz.h>
#include <stdio.h>
#include <stdlib.h>
main()
{
fz_context *ctx = fz_new_context(NULL, NULL, FZ_STORE_UNLIMITED);
if (!ctx) {
fprintf(stderr, "Failed to create a new Fitz context!\n");
return EXIT_FAILURE;
}
... do stuff ...
fz_drop_context(ctx);
return EXIT_SUCCESS;
}
MuPDF uses a setjmp based exception handling system.
This is encapsulated by the use of three macros: fz_try,
fz_always, and fz_catch. When an error is
raised by fz_throw, or re-raised by
fz_rethrow, execution will jump to the enclosing
always/catch block.
All functions you call should be guarded by a fz_try
block to catch the errors, or the program will call exit()
on errors. You don’t want that.
The fz_always block is optional. It is typically used to
free memory or release resources unconditionally, in both the case when
the execution of the try block succeeds, and when an error occurs.
fz_try(ctx) {
// Do stuff that may throw an exception.
}
fz_always(ctx) {
// This (optional) block is always executed.
}
fz_catch(ctx) {
// This block is only executed when recovering from an exception.
}
Since the fz_try macro is based on setjmp,
the same conditions that apply to local variables in the presence of
setjmp apply. Any locals written to inside the try block
may be restored to their pre-try state when an error occurs. We provide
a fz_var() macro to guard against this.
In the following example, if we don’t guard buf with
fz_var, then when an error occurs the buf
local variable might have be reset to its pre-try value
(NULL) and we would leak the memory.
char *buf = NULL;
fz_var(buf);
fz_try(ctx) {
buf = fz_malloc(ctx, 100);
// Do stuff with buf that may throw an exception.
}
fz_always(ctx) {
fz_free(ctx, buf);
}
fz_catch(ctx) {
fz_rethrow(ctx);
}
Carefully note that you should never return from
within a fz_try or fz_always block! Doing so
will unbalance the exception stack, and things will go catastrophically
wrong. Instead, it is possible to break out of the fz_try
and fz_always block by using a break statement if you want
to exit the block early without throwing an exception.
Throwing a new exception can be done with fz_throw.
Passing an exception along after having cleaned up in the
fz_catch block can be done with fz_rethrow.
fz_throw takes a printf-like formatting
string.
enum {
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
};
void fz_throw(fz_context *ctx, int error_code, const char *fmt, ...);
void fz_rethrow(fz_context *ctx);
All memory in Fitz is allocated through an allocator, which allows you to use a custom allocator instead of the system malloc if you need to.
You should not need to do raw memory allocation using the Fitz
context, but if you do, here are the functions you need. These work just
like the regular C functions, but take a Fitz context and throw an
exception if the allocation fails. They will not return
NULL; either they will succeed or they will throw an
exception.
void *fz_malloc(fz_context *ctx, size_t size);
void *fz_realloc(fz_context *ctx, void *old, size_t size);
void *fz_calloc(fz_context *ctx, size_t count, size_t size);
void fz_free(fz_context *ctx, void *ptr);
There are also some macros that allocate structures and arrays, together with a type cast to catch typing errors.
T *fz_malloc_struct(fz_context *ctx, T); // Allocate and zero the memory.
T *fz_malloc_array(fz_context *ctx, size_t count, T); // Allocate uninitialized memory!
T *fz_realloc_array(fz_context *ctx, T *old, size_t count, T);
In the rare case that you need an allocation that returns
NULL on failure, there are variants for that too:
fz_malloc_no_throw, etc.
The pool allocator is used for allocating many small objects that live and die together. All objects allocated from the pool will be freed when the pool is freed.
fz_pool *fz_new_pool(fz_context *ctx);
void *fz_pool_alloc(fz_context *ctx, fz_pool *pool, size_t size);
char *fz_pool_strdup(fz_context *ctx, fz_pool *pool, const char *s);
void fz_drop_pool(fz_context *ctx, fz_pool *pool);
Most objects in MuPDF use reference counting to keep track of when they are no longer used and can be freed. We use the verbs “keep” and “drop” to increment and decrement the reference count. For simplicity, we also use the word “drop” for non-reference counted objects (so that in case we change our minds and decide to add reference counting to an object, the code that uses it need not change).
We obviously need to deal with lots of points, rectangles, and transformations in MuPDF.
Points are fairly self evident. The fz_make_point
utility function is for use with Visual Studio that doesn’t yet support
the C99 struct initializer syntax.
typedef struct {
float x, y;
} fz_point;
fz_point fz_make_point(float x, float y);
Rectangles are represented by two pairs of coordinates. The
x0, y0 pair have the smallest values, and in
the normal coordinate space used by MuPDF that is the upper left corner.
The x1, y1 pair have the largest values,
typically the lower right corner.
In order to represent an infinite unbounded area, we use an
x0 that is larger than the x1.
typedef struct {
float x0, y0;
float x1, y1;
} fz_rect;
const fz_rect fz_infinite_rect = { 1, 1, -1, -1 };
const fz_rect fz_empty_rect = { 0, 0, 0, 0 };
const fz_rect fz_unit_rect = { 0, 0, 1, 1 };
fz_rect fz_make_rect(float x0, float y0, float x1, float y1);
Our matrix structure is a row-major 3x3 matrix with the last column
always [ 0 0 1 ]. This is represented as a struct with six
fields, in the same order as in PDF and Postscript. The identity matrix
is a global constant, for easy access.
/ a b 0 \
| c d 0 |
\ e f 1 /
typedef struct {
float a, b, c, d, e, f;
} fz_matrix;
const fz_matrix fz_identity = { 1, 0, 0, 1, 0, 0 };
fz_matrix fz_make_matrix(float a, float b, float c, float d, float e, float f);
Sometimes we need to represent a non-axis aligned rectangular-ish area, such as the area covered by some rotated text. For this we use a quad representation, using a points for each of the upper/lower/left/right corners as seen from the reading direction of the text represented.
typedef struct {
fz_point ul, ur, ll, lr;
} fz_quad;
These are simple mathematical operations that can not throw errors, so do not need a context argument.
float fz_abs(float f)float fz_min(float a, float b)float fz_max(float a, float b)float fz_clamp(float f, float min, float max)int fz_absi(int i)int fz_mini(int a, int b)int fz_maxi(int a, int b)int fz_clampi(int i, int min, int max)fz_matrix fz_concat(fz_matrix left, fz_matrix right)fz_matrix fz_scale(float sx, float sy)fz_matrix fz_shear(float sx, float sy)fz_matrix fz_rotate(float degrees)fz_matrix fz_translate(float tx, float ty)fz_matrix fz_invert_matrix(fz_matrix matrix)fz_point fz_transform_point(fz_point point, fz_matrix m)fz_point fz_transform_vector(fz_point vector, fz_matrix m)int fz_is_empty_rect(fz_rect r)fz_rect is empty.
int fz_is_infinite_rect(fz_rect r)fz_rect is infinite.
fz_rect fz_transform_rect(fz_rect rect, fz_matrix m)fz_rect according to the given matrix.
int fz_is_point_inside_rect(fz_point p, fz_rect r)fz_rect.
fz_quad fz_transform_quad(fz_quad q, fz_matrix m)fz_quad according to the given matrix.
int fz_is_point_inside_quad(fz_point p, fz_quad q)fz_quad.
fz_matrix fz_transform_page(fz_rect mediabox, float resolution, float rotate)0, 90,
180, and 270 are valid values).