Images are ubiquitous in document formats, and come in a huge variety of formats, ranging from full colour to monochrome, compressed to uncompressed, large to small. The ability to efficiently represent and decode 2d arrays of pixels is vital.
MuPDF represents images using an abstract type,
fz_image. This takes the form of a base class, upon which
different implementations can be built. All `fz_image`s are reference
counted, using the standard fz_keep and
fz_drop conventions:
/*
fz_drop_image: Drop a reference to an image.
image: The image to drop a reference to.
*/
void fz_drop_image(fz_context *ctx, fz_image *image);
/*
fz_keep_image: Increment the reference count of an image.
image: The image to take a reference to.
Returns a pointer to the image.
*/
fz_image *fz_keep_image(fz_context *ctx, fz_image *image);
The key operation required is to be able to request a decoded version
of a subarea of that image (yielding a fz_pixmap), suitable
for rendering at a given size:
/*
fz_get_pixmap_from_image: Called to get a handle to a pixmap from an image.
image: The image to retrieve a pixmap from.
subarea: The subarea of the image that we actually care about (or NULL
to indicate the whole image).
trans: Optional, unless subarea is given. If given, then on entry this is
the transform that will be applied to the complete image. It should be
updated on exit to the transform to apply to the given subarea of the
image. This is used to calculate the desired width/height for subsampling.
w: If non-NULL, a pointer to an int to be updated on exit to the
width (in pixels) that the scaled output will cover.
h: If non-NULL, a pointer to an int to be updated on exit to the
height (in pixels) that the scaled output will cover.
Returns a non NULL pixmap pointer. May throw exceptions.
*/
fz_pixmap *fz_get_pixmap_from_image(fz_context *ctx, fz_image *image, const fz_irect *subarea, fz_matrix *trans, int *w, int *h);
Frequently this will involve decoding the image from its source data, so should be considered a potentially expensive call, both in terms of CPU time, and memory usage.
To minimise the impact of such decodes, `fz_image`s make use of the
Store (see ) to cache decoded versions in. This means that (subject to
enough memory being available) repeated calls to get a
fz_pixmap from the same fz_image (with the
same parameters) will return the same fz_pixmap each time,
with no further decode being required.
The usual reference counting behaviour applies to `fz_image`s, with
fz_keep_image and fz_drop_image claiming and
releasing references respectively.
Depending on the size at which a fz_image is to be used,
it may not be worth decoding it at full resolution; instead, decoding it
at a smaller size can save memory (and frequently time). In addition,
subsequent rendering operations can often be faster due to having to
handle fewer pixels for no quality loss in the final output.
To facilitate this, `fz_image`s will subsample images as appropriate.
Subsampling involves an image being decoded to a size an integer power
of 2 smaller than their native size. For instance, if an image has a
native size of 400x300, and is to be rendered to a final size of 40x30,
fz_get_pixmap_from_image may subsample the returned image
by up to 8 in each direction, resulting in a 50x37 image.
Subsequent operations (such as smooth scaling and rendering) will proceed much faster due to fewer pixels being involved, and around one sixteenth of the memory will be required.
Many images have a resolution encoded within them. This may or may not be honoured in the way they are positioned on the page, and it will certainly not be honoured when zooming is taken into account, but for some operations it is useful to be able to request it.
/*
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);
If no resolution is specified within the image, sensible defaults are returned.
A key ability of `fz_image`s is that they are automatically cached in
the fz_store when decoded - repeated requests for pixmaps
from the same image will (not necessarily) require the image to be
decoded again and again.
The most common type of fz_image is
fz_compressed_image - that is, an image based upon a
fz_buffer of data in a standard compressed format, such as
JPEG, PNG, TIFF, and others.
With such images, the data is held in a
fz_compressed_buffer:
typedef struct fz_compressed_buffer_s
{
fz_compression_params params;
fz_buffer *buffer;
} fz_compressed_buffer;
The data is held in the buffer field, and the details of the
compression used are given in the params field, of type
fz_compression_params:
struct fz_compression_params_s
{
int type;
union {
struct {
int color_transform; /* Use -1 for unset */
} jpeg;
struct {
int smask_in_data;
} jpx;
struct {
int columns;
int rows;
int k;
int end_of_line;
int encoded_byte_align;
int end_of_block;
int black_is_1;
int damaged_rows_before_error;
} fax;
struct
{
int columns;
int colors;
int predictor;
int bpc;
}
flate;
struct
{
int columns;
int colors;
int predictor;
int bpc;
int early_change;
} lzw;
} u;
};
The choice of which of the union clauses is used is made by the type field:
enum
{
FZ_IMAGE_UNKNOWN = 0,
/* Uncompressed samples */
FZ_IMAGE_RAW,
/* Compressed samples */
FZ_IMAGE_FAX,
FZ_IMAGE_FLATE,
FZ_IMAGE_LZW,
FZ_IMAGE_RLD,
/* Full image formats */
FZ_IMAGE_BMP,
FZ_IMAGE_GIF,
FZ_IMAGE_JPEG,
FZ_IMAGE_JPX,
FZ_IMAGE_JXR,
FZ_IMAGE_PNG,
FZ_IMAGE_PNM,
FZ_IMAGE_TIFF,
};
To determine if a fz_image is a compressed image,
call:
/*
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);
The easiest way to tell if an image is a compressed image is to request its underlying buffer. If it returns NULL, you know it is not this sort of image.
The next most common type of image is based upon a decoded
fz_pixmap. These are generally only used if the pixmap
takes less storage than the compressed data would.
/*
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);
The easiest way to tell if an image is a decoded image is to request its underlying tile. If it returns NULL, you know it is not this sort of image.
The final standard sort of image in MuPDF (though more types may of course be added in future) is that based upon a display list.
We use this to easily embed one file format within another. For example, EPUB files frequently contain SVG images for title pages. We open the SVG image as a separate document, run it to a display list, and close the document. We can then create an image from the display list, and use this in the HTML flow of the EPUB document.
These images maintain the properties of the original (vector-based) document in that they remain scalable even after conversion to an image.
To create an image from a standard type, simply call the appropriate
function. For example, if you have a fz_buffer with the
source data:
/*
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);
If the data is in a file, use:
/*
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);
This loads the data into memory, and calls
fz_new_image_from_buffer internally.
If the data cannot be recognised from its header, and more
information is required, then the data can be formed in a
fz_compressed_buffer, and an image created with:
/*
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.
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);
Finally, if we have a decoded fz_pixmap, we can form a
new image from it:
/*
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);
Should it be necessary, support for new types of image can be
implemented fairly simply, by defining a structure derived from a
fz_image. Perhaps:
typedef struct
{
fz_image super;
<foo specific fields>
} foo_image;
Then we’d define a new image creation function,
fz_new_image_from_foo, of the form:
fz_image *fz_new_image_from_foo(fz_context *ctx, <foo specific parameters>) {
foo_image *foo = fz_new_image(ctx, ..., foo_image, foo_get, foo_size, foo_drop);
if (!foo)
return NULL;
<initialise foo specific fields from foo specific parameters>
return &foo->super;
}
The key call here is the call to fz_new_image. This is a
macro which wraps a call to fz_new_image_of_size:
/*
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*)Memento_label(fz_new_image_of_size(CTX,W,H,B,CS,X,Y,I,IM,\
D,C,M,sizeof(T),G,S,Z),#T))
The macro takes identical parameters to the function other than passing the structure type in place of the structure type saved, and performing a typecast to simplify the typical enclosing code.
Both function and macro take pointers to 3 functions that need to be
defined for the new format. Firstly, foo_get is of the
following type:
/*
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);
Secondly, foo_get_size will be of type:
/*
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 *);
Finally, foo_drop will be of type:
/*
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);
The actual deallocation of the fz_image block and its
associated resources will be done on return from this function. The
fz_drop_image_fn is responsible just for deallocating its
implementation specific resources (i.e. the contents of
foo_image rather than fz_image).
While caching of decoded images happens automatically within MuPDF, it is perhaps worth saying a small amount about it.
Whenever a decoded image is requested, MuPDF searches in the store (see ) to see if a suitable pixmap exists there already. If one is found, the store remembers that is has been reused, and returned immediately - no decoding is done.
If no suitable pixmap is found, MuPDF calculates how large the image would be on a rendered page. By comparing this size to the native size of the image, it calculates a log 2 subsampling factor to use. That is, it attempts to avoid decoding the image at full size, when one 1/2 (or 1/4 etc) of the width/height would do.
A log 2 subsampling is used because a) some compression formats such as JPEG can achieve this as part of their decompression run, and b) it is easy to rapidly shrink decompressed pixmaps in this way.
The decoded and subsampled image is then placed into the store so that it will (hopefully) be found the next time a decode of the image is requested.
MuPDF is written as an extensible framework for handling different
document types. Each different document format provides a
fz_document_handler structure that provides the required
callbacks to recognise and open files of its supported type. For
example:
extern fz_document_handler pdf_document_handler;
extern fz_document_handler xps_document_handler;
extern fz_document_handler svg_document_handler;
...
At startup, the calling program must register the required document
handlers. It can either register them each individually, by repeatedly
calling fz_register_document_handler:
/*
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);
For example:
fz_register_document_handler(ctx, &pdf_document_handler);
fz_register_document_handler(ctx, &xps_document_handler);
fz_register_document_handler(ctx, &svg_document_handler);
...
or, it can use a convenience function to register all the standard handlers enabled in a given build:
/*
fz_register_document_handler: Register handlers
for all the standard document types supported in
this build.
*/
void fz_register_document_handlers(fz_context *ctx);
To implement a new document handler, a new
fz_document_handler structure is required. There are 3
components to such a structure, all function pointers:
typedef struct fz_document_handler_s
{
fz_document_recognize_fn *recognize;
fz_document_open_fn *open;
fz_document_open_with_stream_fn *open_with_stream;
} fz_document_handler;
The first is a function to recognize a document from a magic string, typically a mimetype or a filename:
/*
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);
The second is a function to open a document from a filename:
/*
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);
This function can permissibly be NULL, as it can be synthesized automatically from the third entry, a function to open a document from a stream:
/*
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);
To create a fz_document use the
fz_new_document macro. For a document of type foo,
typically a foo_document structure would be defined as
below:
typedef struct
{
fz_document super;
<foo specific fields>
} foo_document;
This would then be created using a call to
fz_new_document, such as:
foo_document *foo = fz_new_document(ctx, foo_document);
This returns an empty document structure with super
populated with default values, and the foo specific fields initialized
to 0. The document handler then needs to fill in the document level
functions.
The fz_document structure contains a list of functions
used to implement the document level calls:
typedef struct fz_document_s
{
int refs;
fz_document_drop_fn *drop_document;
fz_document_needs_password_fn *needs_password;
fz_document_authenticate_password_fn *authenticate_password;
fz_document_has_permission_fn *has_permission;
fz_document_load_outline_fn *load_outline;
fz_document_layout_fn *layout;
fz_document_make_bookmark_fn *make_bookmark;
fz_document_lookup_bookmark_fn *lookup_bookmark;
fz_document_resolve_link_fn *resolve_link;
fz_document_count_pages_fn *count_pages;
fz_document_load_page_fn *load_page;
fz_document_lookup_metadata_fn *lookup_metadata;
int did_layout;
int is_reflowable;
} fz_document;
Implementations must fill in the drop_document field,
with a pointer to a function called to free any resources help by the
document when the reference count drops to 0. In the unlikely event that
your implementation has no resources, this field can be left NULL.
/*
fz_document_drop_fn: 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);
If your document handler is capable of handling password protected
documents, then you must fill in the needs_password field
with a pointer to a function called to enquire whether a given document
needs a password:
/*
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);
If your document handler is capable of handling password protected
documents, then you must fill in the authenticate_password
field with a pointer to a function called to attempt to authenticate a
password:
/*
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);
Certain document types encode permissions within them to say what
users are allowed to do with them (printing, extracting etc). If your
document handler’s format has this concept, then you must fill in the
has_permission field with a pointer to a function called to
attempt to query such permissions:
/*
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);
Certain document types can optionally include outline (table of
contents) information within them. If your document handler’s format has
this concept, then you must fill in the load_outline field
with a pointer to a function called to attempt to load such information
if it is there:
/*
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);
If your document format requires a layout pass before it can be
viewed, then you must fill in the layout field with a
pointer to a function called to perform such a layout:
/*
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);
If your document requires a layout pass, you should provide functions
to both make and resolve bookmarks to enable reader positions to be kept
over layout changes. Accordingly the make_bookmark and
lookup_bookmark fields should be filled out:
/*
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);
Some document formats can encode internal links that point to another
page in the document. If your document supports this concept, then you
must fill in the resolve_link field with a pointer to a
function called to resolve a textual link to a page number, and location
on that page:
/*
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);
All document formats must fill in the count_pages field
with a pointer to a function called to return the number of pages in a
document:
/*
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);
Different document formats encode different types of metadata. We
therefore have an extensible function to allow such data to be queried.
If your document handler wishes to support this, then the
lookup_metadata field must be filled in with a pointer to a
function to perform such lookups:
/*
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);
All document formats must fill in the load_page field
with a pointer to a function called to return a reference to a
fz_page structure:
/*
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);
To create a fz_page use the fz_new_page
macro. For a document of type foo, typically a foo_page
structure would be defined as below:
typedef struct
{
fz_page super;
<foo specific fields>
} foo_page;
This would then be created using a call to fz_new_page,
such as:
foo_page *foo = fz_new_page(ctx, foo_page);
This returns an empty document structure with super
populated with default values, and the foo specific fields initialized
to 0. The document handler implementation then needs to fill in the page
level functions.
The fz_page structure contains a list of functions used
to implement the page level calls:
typedef struct fz_page_s
{
int refs;
fz_page_drop_page_fn *drop_page;
fz_page_bound_page_fn *bound_page;
fz_page_run_page_contents_fn *run_page_contents;
fz_page_load_links_fn *load_links;
fz_page_first_annot_fn *first_annot;
fz_page_page_presentation_fn *page_presentation;
fz_page_control_separation_fn *control_separation;
fz_page_separation_disabled_fn *separation_disabled;
fz_page_count_separations_fn *count_separations;
fz_page_get_separation_fn *get_separation;
} fz_page;
The fz_page (and hence derived foo_page)
structures are reference counted. The refs field is used to
keep the reference count in. All the reference counting is handled by
the core library, and all that is required of the implementation is that
it should supply a drop_page function that will be called
when the reference count reaches zero. This is of type:
/*
fz_page_drop_page_fn: Type for a function to release all the
resources held by a page. Called automatically when the
reference count for that page reaches zero.
*/
typedef void (fz_page_drop_page_fn)(fz_context *ctx, fz_page *page);
Implementations must fill in the bound_page field with
the address of a function to return the pages bounding box, of type:
/*
fz_page_bound_page_fn: Type for a function to return the
bounding box of a page. See fz_bound_page for more
information.
*/
typedef fz_rect *(fz_page_bound_page_fn)(fz_context *ctx, fz_page *page, fz_rect *);
Implementations must fill in the run_page_contents field
with the address of a function to interpret the contents of a page, of
type:
/*
fz_page_run_page_contents_fn: Type for a function to run the
contents of a page. See fz_run_page_contents for more
information.
*/
typedef void (fz_page_run_page_contents_fn)(fz_context *ctx, fz_page *page, fz_device *dev, const fz_matrix *transform, fz_cookie *cookie);
If a document format supports internal or external hyperlinks, then
its implementation must fill in the load_links field with
the address of a function to load the links from a page, of type:
/*
fz_page_load_links_fn: Type for a function to load the links
from a page. See fz_load_links for more information.
*/
typedef fz_link *(fz_page_load_links_fn)(fz_context *ctx, fz_page *page);
If a document format supports annotations, then its implementation
must fill in the first_annot field with the address of a
function to load the annotations from a page, of type:
/*
fz_page_first_annot_fn: Type for a function to load the
annotations from a page. See fz_first_annot for more
information.
*/
typedef fz_annot *(fz_page_first_annot_fn)(fz_context *ctx, fz_page *page);
Some document formats can encode information that specifies how pages
should be presented to the user as a slideshow - how long they should be
displayed, and which transition to use when moving to the next page etc.
In implementations of document handlers for such formats, they should
fill in the page_presentation field with the address of a
function to obtain this information, of type:
/*
fz_page_page_presentation_fn: Type for a function to
obtain the details of how this page should be presented when
in presentation mode. See fz_page_presentation for more
information.
*/
typedef fz_transition *(fz_page_page_presentation_fn)(fz_context *ctx, fz_page *page, fz_transition *transition, float *duration);
Some document formats can encapsulate multiple color separations. In
order to allow proofing of such formats, MuPDF allows such separations
to be enumerated and enabled/disabled. In document handlers for such
document formats, the control_separation,
separation_disabled, count_separations and
get_separation fields should be filled in with functions of
the following types respectively:
/*
fz_page_control_separation: Type for a function to enable/
disable separations on a page. See fz_control_separation for
more information.
*/
typedef void (fz_page_control_separation_fn)(fz_context *ctx, fz_page *page, int separation, int disable);
/*
fz_page_separation_disabled_fn: Type for a function to detect
whether a given separation is enabled or disabled on a page.
See fz_separation_disabled for more information.
*/
typedef int (fz_page_separation_disabled_fn)(fz_context *ctx, fz_page *page, int separation);
/*
fz_page_count_separations_fn: Type for a function to count
the number of separations on a page. See fz_count_separations
for more information.
*/
typedef int (fz_page_count_separations_fn)(fz_context *ctx, fz_page *page);
/*
fz_page_get_separation_fn: Type for a function to retrieve
details of a separation on a page. See fz_get_separation
for more information.
*/
typedef const char *(fz_page_get_separation_fn)(fz_context *ctx, fz_page *page, int separation, uint32_t *rgb, uint32_t *cmyk);
MuPDF contains a range of document handlers for different formats.
Which of these are built/enabled by default depends on configuration
options in the include/mupdf/fitz/config.h file. See for
more information.
Support for PDF (Portable Document Format) is provided by
pdf_document_handler. All current versions at the time of
writing (i.e up to and including PDF 2.0) are supported.
MuPDF contains functionality to allow deeper access to the contents
and structure of a PDF file than is exposed through the standard
fz_ prefixed functions, by using pdf_ prefixed
functions.
The library provides a pdf_specifics function to safely
promote a fz_document pointer to a
pdf_document pointer. This will return NULL if the document
is not a PDF, indicating that the pdf_ functions cannot be
used.
Support for XPS (Open XML Paper Specification) is provided by
xps_document_handler. All current versions at the time of
writing are supported.
Support for EPUB v2 is provided by
epub_document_handler. Tables are not currently supported,
but is planned. Support for v3 is not planned.
The same document handler supports the FB2 (Fiction Book 2) electronic book format.
Support for basic HTML + simple CSS is provided by
htdoc_document_handler. Tables are not currently supported,
but is planned.
Support for SVG (Scalable Vector Graphics) is provided by
svg_document_handler. Support is incomplete, but sufficient
for many files.
Support for a range of common image types (including PNG, JPEG, TIFF,
JPEG2000, BMP and GIF) is provided by
image_document_handler.
Support for CBZ (Comic Book Archive) format is provided by
cbz_document_handler. This supports files in .zip or .tar
format.
In we introduced the concept of the Store, and its use in getting the most out of the available memory of a system. Here we explain the implementation, so document handler authors (and application programmers) can make use of the same mechanism.
These keep and drop calls for simple objects are generally implemented by using one of a set of standard functions. There are a range of these, depending on the expected size of the reference counts, and all handle the locking required to ensure thread safety:
void *fz_keep_imp(fz_context *ctx, void *p, int *refs);
void *fz_keep_imp8(fz_context *ctx, void *p, int8_t *refs);
void *fz_keep_imp16(fz_context *ctx, void *p, int16_t *refs);
int fz_drop_imp(fz_context *ctx, void *p, int *refs);
int fz_drop_imp8(fz_context *ctx, void *p, int8_t *refs);
int fz_drop_imp16(fz_context *ctx, void *p, int16_t *refs);
As an example, a fz_path structure is defined as:
typedef struct {
int8_t refs;
} fz_path;
and thus appropriate keep and drop functions can be defined simply:
fz_path *fz_keep_path(fz_context *ctx, fz_path *path)
{
return fz_keep_imp8(ctx, &path->refs);
}
void fz_drop_path(fz_context *ctx, fz_path *path)
{
if (!fz_drop_imp8(ctx, &path->refs))
return;
/* code to free the contents of the path structure */
...
}
More complex variations of these functions are available to cope with ‘storable’ objects, and still more complex versions to cope with ‘key storable’ objects - these are explained in the following sections.
However they are implemented, these objects all look basically the same to most users - they can simply be ‘kept’ and ‘dropped’ as required.
As mentioned above, most MuPDF objects are reference counted. This
means that on creation (typically with a fz_new_… call),
they have a reference count of 1. Think of these object pointers as
‘handles’.
In the event that a fz_new_… call fails (perhaps due to
running out of memory), then it will tidy up any partially constructed
object(s) before throwing an exception.
If a ‘copy’ of the object is required, a new handle can be generated
using the appropriate fz_keep_… call. This is a very low
cost operation that just involves incrementing the reference count, so
no physical copying of the data is involved. Accordingly it is vital
that objects that have multiple handles do not have their contents
altered.
Once a reference is finished with, it should be disposed of using the
appropriate fz_drop_… call. This is true regardless of
whether the handle was created by a fz_new_… or a
fz_keep_… call. This drops the reference count by 1.
Once the reference count hits 0, the storage used by the object is freed.
It is a matter of design that no fz_drop_… (or
fz_free) call ever throws an exception. Furthermore, all
such ‘destructor’ calls must accept a NULL pointer (and do nothing).
This vastly simplifies error handling in most cases.
As an implementation detail, certain objects within MuPDF are allocated statically and have a reference count of -1. Any negative values are unaffected by reference counting operations, and will never be freed. Nonetheless, these should be treated exactly as normal objects and kept/dropped as usual.
It is up to the developer to choose which size of storage to use for
the reference count, remembering that the MuPDF counting routines do not
detect overflow. If someone takes more than 127 references to an object
built upon an int8_t, for example, the reference counting
routines will believe that it is a static object, and it will never be
freed.
All allocations within MuPDF (and its sub-libraries) call
fz_malloc and family. These functions ultimately call down
to the custom allocator functions passed into the
fz_new_context call (or to malloc and family
if no custom allocators were supplied). (See for details).
If a call to the underlying custom allocator fails, MuPDF will automatically seek to evict the least recently used objects from the store that are not currently being used, and then will retry the allocation. This can happen several times, with more and more objects being freed between each attempt.
Allocation failures are therefore only fatal to MuPDF if there are no remaining objects to be freed in the store.
This ‘just in time’ scavenging of memory means that the store limit can safely be set to a high level (or to be unlimited), and MuPDF will still operate within safe bounds.
Every “storable piece of information” in MuPDF is held in a data
structure that begins with a fz_storable structure. Rather
than repeatedly say “a storable piece of information”, we shall
henceforth just say "`a `fz_storable``".
MuPDF uses reference counting for most of its data structures (see ), and `fz_storable`s are no exception.
The objects in the Store are held in a chain according to when they were last used. Whenever an object is ‘used’, it is moved to the head of the chain. Whenever we need to evict an object from the Store to make room, we therefore discard objects from the tail of the chain. In this way frequently used objects are kept around, while rarely used ones are discarded in preference.
Whenever MuPDF needs to use a fz_storable, it first
checks to see if there is one in the Store already. It does this by
forming a unique ‘key’ and scanning the Store for an object of a given
type, with that key. If the object exists within the Store, the fact
that the object has been used is noted (i.e. it is moved to the front of
the usage chain), a reference is taken, and returned to the caller.
If no reference is returned, the code creates its own version of the
fz_storable. It calculates its size, and puts it into the
Store, together with the same key as before. The Store takes a reference
to the object, links it into its data structure, and updates its running
total of the size of all the objects within it.
If placing a new object into the Store would take it over the limit, it runs through and looks for the least recently used objects to evict to bring the limit down. In order for an object to be considered for eviction, their refcount must be 1. We know that the Store is holding 1 reference to the object - if anything else is, then removing it from the Store won’t actually save us any memory.
Regardless of whether the Store can be reduced to a suitable size,
the object is always placed into the store. This ensures that the
Store’s figure for "`amount of memory used by
fz_storable’s`" remains correct (thus ensuring that should
objects become evictable, the store size will fall correctly). It also
does no harm, because clearly we have managed to allocate enough memory
to form the fz_storable in the first place.
Regardless of whether a caller finds the object in the Store, or has
to store it itself, it then proceeds identically. It uses the object for
whatever purpose it needed it, and then calls the appropriate
fz_drop function to lose its reference. The object will
live on in the Store until it needs to be evicted to make room.
When the fz_context (or, more accurately, the last of a
set of cloned contexts) is finally destroyed, the Store is destroyed
too. This results in every object in the Store being released. Unless
something has gone wrong with reference counting, this will result in
all our objects being freed.
As discussed above, the Store is basically a set of key/value pairs. While the values are always `fz_storable`s, the keys can be of many different types, due to coming from many disparate parts of the system.
Accordingly, we need a mechanism to allow us to safely know what ‘type’ a given key is, and to compare 2 keys of identical type.
We solve this, by using a fz_store_type structure:
typedef struct fz_store_type_s
{
int (*make_hash_key)(fz_context *ctx, fz_store_hash *, void *);
void *(*keep_key)(fz_context *,void *);
void (*drop_key)(fz_context *,void *);
int (*cmp_key)(fz_context *ctx, void *, void *);
void (*print)(fz_context *ctx, fz_output *out, void *);
int (*needs_reap)(fz_context *ctx, void *);
} fz_store_type;
We will have just one instance of this for each type - normally a static const structure defined in the code. Whenever we insert (or lookup) something in the store, we pass the address of that ‘types’ structure.
We only compare items if they have the same type pointer, and any
comparison is done using the cmp_key function pointer
therein. In common with normal C idioms, 0 means match, non zero means
different.
The keep_key and drop_key entries are used
to implement reference counting of keys. Keys can be an amalgam of
several reference counted objects, so a single call to the keep or drop
functions provided here will take or release references for all these
objects in one operation.
The print function is purely for debugging purposes as
part of calls to fz_print_store - it should generate a
human readable summary of the key to the given fz_output
stream.
The make_hash_key and needs_reap functions
are explained in the following subsections.
In order to ensure the Store performs well, we must ensure that certain processes run efficiently - notably searching for an existing entry, insertion and deletion.
Accordingly, the Store is implemented based on a hash table. For
every ‘key’, we need to be able to form a hash, but this process is
complicated slightly by the fact that every different
fz_storable has a different type for the key.
We solve this by having the make_hash_key member of the
fz_store_type structure convert whatever its key data is
into a common structure:
typedef struct fz_store_hash_s
{
fz_store_drop_fn *drop;
union
{
struct
{
const void *ptr;
int i;
} pi; /* 8 or 12 bytes */
struct
{
const void *ptr;
int i;
fz_irect r;
} pir; /* 24 or 28 bytes */
struct
{
int id;
float m[4];
} im; /* 20 bytes */
struct
{
unsigned char src_md5[16];
unsigned char dst_md5[16];
unsigned int ri:2;
unsigned int bp:1;
unsigned int bpp16:1;
unsigned int proof:1;
unsigned int src_extras:5;
unsigned int dst_extras:5;
unsigned int copy_spots:1;
} link; /* 36 bytes */
} u;
} fz_store_hash; /* 40 or 44 bytes */
The caller will always arrange for this structure to be zero filled
on entry to the make_hash_key call. On exit, it should have
been updated with the key details. Implementers may extend the union
found in this structure as required, though ideally the size of the
overall structure should be minimised to avoid unnecessary work.
Once the Store has formed a fz_store_hash it can then
generate the required hash for the hash table as required.
Some objects can be used both as values within the Store, and as a component of keys within the Store. We refer to these objects as ‘key storable’ objects. In this case, we need to take additional care to ensure that we do not end up keeping an item within the store purely because its value is referred to by another key in the store.
An example of this are fz_images in PDF files. Each
fz_image is placed into the Store to enable it to be easily
reused. When the image is rendered, a pixmap is generated from the
image, and the pixmap is placed into the Store so it can be reused on
subsequent renders. The image forms part of the key for the pixmap.
When we close the pdf document (and any associated pages/display lists etc), we drop the images from the Store. This may leave us in the position of the images having non-zero reference counts purely because they are used as part of the keys for the pixmaps.
The pixmaps can never be found by a search of the Store, because to
find them, we’d have to search for them using the appropriate
fz_image. They are therefore, to all intents and purposes
‘dead’, and just taking up useless space.
We therefore use special reference counting functions to implement
these fz_key_storable items,
fz_keep_key_storable and fz_drop_key_storable
rather than the more usual fz_keep_storable and
fz_drop_storable.
The sole difference is that these enable us to store the number of
references to these items that are used in keys. This is achieved by
callers taking and dropping references for use in keys with
fz_keep_key_storable_key and
fz_drop_key_storable_key.
This means that key storable items need to provide two sets of keep and drop functions, one for ‘normal’ callers, and one for use during key handling. For example:
fz_image *fz_keep_image(fz_context *ctx, fz_image *image);
void fz_drop_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);
The purpose of this extra work is to allow us to spot when we may need to check the Store for ‘dead’ entries - those that can never be found by searching the Store.
When the number of references to a key storable object equals the number of references to an object from keys in the Store, we know that we can remove all the items which have that object as part of the key. This is done by running a pass over the store, ‘reaping’ those items.
If a key does not consist of any storable objects, then the
needs_reap entry in its fz_store_type can
safely be left as NULL. If it does, however, it must provide an
implementation to check whether a reap pass is required. Essentially
this needs to check if any of its constituent
fz_key_storable objects need reaping, which can be done by
a call to:
int fz_key_storable_needs_reaping(fz_context *ctx, const fz_key_storable *ks);
Reap passes are slower than we would like as they touch every item in
the store. We therefore provide a way to ‘batch’ such reap passes
together, using fz_defer_reap_start and
fz_defer_reap_end to bracket a region in which many may be
triggered.
The need for a reap is detected as part of normal operations in the core code, and such passes are then triggered automatically as required. The user need never (and indeed cannot) trigger such passes manually. The user can, however, exercise some control over when such operations take place.
If an application is about to perform an operation that may drop many
objects (say dropping a collection of cached display lists), then it
should call fz_defer_reap_start beforehand, and match that
with a fz_defer_reap_end afterwards. Any reap passes
triggered by the dropping of objects within the display lists would be
deferred until the end - resulting in at most one pass rather than
potentially many.
In , we introduced the central concept of a fz_device,
and described the normal ones found in a standard MuPDF build. We
skipped over the actual implementation details of how to call, or
implement such devices. We rectify that here.
As mentioned before, although each device offers a set of function pointers, we prefer people not to call these directly, but rather to call some convenience functions that map down onto these. This protects us against API changes in future, and copes automatically with NULL pointers (in the case when a device doesn’t care about a particular type of call).
We describe these convenience functions here; implementers of devices
can trivially extrapolate the behaviour of the function pointers from
these descriptions. For example, the fz_fill_path function
described here is implemented by the fill_path function
pointer in the fz_device that takes the identical arguments
and has the same return conditions.
Line Art is handled by the device functions to plot paths. See for more information.
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);
Text is handled by the device functions to plot text. See for more information.
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);
The fz_clip_text and fz_clip_stroke_text
functions are used to start a clip. Subsequent operations will be
clipped through the areas delimited by these, until a
fz_pop_clip is seen. See for more details.
Sometimes formats (such as PDF) can send text that has no rendered appearance. We refer to this as ‘ignored’ text. This serves a variety of purposes, the most usual of which is to allow text to be copy/paste out of a document when the actual appearance of that text is given in the form of an image or line art.
For example, a product logo may be rendered using vector graphics, which would ordinarily not have any textual meaning. By including some ignored text, then a user can copy the content out as text, or a text-to-speech engine can correctly enunciate the page contents.
An alternative common example would be where a document has been scanned, and then the text within it has been run through an OCR (Optical Character Recognition) process. The OCR engine would typically include its results as ignored text. The final document would look identical to the scans, but would copy/paste as expected.
Images are handled by the device functions to plot images. See for more information.
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);
The fz_clip_image_mask function is used to start a clip.
Subsequent operations will be clipped through the area delimited by
this, until a fz_pop_clip is seen. See for more
details.
Shaded areas (such as radial, linear and mesh based shadings) are
rendered by filling a (normally) clipped region with a shade. This is
achieved by calling fz_fill_shade. See for more
details.
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);
Graphical objects can be restricted to a given area using Clipping. The area to clip to can be specified as paths, text, or images as explained in , , and .
Each call to such a function starts a clipping group, which will be terminated by calling:
void fz_pop_clip(fz_context *ctx, fz_device *dev);
Clipping groups can be nested, allowing complex graphical effects.
A related concept to clipping, is that of masking. Whereas clipping regions are simple on or off things, where content is chopped off at hard edges, masking allows for regions that allow just some proportion of the content to show through.
Masking operations take place in 2 stages; first the mask itself is defined, then the content to be masked.
Stage 1 begins by calling fz_begin_mask to start a mask
definition group. Any series of graphical operations can now be sent to
the device which will combine together to create the mask.
Stage 1 is terminated and Stage 2 begins by calling
fz_end_mask. This converts the mask definition into a ‘soft
clip’. Any series of graphical operations can now be sent to the device
which will combine together to create the mask contents.
The whole process is then completed by calling
fz_pop_clip. This renders the mask contents through the
soft clip, giving the final results.
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_end_mask(fz_context *ctx, fz_device *dev);
Some document formats (such as PDF) offer a rich transparency model that allows graphical objects to be ’Grouped’ together and imposed upon the page as if they have a given opacity, using a variety of different blend modes.
MuPDF implements this by using the fz_begin_group and
fz_end_group calls.
void fz_begin_group(fz_context *ctx, fz_device *dev, const fz_rect *area, int isolated, int knockout, int blendmode, float alpha);
void fz_end_group(fz_context *ctx, fz_device *dev);
The exact details of PDF transparency are too complex to explain here; for a full explanation see The PDF Reference Manual.
Many document formats allow for content to be tiled repeatedly. Frequently this is used to implement patterns for filling other graphical operations.
MuPDF implements this by allowing a group of content to be defined that is then tiled repeatedly across an area.
The content definition begins by calling
fz_begin_tile_id, giving the area of the page to be filled
(area), the area of a single tile (view), the
x and y steps between repeats of the tile (xstep and
ystep), the transformation to take all of these
measurements out of pattern space to device space (ctm) and
an integer id.
The purpose of id is to allow for efficient caching of
rendered tiles. If id is 0, then no caching is performed.
If it is non-zero, then it assumed to uniquely identify this tile. The
tile can be safely placed into the Store (see ) and future uses of this
tile can short circuit the tile definition/rendering phase.
If a tile is found in the store, then fz_begin_tile_id
will return non-zero and the caller can proceed directly to the call to
fz_end_tile.
Any graphical operations sent to the device will be taken as part of
the tile content, until fz_end_tile is called, whereupon
these graphical operations will be imposed upon the output.
For the convenience of the caller, if no id is available (and hence
no caching is possible), the fz_begin_tile variant can be
used instead.
The id is set by the caller - i.e. the interpreter for the document format in use. Care should be taken by the caller to make these unique.
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_end_tile(fz_context *ctx, fz_device *dev);
Every device has a set of render flags (a simple int, in which bits can be set or cleared).
These flags tend to have meanings specific to individual devices. In an ideal world they would not be required, but having this mechanism here can provide noticeable quality improvements.
void fz_render_flags(fz_context *ctx, fz_device *dev, int set, int clear);
The function basically does:
flags = (flags | set) & ~clear;
That is to say, the bits given in set are set, and then
the bits given in clear are cleared.
The current only documented use of this is for the GProof device to request the Draw device to grid fit its tiled images.
The reason for using Render Flags rather than Device Hints (see ) is that Render Flags can be carried forward though display lists.
Some pages redefine the basic default colorspaces (for color
management purposes). This is handled at the device level using the
fz_set_default_colorspaces call:
void fz_set_default_colorspaces(fz_context *ctx, fz_device *dev, fz_default_colorspaces *default_cs);
The device typically takes a reference to the default_cs
object and refers to it as required.
Some file formats (such as PDF) have the concept of ‘tagged content’. Graphical objects within the page stream can be tagged with information regarding how they correspond to each other on the page.
PDF files are rarely authored directly, but are typically ‘distilled’ from documents created in other programs (such as illustrator or similar packages). These other programs frequently have the concept of ‘layers’, and this layer information is generally carried over into the created PDF file using this tagging mechanism.
In fact, layers are such a ubiquitous source of tag information, that the PDF processing community (and some applications) frequently refers to such information as ‘layer’ information, even though this is an abuse of the terminology. MuPDF follows this convention.
Other interpreters may use layer information to explicitly encode genuine layers of course!
There is no render-time special treatment of layered content, so content is simply composited blindly onto the same output image. Indeed, layers do not necessarily even nest nicely with other content, and can cross groups etc in unpredictable ways.
As a document is interpreted, when a layer (or a tag) start or end is found, the device is signalled using the following calls:
void (*begin_layer)(fz_context *, fz_device *, const char *layer_name);
void (*end_layer)(fz_context *, fz_device *);
Not all content on a given layer may necessarily be sent at once - there may be several start/end pairs with the same tag.
As an example, consider a newspaper laid out in a desktop processor. Multiple ‘stories’ on the same page may be laid out each in multiple columns of content. The PDF file produced from this may tag each column with an identifier for the story from which it came, and the stories may be interleaved with one another.
By collating only the content tagged with a given identifier (layer name), individual stories may be able to be extracted from a PDF page.
The use of tagged content will vary from application to application, following convention, but no hard and fast rules.
Paths are reference counted objects, with the implicit understanding that once more than one reference exists to a path, it will no longer be modified.
A reference to a new empty path can be created using
fz_new_path:
/*
fz_new_path: Create an empty path, and return
a reference to it.
Throws exception on failure to allocate.
*/
fz_path *fz_new_path(fz_context *ctx);
Once a path exists, commands can be added to it. The first command must always be a ‘move’.
/*
fz_moveto: Append a 'moveto' command to a path.
path: The path to modify.
x, y: The coordinate to move to.
Throws exceptions on failure to allocate.
*/
void fz_moveto(fz_context *ctx, fz_path *path, float x, float y);
Once we have moved to a point, subsequent commands can be added, such as lines, quads (quadratic beziers) and curves (cubic beziers).
/*
fz_lineto: Append a 'lineto' command to a path.
path: The path to modify.
x, y: The coordinate to line to.
Throws exceptions on failure to allocate.
*/
void fz_lineto(fz_context *ctx, fz_path *path, float x, float y);
/*
fz_quadto: Append a 'quadto' command to a path. (For a
quadratic bezier).
path: The path to modify.
x0, y0: The control coordinates for the quadratic curve.
x1, y1: The end coordinates for the quadratic curve.
Throws exceptions on failure to allocate.
*/
void fz_quadto(fz_context *ctx, fz_path *path, float x0, float y0, float x1, float y1);
/*
fz_curveto: Append a 'curveto' command to a path. (For a
cubic bezier).
path: The path to modify.
x0, y0: The coordinates of the first control point for the
curve.
x1, y1: The coordinates of the second control point for the
curve.
x2, y2: The end coordinates for the curve.
Throws exceptions on failure to allocate.
*/
void fz_curveto(fz_context *ctx, fz_path *path, float x0, float y0, float x1, float y1, float x2, float y2);
In addition, we have 2 functions for adding curves (cubic beziers)
where one of the control points is coincident with the neighbouring
endpoints. These functions mirror the usage in PDF, but offer no
benefits other than convenience as such curves are detected
automatically as part of an fz_curveto call.
/*
fz_curvetov: Append a 'curvetov' command to a path. (For a
cubic bezier with the first control coordinate equal to
the start point).
path: The path to modify.
x1, y1: The coordinates of the second control point for the
curve.
x2, y2: The end coordinates for the curve.
Throws exceptions on failure to allocate.
*/
void fz_curvetov(fz_context *ctx, fz_path *path, float x1, float y1, float x2, float y2);
/*
fz_curvetoy: Append a 'curvetoy' command to a path. (For a
cubic bezier with the second control coordinate equal to
the end point).
path: The path to modify.
x0, y0: The coordinates of the first control point for the
curve.
x2, y2: The end coordinates for the curve (and the second
control coordinate).
Throws exceptions on failure to allocate.
*/
void fz_curvetoy(fz_context *ctx, fz_path *path, float x0, float y0, float x2, float y2);
At any point after the initial move, we can close the path using
fz_closepath:
/*
fz_closepath: Close the current subpath.
path: The path to modify.
Throws exceptions on failure to allocate, and illegal
path closes.
*/
void fz_closepath(fz_context *ctx, fz_path *path);
After a path has been closed, the only acceptable next command is a move. A path need not be closed before a second or subsequent move is sent.
For details of exactly what each of these path segment types means, see “The PDF Reference Manual” or “The Postscript Language Reference Manual”.
Finally, we have one additional path construction function,
fz_rectto. This appends a rectangle to the current path.
This rectangle is equivalent to a move, 3 lines and a closepath, and so
is the one exception to the rule that paths must begin with a move (as
one is implicit within the rectangle command).
/*
fz_rectto: Append a 'rectto' command to a path.
The rectangle is equivalent to:
moveto x0 y0
lineto x1 y0
lineto x1 y1
lineto x0 y1
closepath
path: The path to modify.
x0, y0: First corner of the rectangle.
x1, y1: Second corner of the rectangle.
Throws exceptions on failure to allocate.
*/
void fz_rectto(fz_context *ctx, fz_path *path, float x0, float y0, float x1, float y1);
Finally, during path construction, the coordinate at which the
notional path cursor has reached can be read using the
fz_currentpoint function.
/*
fz_currentpoint: Return the current point that a path has
reached or (0,0) if empty.
path: path to return the current point of.
*/
fz_point fz_currentpoint(fz_context *ctx, fz_path *path);
As stated before, `fz_path`s are reference counted objects. Once one has been created, references can be created/destroyed using the standard keep/drop conventions:
/*
fz_keep_path: Take an additional reference to
a path.
No modifications should be carried out on a path
to which more than one reference is held, as
this can cause race conditions.
Never throws exceptions.
*/
fz_path *fz_keep_path(fz_context *ctx, const fz_path *path);
/*
fz_drop_path: Drop a reference to a path,
destroying the path if it is the last
reference.
Never throws exceptions.
*/
void fz_drop_path(fz_context *ctx, const fz_path *path);
A path with more than one reference is considered to be ‘frozen’ or ‘immutable’. It is not safe to modify such a path, as the other holder of a reference to it may not expect it to be being changed. That is to say that modification operations on paths are not atomic between threads.
If you have a path that you wish to be able to modify, simply call
fz_clone_path to obtain a reference to a copy of the path
that is safe to modify:
/*
fz_clone_path: Clone the data for a path.
This is used in preference to fz_keep_path when a whole
new copy of a path is required, rather than just a shared
pointer. This probably indicates that the path is about to
be modified.
path: path to clone.
Throws exceptions on failure to allocate.
*/
fz_path *fz_clone_path(fz_context *ctx, fz_path *path);
Because Paths are such a crucial part of MuPDF, and are used so widely in document content, we take particular care to allow them to be expressed and accessed efficiently.
This means that at path construction time, we spot simple cases where we can optimise the path representation. For example, a move immediately following a move can cause the first move to be dropped. Similarly, a curve with both control points coincident with the endpoints can be expressed as a line.
This means that if you read a path out after construction (see ) you cannot rely on the exact representation being the same.
In addition, after constructing a path, there are some simple things that can be done to minimise the memory used.
As paths are constructed, the data buffers within them grow. For efficiency, these grow with some slack in them, so at the end of construction there can be a non-trivial amount of space wasted.
If you intend to simply use the path, and then discard it, this does
not matter. If instead you intend to keep the path around for a while,
it may be worth calling fz_trim_path to shrink the storage
buffers as much as possible.
/*
fz_trim_path: Minimise the internal storage
used by a path.
As paths are constructed, the internal buffers
grow. To avoid repeated reallocations they
grow with some spare space. Once a path has
been fully constructed, this call allows the
excess space to be trimmed.
Never throws exceptions.
*/
void fz_trim_path(fz_context *ctx, fz_path *path);
MuPDF automatically calls this function when
fz_keep_path is called for the first time as having more
than one reference to a path is considered a good indication of it being
kept around for a while.
For cases where large numbers of paths are kept around for a long
period of time, for example in a fz_display_list (see ), it
can be advantageous to ‘pack’ paths to further minimise the space they
use.
To pack a path, first call fz_packed_path_size to obtain
the number of bytes required to pack a path:
/*
fz_packed_path_size: Return the number of
bytes required to pack a path.
Never throws exceptions.
*/
int fz_packed_path_size(const fz_path *path);
Then, call fz_pack_path with some (suitably aligned)
memory of the appropriate size to actually pack the path:
/*
fz_pack_path: Pack a path into the given block.
To minimise the size of paths, this function allows them to be
packed into a buffer with other information.
pack: Pointer to a block of data to pack the path into. Should
be aligned by the caller to the same alignment as required for
an fz_path pointer.
max: The number of bytes available in the block.
If max < sizeof(fz_path) then an exception will
be thrown. If max >= the value returned by
fz_packed_path_size, then this call will never
fail, except in low memory situations with large
paths.
path: The path to pack.
Paths can be 'unpacked', 'flat', or 'open'. Standard paths, as
created are 'unpacked'. Paths that will pack into less than max
bytes will be packed as 'flat', unless they are too large (where
large indicates that they exceed some private implementation
defined limits, currently including having more than 256
256 coordinates or commands).
Large paths are 'open' packed as a header into the given block,
plus pointers to other data blocks. Paths can be used
interchangably regardless of how they are packed.
Returns the number of bytes within the block used. Callers can
access the packed path data by casting the value of pack on
entry to be an fz_path *.
Throws exceptions on failure to allocate, or if
max < sizeof(fz_path).
*/
int fz_pack_path(fz_context *ctx, uint8_t *pack, int max, const fz_path *path);
After a successful call to fz_pack_path, the pointer to
the block of memory can be cast to an fz_path
* and used as normal.
All the path routines recognise packed paths and will use them interchangeably. Packed paths may not be modified once created, however.
Once a path has been constructed, a common operation is to apply a
transformation to it. This is equivalent to transforming every point in
the existing path. A path can be transformed using
fz_transform_path.
/*
fz_transform_path: Transform a path by a given
matrix.
path: The path to modify (must not be a packed path).
transform: The transform to apply.
Throws exceptions if the path is packed, or on failure
to allocate.
*/
void fz_transform_path(fz_context *ctx, fz_path *path, const fz_matrix *transform);
This counts as modifying a path of course, so ensure that you are the
only reference holder, or fz_clone_path it first.
Sometimes it can be desirable to know the area covered by a path. The
fz_bound_path function enables exactly this, both for
filled and stroked path. For details of the fz_stroke_state
structure, see .
/*
fz_bound_path: Return a bounding rectangle for a path.
path: The path to bound.
stroke: If NULL, the bounding rectangle given is for
the filled path. If non-NULL the bounding rectangle
given is for the path stroked with the given attributes.
ctm: The matrix to apply to the path during stroking.
r: Pointer to a fz_rect which will be used to hold
the result.
*/
fz_rect *fz_bound_path(fz_context *ctx, const fz_path *path, const fz_stroke_state *stroke, const fz_matrix *ctm, fz_rect *r);
Where filling a path simply requires details of the fill to be used,
stroking a path requires far more information; varying the thickness of
the line, or the dash pattern, or linecaps/joins used can can radically
alter its appearance. The details of these stroke attributes are passed
in a fz_stroke_state structure.
Stroke states are created and managed with reference counting using
the functions described below, but unlike other structures, the
definition of the structure itself is public. Callers are expected to
alter the different fields in the structure themselves. The sole
exception to this is the refs field, that should only be
altered using the usual fz_keep_stroke_state and
fz_drop_stroke_state mechanisms.
typedef struct fz_stroke_state_s fz_stroke_state;
typedef enum fz_linecap_e
{
FZ_LINECAP_BUTT = 0,
FZ_LINECAP_ROUND = 1,
FZ_LINECAP_SQUARE = 2,
FZ_LINECAP_TRIANGLE = 3
} fz_linecap;
typedef enum fz_linejoin_e
{
FZ_LINEJOIN_MITER = 0,
FZ_LINEJOIN_ROUND = 1,
FZ_LINEJOIN_BEVEL = 2,
FZ_LINEJOIN_MITER_XPS = 3
} fz_linejoin;
struct fz_stroke_state_s
{
int refs;
fz_linecap start_cap, dash_cap, end_cap;
fz_linejoin linejoin;
float linewidth;
float miterlimit;
float dash_phase;
int dash_len;
float dash_list[32];
};
It is hoped that the meaning of the individual fields within a
fz_stroke_state structure are self evident to anyone
working in this field. If you are unfamiliar with any of the concepts
here, see “The PDF Reference Manual” or “The Postscript Language
Reference Manual” for more details.
Most simply a reference to a stroke state structure can be obtained
by calling fz_new_stroke_state:
/*
fz_new_stroke_state: Create a new (empty) stroke state
structure (with no dash data) and return a reference to it.
Throws exception on failure to allocate.
*/
fz_stroke_state *fz_new_stroke_state(fz_context *ctx);
For stroke states that include dash information, call:
/*
fz_new_stroke_state_with_dash_len: Create a new (empty)
stroke state structure, with room for dash data of the
given length, and return a reference to it.
len: The number of dash elements to allow room for.
Throws exception on failure to allocate.
*/
fz_stroke_state *fz_new_stroke_state_with_dash_len(fz_context *ctx, int len);
Once obtained, references can be kept or dropped in the usual fashion:
/*
fz_keep_stroke_state: Take an additional reference to
a stroke state structure.
No modifications should be carried out on a stroke
state to which more than one reference is held, as
this can cause race conditions.
Never throws exceptions.
*/
fz_stroke_state *fz_keep_stroke_state(fz_context *ctx, const fz_stroke_state *stroke);
/*
fz_drop_stroke_state: Drop a reference to a stroke
state structure, destroying the structure if it is
the last reference.
Never throws exceptions.
*/
void fz_drop_stroke_state(fz_context *ctx, const fz_stroke_state *stroke);
Once more than one reference is held to a stroke state, it should be considered ‘frozen’ or ‘immutable’ as other reference holders may be confused by changes to it. Accordingly, we provide functions to ensure that we are holding a reference to an ‘unshared’ stroke state:
/*
fz_unshare_stroke_state: Given a reference to a
(possibly) shared stroke_state structure, return
a reference to an equivalent stroke_state structure
that is guaranteed to be unshared (i.e. one that can
safely be modified).
shared: The reference to a (possibly) shared structure
to unshare. Ownership of this reference is passed in
to this function, even in the case of exceptions being
thrown.
Exceptions may be thrown in the event of failure to
allocate if required.
*/
fz_stroke_state *fz_unshare_stroke_state(fz_context *ctx, fz_stroke_state *shared);
/*
fz_unshare_stroke_state_with_dash_len: Given a reference to a
(possibly) shared stroke_state structure, return a reference
to a stroke_state structure (with room for a given amount of
dash data) that is guaranteed to be unshared (i.e. one that
can safely be modified).
shared: The reference to a (possibly) shared structure
to unshare. Ownership of this reference is passed in
to this function, even in the case of exceptions being
thrown.
Exceptions may be thrown in the event of failure to
allocate if required.
*/
fz_stroke_state *fz_unshare_stroke_state_with_dash_len(fz_context *ctx, fz_stroke_state *shared, int len);
Finally, we have a simple function to clone a stroke state and return a new reference to it:
/*
fz_clone_stroke_state: Create an identical stroke_state
structure and return a reference to it.
stroke: The stroke state reference to clone.
Exceptions may be thrown in the event of a failure to
allocate.
*/
fz_stroke_state *fz_clone_stroke_state(fz_context *ctx, fz_stroke_state *stroke);
Given a path, it can be useful to be able to read it out again. MuPDF uses this internally in a output devices such as the PDF or SVG devices (see or ) to convert paths to a new representation, and in the draw device (see ) for rendering.
To isolate callers from the implementation specifics of paths, MuPDF
offers a mechanism to ‘walk’ a fz_path, getting a callback
for each command in the path.
typedef struct
{
/* Compulsory ones */
void (*moveto)(fz_context *ctx, void *arg, float x, float y);
void (*lineto)(fz_context *ctx, void *arg, float x, float y);
void (*curveto)(fz_context *ctx, void *arg, float x1, float y1, float x2, float y2, float x3, float y3);
void (*closepath)(fz_context *ctx, void *arg);
/* Optional ones */
void (*quadto)(fz_context *ctx, void *arg, float x1, float y1, float x2, float y2);
void (*curvetov)(fz_context *ctx, void *arg, float x2, float y2, float x3, float y3);
void (*curvetoy)(fz_context *ctx, void *arg, float x1, float y1, float x3, float y3);
void (*rectto)(fz_context *ctx, void *arg, float x1, float y1, float x2, float y2);
} fz_path_walker;
/*
fz_walk_path: Walk the segments of a path, calling the
appropriate callback function from a given set for each
segment of the path.
path: The path to walk.
walker: The set of callback functions to use. The first
4 callback pointers in the set must be non-NULL. The
subsequent ones can either be supplied, or can be left
as NULL, in which case the top 4 functions will be
called as appropriate to simulate them.
arg: An opaque argument passed in to each callback.
Exceptions will only be thrown if the underlying callback
functions throw them.
*/
void fz_walk_path(fz_context *ctx, const fz_path *path, const fz_path_walker *walker, void *arg);
This function is called by giving a pointer to a structure containing callback functions, one for each type of path segment type. The function will walk the path structure and call the appropriate function pointer for each segment of the path in turn.
Callers of this function should not rely on getting exactly the same sequence of path segments out as was used to construct the path; the internal representation may have been optimised to an equivalent form on construction, and this will be reflected in the callbacks received. The path passed back will however be entirely identical (modulo possible infinitesimal rounding issues).
For example, MuPDF is capable of spotting that a cubic or quadratic bezier is actually a line; in such cases it may represent it as a line internally, saving memory and processing power.
Not all path consumers can cope with the full range of segment types that MuPDF natively supports, so some of the callback entries may be left blank (i.e. set to NULL). Rather than calling such an entry, MuPDF will decompose the path segment into one of the more basic types.
For example, if a path contains a quadratic segment and the
quadto callback entry is NULL, MuPDF will automatically
decompose it to a bezier segment and call the curveto entry
instead.
The primary use of a fz_image is to allow a rendered
pixmap to be retrieved. This is done by calling:
/*
fz_get_pixmap_from_image: Called to get a handle to a pixmap from
an image.
image: The image to retrieve a pixmap from.
subarea: The subarea of the image that we actually care about (or
NULL to indicate the whole image).
trans: Optional, unless subarea is given. If given, then on entry
this is the transform that will be applied to the complete image.
It should be updated on exit to the transform to apply to the given
subarea of the image. This is used to calculate the desired
width/height for subsampling.
w: If non-NULL, a pointer to an int to be updated on exit to the
width (in pixels) that the scaled output will cover.
h: If non-NULL, a pointer to an int to be updated on exit to the
height (in pixels) that the scaled output will cover.
Returns a non NULL pixmap pointer. May throw exceptions.
*/
fz_pixmap *fz_get_pixmap_from_image(fz_context *ctx, fz_image *image, const fz_irect *subarea, fz_matrix *trans, int *w, int *h);
Frequently this will involve decoding the image from its source data, so should be considered a potentially expensive call, both in terms of CPU time, and memory usage.
To minimise the impact of such decodes, `fz_image`s make use of the
Store (see ) to cache decoded versions in. This means that (subject to
enough memory being available) repeated calls to get a
fz_pixmap from the same fz_image (with the
same parameters) will return the same fz_pixmap each time,
with no further decode being required.
The usual reference counting behaviour applies to `fz_image`s, with
fz_keep_image and fz_drop_image claiming and
releasing references respectively.
Depending on the size at which a fz_image is to be used,
it may not be worth decoding it at full resolution; instead, decoding it
at a smaller size can save memory (and frequently time). In addition,
subsequent rendering operations can often be faster due to having to
handle fewer pixels for no quality loss in the final output.
To facilitate this, `fz_image`s will subsample images as appropriate.
Subsampling involves an image being decoded to a size an integer power
of 2 smaller than their native size. For instance, if an image has a
native size of 400x300, and is to be rendered to a final size of 40x30,
fz_get_pixmap_from_image may subsample the returned image
by up to 8 in each direction, resulting in a 50x37 image.
Subsequent operations (such as smooth scaling and rendering) will proceed much faster due to fewer pixels being involved, and around one sixteenth of the memory will be required.
Various different implementations of fz_image exist
within MuPDF.
The fz_compressed_image structure is a specialisation of
fz_image, that holds the source data for an image in a
fz_compressed_buffer. This is the usual form for images
created from PDF and XPS files.
The data for a compressed image can be retrieved by calling:
fz_compressed_buffer *fz_compressed_image_buffer(fz_context *ctx, fz_image *image);
If the supplied fz_image is not a
fz_compressed_image then it will return
NULL.
The fz_pixmap_image structure is a specialisation of
fz_image, that has a fz_pixmap as its source
data. This exists to allow fz_pixmaps from other sources to
be easily fed into the MuPDF rendering engine.
As described in Part 1 (), the central text object in MuPDF is
fz_text. It represents blocks of bidirectional text,
carrying (potentially) both details of the underlying unicode
characters, and the specific glyphs to be used to render them.
typedef struct fz_text_s fz_text;
Text objects are reference counted, with the implicit understanding that once more than one reference exists to an object, it will no longer be modified.
Empty fz_text objects can be created using the
fz_new_text call:
/*
fz_new_text: Create a new empty fz_text object.
Throws exception on failure to allocate.
*/
fz_text *fz_new_text(fz_context *ctx);
Additional references can be taken/released in the usual manner:
/*
fz_keep_text: Add a reference to an fz_text.
text: text object to keep a reference to.
Return the same text pointer.
*/
fz_text *fz_keep_text(fz_context *ctx, const fz_text *text);
/*
fz_drop_text: Drop a reference to the object, freeing
if if is the last one.
text: Object to drop the reference to.
*/
void fz_drop_text(fz_context *ctx, const fz_text *text);
Once created, characters can be added to the fz_text
object either singly:
/*
fz_show_glyph: Add a glyph/unicode value to a text object.
text: Text object to add to.
font: The font the glyph should be added in.
trm: The transform to use for the glyph.
glyph: The glyph id to add.
unicode: The unicode character for the glyph.
wmode: 1 for vertical mode, 0 for horizontal.
bidi_level: The bidirectional level for this glyph.
markup_dir: The direction of the text as specified in the
markup.
language: The language in use (if known, 0 otherwise)
(e.g. FZ_LANG_zh_Hans).
Throws exception on failure to allocate.
*/
void fz_show_glyph(fz_context *ctx, fz_text *text, fz_font *font, const fz_matrix *trm, int glyph, int unicode, int wmode, int bidi_level, fz_bidi_direction markup_dir, fz_text_language language);
or a (unicode) string at a time:
/*
fz_show_string: Add a UTF8 string to a text object.
text: Text object to add to.
font: The font the string should be added in.
trm: The transform to use. Will be updated according
to the advance of the string on exit.
s: The utf-8 string to add.
wmode: 1 for vertical mode, 0 for horizontal.
bidi_level: The bidirectional level for this glyph.
markup_dir: The direction of the text as specified in the
markup.
language: The language in use (if known, 0 otherwise)
(e.g. FZ_LANG_zh_Hans).
Throws exception on failure to allocate.
*/
void fz_show_string(fz_context *ctx, fz_text *text, fz_font *font, fz_matrix *trm, const char *s, int wmode, int bidi_level, fz_bidi_direction markup_dir, fz_text_language language);
Once a fz_text object has been created we can measure
the area it will cover on the page:
/*
fz_bound_text: Find the bounds of a given text object.
text: The text object to find the bounds of.
stroke: Pointer to the stroke attributes (for stroked
text), or NULL (for filled text).
ctm: The matrix in use.
r: pointer to storage for the bounds.
Returns a pointer to r, which is updated to contain the
bounding box for the text object.
*/
fz_rect *fz_bound_text(fz_context *ctx, const fz_text *text, const fz_stroke_state *stroke, const fz_matrix *ctm, fz_rect *r);
As stated before, fz_text objects are referenced
counted. Changes or manipulations cannot safely be carried out on an
object which might be shared with someone else, so we provide a
mechanism to clone an object. Once cloned an object is guaranteed to be
safe to modify.
/*
fz_clone_text: Clone a text object.
text: The text object to clone.
Throws an exception on allocation failure.
*/
fz_text *fz_clone_text(fz_context *ctx, const fz_text *text);
Some formats include a declaration of which language is being used for a given piece of text. This can be used to influence aspects of the text layout, including the exact choice of glyphs used in a given font. While we make relatively little use of this at present, we try to preserve the information as part of our philosophy of not losing any information unnecessarily.
Accordingly, we use ISO 639 language specification strings, for example:
typedef enum fz_text_language_e
{
FZ_LANG_UNSET = 0,
FZ_LANG_ur = FZ_LANG_TAG2('u','r'),
FZ_LANG_urd = FZ_LANG_TAG3('u','r','d'),
FZ_LANG_ko = FZ_LANG_TAG2('k','o'),
FZ_LANG_ja = FZ_LANG_TAG2('j','a'),
FZ_LANG_zh = FZ_LANG_TAG2('z','h'),
FZ_LANG_zh_Hans = FZ_LANG_TAG3('z','h','s'),
FZ_LANG_zh_Hant = FZ_LANG_TAG3('z','h','t'),
} fz_text_language;
To save space we pack these into 15 bits. Accordingly, we provide a way to pack/unpack these to/from the more normal string representations:
/*
Convert ISO 639 (639-{1,2,3,5}) language specification
strings losslessly to a 15 bit fz_text_language code.
No validation is carried out. Obviously invalid (out
of spec) codes will be mapped to FZ_LANG_UNSET, but
well-formed (but undefined) codes will be blithely
accepted.
*/
fz_text_language fz_text_language_from_string(const char *str);
/*
Recover ISO 639 (639-{1,2,3,5}) language specification
strings losslessly from a 15 bit fz_text_language code.
No validation is carried out. See note above.
*/
char *fz_string_from_text_language(char str[8], fz_text_language lang);
A fz_text structure represents a block of text. At the
lowest level the constituents of a block are `fz_text_item`s.
typedef struct fz_text_item_s fz_text_item;
struct fz_text_item_s
{
float x, y;
int gid; /* -1 for one gid to many ucs mappings */
int ucs; /* -1 for one ucs to many gid mappings */
};
The items can be thought of as the individual ‘characters’ that make
up the display, together with their position. Where possible, we attempt
to give both the glyph id (gid) and the unicode value
(ucs) for the character, but there are various cases where
a 1-1 mapping is not possible.
Some unicode characters can result in a string of glyphs. The glyph
ids will be sent in a series of `fz_text_item`s, in which the first
ucs value will be the source unicode character, and
subsequent ones will be -1.
Some sequences of unicode characters can result in a single glyph.
Again, a sequence of `fz_text_item`s will be sent listing the unicode
values, but all but the first item will have the gid value
set to -1.
In more complex cases, sequences of unicode characters can be
transformed into a sequence of glyphs, with no direct correspondence
between the source text and the output characters. In this case as many
`fz_text_item`s as are required are used, with either the
gid or ucs values padded out by -1s as
necessary.
Different input formats offer the text in different forms. With PDF, the data within the file is (typically) in the form of glyph ids, and mechanisms are optionally provided to infer unicode values from them. Glyphs are sent in any order, and absolutely positioned on the page.
With XPS the input can be either in the form of unicode or glyph ids, and directionality information is encoded in the file. This means that the logical ordering of the glyphs is well defined.
Some formats, such as EPUB and HTML, send unicode text with even less positioning information, and rely on the interpreter to perform layout. Part of this process involves inferring directional information from the source text, and then using shaping mechanisms embedded within the font to do complex conversions to give the final positioned glyph sequences.
In all such cases MuPDF will preserve the logical ordering of the unicode entries, at the cost of drawing glyphs non-monotonically onto the page.
Sequences of `fz_text_item`s that share the same characteristics are gathered together into `fz_text_span`s:
struct fz_text_span_s
{
fz_font *font;
fz_matrix trm;
unsigned wmode : 1; /* 0 horizontal, 1 vertical */
unsigned bidi_level : 7; /* The bidirectional level of text */
unsigned markup_dir : 2; /* The direction of text as marked in the original document */
unsigned language : 15; /* The language as marked in the original document */
int len, cap;
fz_text_item *items;
fz_text_span *next;
};
Sequences of these spans are then gathered up into a linked list
rooted in a fz_text.
struct fz_text_s
{
int refs;
fz_text_span *head, *tail;
};
As described in , fz_shade is an encapsulation of the
information required to define a PDF shading. This is essentially a
superset of all the shading types provided by our supported document
handlers. If we ever meet a format that requires features not provided
in PDF, then fz_shade will be extended to cope.
typedef struct fz_shade_s
{
fz_storable storable;
fz_rect bbox; /* can be fz_infinite_rect */
fz_colorspace *colorspace;
fz_matrix matrix; /* matrix from pattern dict */
int use_background; /* background color for fills but not 'sh' */
float background[FZ_MAX_COLORS];
int use_function;
float function[256][FZ_MAX_COLORS + 1];
int type; /* function, linear, radial, mesh */
union
{
struct
{
int extend[2];
float coords[2][3]; /* (x,y,r) twice */
} l_or_r;
struct
{
int vprow;
int bpflag;
int bpcoord;
int bpcomp;
float x0, x1;
float y0, y1;
float c0[FZ_MAX_COLORS];
float c1[FZ_MAX_COLORS];
} m;
struct[]
{
fz_matrix matrix;
int xdivs;
int ydivs;
float domain[2][2];
float *fn_vals;
} f;
} u;
fz_compressed_buffer *buffer;
} fz_shade;
Currently, there is no defined API for creating a shading due to the
public nature of the structure. Just call
fz_malloc_struct(ctx, fz_shade) and initialise
the fields accordingly.
We may look to add convenience functions in the future, as this is likely to be desirable for the JNI (and other) bindings.
Shading objects are reference counted, with the implicit
understanding that once more than one reference exists to a
fz_shade, it will no longer be modified.
Additional references can be taken and dropped as usual:
/*
fz_keep_shade: Add a reference to an fz_shade.
shade: The reference to keep.
Returns shade.
*/
fz_shade *fz_keep_shade(fz_context *ctx, fz_shade *shade);
/*
fz_drop_shade: Drop a reference to an fz_shade.
shade: The reference to drop. If this is the last
reference, shade will be destroyed.
*/
void fz_drop_shade(fz_context *ctx, fz_shade *shade);
We also provide a function to process a given shading, by calling:
Once created, we can ask for the bounds of a given shade under a given transformation. This can sometimes be infinite.
/*
fz_bound_shade: Bound a given shading.
shade: The shade to bound.
ctm: The transform to apply to the shade before bounding.
r: Pointer to storage to put the bounds in.
Returns r, updated to contain the bounds for the shading.
*/
fz_rect *fz_bound_shade(fz_context *ctx, fz_shade *shade, const fz_matrix *ctm, fz_rect *r);
For devices that require shadings as rasterised objects, we provide a
function to paint a shading to a fz_pixmap:
/*
fz_paint_shade: Render a shade to a given pixmap.
shade: The shade to paint.
ctm: The transform to apply.
dest: The pixmap to render into.
bbox: Pointer to a bounding box to limit the rendering
of the shade.
*/
void fz_paint_shade(fz_context *ctx, fz_shade *shade, const fz_matrix *ctm, fz_pixmap *dest, const fz_irect *bbox);
This is currently used by the draw and SVG devices.
For devices that wish to get access to a higher level representation of a shading, but do not wish to access the internals of a shading directly, we provide a function to decompose a shading to a mesh.
This is called with functions to ‘prepare’ and ‘fill’ vertices respectively. The mesh is decomposed to triangles internally, each vertex is ‘prepared’ and each triangle ‘filled’ in turn.
The ordering of these calls is not guaranteed, other than the fact that a vertex will always be prepared before it is used as part of a triangle to be filled.
typedef struct fz_vertex_s fz_vertex;
struct fz_vertex_s
{
fz_point p;
float c[FZ_MAX_COLORS];
};
/*
fz_shade_prepare_fn: Callback function type for use with
fz_process_shade.
arg: Opaque pointer from fz_process_shade caller.
v: Pointer to a fz_vertex structure to populate.
c: Pointer to an array of floats to use to populate v.
*/
typedef void (fz_shade_prepare_fn)(fz_context *ctx, void *arg, fz_vertex *v, const float *c);
/*
fz_shade_process_fn: Callback function type for use with
fz_process_shade.
arg: Opaque pointer from fz_process_shade caller.
av, bv, cv: Pointers to a fz_vertex structure describing
the corner locations and colors of a triangle to be
filled.
*/
typedef void (fz_shade_process_fn)(fz_context *ctx, void *arg, fz_vertex *av, fz_vertex *bv, fz_vertex *cv);
/*
fz_process_shade: Process a shade, using supplied callback
functions. This decomposes the shading to a mesh (even ones
that are not natively meshes, such as linear or radial
shadings), and processes triangles from those meshes.
shade: The shade to process.
ctm: The transform to use
prepare: Callback function to 'prepare' each vertex.
This function is passed an array of floats, and populates
an fz_vertex structure.
process: This function is passed 3 pointers to vertex
structures, and actually performs the processing (typically
filling the area between the vertexes).
process_arg: An opaque argument passed through from caller
to callback functions.
*/
void fz_process_shade(fz_context *ctx, fz_shade *shade, const fz_matrix *ctm,
fz_shade_prepare_fn *prepare, fz_shade_process_fn *process, void *process_arg);
This function is used internally as part of
fz_paint_shade, but is intended to also allow extraction of
arbitrary shading data.
=== Stream Internals
The concepts embodied by a fz_stream object, and details
of how to use them were given in . The above, relatively rich, set of
functions are implemented on a fairly simple basic structure.
To implement your own fz_stream, simply define a
creation function, of the form:
fz_stream *fz_new_stream_foo(fz_context *ctx, <more parameters here>)
{
fz_stream *stm;
foo_state *state;
state = <create structure to hold foo specific stream state>
stm = fz_new_stream(ctx, state, foo_next, foo_close);
<set stm->seek if required>
<set stm->meta if required>
return stm;
}
Note that some fz_try/fz_catch-ery may be
required as part of the setup for state.
The hard work for this function is done using
fz_new_stream, and two ‘foo’ specific functions,
foo_next and foo_close. First let’s look at
fz_new_stream:
/*
fz_new_stream: Create a new stream object with the given
internal state and function pointers.
state: Internal state (opaque to everything but implementation).
next: Should provide the next set of bytes (up to max) of stream
data. Return the number of bytes read, or EOF when there is no
more data.
close: Should clean up and free the internal state. May not
throw exceptions.
*/
fz_stream *fz_new_stream(fz_context *ctx, void *state, fz_stream_next_fn *next, fz_stream_close_fn *close);
This creates the main fz_stream structure, populates it
with the given pointers (state, foo_next and
foo_close) and sets the internal buffer pointers up to
indicate an empty buffer.
As soon as anyone tries to read from the buffer (or to find out how
many bytes are available), the MuPDF stream functions will cause
foo_next to be called. This is a function of the following
type:
/*
fz_stream_next_fn: A function type for use when implementing
fz_streams. The supplied function of this type is called
whenever data is required, and the current buffer is empty.
stm: The stream to operate on.
max: a hint as to the maximum number of bytes that the caller
needs to be ready immediately. Can safely be ignored.
Returns -1 if there is no more data in the stream. Otherwise,
the function should find its internal state using stm->state,
refill its buffer, update stm->rp and stm->wp to point to the
start and end of the new data respectively, and then
"return *stm->rp++".
*/
typedef int (fz_stream_next_fn)(fz_context *ctx, fz_stream *stm, size_t max);
When the stream is closed, the foo_close function will
be called. This should be a function of type
fz_stream_close_fn:
/*
fz_stream_close_fn: A function type for use when implementing
fz_streams. The supplied function of this type is called
when the stream is closed, to release the stream specific
state information.
state: The stream state to release.
*/
In our example, if the state was created by a simple
fz_malloc_struct(ctx, foo_state) then
foo_close might be as simple as a fz_free(ctx,
state). If the internal state of the stream is more complex
then the destructor will be similarly more complex.
These three functions (creation, next and close) are all that is required to define a stream.
Optionally, you can also define a seek and/or a meta function, using functions of the following types:
/*
fz_stream_seek_fn: A function type for use when implementing
fz_streams. The supplied function of this type is called when
fz_seek is requested, and the arguments are as defined for
fz_seek.
The stream can find its private state in stm->state.
*/
typedef void (fz_stream_seek_fn)(fz_context *ctx, fz_stream *stm, fz_off_t offset, int whence);
/*
fz_stream_meta_fn: A function type for use when implementing
fz_streams. The supplied function of this type is called when
fz_meta is requested, and the arguments are as defined for
fz_meta.
The stream can find its private state in stm->state.
*/
typedef int (fz_stream_meta_fn)(fz_context *ctx, fz_stream *stm, int key, int size, void *ptr);
The concepts embodied by a fz_output object, and details
of how to use them were given in . The above, relatively rich, set of
functions are implemented on a fairly simple basic structure.
To implement your own fz_output, simply define a
creation function of the form:
fz_output *fz_new_output_foo(fz_context *ctx, <more parameters here>)
{
fz_output *out = fz_new_output(ctx, <state>, foo_write, foo_close);
<optionally set out->seek = foo_seek>
<optionally set out->tell = foo_tell>
return out;
}
This has parallels with the implementation of `fz_stream`s, but is not quite identical.
If state needs no destruction, then we can use NULL in
place of foo_close. Otherwise foo_close should
be a function of type:
/*
fz_output_close_fn: A function type for use when implementing
fz_outputs. The supplied function of this type is called
when the output stream is closed, to release the stream specific
state information.
state: The output stream state to release.
*/
typedef void (fz_output_close_fn)(fz_context *ctx, void *state);
This can be as simple as doing fz_free(ctx,
state), or (depending on the complexity of the state
structure) can require more involved operations to clean up.Many
fz_output implementations rely on close being called to
ensure the output is correctly flushed, and no data lost.
The most important function and the only non-optional one is
foo_write. This is a function of type:
/*
fz_output_write_fn: A function type for use when implementing
fz_outputs. The supplied function of this type is called
whenever data is written to the output.
state: The state for the output stream.
data: a pointer to a buffer of data to write.
n: The number of bytes of data to write.
*/
typedef void (fz_output_write_fn)(fz_context *ctx, void *state, const void *data, size_t n);
Optionally we can choose to have our output stream support
fz_seek_output and fz_tell_output. To do that
we must implement foo_seek and foo_tell
respectively, and assign them out->seek and
out->tell during creation.
/*
fz_output_seek_fn: A function type for use when implementing
fz_outputs. The supplied function of this type is called when
fz_seek_output is requested.
state: The output stream state to seek within.
offset, whence: as defined for fs_seek_output.
*/
typedef void (fz_output_seek_fn)(fz_context *ctx, void *state, fz_off_t offset, int whence);
/*
fz_output_tell_fn: A function type for use when implementing
fz_outputs. The supplied function of this type is called when
fz_tell_output is requested.
state: The output stream state to report on.
Returns the offset within the output stream.
*/
typedef size_t (fz_output_tell_fn)(fz_context *ctx, void *state);
In , we were introduced to the basic Colorspaces available within MuPDF. Here we describe how they work internally, and how new colorspaces can be implemented by document handler authors.
Colorspaces are complicated slightly by the need to cope with both ICC-enabled and ICC-disabled workflows.
The first and most basic colorspace creation method is for creating a non-ICC based colorspace, by calling:
fz_colorspace *fz_new_colorspace(
fz_context *ctx,
const char *name,
enum fz_colorspace_type type,
int flags,
int n,
fz_colorspace_convert_fn *to_ccs,
fz_colorspace_convert_fn *from_ccs,
fz_colorspace_base_fn *base,
fz_colorspace_clamp_fn *clamp,
fz_colorspace_destruct_fn *destruct,
void *data,
size_t size);
The name parameter is a pointer to a (short) ASCII
string describing the colorspace, and n is the number of
colorants in the space.
The type of the colorspace should be chosen as one of
the following types (which should be consistent with the value of
n chosen):
enum fz_colorspace_type
{
FZ_COLORSPACE_NONE,
FZ_COLORSPACE_GRAY,
FZ_COLORSPACE_RGB,
FZ_COLORSPACE_BGR,
FZ_COLORSPACE_CMYK,
FZ_COLORSPACE_LAB,
FZ_COLORSPACE_INDEXED,
FZ_COLORSPACE_SEPARATION,
};
The flags value for is the logical or of a selection of
values from the following enum:
enum
{
FZ_COLORSPACE_IS_DEVICE = 1,
FZ_COLORSPACE_IS_ICC = 2,
FZ_COLORSPACE_IS_CAL = 4,
FZ_COLORSPACE_LAST_PUBLIC_FLAG = 4,
};
MuPDF uses some extra bits internally, so unknown bits should be considered private.
If the colorspace requires any private data (perhaps a palette for an
indexed space), then an opaque pointer can be passed as
data. A function to destroy this data when the colorspace
reference count reaches zero should be passed as
destruct.
Colorspaces are placed into the Store, so some measure of the size of
their data is required - the size in bytes of the colorspaces extra data
should be passed as size.
If this colorspace is based on another one then a function to return
a borrowed reference to the underlying space should be supplied as
base. For instance, an indexed space with an RGB palette
would pass a function that returns fz_device_rgb.
This leaves the 3 functions that do the heavy lifting.
The to_ccs parameter should be a function that takes
n colorant values in the colorspace, and returns them as
RGB values.
The from_ccs parameter should be a function that takes
RGB colorant values, and returns them as n colorant values
in the colorspace.
Finally, the clamp field should be a function that takes
n colorant values in the colorspace, and clamps them into
the appropriate range.
If you have an ICC profile for your colorspace, then you can call one of these functions:
fz_colorspace *fz_new_icc_colorspace(
fz_context *ctx,
const char *name,
int num,
fz_buffer *buf);
fz_colorspace *fz_new_icc_colorspace_from_file(
fz_context *ctx,
const char *name,
const char *path);
fz_colorspace *fz_new_icc_colorspace_from_stream(
fz_context *ctx,
const char *name,
fz_stream *in);
They all load the ICC profile from the specified source, and create
the ICC based fz_colorspace.
Unfortunately, in non-ICC based workflows, ICC profiles can’t be
loaded. This means that document handlers have to be prepared to ‘fall
back’ to a non-ICC based approximation. This has to be done at the
document handler level; for example the PDF agent calls
fz_get_cmm_engine, and if it returns NULL, drops back to
the alternate specified space.
One final route to create colorspaces exists, that of creating them from given calibration settings. This builds upon the ICC workflow, so again, should only be used in the ICC-workflow case.
fz_colorspace *fz_new_cal_colorspace(
fz_context *ctx,
const char *name,
float *wp,
float *bp,
float *gamma,
float *matrix);
MuPDF can optionally make use of a color management engine to offer a fully color managed workflow.
Its use of the engine is encapsulated within the
fz_cmm_engine structure. Currently we provide an
implementation of this structure using a modified version of LCMS2
(known as LCMS2MT), but systems with other CMM engines in already can
use those instead by reimplementing the functions therein.
By default, on start-up, MuPDF has no color management engine enabled. This keeps the library size down (and performance up!) for people who do not wish to use it.
The relevant functions are:
/*
fz_set_cmm_engine: Set the color management engine to
be used. This should only ever be called on the "base"
context before cloning it, and before opening any files.
Attempting to change the engine in use once a file has
been opened, or to use different color management engine
for the same file in different threads will lead to
undefined behaviour, including crashing.
Using different ICC engines for different files using
different sets of fz_contexts should theoretically be
possible.
*/
void fz_set_cmm_engine(fz_context *ctx, const fz_cmm_engine *engine);
/*
Currently we only provide a single color management
engine, based on a (modified) LCMS2.
An unmodified LCMS2 should work too, but only when restricted
to a single thread.
*/
extern fz_cmm_engine fz_cmm_engine_lcms;
Thus to enable the color managed workflow using LCMS, call:
fz_set_cmm_engine(ctx, &fz_cmm_engine_lcms);
It is best to do this immediately after creating the base context.
It is possible to switch between ICC and non-ICC workflows in the same instance of MuPDF (and even to use the two simultaneously). It is, however, not generally possible to swap a given context once operations on that context have started. This is because any outstanding `fz_colorspace`s (such as those found within the store) will still refer to the wrong color management implementation!
Which fonts are built into MuPDF is a vexed question that will very much depend upon exactly where you got your MuPDF library, and what options were used to build it. While MuPDF is supplied from the authors with a wide range of fonts, the decision about which of these should be built in is left to the builder. This allows the size of the resultant library to be tuned; there is a trade-off to be made between the number of fonts included (and hence the language/script coverage) and the size of the shipped binary.
In many typographical applications, if a given glyph cannot be located for display (perhaps because the required font is not on a system), it may be rendered as a empty box. Such boxes are known informally as Tofu.
MuPDF tends not to display such boxes, but the notion of Tofu corresponding to “glyphs not existing" is carried over.
Specifically, while MuPDF is supplied with a large number of fonts, giving the best possible coverage for scripts/languages from across the world, we allow builders of MuPDF to customise the resultant library by omitting (or “Tofuing") particular sets of fonts.
This is done by building the library with a range of different
predefines to the C compiler, all beginning TOFU_.
Broadly the fonts supplied fall into the following categories:
The PDF standard requires all viewers to provide 14 ’standard’ fonts (or metric-compatible clones thereof); Courier, Courier-Oblique, Courier-Bold, Courier-BoldOblique, Helvetica, Helvetica-Oblique, Helvetica-Bold, Helvetica-BoldOblique, Times-Roman, Times-Italic, Times-Bold, Times-BoldItalic, Symbol and ZapfDingbats. Accordingly, MuPDF is supplied with equivalent font families (Nimbus Mono, Nimbus Sans, Nimbus Roman, Standard Symbols, and Dingbats) for these fonts that answer to the standard names.
It is extremely unlikely that any builder of a general purpose MuPDF library will choose to leave these fonts out of a distribution, as many PDF files rely (quite reasonably) on them being available.
Nonetheless, if a builder is in control of the exact set of files that will be read by MuPDF (perhaps for a system where content is tightly controlled, and made to specific standards with all the fonts embedded) it is possible for MuPDF to be built and used without any fonts embedded.
This can be achieved by building with TOFU_BASE14. We
only recommend this for experienced users who are in control of the
content to be displayed.
Charis SIL is supplied and is used as our default for ebook reading.
This font can be omitted from builds by building with
TOFU_SIL.
Support for Chinese, Japanese, Korean and Vietnamese scripts (CJKV or CJK for short) is given by default by the “Source Han Serif Regular" font collection. This has 4 subfonts embedded within a single TrueType collection.
This collection can be omitted from builds by building with
TOFJ_CJK, TOFU_CJK_EXT or
TOFU_CJK_LANG.
Google has produced a range of fonts that offer exceptional coverage for scripts/languages worldwide. The idea of these fonts is that with them, you should see “no tofu". Accordingly, these are know as the “noto" fonts.
MuPDF provides a huge number of these, too many to list here. These provide great coverage, at the expense of a significant size taken in the built library.
Many builders choose to eliminate these, by building with
TOFU_NOTO defined.
Noto Serif is supplied as a“fallback" font. It provides reasonable coverage for non-Latin, non-CJKV glyphs, so is useful as a “last resort" for content that needs glyphs that fall outside of the "base 14" fonts.
This font can be omitted from builds by building with
TOFU_NOTO.
Additionally, if built with TOFU_CJK_LANG, MuPDF
includes the DroidSansFallbackFull font. This provides decent coverage
for glyphs used in CJK languages, and will be used as a font of last
resort given that Source Han Serif Regular is not included.
If MuPDF is built with TOFU_CJK_EXT, then MuPDF will
include DroidSansFallback (a smaller version of DroidSansFallbackFull)
instead. This provides worse coverage for CJK glyphs, but for a smaller
size.
Finally, if MuPDF is built with TOFU_CJK then even
DroidSansFallback will be omitted, leaving a system that cannot render
any CJK glyphs at all, unless the font in question is embedded within
the source PDF file.
The easiest way to customise the set of fonts included within a build
of MuPDF is to use the TOFU_… build predefines described
above. This allows fonts to omitted from the build.
Further customisation (both adding and subtracting fonts) is possible with some more work, but this requires some source code alteration.
The source/fitz/font-table.h file lists the fonts that
are to be made available to MuPDF. Remove a line from this file, and
that font will not be available in the built library.
The ordering of fonts within font-table.h is important; it is searched in a linear fashion, and the first match for any given query found. This means, for example, that fonts intended to provide support for a specific language with a given script should be listed before fonts that offer support for any language with that script.
To add new fonts, they must first be added to this file, and then the build scripts must be updated to include the font itself. Note that many fonts appear multiple times in the table, either providing different scripts/languages, or to allow each font to respond to multiple different names.
Updating the build scripts for new fonts depends on the platform you are building for.
The MSVC solution mupdf.sln contains a
libresources project. The fonts to be included in the build
are included as sources here. Simply add new fonts to this project, and
they should be included automatically on the next build.
Note that the symbol under which the font appears in the build
depends upon the path to the font name, so it is best to follow the
pattern provided by the existing fonts;
resources/fonts/<foundry name>/<font
name>.<suffix>.
The Makefile contains a section that sets the
FONT_BIN macro to a list of files found from files within
resources/fonts using wildcards. Either put the new fonts
to be included into this directory, or extend FONT_BIN to
include the source for your font.
Note that the name under which the font appears in the build depends
upon the path to the font name, so it is best to follow the pattern
provided by the existing fonts; resources/fonts/<foundry
name>/<font name>.<suffix>.