diff options
Diffstat (limited to 'src/3rdparty/libjpeg/src/README.md')
| -rw-r--r-- | src/3rdparty/libjpeg/src/README.md | 143 |
1 files changed, 84 insertions, 59 deletions
diff --git a/src/3rdparty/libjpeg/src/README.md b/src/3rdparty/libjpeg/src/README.md index a769259891..923e61d231 100644 --- a/src/3rdparty/libjpeg/src/README.md +++ b/src/3rdparty/libjpeg/src/README.md @@ -1,14 +1,14 @@ Background ========== -libjpeg-turbo is a JPEG image codec that uses SIMD instructions (MMX, SSE2, -AVX2, NEON, AltiVec) to accelerate baseline JPEG compression and decompression -on x86, x86-64, ARM, and PowerPC systems, as well as progressive JPEG -compression on x86 and x86-64 systems. On such systems, libjpeg-turbo is -generally 2-6x as fast as libjpeg, all else being equal. On other types of -systems, libjpeg-turbo can still outperform libjpeg by a significant amount, by -virtue of its highly-optimized Huffman coding routines. In many cases, the -performance of libjpeg-turbo rivals that of proprietary high-speed JPEG codecs. +libjpeg-turbo is a JPEG image codec that uses SIMD instructions to accelerate +baseline JPEG compression and decompression on x86, x86-64, Arm, PowerPC, and +MIPS systems, as well as progressive JPEG compression on x86, x86-64, and Arm +systems. On such systems, libjpeg-turbo is generally 2-6x as fast as libjpeg, +all else being equal. On other types of systems, libjpeg-turbo can still +outperform libjpeg by a significant amount, by virtue of its highly-optimized +Huffman coding routines. In many cases, the performance of libjpeg-turbo +rivals that of proprietary high-speed JPEG codecs. libjpeg-turbo implements both the traditional libjpeg API as well as the less powerful but more straightforward TurboJPEG API. libjpeg-turbo also features @@ -21,7 +21,26 @@ derivative of libjpeg v6b developed by Miyasaka Masaru. The TigerVNC and VirtualGL projects made numerous enhancements to the codec in 2009, and in early 2010, libjpeg-turbo spun off into an independent project, with the goal of making high-speed JPEG compression/decompression technology available to a -broader range of users and developers. +broader range of users and developers. libjpeg-turbo is an ISO/IEC and ITU-T +reference implementation of the JPEG standard. + +More information about libjpeg-turbo can be found at +<https://libjpeg-turbo.org>. + + +Funding +======= + +libjpeg-turbo is an independent open source project, but we rely on patronage +and funded development in order to maintain that independence. The easiest way +to ensure that libjpeg-turbo remains community-focused and free of any one +organization's agenda is to +[sponsor our project through GitHub](https://github.com/sponsors/libjpeg-turbo). +All sponsorship money goes directly toward funding the labor necessary to +maintain libjpeg-turbo, support the user community, and implement bug fixes and +strategically important features. + +[](https://github.com/sponsors/libjpeg-turbo) License @@ -135,25 +154,24 @@ without recompiling. libjpeg-turbo does not claim to support all of the libjpeg v7+ features, nor to produce identical output to libjpeg v7+ in all cases (see below.) -By passing an argument of `--with-jpeg7` or `--with-jpeg8` to `configure`, or -an argument of `-DWITH_JPEG7=1` or `-DWITH_JPEG8=1` to `cmake`, you can build a -version of libjpeg-turbo that emulates the libjpeg v7 or v8 ABI, so that -programs that are built against libjpeg v7 or v8 can be run with libjpeg-turbo. -The following section describes which libjpeg v7+ features are supported and -which aren't. +By passing an argument of `-DWITH_JPEG7=1` or `-DWITH_JPEG8=1` to `cmake`, you +can build a version of libjpeg-turbo that emulates the libjpeg v7 or v8 ABI, so +that programs that are built against libjpeg v7 or v8 can be run with +libjpeg-turbo. The following section describes which libjpeg v7+ features are +supported and which aren't. ### Support for libjpeg v7 and v8 Features #### Fully supported -- **libjpeg: IDCT scaling extensions in decompressor**<br> +- **libjpeg API: IDCT scaling extensions in decompressor**<br> libjpeg-turbo supports IDCT scaling with scaling factors of 1/8, 1/4, 3/8, 1/2, 5/8, 3/4, 7/8, 9/8, 5/4, 11/8, 3/2, 13/8, 7/4, 15/8, and 2/1 (only 1/4 and 1/2 are SIMD-accelerated.) -- **libjpeg: Arithmetic coding** +- **libjpeg API: Arithmetic coding** -- **libjpeg: In-memory source and destination managers**<br> +- **libjpeg API: In-memory source and destination managers**<br> See notes below. - **cjpeg: Separate quality settings for luminance and chrominance**<br> @@ -180,19 +198,19 @@ which aren't. NOTE: As of this writing, extensive research has been conducted into the usefulness of DCT scaling as a means of data reduction and SmartScale as a -means of quality improvement. The reader is invited to peruse the research at -<http://www.libjpeg-turbo.org/About/SmartScale> and draw his/her own conclusions, +means of quality improvement. Readers are invited to peruse the research at +<http://www.libjpeg-turbo.org/About/SmartScale> and draw their own conclusions, but it is the general belief of our project that these features have not demonstrated sufficient usefulness to justify inclusion in libjpeg-turbo. -- **libjpeg: DCT scaling in compressor**<br> +- **libjpeg API: DCT scaling in compressor**<br> `cinfo.scale_num` and `cinfo.scale_denom` are silently ignored. There is no technical reason why DCT scaling could not be supported when emulating the libjpeg v7+ API/ABI, but without the SmartScale extension (see below), only scaling factors of 1/2, 8/15, 4/7, 8/13, 2/3, 8/11, 4/5, and 8/9 would be available, which is of limited usefulness. -- **libjpeg: SmartScale**<br> +- **libjpeg API: SmartScale**<br> `cinfo.block_size` is silently ignored. SmartScale is an extension to the JPEG format that allows for DCT block sizes other than 8x8. Providing support for this new format would be @@ -205,7 +223,7 @@ demonstrated sufficient usefulness to justify inclusion in libjpeg-turbo. interest in providing this feature would be as a means of supporting additional DCT scaling factors. -- **libjpeg: Fancy downsampling in compressor**<br> +- **libjpeg API: Fancy downsampling in compressor**<br> `cinfo.do_fancy_downsampling` is silently ignored. This requires the DCT scaling feature, which is not supported. @@ -246,17 +264,6 @@ programs that need them, without breaking ABI compatibility for programs that don't, and it allows those functions to be provided in the "official" libjpeg-turbo binaries. -Those who are concerned about maintaining strict conformance with the libjpeg -v6b or v7 API can pass an argument of `--without-mem-srcdst` to `configure` or -an argument of `-DWITH_MEM_SRCDST=0` to `cmake` prior to building -libjpeg-turbo. This will restore the pre-1.3 behavior, in which -`jpeg_mem_src()` and `jpeg_mem_dest()` are only included when emulating the -libjpeg v8 API/ABI. - -On Un*x systems, including the in-memory source/destination managers changes -the dynamic library version from 62.1.0 to 62.2.0 if using libjpeg v6b API/ABI -emulation and from 7.1.0 to 7.2.0 if using libjpeg v7 API/ABI emulation. - Note that, on most Un*x systems, the dynamic linker will not look for a function in a library until that function is actually used. Thus, if a program is built against libjpeg-turbo 1.3+ and uses `jpeg_mem_src()` or @@ -276,29 +283,35 @@ Mathematical Compatibility ========================== For the most part, libjpeg-turbo should produce identical output to libjpeg -v6b. The one exception to this is when using the floating point DCT/IDCT, in -which case the outputs of libjpeg v6b and libjpeg-turbo can differ for the -following reasons: - -- The SSE/SSE2 floating point DCT implementation in libjpeg-turbo is ever so - slightly more accurate than the implementation in libjpeg v6b, but not by - any amount perceptible to human vision (generally in the range of 0.01 to - 0.08 dB gain in PNSR.) - -- When not using the SIMD extensions, libjpeg-turbo uses the more accurate - (and slightly faster) floating point IDCT algorithm introduced in libjpeg - v8a as opposed to the algorithm used in libjpeg v6b. It should be noted, - however, that this algorithm basically brings the accuracy of the floating - point IDCT in line with the accuracy of the slow integer IDCT. The floating - point DCT/IDCT algorithms are mainly a legacy feature, and they do not - produce significantly more accuracy than the slow integer algorithms (to put - numbers on this, the typical difference in PNSR between the two algorithms - is less than 0.10 dB, whereas changing the quality level by 1 in the upper - range of the quality scale is typically more like a 1.0 dB difference.) - -- If the floating point algorithms in libjpeg-turbo are not implemented using - SIMD instructions on a particular platform, then the accuracy of the - floating point DCT/IDCT can depend on the compiler settings. +v6b. There are two exceptions: + +1. When decompressing a JPEG image that uses 4:4:0 chrominance subsampling, the +outputs of libjpeg v6b and libjpeg-turbo can differ because libjpeg-turbo +implements a "fancy" (smooth) 4:4:0 upsampling algorithm and libjpeg did not. + +2. When using the floating point DCT/IDCT, the outputs of libjpeg v6b and +libjpeg-turbo can differ for the following reasons: + + - The SSE/SSE2 floating point DCT implementation in libjpeg-turbo is ever + so slightly more accurate than the implementation in libjpeg v6b, but not + by any amount perceptible to human vision (generally in the range of 0.01 + to 0.08 dB gain in PNSR.) + + - When not using the SIMD extensions, libjpeg-turbo uses the more accurate + (and slightly faster) floating point IDCT algorithm introduced in libjpeg + v8a as opposed to the algorithm used in libjpeg v6b. It should be noted, + however, that this algorithm basically brings the accuracy of the + floating point IDCT in line with the accuracy of the accurate integer + IDCT. The floating point DCT/IDCT algorithms are mainly a legacy + feature, and they do not produce significantly more accuracy than the + accurate integer algorithms. (To put numbers on this, the typical + difference in PNSR between the two algorithms is less than 0.10 dB, + whereas changing the quality level by 1 in the upper range of the quality + scale is typically more like a 1.0 dB difference.) + + - If the floating point algorithms in libjpeg-turbo are not implemented + using SIMD instructions on a particular platform, then the accuracy of + the floating point DCT/IDCT can depend on the compiler settings. While libjpeg-turbo does emulate the libjpeg v8 API/ABI, under the hood it is still using the same algorithms as libjpeg v6b, so there are several specific @@ -331,7 +344,7 @@ in a way that makes the rest of the libjpeg infrastructure happy, so it is necessary to use the slow Huffman decoder when decompressing a JPEG image that has restart markers. This can cause the decompression performance to drop by as much as 20%, but the performance will still be much greater than that of -libjpeg. Many consumer packages, such as PhotoShop, use restart markers when +libjpeg. Many consumer packages, such as Photoshop, use restart markers when generating JPEG images, so images generated by those programs will experience this issue. @@ -342,5 +355,17 @@ The algorithm used by the SIMD-accelerated quantization function cannot produce correct results whenever the fast integer forward DCT is used along with a JPEG quality of 98-100. Thus, libjpeg-turbo must use the non-SIMD quantization function in those cases. This causes performance to drop by as much as 40%. -It is therefore strongly advised that you use the slow integer forward DCT +It is therefore strongly advised that you use the accurate integer forward DCT whenever encoding images with a JPEG quality of 98 or higher. + + +Memory Debugger Pitfalls +======================== + +Valgrind and Memory Sanitizer (MSan) can generate false positives +(specifically, incorrect reports of uninitialized memory accesses) when used +with libjpeg-turbo's SIMD extensions. It is generally recommended that the +SIMD extensions be disabled, either by passing an argument of `-DWITH_SIMD=0` +to `cmake` when configuring the build or by setting the environment variable +`JSIMD_FORCENONE` to `1` at run time, when testing libjpeg-turbo with Valgrind, +MSan, or other memory debuggers. |