Tuning

Some of MuPDF's functionality relies on heuristics to make decisions. Rather than hard code these decisions in the library code, the tuning context allows callers to override the defaults with their own `tuned' versions.

Currently, we have just 2 calls defined here, both to do with image handling, but this may expand in future.

The first tuning function enables fine control over how much of an image MuPDF should decode if it only requires a subarea:

$\begin{lstlisting} /* fz_tune_image_decode_fn: Given the width and height of an... ..._fn)(void *arg, int w, int h, int l2factor, fz_irect *subarea); \end{lstlisting}$

The purpose of allowing larger areas to be decoded than are immediately required, is so that these larger areas can be placed into the cache. This may mean that future requests can be satisfied from the cache rather than requiring complete new decodes. An example of such a situation might be where MuPDF is powering a viewer application, and a page is slowly panned onto screen revealing more and more of an image. These tuning functions put control over such decisions back into the hands of the application author.

Having defined a function of this type to implement the desired strategy, it can be set into the context using:

$\begin{lstlisting} /* fz_tune_image_decode: Set the tuning function to use for ... ...ontext *ctx, fz_tune_image_decode_fn *image_decode, void *arg); \end{lstlisting}$

The second function allows fine control over the scaling used when images are scaled:

$\begin{lstlisting} /* fz_tune_image_scale_fn: Given the source width and height... ...ale_fn)(void *arg, int dst_w, int dst_h, int src_w, int src_h); \end{lstlisting}$

Essentially this routine allows the application author to exercise control over whether images are displayed with interpolation or not. Rather than simple linear interpolation, MuPDF uses the `Mitchell' sampling function. This provides subjectively better quality.

The default is to use the Mitchell scaler only when downscaling, to avoid details `dropping out' of images, but by providing a tuning function, the application author can choose to use it in more (or fewer) cases as desired.

Having defined a function of this type to implement the desired strategy, it can be set into the context using:

$\begin{lstlisting} /* fz_tune_image_scale: Set the tuning function to use for ... ..._context *ctx, fz_tune_image_scale_fn *image_scale, void *arg); \end{lstlisting}$