Add license and other supporting documentation from libjpeg-turbo
git-svn-id: svn://svn.code.sf.net/p/tigervnc/code/trunk@4166 3789f03b-4d11-0410-bbf8-ca57d06f2519
diff --git a/common/jpeg/README-turbo.txt b/common/jpeg/README-turbo.txt
new file mode 100755
index 0000000..40350d0
--- /dev/null
+++ b/common/jpeg/README-turbo.txt
@@ -0,0 +1,207 @@
+*******************************************************************************
+** Background
+*******************************************************************************
+
+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.
+
+libjpeg-turbo was originally based on libjpeg/SIMD by Miyasaka Masaru, but
+the TigerVNC and VirtualGL projects made numerous enhancements to the codec,
+including improved support for Mac OS X, 64-bit support, support for 32-bit
+and big endian pixel formats, accelerated Huffman encoding/decoding, and
+various bug fixes. The goal was to produce a fully open source codec that
+could replace the partially closed source TurboJPEG/IPP codec used by VirtualGL
+and TurboVNC. libjpeg-turbo generally performs in the range of 80-120% of
+TurboJPEG/IPP. It is faster in some areas but slower in others.
+
+It was decided to split libjpeg-turbo into a separate SDK so that other
+projects could take advantage of this technology. The libjpeg-turbo shared
+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 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.
+
+
+*******************************************************************************
+** Using libjpeg-turbo
+*******************************************************************************
+
+=============================
+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.
+For instance:
+
+ [Using libjpeg]
+ > time cjpeg <vgl_5674_0098.ppm >vgl_5674_0098.jpg
+ real 0m0.392s
+ user 0m0.074s
+ sys 0m0.020s
+
+ [Using libjpeg-turbo]
+ > export LD_LIBRARY_PATH=/opt/libjpeg-turbo/{lib}:$LD_LIBRARY_PATH
+ > time cjpeg <vgl_5674_0098.ppm >vgl_5674_0098.jpg
+ real 0m0.109s
+ user 0m0.029s
+ sys 0m0.010s
+
+NOTE: {lib} can be lib, lib32, lib64, or lib/64, depending on the O/S and
+architecture.
+
+System administrators can also replace the libjpeg sym links in /usr/{lib} with
+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 jpeg62.dll into
+c:\libjpeg-turbo\bin, and the PATH environment variable can be modified such
+that this directory is searched before any others that might contain
+jpeg62.dll. However, if jpeg62.dll also exists in an application's install
+directory, then Windows will load the application's version of it first. Thus,
+if an application ships with jpeg62.dll, then back up the application's version
+of jpeg62.dll and copy c:\libjpeg-turbo\bin\jpeg62.dll into the application's
+install directory to accelerate it.
+
+The version of jpeg62.dll distributed in the libjpeg-turbo SDK requires the
+Visual C++ 2008 C run time DLL (msvcr90.dll). This library ships with more
+recent versions of Windows, but users of older versions 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 distributed version of jpeg62.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().
+
+Mac applications typically embed their own copies of libjpeg.62.dylib inside
+the (hidden) application bundle, so it is not possible to globally replace
+libjpeg on OS X systems. If an application uses a shared library version of
+libjpeg, then it may be possible to replace the application's version of it.
+This would generally involve copying libjpeg.62.dylib into the appropriate
+place in the application bundle and using install_name_tool to repoint the
+dylib to the new directory. This requires an advanced knowledge of OS X and
+would not survive an upgrade or a re-install of the application. Thus, it is
+not recommended for most users.
+
+=======================
+Replacing TurboJPEG/IPP
+=======================
+
+libjpeg-turbo is a drop-in replacement for the TurboJPEG/IPP SDK used by
+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
+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.
+
+You can also build the VirtualGL 2.1.x and TurboVNC 0.6 source code with
+the libjpeg-turbo SDK instead of TurboJPEG/IPP. It should work identically.
+libjpeg-turbo also includes static library versions of TurboJPEG/OSS, which
+are used to build TurboVNC 1.0 and later.
+
+========================================
+Using libjpeg-turbo in Your Own Programs
+========================================
+
+For the most part, libjpeg-turbo should work identically to libjpeg, so in
+most cases, an application can be built against libjpeg and then run against
+libjpeg-turbo. On Unix systems, you can build against libjpeg-turbo instead
+of libjpeg by setting
+
+ CPATH=/opt/libjpeg-turbo/include
+ and
+ LIBRARY_PATH=/opt/libjpeg-turbo/{lib}
+
+({lib} = lib32 or lib64, depending on whether you are building a 32-bit or a
+64-bit application.)
+
+If using Cygwin, then set
+
+ CPATH=/cygdrive/c/libjpeg-turbo-gcc[64]/include
+ and
+ LIBRARY_PATH=/cygdrive/c/libjpeg-turbo-gcc[64]/lib
+
+If using MinGW, then set
+
+ CPATH=/c/libjpeg-turbo-gcc[64]/include
+ and
+ LIBRARY_PATH=/c/libjpeg-turbo-gcc[64]/lib
+
+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
+libjpeg-turbo static library.
+
+To force a Linux, Solaris, or MinGW application to link against the static
+version of libjpeg-turbo, you can use the following linker options:
+
+ -Wl,-Bstatic -ljpeg -Wl,-Bdynamic
+
+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
+variable, and then link against either jpeg.lib (to use jpeg62.dll) or
+jpeg-static.lib (to use the static version of libjpeg-turbo.)
+
+=====================
+Colorspace Extensions
+=====================
+
+libjpeg-turbo includes extensions which allow JPEG images to be compressed
+directly from (and decompressed directly to) buffers which use BGR, BGRA,
+RGBA, ABGR, and ARGB pixel ordering. This is implemented with six new
+colorspace constants:
+
+ JCS_EXT_RGB /* red/green/blue */
+ JCS_EXT_RGBX /* red/green/blue/x */
+ JCS_EXT_BGR /* blue/green/red */
+ JCS_EXT_BGRX /* blue/green/red/x */
+ JCS_EXT_XBGR /* x/blue/green/red */
+ JCS_EXT_XRGB /* x/red/green/blue */
+
+Setting cinfo.in_color_space (compression) or cinfo.out_color_space
+(decompression) to one of these values will cause libjpeg-turbo to read the
+red, green, and blue values from (or write them to) the appropriate position in
+the pixel when YUV conversion is performed.
+
+Your application can check for the existence of these extensions at compile
+time with:
+
+ #ifdef JCS_EXTENSIONS
+
+At run time, attempting to use these extensions with a version of libjpeg
+that doesn't support them will result in a "Bogus input colorspace" error.