The Tor Browser / file comparison
comparison: media/libjpeg/README-turbo.txt
media/libjpeg/README-turbo.txt
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
equal
deleted
inserted
replaced
| -1:000000000000 | 0:d53ae20c8475 |
|---|---|
| 1 ******************************************************************************* | |
| 2 ** Background | |
| 3 ******************************************************************************* | |
| 4 | |
| 5 libjpeg-turbo is a JPEG image codec that uses SIMD instructions (MMX, SSE2, | |
| 6 NEON) to accelerate baseline JPEG compression and decompression on x86, x86-64, | |
| 7 and ARM systems. On such systems, libjpeg-turbo is generally 2-4x as fast as | |
| 8 libjpeg, all else being equal. On other types of systems, libjpeg-turbo can | |
| 9 still outperform libjpeg by a significant amount, by virtue of its | |
| 10 highly-optimized Huffman coding routines. In many cases, the performance of | |
| 11 libjpeg-turbo rivals that of proprietary high-speed JPEG codecs. | |
| 12 | |
| 13 libjpeg-turbo implements both the traditional libjpeg API as well as the less | |
| 14 powerful but more straightforward TurboJPEG API. libjpeg-turbo also features | |
| 15 colorspace extensions that allow it to compress from/decompress to 32-bit and | |
| 16 big-endian pixel buffers (RGBX, XBGR, etc.), as well as a full-featured Java | |
| 17 interface. | |
| 18 | |
| 19 libjpeg-turbo was originally based on libjpeg/SIMD, an MMX-accelerated | |
| 20 derivative of libjpeg v6b developed by Miyasaka Masaru. The TigerVNC and | |
| 21 VirtualGL projects made numerous enhancements to the codec in 2009, and in | |
| 22 early 2010, libjpeg-turbo spun off into an independent project, with the goal | |
| 23 of making high-speed JPEG compression/decompression technology available to a | |
| 24 broader range of users and developers. | |
| 25 | |
| 26 | |
| 27 ******************************************************************************* | |
| 28 ** License | |
| 29 ******************************************************************************* | |
| 30 | |
| 31 Most of libjpeg-turbo inherits the non-restrictive, BSD-style license used by | |
| 32 libjpeg (see README.) The TurboJPEG wrapper (both C and Java versions) and | |
| 33 associated test programs bear a similar license, which is reproduced below: | |
| 34 | |
| 35 Redistribution and use in source and binary forms, with or without | |
| 36 modification, are permitted provided that the following conditions are met: | |
| 37 | |
| 38 - Redistributions of source code must retain the above copyright notice, | |
| 39 this list of conditions and the following disclaimer. | |
| 40 - Redistributions in binary form must reproduce the above copyright notice, | |
| 41 this list of conditions and the following disclaimer in the documentation | |
| 42 and/or other materials provided with the distribution. | |
| 43 - Neither the name of the libjpeg-turbo Project nor the names of its | |
| 44 contributors may be used to endorse or promote products derived from this | |
| 45 software without specific prior written permission. | |
| 46 | |
| 47 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS", | |
| 48 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
| 49 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
| 50 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE | |
| 51 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR | |
| 52 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF | |
| 53 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS | |
| 54 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN | |
| 55 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | |
| 56 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE | |
| 57 POSSIBILITY OF SUCH DAMAGE. | |
| 58 | |
| 59 | |
| 60 ******************************************************************************* | |
| 61 ** Using libjpeg-turbo | |
| 62 ******************************************************************************* | |
| 63 | |
| 64 libjpeg-turbo includes two APIs that can be used to compress and decompress | |
| 65 JPEG images: | |
| 66 | |
| 67 TurboJPEG API: This API provides an easy-to-use interface for compressing | |
| 68 and decompressing JPEG images in memory. It also provides some functionality | |
| 69 that would not be straightforward to achieve using the underlying libjpeg | |
| 70 API, such as generating planar YUV images and performing multiple | |
| 71 simultaneous lossless transforms on an image. The Java interface for | |
| 72 libjpeg-turbo is written on top of the TurboJPEG API. | |
| 73 | |
| 74 libjpeg API: This is the de facto industry-standard API for compressing and | |
| 75 decompressing JPEG images. It is more difficult to use than the TurboJPEG | |
| 76 API but also more powerful. The libjpeg API implementation in libjpeg-turbo | |
| 77 is both API/ABI-compatible and mathematically compatible with libjpeg v6b. | |
| 78 It can also optionally be configured to be API/ABI-compatible with libjpeg v7 | |
| 79 and v8 (see below.) | |
| 80 | |
| 81 There is no significant performance advantage to either API when both are used | |
| 82 to perform similar operations. | |
| 83 | |
| 84 ====================== | |
| 85 Installation Directory | |
| 86 ====================== | |
| 87 | |
| 88 This document assumes that libjpeg-turbo will be installed in the default | |
| 89 directory (/opt/libjpeg-turbo on Un*x and Mac systems and | |
| 90 c:\libjpeg-turbo[-gcc][64] on Windows systems. If your installation of | |
| 91 libjpeg-turbo resides in a different directory, then adjust the instructions | |
| 92 accordingly. | |
| 93 | |
| 94 ============================= | |
| 95 Replacing libjpeg at Run Time | |
| 96 ============================= | |
| 97 | |
| 98 Un*x | |
| 99 ---- | |
| 100 | |
| 101 If a Un*x application is dynamically linked with libjpeg, then you can replace | |
| 102 libjpeg with libjpeg-turbo at run time by manipulating LD_LIBRARY_PATH. | |
| 103 For instance: | |
| 104 | |
| 105 [Using libjpeg] | |
| 106 > time cjpeg <vgl_5674_0098.ppm >vgl_5674_0098.jpg | |
| 107 real 0m0.392s | |
| 108 user 0m0.074s | |
| 109 sys 0m0.020s | |
| 110 | |
| 111 [Using libjpeg-turbo] | |
| 112 > export LD_LIBRARY_PATH=/opt/libjpeg-turbo/{lib}:$LD_LIBRARY_PATH | |
| 113 > time cjpeg <vgl_5674_0098.ppm >vgl_5674_0098.jpg | |
| 114 real 0m0.109s | |
| 115 user 0m0.029s | |
| 116 sys 0m0.010s | |
| 117 | |
| 118 ({lib} = lib32 or lib64, depending on whether you wish to use the 32-bit or the | |
| 119 64-bit version of libjpeg-turbo.) | |
| 120 | |
| 121 System administrators can also replace the libjpeg symlinks in /usr/lib* with | |
| 122 links to the libjpeg-turbo dynamic library located in /opt/libjpeg-turbo/{lib}. | |
| 123 This will effectively accelerate every application that uses the libjpeg | |
| 124 dynamic library on the system. | |
| 125 | |
| 126 Windows | |
| 127 ------- | |
| 128 | |
| 129 If a Windows application is dynamically linked with libjpeg, then you can | |
| 130 replace libjpeg with libjpeg-turbo at run time by backing up the application's | |
| 131 copy of jpeg62.dll, jpeg7.dll, or jpeg8.dll (assuming the application has its | |
| 132 own local copy of this library) and copying the corresponding DLL from | |
| 133 libjpeg-turbo into the application's install directory. The official | |
| 134 libjpeg-turbo binary packages only provide jpeg62.dll. If the application uses | |
| 135 jpeg7.dll or jpeg8.dll instead, then it will be necessary to build | |
| 136 libjpeg-turbo from source (see "libjpeg v7 and v8 API/ABI Emulation" below.) | |
| 137 | |
| 138 The following information is specific to the official libjpeg-turbo binary | |
| 139 packages for Visual C++: | |
| 140 | |
| 141 -- jpeg62.dll requires the Visual C++ 2008 C run-time DLL (msvcr90.dll). | |
| 142 msvcr90.dll ships with more recent versions of Windows, but users of older | |
| 143 Windows releases can obtain it from the Visual C++ 2008 Redistributable | |
| 144 Package, which is available as a free download from Microsoft's web site. | |
| 145 | |
| 146 -- Features of the libjpeg API that require passing a C run-time structure, | |
| 147 such as a file handle, from an application to the library will probably not | |
| 148 work with jpeg62.dll, unless the application is also built to use the Visual | |
| 149 C++ 2008 C run-time DLL. In particular, this affects jpeg_stdio_dest() and | |
| 150 jpeg_stdio_src(). | |
| 151 | |
| 152 Mac | |
| 153 --- | |
| 154 | |
| 155 Mac applications typically embed their own copies of the libjpeg dylib inside | |
| 156 the (hidden) application bundle, so it is not possible to globally replace | |
| 157 libjpeg on OS X systems. Replacing the application's version of the libjpeg | |
| 158 dylib would generally involve copying libjpeg.*.dylib from libjpeg-turbo into | |
| 159 the appropriate place in the application bundle and using install_name_tool to | |
| 160 repoint the libjpeg-turbo dylib to its new directory. This requires an | |
| 161 advanced knowledge of OS X and would not survive an upgrade or a re-install of | |
| 162 the application. Thus, it is not recommended for most users. | |
| 163 | |
| 164 ======================================== | |
| 165 Using libjpeg-turbo in Your Own Programs | |
| 166 ======================================== | |
| 167 | |
| 168 For the most part, libjpeg-turbo should work identically to libjpeg, so in | |
| 169 most cases, an application can be built against libjpeg and then run against | |
| 170 libjpeg-turbo. On Un*x systems and Cygwin, you can build against libjpeg-turbo | |
| 171 instead of libjpeg by setting | |
| 172 | |
| 173 CPATH=/opt/libjpeg-turbo/include | |
| 174 and | |
| 175 LIBRARY_PATH=/opt/libjpeg-turbo/{lib} | |
| 176 | |
| 177 ({lib} = lib32 or lib64, depending on whether you are building a 32-bit or a | |
| 178 64-bit application.) | |
| 179 | |
| 180 If using MinGW, then set | |
| 181 | |
| 182 CPATH=/c/libjpeg-turbo-gcc[64]/include | |
| 183 and | |
| 184 LIBRARY_PATH=/c/libjpeg-turbo-gcc[64]/lib | |
| 185 | |
| 186 Building against libjpeg-turbo is useful, for instance, if you want to build an | |
| 187 application that leverages the libjpeg-turbo colorspace extensions (see below.) | |
| 188 On Un*x systems, you would still need to manipulate LD_LIBRARY_PATH or create | |
| 189 appropriate symlinks to use libjpeg-turbo at run time. On such systems, you | |
| 190 can pass -R /opt/libjpeg-turbo/{lib} to the linker to force the use of | |
| 191 libjpeg-turbo at run time rather than libjpeg (also useful if you want to | |
| 192 leverage the colorspace extensions), or you can link against the libjpeg-turbo | |
| 193 static library. | |
| 194 | |
| 195 To force a Un*x or MinGW application to link against the static version of | |
| 196 libjpeg-turbo, you can use the following linker options: | |
| 197 | |
| 198 -Wl,-Bstatic -ljpeg -Wl,-Bdynamic | |
| 199 | |
| 200 On OS X, simply add /opt/libjpeg-turbo/lib/libjpeg.a to the linker command | |
| 201 line. | |
| 202 | |
| 203 To build Visual C++ applications using libjpeg-turbo, add | |
| 204 c:\libjpeg-turbo[64]\include to the system or user INCLUDE environment | |
| 205 variable and c:\libjpeg-turbo[64]\lib to the system or user LIB environment | |
| 206 variable, and then link against either jpeg.lib (to use the DLL version of | |
| 207 libjpeg-turbo) or jpeg-static.lib (to use the static version of libjpeg-turbo.) | |
| 208 | |
| 209 ===================== | |
| 210 Colorspace Extensions | |
| 211 ===================== | |
| 212 | |
| 213 libjpeg-turbo includes extensions that allow JPEG images to be compressed | |
| 214 directly from (and decompressed directly to) buffers that use BGR, BGRX, | |
| 215 RGBX, XBGR, and XRGB pixel ordering. This is implemented with ten new | |
| 216 colorspace constants: | |
| 217 | |
| 218 JCS_EXT_RGB /* red/green/blue */ | |
| 219 JCS_EXT_RGBX /* red/green/blue/x */ | |
| 220 JCS_EXT_BGR /* blue/green/red */ | |
| 221 JCS_EXT_BGRX /* blue/green/red/x */ | |
| 222 JCS_EXT_XBGR /* x/blue/green/red */ | |
| 223 JCS_EXT_XRGB /* x/red/green/blue */ | |
| 224 JCS_EXT_RGBA /* red/green/blue/alpha */ | |
| 225 JCS_EXT_BGRA /* blue/green/red/alpha */ | |
| 226 JCS_EXT_ABGR /* alpha/blue/green/red */ | |
| 227 JCS_EXT_ARGB /* alpha/red/green/blue */ | |
| 228 | |
| 229 Setting cinfo.in_color_space (compression) or cinfo.out_color_space | |
| 230 (decompression) to one of these values will cause libjpeg-turbo to read the | |
| 231 red, green, and blue values from (or write them to) the appropriate position in | |
| 232 the pixel when compressing from/decompressing to an RGB buffer. | |
| 233 | |
| 234 Your application can check for the existence of these extensions at compile | |
| 235 time with: | |
| 236 | |
| 237 #ifdef JCS_EXTENSIONS | |
| 238 | |
| 239 At run time, attempting to use these extensions with a libjpeg implementation | |
| 240 that does not support them will result in a "Bogus input colorspace" error. | |
| 241 Applications can trap this error in order to test whether run-time support is | |
| 242 available for the colorspace extensions. | |
| 243 | |
| 244 When using the RGBX, BGRX, XBGR, and XRGB colorspaces during decompression, the | |
| 245 X byte is undefined, and in order to ensure the best performance, libjpeg-turbo | |
| 246 can set that byte to whatever value it wishes. If an application expects the X | |
| 247 byte to be used as an alpha channel, then it should specify JCS_EXT_RGBA, | |
| 248 JCS_EXT_BGRA, JCS_EXT_ABGR, or JCS_EXT_ARGB. When these colorspace constants | |
| 249 are used, the X byte is guaranteed to be 0xFF, which is interpreted as opaque. | |
| 250 | |
| 251 Your application can check for the existence of the alpha channel colorspace | |
| 252 extensions at compile time with: | |
| 253 | |
| 254 #ifdef JCS_ALPHA_EXTENSIONS | |
| 255 | |
| 256 jcstest.c, located in the libjpeg-turbo source tree, demonstrates how to check | |
| 257 for the existence of the colorspace extensions at compile time and run time. | |
| 258 | |
| 259 =================================== | |
| 260 libjpeg v7 and v8 API/ABI Emulation | |
| 261 =================================== | |
| 262 | |
| 263 With libjpeg v7 and v8, new features were added that necessitated extending the | |
| 264 compression and decompression structures. Unfortunately, due to the exposed | |
| 265 nature of those structures, extending them also necessitated breaking backward | |
| 266 ABI compatibility with previous libjpeg releases. Thus, programs that were | |
| 267 built to use libjpeg v7 or v8 did not work with libjpeg-turbo, since it is | |
| 268 based on the libjpeg v6b code base. Although libjpeg v7 and v8 are still not | |
| 269 as widely used as v6b, enough programs (including a few Linux distros) made | |
| 270 the switch that there was a demand to emulate the libjpeg v7 and v8 ABIs | |
| 271 in libjpeg-turbo. It should be noted, however, that this feature was added | |
| 272 primarily so that applications that had already been compiled to use libjpeg | |
| 273 v7+ could take advantage of accelerated baseline JPEG encoding/decoding | |
| 274 without recompiling. libjpeg-turbo does not claim to support all of the | |
| 275 libjpeg v7+ features, nor to produce identical output to libjpeg v7+ in all | |
| 276 cases (see below.) | |
| 277 | |
| 278 By passing an argument of --with-jpeg7 or --with-jpeg8 to configure, or an | |
| 279 argument of -DWITH_JPEG7=1 or -DWITH_JPEG8=1 to cmake, you can build a version | |
| 280 of libjpeg-turbo that emulates the libjpeg v7 or v8 ABI, so that programs | |
| 281 that are built against libjpeg v7 or v8 can be run with libjpeg-turbo. The | |
| 282 following section describes which libjpeg v7+ features are supported and which | |
| 283 aren't. | |
| 284 | |
| 285 Support for libjpeg v7 and v8 Features: | |
| 286 --------------------------------------- | |
| 287 | |
| 288 Fully supported: | |
| 289 | |
| 290 -- libjpeg: IDCT scaling extensions in decompressor | |
| 291 libjpeg-turbo supports IDCT scaling with scaling factors of 1/8, 1/4, 3/8, | |
| 292 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 | |
| 293 and 1/2 are SIMD-accelerated.) | |
| 294 | |
| 295 -- libjpeg: arithmetic coding | |
| 296 | |
| 297 -- libjpeg: In-memory source and destination managers | |
| 298 See notes below. | |
| 299 | |
| 300 -- cjpeg: Separate quality settings for luminance and chrominance | |
| 301 Note that the libpjeg v7+ API was extended to accommodate this feature only | |
| 302 for convenience purposes. It has always been possible to implement this | |
| 303 feature with libjpeg v6b (see rdswitch.c for an example.) | |
| 304 | |
| 305 -- cjpeg: 32-bit BMP support | |
| 306 | |
| 307 -- cjpeg: -rgb option | |
| 308 | |
| 309 -- jpegtran: lossless cropping | |
| 310 | |
| 311 -- jpegtran: -perfect option | |
| 312 | |
| 313 -- jpegtran: forcing width/height when performing lossless crop | |
| 314 | |
| 315 -- rdjpgcom: -raw option | |
| 316 | |
| 317 -- rdjpgcom: locale awareness | |
| 318 | |
| 319 | |
| 320 Not supported: | |
| 321 | |
| 322 NOTE: As of this writing, extensive research has been conducted into the | |
| 323 usefulness of DCT scaling as a means of data reduction and SmartScale as a | |
| 324 means of quality improvement. The reader is invited to peruse the research at | |
| 325 http://www.libjpeg-turbo.org/About/SmartScale and draw his/her own conclusions, | |
| 326 but it is the general belief of our project that these features have not | |
| 327 demonstrated sufficient usefulness to justify inclusion in libjpeg-turbo. | |
| 328 | |
| 329 -- libjpeg: DCT scaling in compressor | |
| 330 cinfo.scale_num and cinfo.scale_denom are silently ignored. | |
| 331 There is no technical reason why DCT scaling could not be supported when | |
| 332 emulating the libjpeg v7+ API/ABI, but without the SmartScale extension (see | |
| 333 below), only scaling factors of 1/2, 8/15, 4/7, 8/13, 2/3, 8/11, 4/5, and | |
| 334 8/9 would be available, which is of limited usefulness. | |
| 335 | |
| 336 -- libjpeg: SmartScale | |
| 337 cinfo.block_size is silently ignored. | |
| 338 SmartScale is an extension to the JPEG format that allows for DCT block | |
| 339 sizes other than 8x8. Providing support for this new format would be | |
| 340 feasible (particularly without full acceleration.) However, until/unless | |
| 341 the format becomes either an official industry standard or, at minimum, an | |
| 342 accepted solution in the community, we are hesitant to implement it, as | |
| 343 there is no sense of whether or how it might change in the future. It is | |
| 344 our belief that SmartScale has not demonstrated sufficient usefulness as a | |
| 345 lossless format nor as a means of quality enhancement, and thus, our primary | |
| 346 interest in providing this feature would be as a means of supporting | |
| 347 additional DCT scaling factors. | |
| 348 | |
| 349 -- libjpeg: Fancy downsampling in compressor | |
| 350 cinfo.do_fancy_downsampling is silently ignored. | |
| 351 This requires the DCT scaling feature, which is not supported. | |
| 352 | |
| 353 -- jpegtran: Scaling | |
| 354 This requires both the DCT scaling and SmartScale features, which are not | |
| 355 supported. | |
| 356 | |
| 357 -- Lossless RGB JPEG files | |
| 358 This requires the SmartScale feature, which is not supported. | |
| 359 | |
| 360 What About libjpeg v9? | |
| 361 ---------------------- | |
| 362 | |
| 363 libjpeg v9 introduced yet another field to the JPEG compression structure | |
| 364 (color_transform), thus making the ABI backward incompatible with that of | |
| 365 libjpeg v8. This new field was introduced solely for the purpose of supporting | |
| 366 lossless SmartScale encoding. Further, there was actually no reason to extend | |
| 367 the API in this manner, as the color transform could have just as easily been | |
| 368 activated by way of a new JPEG colorspace constant, thus preserving backward | |
| 369 ABI compatibility. | |
| 370 | |
| 371 Our research (see link above) has shown that lossless SmartScale does not | |
| 372 generally accomplish anything that can't already be accomplished better with | |
| 373 existing, standard lossless formats. Thus, at this time, it is our belief that | |
| 374 there is not sufficient technical justification for software to upgrade from | |
| 375 libjpeg v8 to libjpeg v9, and therefore, not sufficient technical justification | |
| 376 for us to emulate the libjpeg v9 ABI. | |
| 377 | |
| 378 ===================================== | |
| 379 In-Memory Source/Destination Managers | |
| 380 ===================================== | |
| 381 | |
| 382 By default, libjpeg-turbo 1.3 and later includes the jpeg_mem_src() and | |
| 383 jpeg_mem_dest() functions, even when not emulating the libjpeg v8 API/ABI. | |
| 384 Previously, it was necessary to build libjpeg-turbo from source with libjpeg v8 | |
| 385 API/ABI emulation in order to use the in-memory source/destination managers, | |
| 386 but several projects requested that those functions be included when emulating | |
| 387 the libjpeg v6b API/ABI as well. This allows the use of those functions by | |
| 388 programs that need them without breaking ABI compatibility for programs that | |
| 389 don't, and it allows those functions to be provided in the "official" | |
| 390 libjpeg-turbo binaries. | |
| 391 | |
| 392 Those who are concerned about maintaining strict conformance with the libjpeg | |
| 393 v6b or v7 API can pass an argument of --without-mem-srcdst to configure or | |
| 394 an argument of -DWITH_MEM_SRCDST=0 to CMake prior to building libjpeg-turbo. | |
| 395 This will restore the pre-1.3 behavior, in which jpeg_mem_src() and | |
| 396 jpeg_mem_dest() are only included when emulating the libjpeg v8 API/ABI. | |
| 397 | |
| 398 On Un*x systems, including the in-memory source/destination managers changes | |
| 399 the dynamic library version from 62.0.0 to 62.1.0 if using libjpeg v6b API/ABI | |
| 400 emulation and from 7.0.0 to 7.1.0 if using libjpeg v7 API/ABI emulation. | |
| 401 | |
| 402 Note that, on most Un*x systems, the dynamic linker will not look for a | |
| 403 function in a library until that function is actually used. Thus, if a program | |
| 404 is built against libjpeg-turbo 1.3+ and uses jpeg_mem_src() or jpeg_mem_dest(), | |
| 405 that program will not fail if run against an older version of libjpeg-turbo or | |
| 406 against libjpeg v7- until the program actually tries to call jpeg_mem_src() or | |
| 407 jpeg_mem_dest(). Such is not the case on Windows. If a program is built | |
| 408 against the libjpeg-turbo 1.3+ DLL and uses jpeg_mem_src() or jpeg_mem_dest(), | |
| 409 then it must use the libjpeg-turbo 1.3+ DLL at run time. | |
| 410 | |
| 411 Both cjpeg and djpeg have been extended to allow testing the in-memory | |
| 412 source/destination manager functions. See their respective man pages for more | |
| 413 details. | |
| 414 | |
| 415 | |
| 416 ******************************************************************************* | |
| 417 ** Mathematical Compatibility | |
| 418 ******************************************************************************* | |
| 419 | |
| 420 For the most part, libjpeg-turbo should produce identical output to libjpeg | |
| 421 v6b. The one exception to this is when using the floating point DCT/IDCT, in | |
| 422 which case the outputs of libjpeg v6b and libjpeg-turbo are not guaranteed to | |
| 423 be identical (the accuracy of the floating point DCT/IDCT is constant when | |
| 424 using libjpeg-turbo's SIMD extensions, but otherwise, it can depend heavily on | |
| 425 the compiler and compiler settings.) | |
| 426 | |
| 427 While libjpeg-turbo does emulate the libjpeg v8 API/ABI, under the hood, it is | |
| 428 still using the same algorithms as libjpeg v6b, so there are several specific | |
| 429 cases in which libjpeg-turbo cannot be expected to produce the same output as | |
| 430 libjpeg v8: | |
| 431 | |
| 432 -- When decompressing using scaling factors of 1/2 and 1/4, because libjpeg v8 | |
| 433 implements those scaling algorithms a bit differently than libjpeg v6b does, | |
| 434 and libjpeg-turbo's SIMD extensions are based on the libjpeg v6b behavior. | |
| 435 | |
| 436 -- When using chrominance subsampling, because libjpeg v8 implements this | |
| 437 with its DCT/IDCT scaling algorithms rather than with a separate | |
| 438 downsampling/upsampling algorithm. | |
| 439 | |
| 440 -- When using the floating point IDCT, for the reasons stated above and also | |
| 441 because the floating point IDCT algorithm was modified in libjpeg v8a to | |
| 442 improve accuracy. | |
| 443 | |
| 444 -- When decompressing using a scaling factor > 1 and merged (AKA "non-fancy" or | |
| 445 "non-smooth") chrominance upsampling, because libjpeg v8 does not support | |
| 446 merged upsampling with scaling factors > 1. | |
| 447 | |
| 448 | |
| 449 ******************************************************************************* | |
| 450 ** Performance Pitfalls | |
| 451 ******************************************************************************* | |
| 452 | |
| 453 =============== | |
| 454 Restart Markers | |
| 455 =============== | |
| 456 | |
| 457 The optimized Huffman decoder in libjpeg-turbo does not handle restart markers | |
| 458 in a way that makes the rest of the libjpeg infrastructure happy, so it is | |
| 459 necessary to use the slow Huffman decoder when decompressing a JPEG image that | |
| 460 has restart markers. This can cause the decompression performance to drop by | |
| 461 as much as 20%, but the performance will still be much greater than that of | |
| 462 libjpeg. Many consumer packages, such as PhotoShop, use restart markers when | |
| 463 generating JPEG images, so images generated by those programs will experience | |
| 464 this issue. | |
| 465 | |
| 466 =============================================== | |
| 467 Fast Integer Forward DCT at High Quality Levels | |
| 468 =============================================== | |
| 469 | |
| 470 The algorithm used by the SIMD-accelerated quantization function cannot produce | |
| 471 correct results whenever the fast integer forward DCT is used along with a JPEG | |
| 472 quality of 98-100. Thus, libjpeg-turbo must use the non-SIMD quantization | |
| 473 function in those cases. This causes performance to drop by as much as 40%. | |
| 474 It is therefore strongly advised that you use the slow integer forward DCT | |
| 475 whenever encoding images with a JPEG quality of 98 or higher. |
