Device Hints are a mechanism that enables control over the behaviour of a device, and to interpreters calling to that device. Informally they offer hints about what a device is going to do and therefore what callers need to worry about.
Device hints take the form of bits in an int that can be enabled (set) or disabled (cleared). Callers can query these hints to customise their behaviour.
Some devices set the hints to non-zero default values.
For example, when running a text-extraction operation (as used to implement text search), there is little point in handling images, or shadings. The text extraction device therefore sets FZ_IGNORE_IMAGE and FZ_IGNORE_SHADE. The interpretation functions (such as fz_run_page or fz_run_display_list can then not bother to prepare images for calling into the device, improving performance.
If, however, you wish to extract the page content to an html file, you might want to include images in this output. So for this, you would disable the FZ_IGNORE_IMAGE hint before running the extraction, and the text extraction device would know to include them in its output structures.
The set of hints is subject to expansion in future, but is currently defined to be:
FZ_DONT_INTERPOLATE_IMAGES being enabled prevents the draw device performing interpolation. MuTool Draw uses this to inhibit interpolation when anti-aliasing is disabled. Finer control over this can now be given using the Tuning Context (see section 5.7 Tuning).
FZ_MAINTAIN_CONTAINER_STACK being enabled helps devices by causing MuPDF to maintain a stack of containers. This effectively moves some logic that would have to be in several devices into a place where it can be easily reused. Currently the only device that makes use of this is the SVG device, but it is hoped that more will use it in future.
FZ_NO_CACHE being enabled tells the interpreter to try to avoid caching any objects after the end of the content run. This can be used, for example, when searching a PDF for a text string to avoid pulling all the images, shadings, fonts etc and other resources for pages into memory at the expense of those that are used on the current page.