DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 1 | ******************************************************************************* |
| 2 | ** Background |
| 3 | ******************************************************************************* |
| 4 | |
DRC | 80803ae | 2011-12-15 13:12:59 +0000 | [diff] [blame] | 5 | libjpeg-turbo is a derivative of libjpeg that uses SIMD instructions (MMX, |
DRC | 11a122b | 2012-02-07 00:14:53 +0000 | [diff] [blame] | 6 | SSE2, NEON) to accelerate baseline JPEG compression and decompression on x86, |
| 7 | x86-64, and ARM systems. On such systems, libjpeg-turbo is generally 2-4x as |
| 8 | fast as the unmodified version of libjpeg, all else being equal. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 9 | |
| 10 | libjpeg-turbo was originally based on libjpeg/SIMD by Miyasaka Masaru, but |
DRC | 0d2d965 | 2011-02-18 22:29:45 +0000 | [diff] [blame] | 11 | the TigerVNC and VirtualGL projects made numerous enhancements to the codec in |
| 12 | 2009, including improved support for Mac OS X, 64-bit support, support for |
DRC | 11a122b | 2012-02-07 00:14:53 +0000 | [diff] [blame] | 13 | 32-bit and big-endian pixel formats (RGBX, XBGR, etc.), accelerated Huffman |
| 14 | encoding/decoding, and various bug fixes. The goal was to produce a fully |
| 15 | open-source codec that could replace the partially closed-source TurboJPEG/IPP |
| 16 | codec used by VirtualGL and TurboVNC. libjpeg-turbo generally achieves 80-120% |
| 17 | of the performance of TurboJPEG/IPP. It is faster in some areas but slower in |
| 18 | others. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 19 | |
DRC | 0d2d965 | 2011-02-18 22:29:45 +0000 | [diff] [blame] | 20 | In early 2010, libjpeg-turbo spun off into its own independent project, with |
| 21 | the goal of making high-speed JPEG compression/decompression technology |
DRC | 11a122b | 2012-02-07 00:14:53 +0000 | [diff] [blame] | 22 | available to a broader range of users and developers. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 23 | |
| 24 | |
| 25 | ******************************************************************************* |
DRC | ce1546e | 2010-02-13 23:06:03 +0000 | [diff] [blame] | 26 | ** License |
| 27 | ******************************************************************************* |
| 28 | |
DRC | 11a122b | 2012-02-07 00:14:53 +0000 | [diff] [blame] | 29 | Most of libjpeg-turbo inherits the non-restrictive, BSD-style license used by |
| 30 | libjpeg (see README.) The TurboJPEG/OSS wrapper (both C and Java versions) and |
DRC | b5624ee | 2011-05-24 14:12:07 +0000 | [diff] [blame] | 31 | associated test programs bear a similar license, which is reproduced below: |
DRC | 1e6b5b4 | 2010-03-20 20:00:51 +0000 | [diff] [blame] | 32 | |
DRC | b5624ee | 2011-05-24 14:12:07 +0000 | [diff] [blame] | 33 | Redistribution and use in source and binary forms, with or without |
| 34 | modification, are permitted provided that the following conditions are met: |
DRC | 65e0cd3 | 2011-04-26 23:44:37 +0000 | [diff] [blame] | 35 | |
DRC | b5624ee | 2011-05-24 14:12:07 +0000 | [diff] [blame] | 36 | - Redistributions of source code must retain the above copyright notice, |
| 37 | this list of conditions and the following disclaimer. |
| 38 | - Redistributions in binary form must reproduce the above copyright notice, |
| 39 | this list of conditions and the following disclaimer in the documentation |
| 40 | and/or other materials provided with the distribution. |
| 41 | - Neither the name of the libjpeg-turbo Project nor the names of its |
| 42 | contributors may be used to endorse or promote products derived from this |
| 43 | software without specific prior written permission. |
| 44 | |
| 45 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS", |
| 46 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| 47 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| 48 | ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE |
| 49 | LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
| 50 | CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
| 51 | SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
| 52 | INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
| 53 | CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
| 54 | ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
| 55 | POSSIBILITY OF SUCH DAMAGE. |
DRC | 7c1df0a | 2011-02-18 02:45:24 +0000 | [diff] [blame] | 56 | |
| 57 | |
| 58 | ******************************************************************************* |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 59 | ** Using libjpeg-turbo |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 60 | ******************************************************************************* |
| 61 | |
DRC | 80803ae | 2011-12-15 13:12:59 +0000 | [diff] [blame] | 62 | libjpeg-turbo includes two APIs that can be used to compress and decompress |
DRC | 9c4590e | 2011-07-26 09:22:16 +0000 | [diff] [blame] | 63 | JPEG images: |
| 64 | |
DRC | 11a122b | 2012-02-07 00:14:53 +0000 | [diff] [blame] | 65 | TurboJPEG API: This API provides an easy-to-use interface for compressing |
| 66 | and decompressing JPEG images in memory. It also provides some functionality |
| 67 | that would not be straightforward to achieve using the underlying libjpeg |
| 68 | API, such as generating planar YUV images and performing multiple |
| 69 | simultaneous lossless transforms on an image. The Java interface for |
| 70 | libjpeg-turbo is written on top of the TurboJPEG API. |
DRC | 9c4590e | 2011-07-26 09:22:16 +0000 | [diff] [blame] | 71 | |
DRC | 11a122b | 2012-02-07 00:14:53 +0000 | [diff] [blame] | 72 | libjpeg API: This is the de facto industry-standard API for compressing and |
DRC | 2c62da3 | 2012-01-17 22:55:03 +0000 | [diff] [blame] | 73 | decompressing JPEG images. It is more difficult to use than the TurboJPEG |
| 74 | API but also more powerful. libjpeg-turbo is both API/ABI-compatible and |
DRC | 9c4590e | 2011-07-26 09:22:16 +0000 | [diff] [blame] | 75 | mathematically compatible with libjpeg v6b. It can also optionally be |
| 76 | configured to be API/ABI-compatible with libjpeg v7 and v8 (see below.) |
| 77 | |
| 78 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 79 | ============================= |
| 80 | Replacing libjpeg at Run Time |
| 81 | ============================= |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 82 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 83 | If a Unix application is dynamically linked with libjpeg, then you can replace |
DRC | ab4db65 | 2011-02-18 04:55:08 +0000 | [diff] [blame] | 84 | libjpeg with libjpeg-turbo at run time by manipulating LD_LIBRARY_PATH. |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 85 | For instance: |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 86 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 87 | [Using libjpeg] |
| 88 | > time cjpeg <vgl_5674_0098.ppm >vgl_5674_0098.jpg |
| 89 | real 0m0.392s |
| 90 | user 0m0.074s |
| 91 | sys 0m0.020s |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 92 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 93 | [Using libjpeg-turbo] |
| 94 | > export LD_LIBRARY_PATH=/opt/libjpeg-turbo/{lib}:$LD_LIBRARY_PATH |
| 95 | > time cjpeg <vgl_5674_0098.ppm >vgl_5674_0098.jpg |
| 96 | real 0m0.109s |
| 97 | user 0m0.029s |
| 98 | sys 0m0.010s |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 99 | |
DRC | ff95aa6 | 2010-06-05 00:22:32 +0000 | [diff] [blame] | 100 | NOTE: {lib} can be lib, lib32, lib64, or lib/64, depending on the O/S and |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 101 | architecture. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 102 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 103 | System administrators can also replace the libjpeg sym links in /usr/{lib} with |
DRC | 11a122b | 2012-02-07 00:14:53 +0000 | [diff] [blame] | 104 | links to the libjpeg-turbo dynamic library located in /opt/libjpeg-turbo/{lib}. |
| 105 | This will effectively accelerate every application that uses the libjpeg |
| 106 | dynamic library on the system. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 107 | |
DRC | ab4db65 | 2011-02-18 04:55:08 +0000 | [diff] [blame] | 108 | The libjpeg-turbo SDK for Visual C++ installs the libjpeg-turbo DLL |
DRC | 11a122b | 2012-02-07 00:14:53 +0000 | [diff] [blame] | 109 | (jpeg62.dll, jpeg7.dll, or jpeg8.dll, depending on whether it was built with |
| 110 | libjpeg v6b, v7, or v8 emulation) into c:\libjpeg-turbo[64]\bin, and the PATH |
DRC | 5559c90 | 2010-10-18 02:21:10 +0000 | [diff] [blame] | 111 | environment variable can be modified such that this directory is searched |
| 112 | before any others that might contain a libjpeg DLL. However, if a libjpeg |
| 113 | DLL exists in an application's install directory, then Windows will load this |
| 114 | DLL first whenever the application is launched. Thus, if an application ships |
| 115 | with jpeg62.dll, jpeg7.dll, or jpeg8.dll, then back up the application's |
DRC | ab4db65 | 2011-02-18 04:55:08 +0000 | [diff] [blame] | 116 | version of this DLL and copy c:\libjpeg-turbo[64]\bin\jpeg*.dll into the |
DRC | 5559c90 | 2010-10-18 02:21:10 +0000 | [diff] [blame] | 117 | application's install directory to accelerate it. |
DRC | 7e0b499 | 2010-02-25 05:52:44 +0000 | [diff] [blame] | 118 | |
DRC | ab4db65 | 2011-02-18 04:55:08 +0000 | [diff] [blame] | 119 | The version of the libjpeg-turbo DLL distributed in the libjpeg-turbo SDK for |
DRC | 11a122b | 2012-02-07 00:14:53 +0000 | [diff] [blame] | 120 | Visual C++ requires the Visual C++ 2008 C run-time DLL (msvcr90.dll). |
DRC | 5559c90 | 2010-10-18 02:21:10 +0000 | [diff] [blame] | 121 | msvcr90.dll ships with more recent versions of Windows, but users of older |
| 122 | Windows releases can obtain it from the Visual C++ 2008 Redistributable |
| 123 | Package, which is available as a free download from Microsoft's web site. |
DRC | 0248dd9 | 2010-02-25 06:21:12 +0000 | [diff] [blame] | 124 | |
DRC | 11a122b | 2012-02-07 00:14:53 +0000 | [diff] [blame] | 125 | NOTE: Features of libjpeg that require passing a C run-time structure, such |
DRC | 0248dd9 | 2010-02-25 06:21:12 +0000 | [diff] [blame] | 126 | as a file handle, from an application to libjpeg will probably not work with |
DRC | ab4db65 | 2011-02-18 04:55:08 +0000 | [diff] [blame] | 127 | the version of the libjpeg-turbo DLL distributed in the libjpeg-turbo SDK for |
| 128 | Visual C++, unless the application is also built to use the Visual C++ 2008 C |
DRC | 11a122b | 2012-02-07 00:14:53 +0000 | [diff] [blame] | 129 | run-time DLL. In particular, this affects jpeg_stdio_dest() and |
DRC | ab4db65 | 2011-02-18 04:55:08 +0000 | [diff] [blame] | 130 | jpeg_stdio_src(). |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 131 | |
DRC | 5559c90 | 2010-10-18 02:21:10 +0000 | [diff] [blame] | 132 | Mac applications typically embed their own copies of the libjpeg dylib inside |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 133 | the (hidden) application bundle, so it is not possible to globally replace |
| 134 | libjpeg on OS X systems. If an application uses a shared library version of |
| 135 | libjpeg, then it may be possible to replace the application's version of it. |
DRC | 5559c90 | 2010-10-18 02:21:10 +0000 | [diff] [blame] | 136 | This would generally involve copying libjpeg.*.dylib from libjpeg-turbo into |
| 137 | the appropriate place in the application bundle and using install_name_tool to |
| 138 | repoint the dylib to the new directory. This requires an advanced knowledge of |
| 139 | OS X and would not survive an upgrade or a re-install of the application. |
| 140 | Thus, it is not recommended for most users. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 141 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 142 | ======================= |
| 143 | Replacing TurboJPEG/IPP |
| 144 | ======================= |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 145 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 146 | libjpeg-turbo is a drop-in replacement for the TurboJPEG/IPP SDK used by |
DRC | ff95aa6 | 2010-06-05 00:22:32 +0000 | [diff] [blame] | 147 | VirtualGL 2.1.x and TurboVNC 0.6 (and prior.) libjpeg-turbo contains a wrapper |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 148 | library (TurboJPEG/OSS) that emulates the TurboJPEG API using libjpeg-turbo |
DRC | 11a122b | 2012-02-07 00:14:53 +0000 | [diff] [blame] | 149 | instead of the closed-source Intel Performance Primitives. You can replace the |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 150 | TurboJPEG/IPP package on Linux systems with the libjpeg-turbo package in order |
DRC | ab4db65 | 2011-02-18 04:55:08 +0000 | [diff] [blame] | 151 | to make existing releases of VirtualGL 2.1.x and TurboVNC 0.x use the new codec |
| 152 | at run time. Note that the 64-bit libjpeg-turbo packages contain only 64-bit |
DRC | ff95aa6 | 2010-06-05 00:22:32 +0000 | [diff] [blame] | 153 | binaries, whereas the TurboJPEG/IPP 64-bit packages contained both 64-bit and |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 154 | 32-bit binaries. Thus, to replace a TurboJPEG/IPP 64-bit package, install |
| 155 | both the 64-bit and 32-bit versions of libjpeg-turbo. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 156 | |
DRC | ff95aa6 | 2010-06-05 00:22:32 +0000 | [diff] [blame] | 157 | You can also build the VirtualGL 2.1.x and TurboVNC 0.6 source code with |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 158 | the libjpeg-turbo SDK instead of TurboJPEG/IPP. It should work identically. |
| 159 | libjpeg-turbo also includes static library versions of TurboJPEG/OSS, which |
DRC | 11a122b | 2012-02-07 00:14:53 +0000 | [diff] [blame] | 160 | are used to build VirtualGL 2.2 and TurboVNC 1.0 and later. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 161 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 162 | ======================================== |
| 163 | Using libjpeg-turbo in Your Own Programs |
| 164 | ======================================== |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 165 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 166 | For the most part, libjpeg-turbo should work identically to libjpeg, so in |
| 167 | most cases, an application can be built against libjpeg and then run against |
DRC | 5559c90 | 2010-10-18 02:21:10 +0000 | [diff] [blame] | 168 | libjpeg-turbo. On Unix systems (including Cygwin), you can build against |
| 169 | libjpeg-turbo instead of libjpeg by setting |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 170 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 171 | CPATH=/opt/libjpeg-turbo/include |
| 172 | and |
| 173 | LIBRARY_PATH=/opt/libjpeg-turbo/{lib} |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 174 | |
DRC | ff95aa6 | 2010-06-05 00:22:32 +0000 | [diff] [blame] | 175 | ({lib} = lib32 or lib64, depending on whether you are building a 32-bit or a |
| 176 | 64-bit application.) |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 177 | |
DRC | 0a1f68e | 2010-02-24 07:24:26 +0000 | [diff] [blame] | 178 | If using MinGW, then set |
| 179 | |
DRC | 3dc1bc2 | 2010-05-10 22:18:10 +0000 | [diff] [blame] | 180 | CPATH=/c/libjpeg-turbo-gcc[64]/include |
DRC | 0a1f68e | 2010-02-24 07:24:26 +0000 | [diff] [blame] | 181 | and |
DRC | 3dc1bc2 | 2010-05-10 22:18:10 +0000 | [diff] [blame] | 182 | LIBRARY_PATH=/c/libjpeg-turbo-gcc[64]/lib |
DRC | 0a1f68e | 2010-02-24 07:24:26 +0000 | [diff] [blame] | 183 | |
| 184 | Building against libjpeg-turbo is useful, for instance, if you want to build an |
| 185 | application that leverages the libjpeg-turbo colorspace extensions (see below.) |
DRC | ab4db65 | 2011-02-18 04:55:08 +0000 | [diff] [blame] | 186 | On Linux and Solaris systems, you would still need to manipulate |
| 187 | LD_LIBRARY_PATH or create appropriate sym links to use libjpeg-turbo at run |
| 188 | time. On such systems, you can pass -R /opt/libjpeg-turbo/{lib} to the linker |
| 189 | to force the use of libjpeg-turbo at run time rather than libjpeg (also useful |
| 190 | if you want to leverage the colorspace extensions), or you can link against the |
DRC | 0a1f68e | 2010-02-24 07:24:26 +0000 | [diff] [blame] | 191 | libjpeg-turbo static library. |
| 192 | |
| 193 | To force a Linux, Solaris, or MinGW application to link against the static |
| 194 | version of libjpeg-turbo, you can use the following linker options: |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 195 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 196 | -Wl,-Bstatic -ljpeg -Wl,-Bdynamic |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 197 | |
DRC | ff95aa6 | 2010-06-05 00:22:32 +0000 | [diff] [blame] | 198 | On OS X, simply add /opt/libjpeg-turbo/lib/libjpeg.a to the linker command |
DRC | 0a1f68e | 2010-02-24 07:24:26 +0000 | [diff] [blame] | 199 | line (this also works on Linux and Solaris.) |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 200 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 201 | To build Visual C++ applications using libjpeg-turbo, add |
DRC | ab4db65 | 2011-02-18 04:55:08 +0000 | [diff] [blame] | 202 | c:\libjpeg-turbo[64]\include to the system or user INCLUDE environment |
| 203 | variable and c:\libjpeg-turbo[64]\lib to the system or user LIB environment |
DRC | 5559c90 | 2010-10-18 02:21:10 +0000 | [diff] [blame] | 204 | variable, and then link against either jpeg.lib (to use the DLL version of |
| 205 | libjpeg-turbo) or jpeg-static.lib (to use the static version of libjpeg-turbo.) |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 206 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 207 | ===================== |
| 208 | Colorspace Extensions |
| 209 | ===================== |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 210 | |
DRC | 80803ae | 2011-12-15 13:12:59 +0000 | [diff] [blame] | 211 | libjpeg-turbo includes extensions that allow JPEG images to be compressed |
| 212 | directly from (and decompressed directly to) buffers that use BGR, BGRX, |
DRC | 67ce3b2 | 2011-12-19 02:21:03 +0000 | [diff] [blame] | 213 | RGBX, XBGR, and XRGB pixel ordering. This is implemented with ten new |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 214 | colorspace constants: |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 215 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 216 | JCS_EXT_RGB /* red/green/blue */ |
| 217 | JCS_EXT_RGBX /* red/green/blue/x */ |
| 218 | JCS_EXT_BGR /* blue/green/red */ |
| 219 | JCS_EXT_BGRX /* blue/green/red/x */ |
| 220 | JCS_EXT_XBGR /* x/blue/green/red */ |
| 221 | JCS_EXT_XRGB /* x/red/green/blue */ |
DRC | 67ce3b2 | 2011-12-19 02:21:03 +0000 | [diff] [blame] | 222 | JCS_EXT_RGBA /* red/green/blue/alpha */ |
| 223 | JCS_EXT_BGRA /* blue/green/red/alpha */ |
| 224 | JCS_EXT_ABGR /* alpha/blue/green/red */ |
| 225 | JCS_EXT_ARGB /* alpha/red/green/blue */ |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 226 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 227 | Setting cinfo.in_color_space (compression) or cinfo.out_color_space |
| 228 | (decompression) to one of these values will cause libjpeg-turbo to read the |
| 229 | red, green, and blue values from (or write them to) the appropriate position in |
DRC | b76c840 | 2011-12-19 15:01:55 +0000 | [diff] [blame] | 230 | the pixel when compressing from/decompressing to an RGB buffer. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 231 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 232 | Your application can check for the existence of these extensions at compile |
| 233 | time with: |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 234 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 235 | #ifdef JCS_EXTENSIONS |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 236 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 237 | At run time, attempting to use these extensions with a version of libjpeg |
| 238 | that doesn't support them will result in a "Bogus input colorspace" error. |
DRC | 77e3964 | 2010-10-12 03:02:31 +0000 | [diff] [blame] | 239 | |
DRC | 67ce3b2 | 2011-12-19 02:21:03 +0000 | [diff] [blame] | 240 | When using the RGBX, BGRX, XBGR, and XRGB colorspaces during decompression, the |
| 241 | X byte is undefined, and in order to ensure the best performance, libjpeg-turbo |
| 242 | can set that byte to whatever value it wishes. If an application expects the X |
DRC | b76c840 | 2011-12-19 15:01:55 +0000 | [diff] [blame] | 243 | byte to be used as an alpha channel, then it should specify JCS_EXT_RGBA, |
DRC | 67ce3b2 | 2011-12-19 02:21:03 +0000 | [diff] [blame] | 244 | JCS_EXT_BGRA, JCS_EXT_ABGR, or JCS_EXT_ARGB. When these colorspace constants |
| 245 | are used, the X byte is guaranteed to be 0xFF, which is interpreted as opaque. |
| 246 | |
| 247 | Your application can check for the existence of the alpha channel colorspace |
| 248 | extensions at compile time with: |
| 249 | |
| 250 | #ifdef JCS_ALPHA_EXTENSIONS |
| 251 | |
DRC | b76c840 | 2011-12-19 15:01:55 +0000 | [diff] [blame] | 252 | jcstest.c, located in the libjpeg-turbo source tree, demonstrates how to check |
| 253 | for the existence of the colorspace extensions at compile time and run time. |
| 254 | |
DRC | 77e3964 | 2010-10-12 03:02:31 +0000 | [diff] [blame] | 255 | ================================= |
| 256 | libjpeg v7 and v8 API/ABI support |
| 257 | ================================= |
| 258 | |
DRC | 6916f87 | 2012-02-03 08:59:21 +0000 | [diff] [blame] | 259 | With libjpeg v7 and v8, new features were added that necessitated extending the |
| 260 | compression and decompression structures. Unfortunately, due to the exposed |
| 261 | nature of those structures, extending them also necessitated breaking backward |
| 262 | ABI compatibility with previous libjpeg releases. Thus, programs that are |
DRC | 77e3964 | 2010-10-12 03:02:31 +0000 | [diff] [blame] | 263 | built to use libjpeg v7 or v8 did not work with libjpeg-turbo, since it is |
| 264 | based on the libjpeg v6b code base. Although libjpeg v7 and v8 are still not |
| 265 | as widely used as v6b, enough programs (including a few Linux distros) have |
| 266 | made the switch that it was desirable to provide support for the libjpeg v7/v8 |
DRC | 6916f87 | 2012-02-03 08:59:21 +0000 | [diff] [blame] | 267 | API/ABI in libjpeg-turbo. Although libjpeg-turbo can now be configured as a |
| 268 | drop-in replacement for libjpeg v7 or v8, it should be noted that not all of |
| 269 | the features in libjpeg v7 and v8 are supported (see below.) |
DRC | 77e3964 | 2010-10-12 03:02:31 +0000 | [diff] [blame] | 270 | |
DRC | 5559c90 | 2010-10-18 02:21:10 +0000 | [diff] [blame] | 271 | By passing an argument of --with-jpeg7 or --with-jpeg8 to configure, or an |
| 272 | argument of -DWITH_JPEG7=1 or -DWITH_JPEG8=1 to cmake, you can build a version |
DRC | 80803ae | 2011-12-15 13:12:59 +0000 | [diff] [blame] | 273 | of libjpeg-turbo that emulates the libjpeg v7 or v8 API/ABI, so that programs |
| 274 | that are built against libjpeg v7 or v8 can be run with libjpeg-turbo. The |
DRC | 5559c90 | 2010-10-18 02:21:10 +0000 | [diff] [blame] | 275 | following section describes which libjpeg v7+ features are supported and which |
| 276 | aren't. |
DRC | 77e3964 | 2010-10-12 03:02:31 +0000 | [diff] [blame] | 277 | |
| 278 | libjpeg v7 and v8 Features: |
| 279 | --------------------------- |
| 280 | |
| 281 | Fully supported: |
| 282 | |
| 283 | -- cjpeg: Separate quality settings for luminance and chrominance |
| 284 | Note that the libpjeg v7+ API was extended to accommodate this feature only |
| 285 | for convenience purposes. It has always been possible to implement this |
| 286 | feature with libjpeg v6b (see rdswitch.c for an example.) |
| 287 | |
| 288 | -- cjpeg: 32-bit BMP support |
| 289 | |
| 290 | -- jpegtran: lossless cropping |
| 291 | |
| 292 | -- jpegtran: -perfect option |
| 293 | |
| 294 | -- rdjpgcom: -raw option |
| 295 | |
| 296 | -- rdjpgcom: locale awareness |
| 297 | |
| 298 | |
| 299 | Fully supported when using libjpeg v7/v8 emulation: |
| 300 | |
| 301 | -- libjpeg: In-memory source and destination managers |
| 302 | |
| 303 | |
| 304 | Not supported: |
| 305 | |
| 306 | -- libjpeg: DCT scaling in compressor |
| 307 | cinfo.scale_num and cinfo.scale_denom are silently ignored. |
DRC | 6916f87 | 2012-02-03 08:59:21 +0000 | [diff] [blame] | 308 | There is no technical reason why DCT scaling cannot be supported, but |
| 309 | without the SmartScale extension (see below), it would only be able to |
| 310 | down-scale using ratios of 1/2, 8/15, 4/7, 8/13, 2/3, 8/11, 4/5, and 8/9, |
| 311 | which is of limited usefulness. |
| 312 | |
| 313 | -- libjpeg: SmartScale |
| 314 | cinfo.block_size is silently ignored. |
| 315 | SmartScale is an extension to the JPEG format that allows for DCT block |
| 316 | sizes other than 8x8. It would be difficult to support this feature while |
| 317 | retaining backward compatibility with libjpeg v6b. |
DRC | 77e3964 | 2010-10-12 03:02:31 +0000 | [diff] [blame] | 318 | |
| 319 | -- libjpeg: IDCT scaling extensions in decompressor |
| 320 | libjpeg-turbo still supports IDCT scaling with scaling factors of 1/2, 1/4, |
| 321 | and 1/8 (same as libjpeg v6b.) |
| 322 | |
| 323 | -- libjpeg: Fancy downsampling in compressor |
| 324 | cinfo.do_fancy_downsampling is silently ignored. |
DRC | 6916f87 | 2012-02-03 08:59:21 +0000 | [diff] [blame] | 325 | This requires the DCT scaling feature, which is not supported. |
DRC | 77e3964 | 2010-10-12 03:02:31 +0000 | [diff] [blame] | 326 | |
DRC | 77e3964 | 2010-10-12 03:02:31 +0000 | [diff] [blame] | 327 | -- jpegtran: Scaling |
DRC | 6916f87 | 2012-02-03 08:59:21 +0000 | [diff] [blame] | 328 | This requires both the DCT scaling and SmartScale features, which are not |
| 329 | supported. |
| 330 | |
| 331 | -- Lossless RGB JPEG files |
| 332 | This requires the SmartScale feature, which is not supported. |
DRC | ab4db65 | 2011-02-18 04:55:08 +0000 | [diff] [blame] | 333 | |
| 334 | |
| 335 | ******************************************************************************* |
| 336 | ** Performance pitfalls |
| 337 | ******************************************************************************* |
| 338 | |
| 339 | =============== |
| 340 | Restart Markers |
| 341 | =============== |
| 342 | |
| 343 | The optimized Huffman decoder in libjpeg-turbo does not handle restart markers |
DRC | 11a122b | 2012-02-07 00:14:53 +0000 | [diff] [blame] | 344 | in a way that makes the rest of the libjpeg infrastructure happy, so it is |
| 345 | necessary to use the slow Huffman decoder when decompressing a JPEG image that |
| 346 | has restart markers. This can cause the decompression performance to drop by |
| 347 | as much as 20%, but the performance will still be much greater than that of |
| 348 | libjpeg. Many consumer packages, such as PhotoShop, use restart markers when |
| 349 | generating JPEG images, so images generated by those programs will experience |
| 350 | this issue. |
DRC | ab4db65 | 2011-02-18 04:55:08 +0000 | [diff] [blame] | 351 | |
| 352 | =============================================== |
| 353 | Fast Integer Forward DCT at High Quality Levels |
| 354 | =============================================== |
| 355 | |
| 356 | The algorithm used by the SIMD-accelerated quantization function cannot produce |
| 357 | correct results whenever the fast integer forward DCT is used along with a JPEG |
| 358 | quality of 98-100. Thus, libjpeg-turbo must use the non-SIMD quantization |
| 359 | function in those cases. This causes performance to drop by as much as 40%. |
| 360 | It is therefore strongly advised that you use the slow integer forward DCT |
| 361 | whenever encoding images with a JPEG quality of 98 or higher. |