DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 1 | ******************************************************************************* |
| 2 | ** Background |
| 3 | ******************************************************************************* |
| 4 | |
| 5 | libjpeg-turbo is a high-speed version of libjpeg for x86 and x86-64 processors |
| 6 | which uses SIMD instructions (MMX, SSE2, etc.) to accelerate baseline JPEG |
DRC | ce1546e | 2010-02-13 23:06:03 +0000 | [diff] [blame] | 7 | compression and decompression. libjpeg-turbo is generally 2-4x as fast |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 8 | as the unmodified version of libjpeg, all else being equal. |
| 9 | |
| 10 | libjpeg-turbo was originally based on libjpeg/SIMD by Miyasaka Masaru, but |
| 11 | the TigerVNC and VirtualGL projects made numerous enhancements to the codec, |
| 12 | including improved support for Mac OS X, 64-bit support, support for 32-bit |
| 13 | and big endian pixel formats, accelerated Huffman encoding/decoding, and |
| 14 | various bug fixes. The goal was to produce a fully open source codec that |
| 15 | could replace the partially closed source TurboJPEG/IPP codec used by VirtualGL |
DRC | ce1546e | 2010-02-13 23:06:03 +0000 | [diff] [blame] | 16 | and TurboVNC. libjpeg-turbo generally performs in the range of 80-120% of |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 17 | TurboJPEG/IPP. It is faster in some areas but slower in others. |
| 18 | |
| 19 | It was decided to split libjpeg-turbo into a separate SDK so that other |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 20 | projects could take advantage of this technology. The libjpeg-turbo shared |
| 21 | libraries can be used as drop-in replacements for libjpeg on most systems. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 22 | |
| 23 | |
| 24 | ******************************************************************************* |
DRC | ce1546e | 2010-02-13 23:06:03 +0000 | [diff] [blame] | 25 | ** License |
| 26 | ******************************************************************************* |
| 27 | |
DRC | ae7fe0b | 2010-08-11 21:46:46 +0000 | [diff] [blame] | 28 | Some of the optimizations to the Huffman encoder (jchuff.c) and decoder |
| 29 | (jdhuff.c) were borrowed from VirtualGL, and thus any distribution of |
| 30 | libjpeg-turbo which includes those optimizations must, as a whole, be subject |
| 31 | to the terms of the wxWindows Library Licence, Version 3.1. A copy of this |
| 32 | license can be found in this directory under LICENSE.txt. The wxWindows |
| 33 | Library License is based on the LGPL but includes provisions which allow the |
| 34 | Library to be statically linked into proprietary libraries and applications |
| 35 | without requiring the resulting binaries to be distributed under the terms of |
| 36 | the LGPL. |
DRC | 1e6b5b4 | 2010-03-20 20:00:51 +0000 | [diff] [blame] | 37 | |
DRC | ae7fe0b | 2010-08-11 21:46:46 +0000 | [diff] [blame] | 38 | The rest of the source code, apart from the Huffman codec optimizations, falls |
| 39 | under a less restrictive, BSD-style license (see README.) You can choose to |
| 40 | distribute libjpeg-turbo, as a whole, under this BSD-style license by simply |
| 41 | replacing the optimized jchuff.c and jdhuff.c with their unoptimized |
| 42 | counterparts from the libjpeg v6b source. |
DRC | ce1546e | 2010-02-13 23:06:03 +0000 | [diff] [blame] | 43 | |
| 44 | |
| 45 | ******************************************************************************* |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 46 | ** Using libjpeg-turbo |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 47 | ******************************************************************************* |
| 48 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 49 | ============================= |
| 50 | Replacing libjpeg at Run Time |
| 51 | ============================= |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 52 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 53 | If a Unix application is dynamically linked with libjpeg, then you can replace |
| 54 | libjpeg with libjpeg-turbo at run time by manipulating the LD_LIBRARY_PATH. |
| 55 | For instance: |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 56 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 57 | [Using libjpeg] |
| 58 | > time cjpeg <vgl_5674_0098.ppm >vgl_5674_0098.jpg |
| 59 | real 0m0.392s |
| 60 | user 0m0.074s |
| 61 | sys 0m0.020s |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 62 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 63 | [Using libjpeg-turbo] |
| 64 | > export LD_LIBRARY_PATH=/opt/libjpeg-turbo/{lib}:$LD_LIBRARY_PATH |
| 65 | > time cjpeg <vgl_5674_0098.ppm >vgl_5674_0098.jpg |
| 66 | real 0m0.109s |
| 67 | user 0m0.029s |
| 68 | sys 0m0.010s |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 69 | |
DRC | ff95aa6 | 2010-06-05 00:22:32 +0000 | [diff] [blame] | 70 | 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] | 71 | architecture. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 72 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 73 | System administrators can also replace the libjpeg sym links in /usr/{lib} with |
| 74 | links to the libjpeg dynamic library located in /opt/libjpeg-turbo/{lib}. This |
| 75 | will effectively accelerate every dynamically linked libjpeg application on the |
| 76 | system. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 77 | |
DRC | 5559c90 | 2010-10-18 02:21:10 +0000 | [diff] [blame] | 78 | The Windows distribution of the libjpeg-turbo SDK installs the libjpeg-turbo |
| 79 | DLL (jpeg62.dll, jpeg7.dll, or jpeg8.dll, depending on whether libjpeg v6b, |
| 80 | v7, or v8 emulation is enabled) into c:\libjpeg-turbo[64]\bin, and the PATH |
| 81 | environment variable can be modified such that this directory is searched |
| 82 | before any others that might contain a libjpeg DLL. However, if a libjpeg |
| 83 | DLL exists in an application's install directory, then Windows will load this |
| 84 | DLL first whenever the application is launched. Thus, if an application ships |
| 85 | with jpeg62.dll, jpeg7.dll, or jpeg8.dll, then back up the application's |
| 86 | version of this DLL and copy c:\libjpeg-turbo\bin\jpeg*.dll into the |
| 87 | application's install directory to accelerate it. |
DRC | 7e0b499 | 2010-02-25 05:52:44 +0000 | [diff] [blame] | 88 | |
DRC | 5559c90 | 2010-10-18 02:21:10 +0000 | [diff] [blame] | 89 | The version of the libjpeg-turbo DLL distributed with the "official" |
| 90 | libjpeg-turbo SDK requires the Visual C++ 2008 C run time DLL (msvcr90.dll). |
| 91 | msvcr90.dll ships with more recent versions of Windows, but users of older |
| 92 | Windows releases can obtain it from the Visual C++ 2008 Redistributable |
| 93 | Package, which is available as a free download from Microsoft's web site. |
DRC | 0248dd9 | 2010-02-25 06:21:12 +0000 | [diff] [blame] | 94 | |
| 95 | NOTE: Features of libjpeg which require passing a C run time structure, such |
| 96 | as a file handle, from an application to libjpeg will probably not work with |
DRC | 5559c90 | 2010-10-18 02:21:10 +0000 | [diff] [blame] | 97 | the "official" version of the libjpeg-turbo DLL unless the application is also |
| 98 | built to use the Visual C++ 2008 C run time DLL. In particular, this affects |
DRC | 0248dd9 | 2010-02-25 06:21:12 +0000 | [diff] [blame] | 99 | jpeg_stdio_dest() and jpeg_stdio_src(). |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 100 | |
DRC | 5559c90 | 2010-10-18 02:21:10 +0000 | [diff] [blame] | 101 | Mac applications typically embed their own copies of the libjpeg dylib inside |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 102 | the (hidden) application bundle, so it is not possible to globally replace |
| 103 | libjpeg on OS X systems. If an application uses a shared library version of |
| 104 | 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] | 105 | This would generally involve copying libjpeg.*.dylib from libjpeg-turbo into |
| 106 | the appropriate place in the application bundle and using install_name_tool to |
| 107 | repoint the dylib to the new directory. This requires an advanced knowledge of |
| 108 | OS X and would not survive an upgrade or a re-install of the application. |
| 109 | Thus, it is not recommended for most users. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 110 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 111 | ======================= |
| 112 | Replacing TurboJPEG/IPP |
| 113 | ======================= |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 114 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 115 | 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] | 116 | 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] | 117 | library (TurboJPEG/OSS) that emulates the TurboJPEG API using libjpeg-turbo |
| 118 | instead of the closed source Intel Performance Primitives. You can replace the |
| 119 | TurboJPEG/IPP package on Linux systems with the libjpeg-turbo package in order |
| 120 | to make existing releases of VirtualGL 2.1.x and TurboVNC use the new codec at |
| 121 | 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] | 122 | binaries, whereas the TurboJPEG/IPP 64-bit packages contained both 64-bit and |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 123 | 32-bit binaries. Thus, to replace a TurboJPEG/IPP 64-bit package, install |
| 124 | both the 64-bit and 32-bit versions of libjpeg-turbo. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 125 | |
DRC | ff95aa6 | 2010-06-05 00:22:32 +0000 | [diff] [blame] | 126 | 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] | 127 | the libjpeg-turbo SDK instead of TurboJPEG/IPP. It should work identically. |
| 128 | libjpeg-turbo also includes static library versions of TurboJPEG/OSS, which |
DRC | ff95aa6 | 2010-06-05 00:22:32 +0000 | [diff] [blame] | 129 | are used to build TurboVNC 1.0 and later. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 130 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 131 | ======================================== |
| 132 | Using libjpeg-turbo in Your Own Programs |
| 133 | ======================================== |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 134 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 135 | For the most part, libjpeg-turbo should work identically to libjpeg, so in |
| 136 | most cases, an application can be built against libjpeg and then run against |
DRC | 5559c90 | 2010-10-18 02:21:10 +0000 | [diff] [blame] | 137 | libjpeg-turbo. On Unix systems (including Cygwin), you can build against |
| 138 | libjpeg-turbo instead of libjpeg by setting |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 139 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 140 | CPATH=/opt/libjpeg-turbo/include |
| 141 | and |
| 142 | LIBRARY_PATH=/opt/libjpeg-turbo/{lib} |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 143 | |
DRC | ff95aa6 | 2010-06-05 00:22:32 +0000 | [diff] [blame] | 144 | ({lib} = lib32 or lib64, depending on whether you are building a 32-bit or a |
| 145 | 64-bit application.) |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 146 | |
DRC | 0a1f68e | 2010-02-24 07:24:26 +0000 | [diff] [blame] | 147 | If using MinGW, then set |
| 148 | |
DRC | 3dc1bc2 | 2010-05-10 22:18:10 +0000 | [diff] [blame] | 149 | CPATH=/c/libjpeg-turbo-gcc[64]/include |
DRC | 0a1f68e | 2010-02-24 07:24:26 +0000 | [diff] [blame] | 150 | and |
DRC | 3dc1bc2 | 2010-05-10 22:18:10 +0000 | [diff] [blame] | 151 | LIBRARY_PATH=/c/libjpeg-turbo-gcc[64]/lib |
DRC | 0a1f68e | 2010-02-24 07:24:26 +0000 | [diff] [blame] | 152 | |
| 153 | Building against libjpeg-turbo is useful, for instance, if you want to build an |
| 154 | application that leverages the libjpeg-turbo colorspace extensions (see below.) |
| 155 | On Linux and Solaris systems, you would still need to manipulate the |
| 156 | LD_LIBRARY_PATH or sym links appropriately to use libjpeg-turbo at run time. |
| 157 | On such systems, you can pass -R /opt/libjpeg-turbo/{lib} to the linker to |
| 158 | force the use of libjpeg-turbo at run time rather than libjpeg (also useful if |
| 159 | you want to leverage the colorspace extensions), or you can link against the |
| 160 | libjpeg-turbo static library. |
| 161 | |
| 162 | To force a Linux, Solaris, or MinGW application to link against the static |
| 163 | version of libjpeg-turbo, you can use the following linker options: |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 164 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 165 | -Wl,-Bstatic -ljpeg -Wl,-Bdynamic |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 166 | |
DRC | ff95aa6 | 2010-06-05 00:22:32 +0000 | [diff] [blame] | 167 | 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] | 168 | line (this also works on Linux and Solaris.) |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 169 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 170 | To build Visual C++ applications using libjpeg-turbo, add |
DRC | 3dc1bc2 | 2010-05-10 22:18:10 +0000 | [diff] [blame] | 171 | c:\libjpeg-turbo[64]\include to your system or user INCLUDE environment |
| 172 | variable and c:\libjpeg-turbo[64]\lib to your system or user LIB environment |
DRC | 5559c90 | 2010-10-18 02:21:10 +0000 | [diff] [blame] | 173 | variable, and then link against either jpeg.lib (to use the DLL version of |
| 174 | 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] | 175 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 176 | ===================== |
| 177 | Colorspace Extensions |
| 178 | ===================== |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 179 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 180 | libjpeg-turbo includes extensions which allow JPEG images to be compressed |
DRC | 646e5a8 | 2010-11-18 19:55:29 +0000 | [diff] [blame] | 181 | directly from (and decompressed directly to) buffers which use BGR, BGRX, |
| 182 | RGBX, XBGR, and XRGB pixel ordering. This is implemented with six new |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 183 | colorspace constants: |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 184 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 185 | JCS_EXT_RGB /* red/green/blue */ |
| 186 | JCS_EXT_RGBX /* red/green/blue/x */ |
| 187 | JCS_EXT_BGR /* blue/green/red */ |
| 188 | JCS_EXT_BGRX /* blue/green/red/x */ |
| 189 | JCS_EXT_XBGR /* x/blue/green/red */ |
| 190 | JCS_EXT_XRGB /* x/red/green/blue */ |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 191 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 192 | Setting cinfo.in_color_space (compression) or cinfo.out_color_space |
| 193 | (decompression) to one of these values will cause libjpeg-turbo to read the |
| 194 | red, green, and blue values from (or write them to) the appropriate position in |
| 195 | the pixel when YUV conversion is performed. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 196 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 197 | Your application can check for the existence of these extensions at compile |
| 198 | time with: |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 199 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 200 | #ifdef JCS_EXTENSIONS |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 201 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 202 | At run time, attempting to use these extensions with a version of libjpeg |
| 203 | that doesn't support them will result in a "Bogus input colorspace" error. |
DRC | 77e3964 | 2010-10-12 03:02:31 +0000 | [diff] [blame] | 204 | |
| 205 | ================================= |
| 206 | libjpeg v7 and v8 API/ABI support |
| 207 | ================================= |
| 208 | |
| 209 | libjpeg v7 and v8 added new features to the API/ABI, and, unfortunately, the |
| 210 | compression and decompression structures were extended in a backward- |
| 211 | incompatible manner to accommodate these features. Thus, programs which are |
| 212 | built to use libjpeg v7 or v8 did not work with libjpeg-turbo, since it is |
| 213 | based on the libjpeg v6b code base. Although libjpeg v7 and v8 are still not |
| 214 | as widely used as v6b, enough programs (including a few Linux distros) have |
| 215 | made the switch that it was desirable to provide support for the libjpeg v7/v8 |
| 216 | API/ABI in libjpeg-turbo. |
| 217 | |
| 218 | Some of the libjpeg v7 and v8 features -- DCT scaling, to name one -- involve |
| 219 | deep modifications to the code which cannot be accommodated by libjpeg-turbo |
| 220 | without either breaking compatibility with libjpeg v6b or producing an |
| 221 | unsupportable mess. In order to fully support libjpeg v8 with all of its |
| 222 | features, we would have to essentially port the SIMD extensions to the libjpeg |
| 223 | v8 code base and maintain two separate code trees. We are hesitant to do this |
| 224 | until/unless the newer libjpeg code bases garner more community support and |
| 225 | involvement and until/unless we have some notion of whether future libjpeg |
| 226 | releases will also be backward-incompatible. |
| 227 | |
DRC | 5559c90 | 2010-10-18 02:21:10 +0000 | [diff] [blame] | 228 | By passing an argument of --with-jpeg7 or --with-jpeg8 to configure, or an |
| 229 | argument of -DWITH_JPEG7=1 or -DWITH_JPEG8=1 to cmake, you can build a version |
| 230 | of libjpeg-turbo which emulates the libjpeg v7 or v8b API/ABI, so that programs |
| 231 | which are built against libjpeg v7 or v8 can be run with libjpeg-turbo. The |
| 232 | following section describes which libjpeg v7+ features are supported and which |
| 233 | aren't. |
DRC | 77e3964 | 2010-10-12 03:02:31 +0000 | [diff] [blame] | 234 | |
| 235 | libjpeg v7 and v8 Features: |
| 236 | --------------------------- |
| 237 | |
| 238 | Fully supported: |
| 239 | |
| 240 | -- cjpeg: Separate quality settings for luminance and chrominance |
| 241 | Note that the libpjeg v7+ API was extended to accommodate this feature only |
| 242 | for convenience purposes. It has always been possible to implement this |
| 243 | feature with libjpeg v6b (see rdswitch.c for an example.) |
| 244 | |
| 245 | -- cjpeg: 32-bit BMP support |
| 246 | |
| 247 | -- jpegtran: lossless cropping |
| 248 | |
| 249 | -- jpegtran: -perfect option |
| 250 | |
| 251 | -- rdjpgcom: -raw option |
| 252 | |
| 253 | -- rdjpgcom: locale awareness |
| 254 | |
| 255 | |
| 256 | Fully supported when using libjpeg v7/v8 emulation: |
| 257 | |
| 258 | -- libjpeg: In-memory source and destination managers |
| 259 | |
| 260 | |
| 261 | Not supported: |
| 262 | |
| 263 | -- libjpeg: DCT scaling in compressor |
| 264 | cinfo.scale_num and cinfo.scale_denom are silently ignored. |
| 265 | |
| 266 | -- libjpeg: IDCT scaling extensions in decompressor |
| 267 | libjpeg-turbo still supports IDCT scaling with scaling factors of 1/2, 1/4, |
| 268 | and 1/8 (same as libjpeg v6b.) |
| 269 | |
| 270 | -- libjpeg: Fancy downsampling in compressor |
| 271 | cinfo.do_fancy_downsampling is silently ignored. |
| 272 | |
| 273 | -- libjpeg: Arithmetic coding/decoding |
| 274 | Not supported due to patent concerns. |
| 275 | |
| 276 | -- jpegtran: Scaling |
| 277 | Seems to depend on the DCT scaling feature, which isn't supported. |