context.h

Go to the documentation of this file.

// Copyright (C) 2004-2025 Artifex Software, Inc.
//
// This file is part of MuPDF.
//
// MuPDF is free software: you can redistribute it and/or modify it under the
// terms of the GNU Affero General Public License as published by the Free
// Software Foundation, either version 3 of the License, or (at your option)
// any later version.
//
// MuPDF is distributed in the hope that it will be useful, but WITHOUT ANY
// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
// FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
// details.
//
// You should have received a copy of the GNU Affero General Public License
// along with MuPDF. If not, see <https://www.gnu.org/licenses/agpl-3.0.en.html>
//
// Alternative licensing terms are available from the licensor.
// For commercial licensing, see <https://www.artifex.com/> or contact
// Artifex Software, Inc., 39 Mesa Street, Suite 108A, San Francisco,
// CA 94129, USA, for further information.
 
#ifndef MUPDF_FITZ_CONTEXT_H
#define MUPDF_FITZ_CONTEXT_H
 
#include "mupdf/fitz/version.h"
#include "mupdf/fitz/system.h"
#include "mupdf/fitz/geometry.h"
 
 
#ifndef FZ_VERBOSE_EXCEPTIONS
#define FZ_VERBOSE_EXCEPTIONS 0
#endif
 
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 struct
{
    void *user;
    void *(*malloc)(void *, size_t);
    void *(*realloc)(void *, void *, size_t);
    void (*free)(void *, void *);
} fz_alloc_context;

#define fz_var(var) fz_var_imp((void *)&(var))
#define fz_try(ctx) if (!fz_setjmp(*fz_push_try(ctx))) if (fz_do_try(ctx)) do
#define fz_always(ctx) while (0); if (fz_do_always(ctx)) do
#define fz_catch(ctx) while (0); if (fz_do_catch(ctx))


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,4);
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,3);

const char *fz_caught_message(fz_context *ctx);

int fz_caught(fz_context *ctx);
 
/*
    Within an fz_catch() block, retrieve the errno code for
    the current SYSTEM exception.
 
    Is undefined for non-SYSTEM errors.
*/
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,3);
void fz_vlog_error_printf(fz_context *ctx, const char *fmt, va_list ap);

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

#if FZ_VERBOSE_EXCEPTIONS
#define fz_vthrow(CTX, ERRCODE, FMT, VA) fz_vthrowFL(CTX, __FILE__, __LINE__, ERRCODE, FMT, VA)
#define fz_throw(CTX, ERRCODE, ...) fz_throwFL(CTX, __FILE__, __LINE__, ERRCODE, __VA_ARGS__)
#define fz_rethrow(CTX) fz_rethrowFL(CTX, __FILE__, __LINE__)
#define fz_morph_error(CTX, FROM, TO) fz_morph_errorFL(CTX, __FILE__, __LINE__, FROM, TO)
#define fz_vwarn(CTX, FMT, VA) fz_vwarnFL(CTX, __FILE__, __LINE__, FMT, VA)
#define fz_warn(CTX, ...) fz_warnFL(CTX, __FILE__, __LINE__, __VA_ARGS__)
#define fz_rethrow_if(CTX, ERRCODE) fz_rethrow_ifFL(CTX, __FILE__, __LINE__, ERRCODE)
#define fz_rethrow_unless(CTX, ERRCODE) fz_rethrow_unlessFL(CTX, __FILE__, __LINE__, ERRCODE)
#define fz_log_error_printf(CTX, ...) fz_log_error_printfFL(CTX, __FILE__, __LINE__, __VA_ARGS__)
#define fz_vlog_error_printf(CTX, FMT, VA) fz_log_error_printfFL(CTX, __FILE__, __LINE__, FMT, VA)
#define fz_log_error(CTX, STR) fz_log_error_printfFL(CTX, __FILE__, __LINE__, STR)
#define fz_do_catch(CTX) fz_do_catchFL(CTX, __FILE__, __LINE__)
FZ_NORETURN void fz_vthrowFL(fz_context *ctx, const char *file, int line, int errcode, const char *fmt, va_list ap);
FZ_NORETURN void fz_throwFL(fz_context *ctx, const char *file, int line, int errcode, const char *fmt, ...) FZ_PRINTFLIKE(5,6);
FZ_NORETURN void fz_rethrowFL(fz_context *ctx, const char *file, int line);
void fz_morph_errorFL(fz_context *ctx, const char *file, int line, int fromcode, int tocode);
void fz_vwarnFL(fz_context *ctx, const char *file, int line, const char *fmt, va_list ap);
void fz_warnFL(fz_context *ctx, const char *file, int line, const char *fmt, ...) FZ_PRINTFLIKE(4,5);
void fz_rethrow_ifFL(fz_context *ctx, const char *file, int line, int errcode);
void fz_rethrow_unlessFL(fz_context *ctx, const char *file, int line, int errcode);
void fz_log_error_printfFL(fz_context *ctx, const char *file, int line, const char *fmt, ...) FZ_PRINTFLIKE(4,5);
void fz_vlog_error_printfFL(fz_context *ctx, const char *file, int line, const char *fmt, va_list ap);
void fz_log_errorFL(fz_context *ctx, const char *file, int line, const char *str);
int fz_do_catchFL(fz_context *ctx, const char *file, int line);
#endif
 
/* Report an error to the registered error callback. */
void fz_report_error(fz_context *ctx);
 
/*
 * Swallow an error and ignore it completely.
 * This should only be called to signal that you've handled a TRYLATER or ABORT error,
 */
void fz_ignore_error(fz_context *ctx);
 
/* Convert an error into another runtime exception.
 * For use when converting an exception from Fitz to a language binding exception.
 */
const char *fz_convert_error(fz_context *ctx, int *code);
 
enum fz_error_type
{
    FZ_ERROR_NONE,
    FZ_ERROR_GENERIC,
 
    FZ_ERROR_SYSTEM, // fatal out of memory or syscall error
    FZ_ERROR_LIBRARY, // unclassified error from third-party library
    FZ_ERROR_ARGUMENT, // invalid or out-of-range arguments to functions
    FZ_ERROR_LIMIT, // failed because of resource or other hard limits
    FZ_ERROR_UNSUPPORTED, // tried to use an unsupported feature
    FZ_ERROR_FORMAT, // syntax or format errors that are unrecoverable
    FZ_ERROR_SYNTAX, // syntax errors that should be diagnosed and ignored
 
    // for internal use only
    FZ_ERROR_TRYLATER, // try-later progressive loading signal
    FZ_ERROR_ABORT, // user requested abort signal
    FZ_ERROR_REPAIRED, // internal flag used when repairing a PDF to avoid cycles
};

void fz_flush_warnings(fz_context *ctx);

 
typedef struct
{
    void *user;
    void (*lock)(void *user, int lock);
    void (*unlock)(void *user, int lock);
} fz_locks_context;
 
enum {
    FZ_LOCK_ALLOC = 0,
    FZ_LOCK_FREETYPE,
    FZ_LOCK_GLYPHCACHE,
    FZ_LOCK_MAX
};
 
#if defined(MEMENTO) || !defined(NDEBUG)
#define FITZ_DEBUG_LOCKING
#endif
 
#ifdef FITZ_DEBUG_LOCKING
 
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);
 
#else
 
#define fz_assert_lock_held(A,B) do { } while (0)
#define fz_assert_lock_not_held(A,B) do { } while (0)
#define fz_lock_debug_lock(A,B) do { } while (0)
#define fz_lock_debug_unlock(A,B) do { } while (0)
 
#endif /* !FITZ_DEBUG_LOCKING */

enum {
    FZ_STORE_UNLIMITED = 0,
    FZ_STORE_DEFAULT = 256 << 20,
};

#define fz_new_context(alloc, locks, max_store) fz_new_context_imp(alloc, locks, max_store, FZ_VERSION)

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);

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

typedef void (fz_warning_cb)(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);


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);

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);

enum {
    // We may box filter images down by a power of 2, before scaling
    // accurately to get the final results. Rendering will be stable.
    // This may be faster and may use less memory than 'QUALITY'
    // rendering, for a (probably imperceptible) degradation of quality.
    FZ_IMAGE_RENDERING_BALANCE = 0,
 
    // We will never box filter images, and instead will always scale
    // accurately. Rendering will be stable. This may be slower and
    // may use more memory than 'HYBRID' rendering, for a (probably
    // imperceptible) improvement in quality.
    FZ_IMAGE_RENDERING_QUALITY = 1,
 
    // We will box filter images down by a power of 2, before scaling
    // accurately to get the final results. We will accept image
    // tiles that have previously been box scaled and cached at higher
    // quality than we need, thus saving us the decode again, at the
    // cost of "rendering instability". i.e. the exact results of
    // rendering may differ according to the order of rendering
    // operations that have happened in the past. The quality
    // differences here are rarely spotted, and very minor, but
    // genuinely exist. In an interactive application, these are
    // well within acceptability, but in an system where results are
    // being compared pixel-by-pixel, this is probably best avoided.
    FZ_IMAGE_RENDERING_SPEED = 2,
};
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);


#define fz_malloc_struct(CTX, TYPE) \
    ((TYPE*)Memento_label(fz_calloc(CTX, 1, sizeof(TYPE)), #TYPE))

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

#define fz_malloc_array(CTX, COUNT, TYPE) \
    ((TYPE*)Memento_label(fz_malloc_array_imp((CTX), (COUNT), sizeof(TYPE)), #TYPE "[]"))
#define fz_realloc_array(CTX, OLD, COUNT, TYPE) \
    ((TYPE*)Memento_label(fz_realloc_array_imp((CTX), (OLD), (COUNT), sizeof(TYPE)), #TYPE "[]"))
 
void *fz_malloc_array_imp(fz_context *ctx, size_t nmemb, size_t size);
void *fz_realloc_array_imp(fz_context *ctx, void *p, size_t nmemb, size_t size);

void *fz_malloc(fz_context *ctx, size_t size);

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);

#define fz_malloc_flexible(ctx, T, M, count) \
    ((T*)Memento_label(fz_calloc(ctx, 1, offsetof(T, M) + sizeof(*((T*)0)->M) * (count)), #T))
#define fz_realloc_flexible(ctx, p, T, M, count) \
    ((T*)Memento_label(fz_realloc(ctx, p, offsetof(T, M) + sizeof(*((T*)0)->M) * (count)), #T))
#define fz_pool_alloc_flexible(ctx, pool, T, M, count) \
    ((T*)fz_pool_alloc(ctx, pool, offsetof(T, M) + sizeof(*((T*)0)->M) * (count)))
#define fz_sizeof_flexible(T, M, count) \
    (offsetof(T, M) + sizeof(*((T*)0)->M) * (count))

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);
 
/*
    Reference counted malloced C strings.
*/
typedef struct
{
    int refs;
    char str[FZ_FLEXIBLE_ARRAY];
} fz_string;
 
/*
    Allocate a new string to hold a copy of str.
 
    Returns with a refcount of 1.
*/
fz_string *fz_new_string(fz_context *ctx, const char *str);
 
/*
    Take another reference to a string.
*/
fz_string *fz_keep_string(fz_context *ctx, fz_string *str);
 
/*
    Drop a reference to a string, freeing if the refcount
    reaches 0.
*/
void fz_drop_string(fz_context *ctx, fz_string *str);
 
#define fz_cstring_from_string(A) ((A) == NULL ? NULL : (A)->str)
 
/* Implementation details: subject to change. */
 
/* Implementations exposed for speed, but considered private. */
 
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);
 
#ifndef FZ_JMPBUF_ALIGN
#define FZ_JMPBUF_ALIGN 32
#endif
 
typedef struct
{
    fz_jmp_buf buffer;
    int state, code;
    char padding[FZ_JMPBUF_ALIGN-sizeof(int)*2];
} fz_error_stack_slot;
 
typedef struct
{
    fz_error_stack_slot *top;
    fz_error_stack_slot stack[256];
    fz_error_stack_slot padding;
    fz_error_stack_slot *stack_base;
    int errcode;
    int errnum; /* errno for SYSTEM class errors */
    void *print_user;
    void (*print)(void *user, const char *message);
    char message[256];
} fz_error_context;
 
typedef struct
{
    void *print_user;
    void (*print)(void *user, const char *message);
    int count;
    char message[256];
} fz_warn_context;
 
typedef struct
{
    int hscale;
    int vscale;
    int scale;
    int bits;
    int text_bits;
    float min_line_width;
} fz_aa_context;
 
typedef enum
{
    FZ_ACTIVITY_NEW_DOC = 0,
    FZ_ACTIVITY_SHUTDOWN = 1
} fz_activity_reason;
 
typedef void (fz_activity_fn)(fz_context *ctx, void *opaque, fz_activity_reason reason, void *reason_arg);
 
typedef struct
{
    void *opaque;
    fz_activity_fn *activity;
} fz_activity_context;
 
void fz_register_activity_logger(fz_context *ctx, fz_activity_fn *activity, void *opaque);
 
struct fz_context
{
    void *user;
 
    /* If master points to itself, then we are the master context.
     * If master is NULL, then we are the master context, but we have
     * been destroyed. We exist just so the count of clones can live
     * on. Otherwise master points to the master context from which
     * we were cloned. */
    fz_context *master;
    /* The number of contexts in this family. 1 for this one, plus
     * 1 for every context cloned (directly or indirectly) from it. */
    int context_count;
 
    /* Only the master version of this is used! */
    int next_document_id;
 
    fz_alloc_context alloc;
    fz_locks_context locks;
    fz_error_context error;
    fz_warn_context warn;
    fz_activity_context activity;
 
    /* unshared contexts */
    fz_aa_context aa;
    uint16_t seed48[7];
#if FZ_ENABLE_ICC
    int icc_enabled;
#endif
 
    /* TODO: should these be unshared? */
    fz_document_handler_context *handler;
    fz_archive_handler_context *archive;
    fz_style_context *style;
    fz_tuning_context *tuning;
 
    /* shared contexts */
    fz_output *stddbg;
    fz_font_context *font;
    fz_hyph_context *hyph;
    fz_colorspace_context *colorspace;
    fz_store *store;
    fz_glyph_cache *glyph_cache;
};
 
fz_context *fz_new_context_imp(const fz_alloc_context *alloc, const fz_locks_context *locks, size_t max_store, const char *version);

static inline void
fz_lock(fz_context *ctx, int lock)
{
    fz_lock_debug_lock(ctx, lock);
    ctx->locks.lock(ctx->locks.user, lock);
}

static inline void
fz_unlock(fz_context *ctx, int lock)
{
    fz_lock_debug_unlock(ctx, lock);
    ctx->locks.unlock(ctx->locks.user, lock);
}
 
/* Lock-safe reference counting functions */
 
#define fz_keep_imp(C,P,R) fz_keep_imp_aux((C), (P), (P) ? (R) : NULL)
#define fz_keep_imp8(C,P,R) fz_keep_imp8_aux((C), (P), (P) ? (R) : NULL)
#define fz_keep_imp16(C,P,R) fz_keep_imp16_aux((C), (P), (P) ? (R) : NULL)
 
#define fz_keep_imp_locked(C,P,R) fz_keep_imp_locked_aux((C), (P), (P) ? (R) : NULL)
#define fz_keep_imp8_locked(C,P,R) fz_keep_imp8_locked_aux((C), (P), (P) ? (R) : NULL)
 
#define fz_drop_imp(C,P,R) fz_drop_imp_aux((C), (P), (P) ? (R) : NULL)
#define fz_drop_imp8(C,P,R) fz_drop_imp8_aux((C), (P), (P) ? (R) : NULL)
#define fz_drop_imp16(C,P,R) fz_drop_imp16_aux((C), (P), (P) ? (R) : NULL)
 
static inline void *
fz_keep_imp_aux(fz_context *ctx, void *p, int *refs)
{
    if (p)
    {
        (void)Memento_checkIntPointerOrNull(refs);
        fz_lock(ctx, FZ_LOCK_ALLOC);
        if (*refs > 0)
        {
            (void)Memento_takeRef(p);
            ++*refs;
        }
        fz_unlock(ctx, FZ_LOCK_ALLOC);
    }
    return p;
}
 
static inline void *
fz_keep_imp_locked_aux(fz_context *ctx FZ_UNUSED, void *p, int *refs)
{
    if (p)
    {
        (void)Memento_checkIntPointerOrNull(refs);
        if (*refs > 0)
        {
            (void)Memento_takeRef(p);
            ++*refs;
        }
    }
    return p;
}
 
static inline void *
fz_keep_imp8_locked_aux(fz_context *ctx FZ_UNUSED, void *p, int8_t *refs)
{
    if (p)
    {
        (void)Memento_checkIntPointerOrNull(refs);
        if (*refs > 0)
        {
            (void)Memento_takeRef(p);
            ++*refs;
        }
    }
    return p;
}
 
static inline void *
fz_keep_imp8_aux(fz_context *ctx, void *p, int8_t *refs)
{
    if (p)
    {
        (void)Memento_checkBytePointerOrNull(refs);
        fz_lock(ctx, FZ_LOCK_ALLOC);
        if (*refs > 0)
        {
            (void)Memento_takeRef(p);
            ++*refs;
        }
        fz_unlock(ctx, FZ_LOCK_ALLOC);
    }
    return p;
}
 
static inline void *
fz_keep_imp16_aux(fz_context *ctx, void *p, int16_t *refs)
{
    if (p)
    {
        (void)Memento_checkShortPointerOrNull(refs);
        fz_lock(ctx, FZ_LOCK_ALLOC);
        if (*refs > 0)
        {
            (void)Memento_takeRef(p);
            ++*refs;
        }
        fz_unlock(ctx, FZ_LOCK_ALLOC);
    }
    return p;
}
 
static inline int
fz_drop_imp_aux(fz_context *ctx, void *p, int *refs)
{
    if (p)
    {
        int drop;
        (void)Memento_checkIntPointerOrNull(refs);
        fz_lock(ctx, FZ_LOCK_ALLOC);
        if (*refs > 0)
        {
            (void)Memento_dropIntRef(p);
            drop = --*refs == 0;
        }
        else
            drop = 0;
        fz_unlock(ctx, FZ_LOCK_ALLOC);
        return drop;
    }
    return 0;
}
 
static inline int
fz_drop_imp8_aux(fz_context *ctx, void *p, int8_t *refs)
{
    if (p)
    {
        int drop;
        (void)Memento_checkBytePointerOrNull(refs);
        fz_lock(ctx, FZ_LOCK_ALLOC);
        if (*refs > 0)
        {
            (void)Memento_dropByteRef(p);
            drop = --*refs == 0;
        }
        else
            drop = 0;
        fz_unlock(ctx, FZ_LOCK_ALLOC);
        return drop;
    }
    return 0;
}
 
static inline int
fz_drop_imp16_aux(fz_context *ctx, void *p, int16_t *refs)
{
    if (p)
    {
        int drop;
        (void)Memento_checkShortPointerOrNull(refs);
        fz_lock(ctx, FZ_LOCK_ALLOC);
        if (*refs > 0)
        {
            (void)Memento_dropShortRef(p);
            drop = --*refs == 0;
        }
        else
            drop = 0;
        fz_unlock(ctx, FZ_LOCK_ALLOC);
        return drop;
    }
    return 0;
}
 
#endif