DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 1 | ******************************************************************************* |
| 2 | ** Background |
| 3 | ******************************************************************************* |
| 4 | |
| 5 | libjpeg-turbo is a high-speed version of libjpeg for x86 and x86-64 processors |
| 6 | which uses SIMD instructions (MMX, SSE2, etc.) to accelerate baseline JPEG |
DRC | ce1546e | 2010-02-13 23:06:03 +0000 | [diff] [blame] | 7 | compression and decompression. libjpeg-turbo is generally 2-4x as fast |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 8 | as the unmodified version of libjpeg, all else being equal. |
| 9 | |
| 10 | libjpeg-turbo was originally based on libjpeg/SIMD by Miyasaka Masaru, but |
| 11 | the TigerVNC and VirtualGL projects made numerous enhancements to the codec, |
| 12 | including improved support for Mac OS X, 64-bit support, support for 32-bit |
| 13 | and big endian pixel formats, accelerated Huffman encoding/decoding, and |
| 14 | various bug fixes. The goal was to produce a fully open source codec that |
| 15 | could replace the partially closed source TurboJPEG/IPP codec used by VirtualGL |
DRC | ce1546e | 2010-02-13 23:06:03 +0000 | [diff] [blame] | 16 | and TurboVNC. libjpeg-turbo generally performs in the range of 80-120% of |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 17 | TurboJPEG/IPP. It is faster in some areas but slower in others. |
| 18 | |
| 19 | It was decided to split libjpeg-turbo into a separate SDK so that other |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 20 | projects could take advantage of this technology. The libjpeg-turbo shared |
| 21 | libraries can be used as drop-in replacements for libjpeg on most systems. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 22 | |
| 23 | |
| 24 | ******************************************************************************* |
DRC | ce1546e | 2010-02-13 23:06:03 +0000 | [diff] [blame] | 25 | ** License |
| 26 | ******************************************************************************* |
| 27 | |
| 28 | Some of the optimizations to the Huffman encoder/decoder were borrowed from |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 29 | VirtualGL, and thus the libjpeg-turbo distribution, as a whole, falls under the |
| 30 | wxWindows Library Licence, Version 3.1. A copy of this license can be found in |
| 31 | this directory under LICENSE.txt. The rest of the source code, apart from |
| 32 | these modifications, falls under a less restrictive license (see README.) |
DRC | ce1546e | 2010-02-13 23:06:03 +0000 | [diff] [blame] | 33 | |
| 34 | |
| 35 | ******************************************************************************* |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 36 | ** Using libjpeg-turbo |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 37 | ******************************************************************************* |
| 38 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 39 | ============================= |
| 40 | Replacing libjpeg at Run Time |
| 41 | ============================= |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 42 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 43 | If a Unix application is dynamically linked with libjpeg, then you can replace |
| 44 | libjpeg with libjpeg-turbo at run time by manipulating the LD_LIBRARY_PATH. |
| 45 | For instance: |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 46 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 47 | [Using libjpeg] |
| 48 | > time cjpeg <vgl_5674_0098.ppm >vgl_5674_0098.jpg |
| 49 | real 0m0.392s |
| 50 | user 0m0.074s |
| 51 | sys 0m0.020s |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 52 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 53 | [Using libjpeg-turbo] |
| 54 | > export LD_LIBRARY_PATH=/opt/libjpeg-turbo/{lib}:$LD_LIBRARY_PATH |
| 55 | > time cjpeg <vgl_5674_0098.ppm >vgl_5674_0098.jpg |
| 56 | real 0m0.109s |
| 57 | user 0m0.029s |
| 58 | sys 0m0.010s |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 59 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 60 | NOTE: {lib} can be lib, lib32, lib64, or lib/amd64, depending on the O/S and |
| 61 | architecture. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 62 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 63 | System administrators can also replace the libjpeg sym links in /usr/{lib} with |
| 64 | links to the libjpeg dynamic library located in /opt/libjpeg-turbo/{lib}. This |
| 65 | will effectively accelerate every dynamically linked libjpeg application on the |
| 66 | system. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 67 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 68 | The Windows version of libjpeg-turbo installs jpeg62.dll into |
| 69 | %systemroot%\system32. However, if jpeg62.dll also exists in an application's |
| 70 | install directory, then Windows will load the application's version of it |
| 71 | first. Thus, if an application ships with jpeg62.dll, then back up the |
| 72 | application's version of jpeg62.dll and copy %systemroot%\system32\jpeg62.dll |
| 73 | into the application's install directory to accelerate it. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 74 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 75 | Mac applications typically embed their own copies of libjpeg.62.dylib inside |
| 76 | the (hidden) application bundle, so it is not possible to globally replace |
| 77 | libjpeg on OS X systems. If an application uses a shared library version of |
| 78 | libjpeg, then it may be possible to replace the application's version of it. |
| 79 | This would generally involve copying libjpeg.62.dylib into the appropriate |
| 80 | place in the application bundle and using install_name_tool to repoint the |
| 81 | dylib to the new directory. This requires an advanced knowledge of OS X and |
| 82 | would not survive an upgrade or a re-install of the application. Thus, it is |
| 83 | not recommended for most users. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 84 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 85 | ======================= |
| 86 | Replacing TurboJPEG/IPP |
| 87 | ======================= |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 88 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 89 | libjpeg-turbo is a drop-in replacement for the TurboJPEG/IPP SDK used by |
| 90 | VirtualGL 2.1.x (and prior) and TurboVNC. libjpeg-turbo contains a wrapper |
| 91 | library (TurboJPEG/OSS) that emulates the TurboJPEG API using libjpeg-turbo |
| 92 | instead of the closed source Intel Performance Primitives. You can replace the |
| 93 | TurboJPEG/IPP package on Linux systems with the libjpeg-turbo package in order |
| 94 | to make existing releases of VirtualGL 2.1.x and TurboVNC use the new codec at |
| 95 | run time. Note that the 64-bit libjpeg-turbo packages contain only 64-bit |
| 96 | binaries, whereas the TurboJPEG/IPP 64-bit packages contain both 64-bit and |
| 97 | 32-bit binaries. Thus, to replace a TurboJPEG/IPP 64-bit package, install |
| 98 | both the 64-bit and 32-bit versions of libjpeg-turbo. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 99 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 100 | You can also build the VirtualGL 2.1.x and TurboVNC source code with |
| 101 | the libjpeg-turbo SDK instead of TurboJPEG/IPP. It should work identically. |
| 102 | libjpeg-turbo also includes static library versions of TurboJPEG/OSS, which |
| 103 | are used to build VirtualGL 2.2 and later. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 104 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 105 | ======================================== |
| 106 | Using libjpeg-turbo in Your Own Programs |
| 107 | ======================================== |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 108 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 109 | For the most part, libjpeg-turbo should work identically to libjpeg, so in |
| 110 | most cases, an application can be built against libjpeg and then run against |
| 111 | libjpeg-turbo. On Unix systems, you can build against libjpeg-turbo instead |
| 112 | of libjpeg by setting |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 113 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 114 | CPATH=/opt/libjpeg-turbo/include |
| 115 | and |
| 116 | LIBRARY_PATH=/opt/libjpeg-turbo/{lib} |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 117 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 118 | ({lib} = lib, lib32, lib64, or lib/amd64, as appropriate.) |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 119 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 120 | This is useful, for instance, if you want to build an application that |
| 121 | leverages the libjpeg-turbo colorspace extensions (see below.) On Linux and |
| 122 | Solaris systems, you would still need to manipulate the LD_LIBRARY_PATH or sym |
| 123 | links appropriately to use libjpeg-turbo at run time. On such systems, you can |
| 124 | pass -R /opt/libjpeg-turbo/{lib} to the linker to force the use of |
| 125 | libjpeg-turbo at run time rather than libjpeg (also useful if you want to |
| 126 | leverage the colorspace extensions), or you can link against the libjpeg-turbo |
| 127 | static library. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 128 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 129 | To force a Linux or Solaris application to link against the static version of |
| 130 | libjpeg-turbo, you can use the following linker options: |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 131 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 132 | -Wl,-Bstatic -ljpeg -Wl,-Bdynamic |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 133 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 134 | or you can simply add /opt/libjpeg-turbo/{lib}/libjpeg.a to the linker command |
| 135 | line (the latter is the only way to link against the static version of |
| 136 | libjpeg-turbo on OS X.) |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 137 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 138 | To build Visual C++ applications using libjpeg-turbo, add |
| 139 | c:\libjpeg-turbo\include to your system or user INCLUDE environment variable |
| 140 | and c:\libjpeg-turbo\lib to your system or user LIB environment variable, and |
| 141 | then link against either jpeg.lib (to use jpeg62.dll) or jpeg-static.lib (to |
| 142 | use the static version of libjpeg-turbo.) |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 143 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 144 | If building an application using Cygwin, then set |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 145 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 146 | CPATH=/cygdrive/c/libjpeg-turbo/include |
| 147 | and |
| 148 | LIBRARY_PATH=/cygdrive/c/libjpeg-turbo/lib |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 149 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 150 | If using MinGW, then set |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 151 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 152 | CPATH=/c/libjpeg-turbo/include |
| 153 | and |
| 154 | LIBRARY_PATH=/c/libjpeg-turbo/lib |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 155 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 156 | and link using -ljpeg in both cases. NOTE: The static libraries shipped with |
| 157 | the Windows version of libjpeg-turbo cannot be used with MinGW and Cygwin. If |
| 158 | you wish to link statically with libjpeg-turbo using MinGW or Cygwin, then you |
| 159 | will need to build libjpeg-turbo from source using GCC. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 160 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 161 | ===================== |
| 162 | Colorspace Extensions |
| 163 | ===================== |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 164 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 165 | libjpeg-turbo includes extensions which allow JPEG images to be compressed |
| 166 | directly from (and decompressed directly to) buffers which use BGR, BGRA, |
| 167 | RGBA, ABGR, and ARGB pixel ordering. This is implemented with six new |
| 168 | colorspace constants: |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 169 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 170 | JCS_EXT_RGB /* red/green/blue */ |
| 171 | JCS_EXT_RGBX /* red/green/blue/x */ |
| 172 | JCS_EXT_BGR /* blue/green/red */ |
| 173 | JCS_EXT_BGRX /* blue/green/red/x */ |
| 174 | JCS_EXT_XBGR /* x/blue/green/red */ |
| 175 | JCS_EXT_XRGB /* x/red/green/blue */ |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 176 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 177 | Setting cinfo.in_color_space (compression) or cinfo.out_color_space |
| 178 | (decompression) to one of these values will cause libjpeg-turbo to read the |
| 179 | red, green, and blue values from (or write them to) the appropriate position in |
| 180 | the pixel when YUV conversion is performed. |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 181 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 182 | Your application can check for the existence of these extensions at compile |
| 183 | time with: |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 184 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 185 | #ifdef JCS_EXTENSIONS |
DRC | 101f09a | 2010-02-12 22:52:37 +0000 | [diff] [blame] | 186 | |
DRC | 68fef83 | 2010-02-16 05:29:10 +0000 | [diff] [blame] | 187 | At run time, attempting to use these extensions with a version of libjpeg |
| 188 | that doesn't support them will result in a "Bogus input colorspace" error. |