Why does the API change?

From time to time, during development, it becomes clear that the public API needs to change; either because the existing API has flaws in it, or to accommodate new functionality. Such changes are not undertaken lightly, and they are kept as minimal as possible.

The alternative would be to freeze the API and to introduce more and more compatibility veneers, ultimately leading to a bloated API and additional complexity. We have done this in the past, and will do it again in future if circumstances demand it, but we consider small changes in the API to be a price worth paying for clarity and simplicity.

To minimise the impact of such changes, we undertake to list the API changes between different versions of the library here, to make it as simple as possible for integrators to make the small changes that may be require to update between versions.

Note, that we only list changes in existing APIs here, not additions to the API.

Changes from v1.14 to v1.15

PDF Portfolios
This functionality has been removed. We do not believe anyone was using this. If you were, please contact us for assistance. This functionality can be achieved using "mutool run" and docs/examples/pdf-portfolio.js.
FZ_ERROR_TRYLATER
This functionality has been removed. We do not believe anyone was using this. If you were, please contact us for assistance.
Annotations/Forms
We are undertaking a significant rework of this functionality at the moment. We do not believe anyone is using this at the moment, and would therefore encourage anyone who is to contact us for help in upgrading.
Various functions involving fz_colorspace have lost consts.
fz_colorspaces are immutable once created, other than changes due to reference counting. Passing a const fz_colorspace to a function that might keep a reference to it either has to take a non const fz_colorspace pointer, or take a const one, and 'break' the const. Having some functions take const fz_colorspace and some not is confusing, so therefore, for simplicity, all fz_colorspaces are now passed as non const. This should not affect any user code.
fz_process_shade()
This now takes an extra 'scissor' argument. To upgrade old code, if you don't have an appropriate scissor rect available, it is safe (but unwise) to pass fz_infinite_rect.
fz_tint_pixmap()
Rather than taking r, g and b, values to tint with, the function now takes 8 bit hex rgb values for black and white, enabling greater control, allowing "low contrast" and "night view" effects.
pdf_add_image()
This no longer requires a mask flag. The image already knows if it is a mask.
pdf_processor.op_BI()
The op_BI callback is now passed an additional colorspace resource name.