context.h File Reference

#include "mupdf/fitz/version.h"
#include "mupdf/fitz/system.h"
#include "mupdf/fitz/geometry.h"

Include dependency graph for context.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	fz_alloc_context
struct	fz_locks_context
struct	fz_string
struct	fz_error_stack_slot
struct	fz_error_context
struct	fz_warn_context
struct	fz_aa_context
struct	fz_activity_context
struct	fz_context

Macros
#define	FZ_VERBOSE_EXCEPTIONS   0
#define	fz_var(var)
#define	fz_try(ctx)
#define	fz_always(ctx)
#define	fz_catch(ctx)
#define	FITZ_DEBUG_LOCKING
#define	fz_new_context(alloc, locks, max_store)
#define	fz_malloc_struct(CTX, TYPE)
#define	fz_malloc_struct_array(CTX, N, TYPE)
#define	fz_malloc_array(CTX, COUNT, TYPE)
#define	fz_realloc_array(CTX, OLD, COUNT, TYPE)
#define	fz_malloc_flexible(ctx, T, M, count)
#define	fz_realloc_flexible(ctx, p, T, M, count)
#define	fz_pool_alloc_flexible(ctx, pool, T, M, count)
#define	fz_sizeof_flexible(T, M, count)
#define	fz_cstring_from_string(A)
#define	FZ_JMPBUF_ALIGN   32
#define	fz_keep_imp(C, P, R)
#define	fz_keep_imp8(C, P, R)
#define	fz_keep_imp16(C, P, R)
#define	fz_keep_imp_locked(C, P, R)
#define	fz_keep_imp8_locked(C, P, R)
#define	fz_drop_imp(C, P, R)
#define	fz_drop_imp8(C, P, R)
#define	fz_drop_imp16(C, P, R)

Typedefs
typedef struct fz_font_context	fz_font_context
typedef struct fz_hyph_context	fz_hyph_context
typedef struct fz_colorspace_context	fz_colorspace_context
typedef struct fz_style_context	fz_style_context
typedef struct fz_tuning_context	fz_tuning_context
typedef struct fz_store	fz_store
typedef struct fz_glyph_cache	fz_glyph_cache
typedef struct fz_document_handler_context	fz_document_handler_context
typedef struct fz_archive_handler_context	fz_archive_handler_context
typedef struct fz_output	fz_output
typedef struct fz_context	fz_context
typedef void	fz_error_cb(void *user, const char *message)
typedef void	fz_warning_cb(void *user, const char *message)
typedef void	fz_tune_image_decode_fn(void *arg, int w, int h, int l2factor, fz_irect *subarea)
typedef int	fz_tune_image_scale_fn(void *arg, int dst_w, int dst_h, int src_w, int src_h)
typedef void	fz_activity_fn(fz_context *ctx, void *opaque, fz_activity_reason reason, void *reason_arg)

Enumerations
enum	fz_error_type {   FZ_ERROR_NONE , FZ_ERROR_GENERIC , FZ_ERROR_SYSTEM , FZ_ERROR_LIBRARY ,   FZ_ERROR_ARGUMENT , FZ_ERROR_LIMIT , FZ_ERROR_UNSUPPORTED , FZ_ERROR_FORMAT ,   FZ_ERROR_SYNTAX , FZ_ERROR_TRYLATER , FZ_ERROR_ABORT , FZ_ERROR_REPAIRED }
enum	{ FZ_LOCK_ALLOC = 0 , FZ_LOCK_FREETYPE , FZ_LOCK_GLYPHCACHE , FZ_LOCK_MAX }
enum	{ FZ_STORE_UNLIMITED = 0 , FZ_STORE_DEFAULT = 256 << 20 }
enum	{ FZ_IMAGE_RENDERING_BALANCE = 0 , FZ_IMAGE_RENDERING_QUALITY = 1 , FZ_IMAGE_RENDERING_SPEED = 2 }
enum	fz_activity_reason { FZ_ACTIVITY_NEW_DOC = 0 , FZ_ACTIVITY_SHUTDOWN = 1 }

Functions
FZ_NORETURN void	fz_vthrow (fz_context *ctx, int errcode, const char *, va_list ap)
FZ_NORETURN void	fz_throw (fz_context *ctx, int errcode, const char *,...) FZ_PRINTFLIKE(3
FZ_NORETURN void FZ_NORETURN void	fz_rethrow (fz_context *ctx)
void	fz_morph_error (fz_context *ctx, int fromcode, int tocode)
void	fz_vwarn (fz_context *ctx, const char *fmt, va_list ap)
void	fz_warn (fz_context *ctx, const char *fmt,...) FZ_PRINTFLIKE(2
void const char *	fz_caught_message (fz_context *ctx)
int	fz_caught (fz_context *ctx)
int	fz_caught_errno (fz_context *ctx)
void	fz_rethrow_if (fz_context *ctx, int errcode)
void	fz_rethrow_unless (fz_context *ctx, int errcode)
void	fz_log_error_printf (fz_context *ctx, const char *fmt,...) FZ_PRINTFLIKE(2
void void	fz_vlog_error_printf (fz_context *ctx, const char *fmt, va_list ap)
void	fz_log_error (fz_context *ctx, const char *str)
void	fz_report_error (fz_context *ctx)
void	fz_ignore_error (fz_context *ctx)
const char *	fz_convert_error (fz_context *ctx, int *code)
void	fz_flush_warnings (fz_context *ctx)
void	fz_assert_lock_held (fz_context *ctx, int lock)
void	fz_assert_lock_not_held (fz_context *ctx, int lock)
void	fz_lock_debug_lock (fz_context *ctx, int lock)
void	fz_lock_debug_unlock (fz_context *ctx, int lock)
fz_context *	fz_clone_context (fz_context *ctx)
void	fz_drop_context (fz_context *ctx)
void	fz_set_user_context (fz_context *ctx, void *user)
void *	fz_user_context (fz_context *ctx)
void	fz_default_error_callback (void *user, const char *message)
void	fz_default_warning_callback (void *user, const char *message)
void	fz_set_error_callback (fz_context *ctx, fz_error_cb *error_cb, void *user)
fz_error_cb *	fz_error_callback (fz_context *ctx, void **user)
void	fz_set_warning_callback (fz_context *ctx, fz_warning_cb *warning_cb, void *user)
fz_warning_cb *	fz_warning_callback (fz_context *ctx, void **user)
void	fz_tune_image_decode (fz_context *ctx, fz_tune_image_decode_fn *image_decode, void *arg)
void	fz_tune_image_scale (fz_context *ctx, fz_tune_image_scale_fn *image_scale, void *arg)
void	fz_tune_image_rendering (fz_context *ctx, int behavior)
int	fz_aa_level (fz_context *ctx)
void	fz_set_aa_level (fz_context *ctx, int bits)
int	fz_text_aa_level (fz_context *ctx)
void	fz_set_text_aa_level (fz_context *ctx, int bits)
int	fz_graphics_aa_level (fz_context *ctx)
void	fz_set_graphics_aa_level (fz_context *ctx, int bits)
float	fz_graphics_min_line_width (fz_context *ctx)
void	fz_set_graphics_min_line_width (fz_context *ctx, float min_line_width)
const char *	fz_user_css (fz_context *ctx)
void	fz_set_user_css (fz_context *ctx, const char *text)
void	fz_load_user_css (fz_context *ctx, const char *filename)
int	fz_use_document_css (fz_context *ctx)
void	fz_set_use_document_css (fz_context *ctx, int use)
void	fz_enable_icc (fz_context *ctx)
void	fz_disable_icc (fz_context *ctx)
void *	fz_malloc_array_imp (fz_context *ctx, size_t nmemb, size_t size)
void *	fz_realloc_array_imp (fz_context *ctx, void *p, size_t nmemb, size_t size)
void *	fz_malloc (fz_context *ctx, size_t size)
void *	fz_calloc (fz_context *ctx, size_t count, size_t size)
void *	fz_realloc (fz_context *ctx, void *p, size_t size)
void	fz_free (fz_context *ctx, void *p)
void *	fz_malloc_no_throw (fz_context *ctx, size_t size)
void *	fz_calloc_no_throw (fz_context *ctx, size_t count, size_t size)
void *	fz_realloc_no_throw (fz_context *ctx, void *p, size_t size)
void *	fz_malloc_aligned (fz_context *ctx, size_t size, int align)
void	fz_free_aligned (fz_context *ctx, void *p)
char *	fz_strdup (fz_context *ctx, const char *s)
void	fz_memrnd (fz_context *ctx, uint8_t *block, int len)
fz_string *	fz_new_string (fz_context *ctx, const char *str)
fz_string *	fz_keep_string (fz_context *ctx, fz_string *str)
void	fz_drop_string (fz_context *ctx, fz_string *str)
void	fz_var_imp (void *)
fz_jmp_buf *	fz_push_try (fz_context *ctx)
int	fz_do_try (fz_context *ctx)
int	fz_do_always (fz_context *ctx)
int	fz_do_catch (fz_context *ctx)
void	fz_register_activity_logger (fz_context *ctx, fz_activity_fn *activity, void *opaque)
fz_context *	fz_new_context_imp (const fz_alloc_context *alloc, const fz_locks_context *locks, size_t max_store, const char *version)

Macro Definition Documentation

FITZ_DEBUG_LOCKING

#define FITZ_DEBUG_LOCKING

fz_always

#define fz_always

(

ctx

)

Value:

while (0); if (fz_do_always(ctx)) do

fz_catch

#define fz_catch

(

ctx

)

Value:

while (0); if (fz_do_catch(ctx))

fz_cstring_from_string

#define fz_cstring_from_string

(

A

)

Value:

((A) == NULL ? NULL : (A)->str)

fz_drop_imp

#define fz_drop_imp	(		C,
			P,
			R )

Value:

fz_drop_imp_aux((C), (P), (P) ? (R) : NULL)

fz_drop_imp16

#define fz_drop_imp16	(		C,
			P,
			R )

Value:

fz_drop_imp16_aux((C), (P), (P) ? (R) : NULL)

fz_drop_imp8

#define fz_drop_imp8	(		C,
			P,
			R )

Value:

fz_drop_imp8_aux((C), (P), (P) ? (R) : NULL)

FZ_JMPBUF_ALIGN

#define FZ_JMPBUF_ALIGN   32

fz_keep_imp

#define fz_keep_imp	(		C,
			P,
			R )

Value:

fz_keep_imp_aux((C), (P), (P) ? (R) : NULL)

fz_keep_imp16

#define fz_keep_imp16	(		C,
			P,
			R )

Value:

fz_keep_imp16_aux((C), (P), (P) ? (R) : NULL)

fz_keep_imp8

#define fz_keep_imp8	(		C,
			P,
			R )

Value:

fz_keep_imp8_aux((C), (P), (P) ? (R) : NULL)

fz_keep_imp8_locked

#define fz_keep_imp8_locked	(		C,
			P,
			R )

Value:

fz_keep_imp8_locked_aux((C), (P), (P) ? (R) : NULL)

fz_keep_imp_locked

#define fz_keep_imp_locked	(		C,
			P,
			R )

Value:

fz_keep_imp_locked_aux((C), (P), (P) ? (R) : NULL)

fz_malloc_array

#define fz_malloc_array	(		CTX,
			COUNT,
			TYPE )

Value:

    ((TYPE*)Memento_label(fz_malloc_array_imp((CTX), (COUNT), sizeof(TYPE)), #TYPE "[]"))

Allocate uninitialized memory for an array of structures, and tag the pointer for Memento. Does NOT clear the memory!

Throws exception in the event of failure to allocate.

fz_malloc_flexible

#define fz_malloc_flexible	(		ctx,
			T,
			M,
			count )

Value:

    ((T*)Memento_label(fz_calloc(ctx, 1, offsetof(T, M) + sizeof(*((T*)0)->M) * (count)), #T))

Flexible array member allocation helpers.

fz_malloc_struct

#define fz_malloc_struct	(		CTX,
			TYPE )

Value:

    ((TYPE*)Memento_label(fz_calloc(CTX, 1, sizeof(TYPE)), #TYPE))

Memory Allocation and Scavenging:

All calls to MuPDF's allocator functions pass through to the underlying allocators passed in when the initial context is created, after locks are taken (using the supplied locking function) to ensure that only one thread at a time calls through.

If the underlying allocator fails, MuPDF attempts to make room for the allocation by evicting elements from the store, then retrying.

Any call to allocate may then result in several calls to the underlying allocator, and result in elements that are only referred to by the store being freed. Allocate memory for a structure, clear it, and tag the pointer for Memento.

Throws exception in the event of failure to allocate.

fz_malloc_struct_array

#define fz_malloc_struct_array	(		CTX,
			N,
			TYPE )

Value:

    ((TYPE*)Memento_label(fz_calloc(CTX, N, sizeof(TYPE)), #TYPE "[]"))

Allocate memory for an array of structures, clear it, and tag the pointer for Memento.

Throws exception in the event of failure to allocate.

fz_new_context

#define fz_new_context	(		alloc,
			locks,
			max_store )

Value:

fz_new_context_imp(alloc, locks, max_store, FZ_VERSION)

Allocate context containing global state.

The global state contains an exception stack, resource store, etc. Most functions in MuPDF take a context argument to be able to reference the global state. See fz_drop_context for freeing an allocated context.

alloc: Supply a custom memory allocator through a set of function pointers. Set to NULL for the standard library allocator. The context will keep the allocator pointer, so the data it points to must not be modified or freed during the lifetime of the context.

locks: Supply a set of locks and functions to lock/unlock them, intended for multi-threaded applications. Set to NULL when using MuPDF in a single-threaded applications. The context will keep the locks pointer, so the data it points to must not be modified or freed during the lifetime of the context.

max_store: Maximum size in bytes of the resource store, before it will start evicting cached resources such as fonts and images. FZ_STORE_UNLIMITED can be used if a hard limit is not desired. Use FZ_STORE_DEFAULT to get a reasonable size.

May return NULL.

fz_pool_alloc_flexible

#define fz_pool_alloc_flexible	(		ctx,
			pool,
			T,
			M,
			count )

Value:

    ((T*)fz_pool_alloc(ctx, pool, offsetof(T, M) + sizeof(*((T*)0)->M) * (count)))

fz_realloc_array

#define fz_realloc_array	(		CTX,
			OLD,
			COUNT,
			TYPE )

Value:

    ((TYPE*)Memento_label(fz_realloc_array_imp((CTX), (OLD), (COUNT), sizeof(TYPE)), #TYPE "[]"))

fz_realloc_flexible

#define fz_realloc_flexible	(		ctx,
			p,
			T,
			M,
			count )

Value:

    ((T*)Memento_label(fz_realloc(ctx, p, offsetof(T, M) + sizeof(*((T*)0)->M) * (count)), #T))

fz_sizeof_flexible

#define fz_sizeof_flexible	(		T,
			M,
			count )

Value:

    (offsetof(T, M) + sizeof(*((T*)0)->M) * (count))

fz_try

#define fz_try

(

ctx

)

Value:

if (!fz_setjmp(*fz_push_try(ctx))) if (fz_do_try(ctx)) do

fz_var

#define fz_var

(

var

)

Value:

fz_var_imp((void *)&(var))

Exception macro definitions. Just treat these as a black box - pay no attention to the man behind the curtain.

FZ_VERBOSE_EXCEPTIONS

#define FZ_VERBOSE_EXCEPTIONS   0

Typedef Documentation

fz_activity_fn

typedef void fz_activity_fn(fz_context *ctx, void *opaque, fz_activity_reason reason, void *reason_arg)

fz_archive_handler_context

typedef struct fz_archive_handler_context fz_archive_handler_context

fz_colorspace_context

typedef struct fz_colorspace_context fz_colorspace_context

fz_context

typedef struct fz_context fz_context

fz_document_handler_context

typedef struct fz_document_handler_context fz_document_handler_context

fz_error_cb

typedef void fz_error_cb(void *user, const char *message)

A callback called whenever an error message is generated. The user pointer passed to fz_set_error_callback() is passed along with the error message.

fz_font_context

typedef struct fz_font_context fz_font_context

fz_glyph_cache

typedef struct fz_glyph_cache fz_glyph_cache

fz_hyph_context

typedef struct fz_hyph_context fz_hyph_context

fz_output

typedef struct fz_output fz_output

fz_store

typedef struct fz_store fz_store

fz_style_context

typedef struct fz_style_context fz_style_context

fz_tune_image_decode_fn

typedef void fz_tune_image_decode_fn(void *arg, int w, int h, int l2factor, fz_irect *subarea)

In order to tune MuPDF's behaviour, certain functions can (optionally) be provided by callers. Given the width and height of an image, the subsample factor, and the subarea of the image actually required, the caller can decide whether to decode the whole image or just a subarea.

arg: The caller supplied opaque argument.

w, h: The width/height of the complete image.

l2factor: The log2 factor for subsampling (i.e. image will be decoded to (w>>l2factor, h>>l2factor)).

subarea: The actual subarea required for the current operation. The tuning function is allowed to increase this in size if required.

fz_tune_image_scale_fn

typedef int fz_tune_image_scale_fn(void *arg, int dst_w, int dst_h, int src_w, int src_h)

Given the source width and height of image, together with the actual required width and height, decide whether we should use mitchell scaling.

arg: The caller supplied opaque argument.

dst_w, dst_h: The actual width/height required on the target device.

src_w, src_h: The source width/height of the image.

Return 0 not to use the Mitchell scaler, 1 to use the Mitchell scaler. All other values reserved.

fz_tuning_context

typedef struct fz_tuning_context fz_tuning_context

fz_warning_cb

typedef void fz_warning_cb(void *user, const char *message)

A callback called whenever a warning message is generated. The user pointer passed to fz_set_warning_callback() is passed along with the warning message.

Enumeration Type Documentation

anonymous enum

anonymous enum

Set the behavior for image rendering and resampling.

Enumerator
FZ_IMAGE_RENDERING_BALANCE
FZ_IMAGE_RENDERING_QUALITY
FZ_IMAGE_RENDERING_SPEED

anonymous enum

anonymous enum

Specifies the maximum size in bytes of the resource store in fz_context. Given as argument to fz_new_context.

FZ_STORE_UNLIMITED: Let resource store grow unbounded.

FZ_STORE_DEFAULT: A reasonable upper bound on the size, for devices that are not memory constrained.

Enumerator
FZ_STORE_UNLIMITED
FZ_STORE_DEFAULT

anonymous enum

anonymous enum

Enumerator
FZ_LOCK_ALLOC
FZ_LOCK_FREETYPE
FZ_LOCK_GLYPHCACHE
FZ_LOCK_MAX

fz_activity_reason

enum fz_activity_reason

Enumerator
FZ_ACTIVITY_NEW_DOC
FZ_ACTIVITY_SHUTDOWN

fz_error_type

enum fz_error_type

Enumerator
FZ_ERROR_NONE
FZ_ERROR_GENERIC
FZ_ERROR_SYSTEM
FZ_ERROR_LIBRARY
FZ_ERROR_ARGUMENT
FZ_ERROR_LIMIT
FZ_ERROR_UNSUPPORTED
FZ_ERROR_FORMAT
FZ_ERROR_SYNTAX
FZ_ERROR_TRYLATER
FZ_ERROR_ABORT
FZ_ERROR_REPAIRED

Function Documentation

fz_aa_level()

int fz_aa_level

(

fz_context *

ctx

)

Get the number of bits of antialiasing we are using (for graphics). Between 0 and 8.

fz_assert_lock_held()

void fz_assert_lock_held	(	fz_context *	ctx,
		int	lock )

fz_assert_lock_not_held()

void fz_assert_lock_not_held	(	fz_context *	ctx,
		int	lock )

fz_calloc()

void * fz_calloc	(	fz_context *	ctx,
		size_t	count,
		size_t	size )

Allocate array of memory of count entries of size bytes. Clears the memory to zero.

Throws exception in the event of failure to allocate.

fz_calloc_no_throw()

void * fz_calloc_no_throw	(	fz_context *	ctx,
		size_t	count,
		size_t	size )

fz_calloc equivalent that returns NULL rather than throwing exceptions.

fz_caught()

int fz_caught

(

fz_context *

ctx

)

Within an fz_catch() block, retrieve the error code for the current exception.

This assumes no intervening use of fz_try/fz_catch.

fz_caught_errno()

int fz_caught_errno

(

fz_context *

ctx

)

fz_caught_message()

void const char * fz_caught_message

(

fz_context *

ctx

)

Within an fz_catch() block, retrieve the formatted message string for the current exception.

This assumes no intervening use of fz_try/fz_catch.

fz_clone_context()

fz_context * fz_clone_context

(

fz_context *

ctx

)

Make a clone of an existing context.

This function is meant to be used in multi-threaded applications where each thread requires its own context, yet parts of the global state, for example caching, are shared.

ctx: Context obtained from fz_new_context to make a copy of. ctx must have had locks and lock/functions setup when created. The two contexts will share the memory allocator, resource store, locks and lock/unlock functions. They will each have their own exception stacks though.

May return NULL.

fz_convert_error()

const char * fz_convert_error	(	fz_context *	ctx,
		int *	code )

fz_default_error_callback()

void fz_default_error_callback	(	void *	user,
		const char *	message )

FIXME: Better not to expose fz_default_error_callback, and fz_default_warning callback and to allow 'NULL' to be used int fz_set_xxxx_callback to mean "defaults".

FIXME: Do we need/want functions like fz_error_callback(ctx, message) to allow callers to inject stuff into the error/warning streams? The default error callback. Declared publicly just so that the error callback can be set back to this after it has been overridden.

fz_default_warning_callback()

void fz_default_warning_callback	(	void *	user,
		const char *	message )

The default warning callback. Declared publicly just so that the warning callback can be set back to this after it has been overridden.

fz_disable_icc()

void fz_disable_icc

(

fz_context *

ctx

)

Disable icc profile based operation.

fz_do_always()

int fz_do_always

(

fz_context *

ctx

)

fz_do_catch()

int fz_do_catch

(

fz_context *

ctx

)

fz_do_try()

int fz_do_try

(

fz_context *

ctx

)

fz_drop_context()

void fz_drop_context

(

fz_context *

ctx

)

Free a context and its global state.

The context and all of its global state is freed, and any buffered warnings are flushed (see fz_flush_warnings). If NULL is passed in nothing will happen.

Must not be called for a context that is being used in an active fz_try(), fz_always() or fz_catch() block.

fz_drop_string()

void fz_drop_string	(	fz_context *	ctx,
		fz_string *	str )

fz_enable_icc()

void fz_enable_icc

(

fz_context *

ctx

)

Enable icc profile based operation.

fz_error_callback()

fz_error_cb * fz_error_callback	(	fz_context *	ctx,
		void **	user )

Retrieve the currently set error callback, or NULL if none has been set. Optionally, if user is non-NULL, the user pointer given when the warning callback was set is also passed back to the caller.

fz_flush_warnings()

void fz_flush_warnings

(

fz_context *

ctx

)

Flush any repeated warnings.

Repeated warnings are buffered, counted and eventually printed along with the number of repetitions. Call fz_flush_warnings to force printing of the latest buffered warning and the number of repetitions, for example to make sure that all warnings are printed before exiting an application.

fz_free()

void fz_free	(	fz_context *	ctx,
		void *	p )

Free a previously allocated block of memory.

fz_free(ctx, NULL) does nothing.

Never throws exceptions.

fz_free_aligned()

void fz_free_aligned	(	fz_context *	ctx,
		void *	p )

fz_free equivalent, for blocks allocated via fz_malloc_aligned.

fz_graphics_aa_level()

int fz_graphics_aa_level

(

fz_context *

ctx

)

Get the number of bits of antialiasing we are using for graphics. Between 0 and 8.

fz_graphics_min_line_width()

float fz_graphics_min_line_width

(

fz_context *

ctx

)

Get the minimum line width to be used for stroked lines.

min_line_width: The minimum line width to use (in pixels).

fz_ignore_error()

void fz_ignore_error

(

fz_context *

ctx

)

fz_keep_string()

fz_string * fz_keep_string	(	fz_context *	ctx,
		fz_string *	str )

fz_load_user_css()

void fz_load_user_css	(	fz_context *	ctx,
		const char *	filename )

Set the user stylesheet by loading the source from a file. If the file is missing, do nothing.

fz_lock_debug_lock()

void fz_lock_debug_lock	(	fz_context *	ctx,
		int	lock )

fz_lock_debug_unlock()

void fz_lock_debug_unlock	(	fz_context *	ctx,
		int	lock )

fz_log_error()

void fz_log_error	(	fz_context *	ctx,
		const char *	str )

Log a (preformatted) string to the registered error stream (stderr by default).

fz_log_error_printf()

void fz_log_error_printf	(	fz_context *	ctx,
		const char *	fmt,
			... )

Format an error message, and log it to the registered error stream (stderr by default).

fz_malloc()

void * fz_malloc	(	fz_context *	ctx,
		size_t	size )

Allocate uninitialized memory of a given size. Does NOT clear the memory!

May return NULL for size = 0.

Throws exception in the event of failure to allocate.

fz_malloc_aligned()

void * fz_malloc_aligned	(	fz_context *	ctx,
		size_t	size,
		int	align )

fz_malloc equivalent, except that the block is guaranteed aligned. Block must be freed later using fz_free_aligned.

fz_malloc_array_imp()

void * fz_malloc_array_imp	(	fz_context *	ctx,
		size_t	nmemb,
		size_t	size )

fz_malloc_no_throw()

void * fz_malloc_no_throw	(	fz_context *	ctx,
		size_t	size )

fz_malloc equivalent that returns NULL rather than throwing exceptions.

fz_memrnd()

void fz_memrnd	(	fz_context *	ctx,
		uint8_t *	block,
		int	len )

Fill block with len bytes of pseudo-randomness.

fz_morph_error()

void fz_morph_error	(	fz_context *	ctx,
		int	fromcode,
		int	tocode )

Called within a catch block this modifies the current exception's code. If it's of type 'fromcode' it is modified to 'tocode'. Typically used for 'downgrading' exception severity.

fz_new_context_imp()

fz_context * fz_new_context_imp	(	const fz_alloc_context *	alloc,
		const fz_locks_context *	locks,
		size_t	max_store,
		const char *	version )

fz_new_string()

fz_string * fz_new_string	(	fz_context *	ctx,
		const char *	str )

fz_push_try()

fz_jmp_buf * fz_push_try

(

fz_context *

ctx

)

fz_realloc()

void * fz_realloc	(	fz_context *	ctx,
		void *	p,
		size_t	size )

Reallocates a block of memory to given size. Existing contents up to min(old_size,new_size) are maintained. The rest of the block is uninitialised.

fz_realloc(ctx, NULL, size) behaves like fz_malloc(ctx, size).

fz_realloc(ctx, p, 0); behaves like fz_free(ctx, p).

Throws exception in the event of failure to allocate.

fz_realloc_array_imp()

void * fz_realloc_array_imp	(	fz_context *	ctx,
		void *	p,
		size_t	nmemb,
		size_t	size )

fz_realloc_no_throw()

void * fz_realloc_no_throw	(	fz_context *	ctx,
		void *	p,
		size_t	size )

fz_realloc equivalent that returns NULL rather than throwing exceptions.

fz_register_activity_logger()

void fz_register_activity_logger	(	fz_context *	ctx,
		fz_activity_fn *	activity,
		void *	opaque )

fz_report_error()

void fz_report_error

(

fz_context *

ctx

)

Now, a debugging feature. If FZ_VERBOSE_EXCEPTIONS is 1 then some of the above functions are replaced by versions that print FILE and LINE information.

fz_rethrow()

FZ_NORETURN void FZ_NORETURN void fz_rethrow

(

fz_context *

ctx

)

fz_rethrow_if()

void fz_rethrow_if	(	fz_context *	ctx,
		int	errcode )

Within an fz_catch() block, rethrow the current exception if the errcode of the current exception matches.

This assumes no intervening use of fz_try/fz_catch.

fz_rethrow_unless()

void fz_rethrow_unless	(	fz_context *	ctx,
		int	errcode )

fz_set_aa_level()

void fz_set_aa_level	(	fz_context *	ctx,
		int	bits )

Set the number of bits of antialiasing we should use (for both text and graphics).

bits: The number of bits of antialiasing to use (values are clamped to within the 0 to 8 range).

fz_set_error_callback()

void fz_set_error_callback	(	fz_context *	ctx,
		fz_error_cb *	error_cb,
		void *	user )

Set the error callback. This will be called as part of the exception handling.

The callback must not throw exceptions!

fz_set_graphics_aa_level()

void fz_set_graphics_aa_level	(	fz_context *	ctx,
		int	bits )

Set the number of bits of antialiasing we should use for graphics.

bits: The number of bits of antialiasing to use (values are clamped to within the 0 to 8 range).

fz_set_graphics_min_line_width()

void fz_set_graphics_min_line_width	(	fz_context *	ctx,
		float	min_line_width )

Set the minimum line width to be used for stroked lines.

min_line_width: The minimum line width to use (in pixels).

fz_set_text_aa_level()

void fz_set_text_aa_level	(	fz_context *	ctx,
		int	bits )

Set the number of bits of antialiasing we should use for text.

bits: The number of bits of antialiasing to use (values are clamped to within the 0 to 8 range).

fz_set_use_document_css()

void fz_set_use_document_css	(	fz_context *	ctx,
		int	use )

Toggle whether to respect document styles in HTML and EPUB.

fz_set_user_context()

void fz_set_user_context	(	fz_context *	ctx,
		void *	user )

Set the user field in the context.

NULL initially, this field can be set to any opaque value required by the user. It is copied on clones.

fz_set_user_css()

void fz_set_user_css	(	fz_context *	ctx,
		const char *	text )

Set the user stylesheet source text for use with HTML and EPUB.

fz_set_warning_callback()

void fz_set_warning_callback	(	fz_context *	ctx,
		fz_warning_cb *	warning_cb,
		void *	user )

Set the warning callback. This will be called as part of the exception handling.

The callback must not throw exceptions!

fz_strdup()

char * fz_strdup	(	fz_context *	ctx,
		const char *	s )

Portable strdup implementation, using fz allocators.

fz_text_aa_level()

int fz_text_aa_level

(

fz_context *

ctx

)

Get the number of bits of antialiasing we are using for text. Between 0 and 8.

fz_throw()

FZ_NORETURN void fz_throw	(	fz_context *	ctx,
		int	errcode,
		const char *	,
			... )

fz_tune_image_decode()

void fz_tune_image_decode	(	fz_context *	ctx,
		fz_tune_image_decode_fn *	image_decode,
		void *	arg )

Set the tuning function to use for image decode.

image_decode: Function to use.

arg: Opaque argument to be passed to tuning function.

fz_tune_image_rendering()

void fz_tune_image_rendering	(	fz_context *	ctx,
		int	behavior )

fz_tune_image_scale()

void fz_tune_image_scale	(	fz_context *	ctx,
		fz_tune_image_scale_fn *	image_scale,
		void *	arg )

Set the tuning function to use for image scaling.

image_scale: Function to use.

arg: Opaque argument to be passed to tuning function.

fz_use_document_css()

int fz_use_document_css

(

fz_context *

ctx

)

Return whether to respect document styles in HTML and EPUB.

fz_user_context()

void * fz_user_context

(

fz_context *

ctx

)

Read the user field from the context.

fz_user_css()

const char * fz_user_css

(

fz_context *

ctx

)

Get the user stylesheet source text.

fz_var_imp()

void fz_var_imp

(

void *

)

fz_vlog_error_printf()

void void fz_vlog_error_printf	(	fz_context *	ctx,
		const char *	fmt,
		va_list	ap )

fz_vthrow()

FZ_NORETURN void fz_vthrow	(	fz_context *	ctx,
		int	errcode,
		const char *	,
		va_list	ap )

These macros provide a simple exception handling system. Use them as follows:

fz_try(ctx) ... fz_catch(ctx) ...

or as:

fz_try(ctx) ... fz_always(ctx) ... fz_catch(ctx) ...

Code within the fz_try() section can then throw exceptions using fz_throw() (or fz_vthrow()).

They are implemented with setjmp/longjmp, which can have unfortunate consequences for 'losing' local variable values on a throw. To avoid this we recommend calling 'fz_var(variable)' before the fz_try() for any local variable whose value may change within the fz_try() block and whose value will be required afterwards.

Do not call anything in the fz_always() section that can throw.

Any exception can be rethrown from the fz_catch() section using fz_rethrow() as long as there has been no intervening use of fz_try/fz_catch. Throw an exception.

This assumes an enclosing fz_try() block within the callstack.

fz_vwarn()

void fz_vwarn	(	fz_context *	ctx,
		const char *	fmt,
		va_list	ap )

Log a warning.

This goes to the registered warning stream (stderr by default).

fz_warn()

void fz_warn	(	fz_context *	ctx,
		const char *	fmt,
			... )

fz_warning_callback()

fz_warning_cb * fz_warning_callback	(	fz_context *	ctx,
		void **	user )

Retrieve the currently set warning callback, or NULL if none has been set. Optionally, if user is non-NULL, the user pointer given when the warning callback was set is also passed back to the caller.