Index: README-turbo.txt |
=================================================================== |
--- README-turbo.txt (revision 111873) |
+++ README-turbo.txt (working copy) |
@@ -2,7 +2,7 @@ |
** Background |
******************************************************************************* |
-libjpeg-turbo is a derivative of libjpeg which uses SIMD instructions (MMX, |
+libjpeg-turbo is a derivative of libjpeg that uses SIMD instructions (MMX, |
SSE2, etc.) to accelerate baseline JPEG compression and decompression on x86 |
and x86-64 systems. On such systems, libjpeg-turbo is generally 2-4x as fast |
as the unmodified version of libjpeg, all else being equal. |
@@ -59,7 +59,7 @@ |
** Using libjpeg-turbo |
******************************************************************************* |
-libjpeg-turbo includes two APIs which can be used to compress and decompress |
+libjpeg-turbo includes two APIs that can be used to compress and decompress |
JPEG images: |
TurboJPEG/OSS: This API wraps libjpeg-turbo and provides an easy-to-use |
@@ -122,7 +122,7 @@ |
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 |
+NOTE: Features of libjpeg that require passing a C run time structure, such |
as a file handle, from an application to libjpeg will probably not work with |
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 |
@@ -208,9 +208,9 @@ |
Colorspace Extensions |
===================== |
-libjpeg-turbo includes extensions which allow JPEG images to be compressed |
-directly from (and decompressed directly to) buffers which use BGR, BGRX, |
-RGBX, XBGR, and XRGB pixel ordering. This is implemented with six new |
+libjpeg-turbo includes extensions that allow JPEG images to be compressed |
+directly from (and decompressed directly to) buffers that use BGR, BGRX, |
+RGBX, XBGR, and XRGB pixel ordering. This is implemented with ten new |
colorspace constants: |
JCS_EXT_RGB /* red/green/blue */ |
@@ -219,11 +219,15 @@ |
JCS_EXT_BGRX /* blue/green/red/x */ |
JCS_EXT_XBGR /* x/blue/green/red */ |
JCS_EXT_XRGB /* x/red/green/blue */ |
+ JCS_EXT_RGBA /* red/green/blue/alpha */ |
+ JCS_EXT_BGRA /* blue/green/red/alpha */ |
+ JCS_EXT_ABGR /* alpha/blue/green/red */ |
+ JCS_EXT_ARGB /* alpha/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. |
+the pixel when compressing from/decompressing to an RGB buffer. |
Your application can check for the existence of these extensions at compile |
time with: |
@@ -233,13 +237,28 @@ |
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. |
+When using the RGBX, BGRX, XBGR, and XRGB colorspaces during decompression, the |
+X byte is undefined, and in order to ensure the best performance, libjpeg-turbo |
+can set that byte to whatever value it wishes. If an application expects the X |
+byte to be used as an alpha channel, then it should specify JCS_EXT_RGBA, |
+JCS_EXT_BGRA, JCS_EXT_ABGR, or JCS_EXT_ARGB. When these colorspace constants |
+are used, the X byte is guaranteed to be 0xFF, which is interpreted as opaque. |
+ |
+Your application can check for the existence of the alpha channel colorspace |
+extensions at compile time with: |
+ |
+ #ifdef JCS_ALPHA_EXTENSIONS |
+ |
+jcstest.c, located in the libjpeg-turbo source tree, demonstrates how to check |
+for the existence of the colorspace extensions at compile time and run time. |
+ |
================================= |
libjpeg v7 and v8 API/ABI support |
================================= |
libjpeg v7 and v8 added new features to the API/ABI, and, unfortunately, the |
compression and decompression structures were extended in a backward- |
-incompatible manner to accommodate these features. Thus, programs which are |
+incompatible manner to accommodate these features. Thus, programs that are |
built to use libjpeg v7 or v8 did not work with libjpeg-turbo, since it is |
based on the libjpeg v6b code base. Although libjpeg v7 and v8 are still not |
as widely used as v6b, enough programs (including a few Linux distros) have |
@@ -247,7 +266,7 @@ |
API/ABI in libjpeg-turbo. |
Some of the libjpeg v7 and v8 features -- DCT scaling, to name one -- involve |
-deep modifications to the code which cannot be accommodated by libjpeg-turbo |
+deep modifications to the code that cannot be accommodated by libjpeg-turbo |
without either breaking compatibility with libjpeg v6b or producing an |
unsupportable mess. In order to fully support libjpeg v8 with all of its |
features, we would have to essentially port the SIMD extensions to the libjpeg |
@@ -258,8 +277,8 @@ |
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 v8 API/ABI, so that programs |
-which are built against libjpeg v7 or v8 can be run with libjpeg-turbo. The |
+of libjpeg-turbo that emulates the libjpeg v7 or v8 API/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. |