Otherwise the TurboJPEG 3.2 API would allow callers compiled against
TurboJPEG 3.1 and prior to set TJPARAM_SUBSAMP to a value that, from the
caller's point of view, is undefined. tj3DecompressHeader() would also
potentially set TJPARAM_SUBSAMP to a value that would overflow the
caller's static tjMCUWidth[] and tjMCUHeight[] arrays.
The trick here is to redefine tj3Init() in the TurboJPEG header as a
macro that wraps a new undocumented function, tj3InitVersion(), and
passes it an API version constant (TURBOJPEG_VERSION_NUMBER = 3002000)
that is also defined in the header. (This is a similar trick to the one
that the libjpeg v6a+ API uses for jpeg_create_*compress().) The old
tj3Init() function is still exposed in the library, and it now calls
tj3InitVersion(..., 3001000) internally. Based on the API version, the
API then sets and enforces an internal limit on the number of
chrominance subsampling options (TJ_NUMSAMP if the caller was compiled
against TurboJPEG 3.2+ or 7 otherwise.)
Thus, if an application is compiled against TurboJPEG 3.1-, it will
still call the old tj3Init() function, which sets the API version to
3.1 and doesn't expose TJSAMP_410 or TJSAMP_24. If an application is
compiled against TurboJPEG 3.2+, then it will call the new
tj3InitVersion() function via the tj3Init() macro, which sets the API
version to 3.2 and exposes TJSAMP_410 and TJSAMP_24.
Ramifications:
- Applications compiled against TurboJPEG 3.2+ will not be able to use
the TurboJPEG 3.1- API library at run time, because the
tj3InitVersion() function will not be available.
- Applications compiled against TurboJPEG 3.1- will work the same
regardless of whether they use the TurboJPEG 3.1- or 3.2+ API library
at run time.
- Applications that weren't specifically developed for TurboJPEG 3.2+
will not know about TJSAMP_410 or TJSAMP_24. Thus, when decompressing
or transforming without transposition, such applications will gain the
ability to obtain the iMCU width/height of a 4:1:0 or 2:4 JPEG image,
which is useful when adjusting the cropping region. However, they
will not gain any other abilities.
Since the default JPEG colorspace depends on the source pixel format and
selected subsampling level, it is useful to allow applications to
restore the default behavior if they have previously specified a JPEG
colorspace using TJPARAM_COLORSPACE.
Closes#852
