Background ========== libjpeg-turbo is a JPEG image codec that uses SIMD instructions (MMX, SSE2, NEON, AltiVec) to accelerate baseline JPEG compression and decompression on x86, x86-64, ARM, and PowerPC systems. On such systems, libjpeg-turbo is generally 2-6x as fast as libjpeg, all else being equal. On other types of systems, libjpeg-turbo can still outperform libjpeg by a significant amount, by virtue of its highly-optimized Huffman coding routines. In many cases, the performance of libjpeg-turbo rivals that of proprietary high-speed JPEG codecs. libjpeg-turbo implements both the traditional libjpeg API as well as the less powerful but more straightforward TurboJPEG API. libjpeg-turbo also features colorspace extensions that allow it to compress from/decompress to 32-bit and big-endian pixel buffers (RGBX, XBGR, etc.), as well as a full-featured Java interface. libjpeg-turbo was originally based on libjpeg/SIMD, an MMX-accelerated derivative of libjpeg v6b developed by Miyasaka Masaru. The TigerVNC and VirtualGL projects made numerous enhancements to the codec in 2009, and in early 2010, libjpeg-turbo spun off into an independent project, with the goal of making high-speed JPEG compression/decompression technology available to a broader range of users and developers. License ======= libjpeg-turbo is covered by three compatible BSD-style open source licenses. Refer to [LICENSE.md](LICENSE.md) for a roll-up of license terms. Building libjpeg-turbo ====================== Refer to [BUILDING.md](BUILDING.md) for complete instructions. Using libjpeg-turbo =================== libjpeg-turbo includes two APIs that can be used to compress and decompress JPEG images: - **TurboJPEG API** This API provides an easy-to-use interface for compressing and decompressing JPEG images in memory. It also provides some functionality that would not be straightforward to achieve using the underlying libjpeg API, such as generating planar YUV images and performing multiple simultaneous lossless transforms on an image. The Java interface for libjpeg-turbo is written on top of the TurboJPEG API. - **libjpeg API** This is the de facto industry-standard API for compressing and decompressing JPEG images. It is more difficult to use than the TurboJPEG API but also more powerful. The libjpeg API implementation in libjpeg-turbo is both API/ABI-compatible and mathematically compatible with libjpeg v6b. It can also optionally be configured to be API/ABI-compatible with libjpeg v7 and v8 (see below.) There is no significant performance advantage to either API when both are used to perform similar operations. Colorspace Extensions --------------------- libjpeg-turbo includes extensions that allow JPEG images to be compressed directly from (and decompressed directly to) buffers that use BGR, BGRX, RGBX, XBGR, and XRGB pixel ordering. This is implemented with ten new colorspace constants: JCS_EXT_RGB JCS_EXT_RGBX JCS_EXT_BGR JCS_EXT_BGRX JCS_EXT_XBGR JCS_EXT_XRGB JCS_EXT_RGBA JCS_EXT_BGRA JCS_EXT_ABGR JCS_EXT_ARGB Setting `cinfo.in_color_space` (compression) or `cinfo.out_color_space` (decompression) to one of these values will cause libjpeg-turbo to read the red, green, and blue values from (or write them to) the appropriate position in the pixel when compressing from/decompressing to an RGB buffer. Your application can check for the existence of these extensions at compile time with: #ifdef JCS_EXTENSIONS At run time, attempting to use these extensions with a libjpeg implementation that does not support them will result in a "Bogus input colorspace" error. Applications can trap this error in order to test whether run-time support is available for the colorspace extensions. When using the RGBX, BGRX, XBGR, and XRGB colorspaces during decompression, the X byte is undefined, and in order to ensure the best performance, libjpeg-turbo can set that byte to whatever value it wishes. If an application expects the X byte to be used as an alpha channel, then it should specify `JCS_EXT_RGBA`, `JCS_EXT_BGRA`, `JCS_EXT_ABGR`, or `JCS_EXT_ARGB`. When these colorspace constants are used, the X byte is guaranteed to be 0xFF, which is interpreted as opaque. Your application can check for the existence of the alpha channel colorspace extensions at compile time with: #ifdef JCS_ALPHA_EXTENSIONS [jcstest.c](jcstest.c), located in the libjpeg-turbo source tree, demonstrates how to check for the existence of the colorspace extensions at compile time and run time. libjpeg v7 and v8 API/ABI Emulation ----------------------------------- With libjpeg v7 and v8, new features were added that necessitated extending the compression and decompression structures. Unfortunately, due to the exposed nature of those structures, extending them also necessitated breaking backward ABI compatibility with previous libjpeg releases. Thus, programs that were built to use libjpeg v7 or v8 did not work with libjpeg-turbo, since it is based on the libjpeg v6b code base. Although libjpeg v7 and v8 are not as widely used as v6b, enough programs (including a few Linux distros) made the switch that there was a demand to emulate the libjpeg v7 and v8 ABIs in libjpeg-turbo. It should be noted, however, that this feature was added primarily so that applications that had already been compiled to use libjpeg v7+ could take advantage of accelerated baseline JPEG encoding/decoding without recompiling. libjpeg-turbo does not claim to support all of the libjpeg v7+ features, nor to produce identical output to libjpeg v7+ in all cases (see below.) By passing an argument of `--with-jpeg7` or `--with-jpeg8` to `configure`, or an argument of `-DWITH_JPEG7=1` or `-DWITH_JPEG8=1` to `cmake`, you can build a version of libjpeg-turbo that emulates the libjpeg v7 or v8 ABI, so that programs that are built against libjpeg v7 or v8 can be run with libjpeg-turbo. The following section describes which libjpeg v7+ features are supported and which aren't. ### Support for libjpeg v7 and v8 Features #### Fully supported - **libjpeg: IDCT scaling extensions in decompressor** libjpeg-turbo supports IDCT scaling with scaling factors of 1/8, 1/4, 3/8, 1/2, 5/8, 3/4, 7/8, 9/8, 5/4, 11/8, 3/2, 13/8, 7/4, 15/8, and 2/1 (only 1/4 and 1/2 are SIMD-accelerated.) - **libjpeg: Arithmetic coding** - **libjpeg: In-memory source and destination managers** See notes below. - **cjpeg: Separate quality settings for luminance and chrominance** Note that the libpjeg v7+ API was extended to accommodate this feature only for convenience purposes. It has always been possible to implement this feature with libjpeg v6b (see rdswitch.c for an example.) - **cjpeg: 32-bit BMP support** - **cjpeg: `-rgb` option** - **jpegtran: Lossless cropping** - **jpegtran: `-perfect` option** - **jpegtran: Forcing width/height when performing lossless crop** - **rdjpgcom: `-raw` option** - **rdjpgcom: Locale awareness** #### Not supported NOTE: As of this writing, extensive research has been conducted into the usefulness of DCT scaling as a means of data reduction and SmartScale as a means of quality improvement. The reader is invited to peruse the research at <http://www.libjpeg-turbo.org/About/SmartScale> and draw his/her own conclusions, but it is the general belief of our project that these features have not demonstrated sufficient usefulness to justify inclusion in libjpeg-turbo. - **libjpeg: DCT scaling in compressor** `cinfo.scale_num` and `cinfo.scale_denom` are silently ignored. There is no technical reason why DCT scaling could not be supported when