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