Various documentation tweaks
git-svn-id: svn+ssh://svn.code.sf.net/p/libjpeg-turbo/code/branches/1.1.x@387 632fc199-4ca6-4c93-a231-07263d6284db
This commit is contained in:
DRC
127
README-turbo.txt
127
README-turbo.txt
@@ -5,7 +5,7 @@
|
||||
libjpeg-turbo is a high-speed version of libjpeg for x86 and x86-64 processors
|
||||
which uses SIMD instructions (MMX, SSE2, etc.) to accelerate baseline JPEG
|
||||
compression and decompression. libjpeg-turbo is generally 2-4x as fast
|
||||
as the unmodified version of libjpeg, all else being equal.
|
||||
as the unmodified version of libjpeg v6b, all else being equal.
|
||||
|
||||
libjpeg-turbo was originally based on libjpeg/SIMD by Miyasaka Masaru, but
|
||||
the TigerVNC and VirtualGL projects made numerous enhancements to the codec,
|
||||
@@ -25,49 +25,21 @@ libraries can be used as drop-in replacements for libjpeg on most systems.
|
||||
** License
|
||||
*******************************************************************************
|
||||
|
||||
Some of the optimizations to the Huffman encoder (jchuff.c) and decoder
|
||||
(jdhuff.c) were borrowed from VirtualGL, and thus any distribution of
|
||||
libjpeg-turbo which includes those optimizations must, as a whole, be subject
|
||||
to the terms of the wxWindows Library Licence, Version 3.1. A copy of this
|
||||
license can be found in this directory under LICENSE.txt. The wxWindows
|
||||
Library License is based on the LGPL but includes provisions which allow the
|
||||
Library to be statically linked into proprietary libraries and applications
|
||||
without requiring the resulting binaries to be distributed under the terms of
|
||||
the LGPL.
|
||||
The TurboJPEG/OSS wrapper, as well as some of the optimizations to the Huffman
|
||||
encoder (jchuff.c) and decoder (jdhuff.c), were borrowed from VirtualGL, and
|
||||
thus any distribution of libjpeg-turbo which includes those files must, as a
|
||||
whole, be subject to the terms of the wxWindows Library Licence, Version 3.1.
|
||||
A copy of this license can be found in this directory under LICENSE.txt. The
|
||||
wxWindows Library License is based on the LGPL but includes provisions which
|
||||
allow the Library to be statically linked into proprietary libraries and
|
||||
applications without requiring the resulting binaries to be distributed under
|
||||
the terms of the LGPL.
|
||||
|
||||
The rest of the source code, apart from the Huffman codec optimizations, falls
|
||||
under a less restrictive, BSD-style license (see README.) You can choose to
|
||||
distribute libjpeg-turbo, as a whole, under this BSD-style license by simply
|
||||
replacing the optimized jchuff.c and jdhuff.c with their unoptimized
|
||||
counterparts from the libjpeg v6b source.
|
||||
|
||||
|
||||
*******************************************************************************
|
||||
** Performance pitfalls
|
||||
*******************************************************************************
|
||||
|
||||
===============
|
||||
Restart Markers
|
||||
===============
|
||||
|
||||
The optimized Huffman decoder in libjpeg-turbo does not handle restart markers
|
||||
in a way that makes libjpeg 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 much greater than that of libjpeg v6b. Many
|
||||
consumer packages, such as PhotoShop, use restart markers when generating JPEG
|
||||
images, so images generated by those programs will experience this issue.
|
||||
|
||||
===============================================
|
||||
Fast Integer Forward DCT at High Quality Levels
|
||||
===============================================
|
||||
|
||||
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
|
||||
whenever encoding images with a JPEG quality of 98 or higher.
|
||||
The rest of the source code, apart from TurboJPEG/OSS and the Huffman codec
|
||||
optimizations, falls under a less restrictive, BSD-style license (see README.)
|
||||
You can choose to distribute libjpeg-turbo, as a whole, under this BSD-style
|
||||
license by simply removing TurboJPEG/OSS and replacing the optimized jchuff.c
|
||||
and jdhuff.c with their unoptimized counterparts from the libjpeg v6b source.
|
||||
|
||||
|
||||
*******************************************************************************
|
||||
@@ -79,7 +51,7 @@ Replacing libjpeg at Run Time
|
||||
=============================
|
||||
|
||||
If a Unix application is dynamically linked with libjpeg, then you can replace
|
||||
libjpeg with libjpeg-turbo at run time by manipulating the LD_LIBRARY_PATH.
|
||||
libjpeg with libjpeg-turbo at run time by manipulating LD_LIBRARY_PATH.
|
||||
For instance:
|
||||
|
||||
[Using libjpeg]
|
||||
@@ -103,28 +75,29 @@ links to the libjpeg dynamic library located in /opt/libjpeg-turbo/{lib}. This
|
||||
will effectively accelerate every dynamically linked libjpeg application on the
|
||||
system.
|
||||
|
||||
The Windows distribution of the libjpeg-turbo SDK installs the libjpeg-turbo
|
||||
DLL (jpeg62.dll, jpeg7.dll, or jpeg8.dll, depending on whether libjpeg v6b,
|
||||
v7, or v8 emulation is enabled) into c:\libjpeg-turbo[64]\bin, and the PATH
|
||||
The libjpeg-turbo SDK for Visual C++ installs the libjpeg-turbo DLL
|
||||
(jpeg62.dll, jpeg7.dll, or jpeg8.dll, depending on whether libjpeg v6b, v7, or
|
||||
v8 emulation is enabled) into c:\libjpeg-turbo[64]\bin, and the PATH
|
||||
environment variable can be modified such that this directory is searched
|
||||
before any others that might contain a libjpeg DLL. However, if a libjpeg
|
||||
DLL exists in an application's install directory, then Windows will load this
|
||||
DLL first whenever the application is launched. Thus, if an application ships
|
||||
with jpeg62.dll, jpeg7.dll, or jpeg8.dll, then back up the application's
|
||||
version of this DLL and copy c:\libjpeg-turbo\bin\jpeg*.dll into the
|
||||
version of this DLL and copy c:\libjpeg-turbo[64]\bin\jpeg*.dll into the
|
||||
application's install directory to accelerate it.
|
||||
|
||||
The version of the libjpeg-turbo DLL distributed with the "official"
|
||||
libjpeg-turbo SDK requires the Visual C++ 2008 C run time DLL (msvcr90.dll).
|
||||
The version of the libjpeg-turbo DLL distributed in the libjpeg-turbo SDK for
|
||||
Visual C++ requires the Visual C++ 2008 C run time DLL (msvcr90.dll).
|
||||
msvcr90.dll ships with more recent versions of Windows, but users of older
|
||||
Windows releases can obtain it from the Visual C++ 2008 Redistributable
|
||||
Package, which is available as a free download from Microsoft's web site.
|
||||
|
||||
NOTE: Features of libjpeg which require passing a C run time structure, such
|
||||
as a file handle, from an application to libjpeg will probably not work with
|
||||
the "official" version of the libjpeg-turbo DLL unless the application is also
|
||||
built to use the Visual C++ 2008 C run time DLL. In particular, this affects
|
||||
jpeg_stdio_dest() and jpeg_stdio_src().
|
||||
the version of the libjpeg-turbo DLL distributed in the libjpeg-turbo SDK for
|
||||
Visual C++, unless the application is also built to use the Visual C++ 2008 C
|
||||
run time DLL. In particular, this affects jpeg_stdio_dest() and
|
||||
jpeg_stdio_src().
|
||||
|
||||
Mac applications typically embed their own copies of the libjpeg dylib inside
|
||||
the (hidden) application bundle, so it is not possible to globally replace
|
||||
@@ -145,8 +118,8 @@ VirtualGL 2.1.x and TurboVNC 0.6 (and prior.) libjpeg-turbo contains a wrapper
|
||||
library (TurboJPEG/OSS) that emulates the TurboJPEG API using libjpeg-turbo
|
||||
instead of the closed source Intel Performance Primitives. You can replace the
|
||||
TurboJPEG/IPP package on Linux systems with the libjpeg-turbo package in order
|
||||
to make existing releases of VirtualGL 2.1.x and TurboVNC use the new codec at
|
||||
run time. Note that the 64-bit libjpeg-turbo packages contain only 64-bit
|
||||
to make existing releases of VirtualGL 2.1.x and TurboVNC 0.x use the new codec
|
||||
at run time. Note that the 64-bit libjpeg-turbo packages contain only 64-bit
|
||||
binaries, whereas the TurboJPEG/IPP 64-bit packages contained both 64-bit and
|
||||
32-bit binaries. Thus, to replace a TurboJPEG/IPP 64-bit package, install
|
||||
both the 64-bit and 32-bit versions of libjpeg-turbo.
|
||||
@@ -180,11 +153,11 @@ If using MinGW, then set
|
||||
|
||||
Building against libjpeg-turbo is useful, for instance, if you want to build an
|
||||
application that leverages the libjpeg-turbo colorspace extensions (see below.)
|
||||
On Linux and Solaris systems, you would still need to manipulate the
|
||||
LD_LIBRARY_PATH or sym links appropriately to use libjpeg-turbo at run time.
|
||||
On such systems, you can pass -R /opt/libjpeg-turbo/{lib} to the linker to
|
||||
force the use of libjpeg-turbo at run time rather than libjpeg (also useful if
|
||||
you want to leverage the colorspace extensions), or you can link against the
|
||||
On Linux and Solaris systems, you would still need to manipulate
|
||||
LD_LIBRARY_PATH or create appropriate sym links to use libjpeg-turbo at run
|
||||
time. On such systems, you can pass -R /opt/libjpeg-turbo/{lib} to the linker
|
||||
to force the use of libjpeg-turbo at run time rather than libjpeg (also useful
|
||||
if you want to leverage the colorspace extensions), or you can link against the
|
||||
libjpeg-turbo static library.
|
||||
|
||||
To force a Linux, Solaris, or MinGW application to link against the static
|
||||
@@ -196,8 +169,8 @@ On OS X, simply add /opt/libjpeg-turbo/lib/libjpeg.a to the linker command
|
||||
line (this also works on Linux and Solaris.)
|
||||
|
||||
To build Visual C++ applications using libjpeg-turbo, add
|
||||
c:\libjpeg-turbo[64]\include to your system or user INCLUDE environment
|
||||
variable and c:\libjpeg-turbo[64]\lib to your system or user LIB environment
|
||||
c:\libjpeg-turbo[64]\include to the system or user INCLUDE environment
|
||||
variable and c:\libjpeg-turbo[64]\lib to the system or user LIB environment
|
||||
variable, and then link against either jpeg.lib (to use the DLL version of
|
||||
libjpeg-turbo) or jpeg-static.lib (to use the static version of libjpeg-turbo.)
|
||||
|
||||
@@ -255,7 +228,7 @@ releases will also be backward-incompatible.
|
||||
|
||||
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 which emulates the libjpeg v7 or v8b API/ABI, so that programs
|
||||
of libjpeg-turbo which emulates the libjpeg v7 or v8 API/ABI, so that programs
|
||||
which 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.
|
||||
@@ -300,3 +273,31 @@ Not supported:
|
||||
|
||||
-- jpegtran: Scaling
|
||||
Seems to depend on the DCT scaling feature, which isn't supported.
|
||||
|
||||
|
||||
*******************************************************************************
|
||||
** Performance pitfalls
|
||||
*******************************************************************************
|
||||
|
||||
===============
|
||||
Restart Markers
|
||||
===============
|
||||
|
||||
The optimized Huffman decoder in libjpeg-turbo does not handle restart markers
|
||||
in a way that makes libjpeg 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 much greater than that of libjpeg v6b. Many
|
||||
consumer packages, such as PhotoShop, use restart markers when generating JPEG
|
||||
images, so images generated by those programs will experience this issue.
|
||||
|
||||
===============================================
|
||||
Fast Integer Forward DCT at High Quality Levels
|
||||
===============================================
|
||||
|
||||
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
|
||||
whenever encoding images with a JPEG quality of 98 or higher.
|
||||
|
||||
Reference in New Issue
Block a user