Replace TightVNC encoder with TurboVNC encoder. This patch is the result of further research and discussion that revealed the following:

-- TightPng encoding and the rfbTightNoZlib extension need not conflict.  Since
   TightPng is a separate encoding type, not supported by TurboVNC-compatible
   viewers, then the rfbTightNoZlib extension can be used solely whenever the
   encoding type is Tight and disabled with the encoding type is TightPng.

-- In the TightVNC encoder, compression levels above 5 are basically useless.
   On the set of 20 low-level datasets that were used to design the TurboVNC
   encoder (these include the eight 2D application captures that were also used
   when designing the TightVNC encoder, as well as 12 3D application captures
   provided by the VirtualGL Project--
   see http://www.virtualgl.org/pmwiki/uploads/About/tighttoturbo.pdf), moving
   from Compression Level (CL) 5 to CL 9 in the TightVNC encoder did not
   increase the compression ratio of any datasets more than 10%, and the
   compression ratio only increased by more than 5% on four of them.  The
   compression ratio actually decreased a few percent on five of them.  In
   exchange for this paltry increase in compression ratio, the CPU usage, on
   average, went up by a factor of 5.  Thus, for all intents and purposes,
   TightVNC CL 5 provides the "best useful compression" for that encoder.

-- TurboVNC's best compression level (CL 2) compresses 3D and video workloads
   significantly more "tightly" than TightVNC CL 5 (~70% better, in the
   aggregate) but does not quite achieve the same level of compression with 2D
   workloads (~20% worse, in the aggregate.) This decrease in compression ratio
   may or may not be noticeable, since many of the datasets it affects are not
   performance-critical (such as the console output of a compilation, etc.)
   However, for peace of mind, it was still desirable to have a mode that
   compressed with equal "tightness" to TightVNC CL 5, since we proposed to
   replace that encoder entirely.

-- A new mode was discovered in the TurboVNC encoder that produces, in the
   aggregate, similar compression ratios on 2D datasets as TightVNC CL 5.  That
   new mode involves using Zlib level 7 (the same level used by TightVNC CL 5)
   but setting the "palette threshold" to 256, so that indexed color encoding
   is used whenever possible.  This mode reduces bandwidth only marginally
   (typically 10-20%) relative to TurboVNC CL 2 on low-color workloads, in
   exchange for nearly doubling CPU usage, and it does not benefit high-color
   workloads at all (since those are usually encoded with JPEG.)  However, it
   provides a means of reproducing the same "tightness" as the TightVNC
   encoder on 2D workloads without sacrificing any compression for 3D/video
   workloads, and without using any more CPU time than necessary.

-- The TurboVNC encoder still performs as well or better than the TightVNC
   encoder when plain libjpeg is used instead of libjpeg-turbo.

Specific notes follow:

common/turbojpeg.c common/turbojpeg.h:
Added code to emulate the libjpeg-turbo colorspace extensions, so that the
TurboJPEG wrapper can be used with plain libjpeg as well.  This required
updating the TurboJPEG wrapper to the latest code from libjpeg-turbo 1.2.0,
mainly because the TurboJPEG 1.2 API handles pixel formats in a much cleaner
way, which made the conversion code easier to write.  It also eases the
maintenance to have the wrapper synced as much as possible with the upstream
code base (so I can merge any relevant bug fixes that are discovered upstream.)
The libvncserver version of the TurboJPEG wrapper is a "lite" version,
containing only the JPEG compression/decompression code and not the lossless
transform, YUV encoding/decoding, and dynamic buffer allocation features from
TurboJPEG 1.2.

configure.ac:
Removed the --with-turbovnc option.  configure still checks for the presence of
libjpeg-turbo, but only for the purposes of printing a performance warning if
it isn't available.

rfb/rfb.h:
Fix a bug introduced with the initial TurboVNC encoder patch.  We cannot use
tightQualityLevel for the TurboVNC 1-100 quality level, because
tightQualityLevel is also used by ZRLE.  Thus, a new parameter
(turboQualityLevel) was created.

rfb/rfbproto.h:
Remove TurboVNC-specific #ifdefs and language

libvncserver/rfbserver.c:
Remove TurboVNC-specific #ifdefs.  Fix afore-mentioned tightQualityLevel bug.

libvncserver/tight.c:
Replaced the TightVNC encoder with the TurboVNC encoder.  Relative to the
initial TurboVNC encoder patch, this patch also:
-- Adds TightPng support to the TurboVNC encoder
-- Adds the afore-mentioned low-bandwidth mode, which is mapped externally to
   Compression Level 9

test/*:
Included TJUnitTest (a regression test for the TurboJPEG wrapper) as well as
TJBench (a benchmark for same.)  These are useful for ensuring that the wrapper
still functions correctly and performantly if it needs to be modified for
whatever reason.  Both of these programs are derived from libjpeg-turbo 1.2.0.
As with the TurboJPEG wrapper, they do not contain the more advanced features
of TurboJPEG 1.2, such as YUV encoding/decoding and lossless transforms.

1 files changed, 477 insertions, 203 deletions

diff --git a/common/turbojpeg.h b/common/turbojpeg.h
index 6e3e259..ab8adda 100644
--- a/common/turbojpeg.h
+++ b/common/turbojpeg.h
@@ -1,255 +1,529 @@
-/* Copyright (C)2004 Landmark Graphics Corporation
- * Copyright (C)2005, 2006 Sun Microsystems, Inc.
- * Copyright (C)2009-2011 D. R. Commander
+/*
+ * Copyright (C)2009-2012 D. R. Commander.  All Rights Reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
  *
- * This library is free software and may be redistributed and/or modified under
- * the terms of the wxWindows Library License, Version 3.1 or (at your option)
- * any later version.  The full license is in the LICENSE.txt file included
- * with this distribution.
+ * - Redistributions of source code must retain the above copyright notice,
+ *   this list of conditions and the following disclaimer.
+ * - Redistributions in binary form must reproduce the above copyright notice,
+ *   this list of conditions and the following disclaimer in the documentation
+ *   and/or other materials provided with the distribution.
+ * - Neither the name of the libjpeg-turbo Project nor the names of its
+ *   contributors may be used to endorse or promote products derived from this
+ *   software without specific prior written permission.
  *
- * This library is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * wxWindows Library License for more details.
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS",
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
  */
 
-#if (defined(_MSC_VER) || defined(__CYGWIN__) || defined(__MINGW32__)) \
-	&& defined(_WIN32) && defined(DLLDEFINE)
+#ifndef __TURBOJPEG_H__
+#define __TURBOJPEG_H__
+
+#if defined(_WIN32) && defined(DLLDEFINE)
 #define DLLEXPORT __declspec(dllexport)
 #else
 #define DLLEXPORT
 #endif
-
 #define DLLCALL
 
 
-/* Subsampling */
-#define NUMSUBOPT 4
-
-enum {TJ_444=0, TJ_422, TJ_420, TJ_GRAYSCALE};
-#define TJ_411 TJ_420  /* for backward compatibility with VirtualGL <= 2.1.x,
-                          TurboVNC <= 0.6, and TurboJPEG/IPP */
-
-
-/* Flags */
-#define TJ_BGR             1
-  /* The components of each pixel in the source/destination bitmap are stored
-     in B,G,R order, not R,G,B */
-#define TJ_BOTTOMUP        2
-  /* The source/destination bitmap is stored in bottom-up (Windows, OpenGL)
-     order, not top-down (X11) order */
-#define TJ_FORCEMMX        8
-  /* Turn off CPU auto-detection and force TurboJPEG to use MMX code
-     (IPP and 32-bit libjpeg-turbo versions only) */
-#define TJ_FORCESSE       16
-  /* Turn off CPU auto-detection and force TurboJPEG to use SSE code
-     (32-bit IPP and 32-bit libjpeg-turbo versions only) */
-#define TJ_FORCESSE2      32
-  /* Turn off CPU auto-detection and force TurboJPEG to use SSE2 code
-     (32-bit IPP and 32-bit libjpeg-turbo versions only) */
-#define TJ_ALPHAFIRST     64
-  /* If the source/destination bitmap is 32 bpp, assume that each pixel is
-     ARGB/XRGB (or ABGR/XBGR if TJ_BGR is also specified) */
-#define TJ_FORCESSE3     128
-  /* Turn off CPU auto-detection and force TurboJPEG to use SSE3 code
-     (64-bit IPP version only) */
-#define TJ_FASTUPSAMPLE  256
-  /* Use fast, inaccurate 4:2:2 and 4:2:0 YUV upsampling routines
-     (libjpeg and libjpeg-turbo versions only) */
+/**
+ * @addtogroup TurboJPEG Lite
+ * TurboJPEG API.  This API provides an interface for generating and decoding
+ * JPEG images in memory.
+ *
+ * @{
+ */
+
+
+/**
+ * The number of chrominance subsampling options
+ */
+#define TJ_NUMSAMP 5
+
+/**
+ * Chrominance subsampling options.
+ * When an image is converted from the RGB to the YCbCr colorspace as part of
+ * the JPEG compression process, some of the Cb and Cr (chrominance) components
+ * can be discarded or averaged together to produce a smaller image with little
+ * perceptible loss of image clarity (the human eye is more sensitive to small
+ * changes in brightness than small changes in color.)  This is called
+ * "chrominance subsampling".
+ */
+enum TJSAMP
+{
+  /**
+   * 4:4:4 chrominance subsampling (no chrominance subsampling).  The JPEG or
+   * YUV image will contain one chrominance component for every pixel in the
+   * source image.
+   */
+  TJSAMP_444=0,
+  /**
+   * 4:2:2 chrominance subsampling.  The JPEG or YUV image will contain one
+   * chrominance component for every 2x1 block of pixels in the source image.
+   */
+  TJSAMP_422,
+  /**
+   * 4:2:0 chrominance subsampling.  The JPEG or YUV image will contain one
+   * chrominance component for every 2x2 block of pixels in the source image.
+   */
+  TJSAMP_420,
+  /**
+   * Grayscale.  The JPEG or YUV image will contain no chrominance components.
+   */
+  TJSAMP_GRAY,
+  /**
+   * 4:4:0 chrominance subsampling.  The JPEG or YUV image will contain one
+   * chrominance component for every 1x2 block of pixels in the source image.
+   */
+  TJSAMP_440
+};
+
+/**
+ * MCU block width (in pixels) for a given level of chrominance subsampling.
+ * MCU block sizes:
+ * - 8x8 for no subsampling or grayscale
+ * - 16x8 for 4:2:2
+ * - 8x16 for 4:4:0
+ * - 16x16 for 4:2:0 
+ */
+static const int tjMCUWidth[TJ_NUMSAMP]  = {8, 16, 16, 8, 8};
+
+/**
+ * MCU block height (in pixels) for a given level of chrominance subsampling.
+ * MCU block sizes:
+ * - 8x8 for no subsampling or grayscale
+ * - 16x8 for 4:2:2
+ * - 8x16 for 4:4:0
+ * - 16x16 for 4:2:0 
+ */
+static const int tjMCUHeight[TJ_NUMSAMP] = {8, 8, 16, 8, 16};
+
+
+/**
+ * The number of pixel formats
+ */
+#define TJ_NUMPF 11
+
+/**
+ * Pixel formats
+ */
+enum TJPF
+{
+  /**
+   * RGB pixel format.  The red, green, and blue components in the image are
+   * stored in 3-byte pixels in the order R, G, B from lowest to highest byte
+   * address within each pixel.
+   */
+  TJPF_RGB=0,
+  /**
+   * BGR pixel format.  The red, green, and blue components in the image are
+   * stored in 3-byte pixels in the order B, G, R from lowest to highest byte
+   * address within each pixel.
+   */
+  TJPF_BGR,
+  /**
+   * RGBX pixel format.  The red, green, and blue components in the image are
+   * stored in 4-byte pixels in the order R, G, B from lowest to highest byte
+   * address within each pixel.  The X component is ignored when compressing
+   * and undefined when decompressing.
+   */
+  TJPF_RGBX,
+  /**
+   * BGRX pixel format.  The red, green, and blue components in the image are
+   * stored in 4-byte pixels in the order B, G, R from lowest to highest byte
+   * address within each pixel.  The X component is ignored when compressing
+   * and undefined when decompressing.
+   */
+  TJPF_BGRX,
+  /**
+   * XBGR pixel format.  The red, green, and blue components in the image are
+   * stored in 4-byte pixels in the order R, G, B from highest to lowest byte
+   * address within each pixel.  The X component is ignored when compressing
+   * and undefined when decompressing.
+   */
+  TJPF_XBGR,
+  /**
+   * XRGB pixel format.  The red, green, and blue components in the image are
+   * stored in 4-byte pixels in the order B, G, R from highest to lowest byte
+   * address within each pixel.  The X component is ignored when compressing
+   * and undefined when decompressing.
+   */
+  TJPF_XRGB,
+  /**
+   * Grayscale pixel format.  Each 1-byte pixel represents a luminance
+   * (brightness) level from 0 to 255.
+   */
+  TJPF_GRAY,
+  /**
+   * RGBA pixel format.  This is the same as @ref TJPF_RGBX, except that when
+   * decompressing, the X component is guaranteed to be 0xFF, which can be
+   * interpreted as an opaque alpha channel.
+   */
+  TJPF_RGBA,
+  /**
+   * BGRA pixel format.  This is the same as @ref TJPF_BGRX, except that when
+   * decompressing, the X component is guaranteed to be 0xFF, which can be
+   * interpreted as an opaque alpha channel.
+   */
+  TJPF_BGRA,
+  /**
+   * ABGR pixel format.  This is the same as @ref TJPF_XBGR, except that when
+   * decompressing, the X component is guaranteed to be 0xFF, which can be
+   * interpreted as an opaque alpha channel.
+   */
+  TJPF_ABGR,
+  /**
+   * ARGB pixel format.  This is the same as @ref TJPF_XRGB, except that when
+   * decompressing, the X component is guaranteed to be 0xFF, which can be
+   * interpreted as an opaque alpha channel.
+   */
+  TJPF_ARGB
+};
+
+/**
+ * Red offset (in bytes) for a given pixel format.  This specifies the number
+ * of bytes that the red component is offset from the start of the pixel.  For
+ * instance, if a pixel of format TJ_BGRX is stored in <tt>char pixel[]</tt>,
+ * then the red component will be <tt>pixel[tjRedOffset[TJ_BGRX]]</tt>.
+ */
+static const int tjRedOffset[TJ_NUMPF] = {0, 2, 0, 2, 3, 1, 0, 0, 2, 3, 1};
+/**
+ * Green offset (in bytes) for a given pixel format.  This specifies the number
+ * of bytes that the green component is offset from the start of the pixel.
+ * For instance, if a pixel of format TJ_BGRX is stored in
+ * <tt>char pixel[]</tt>, then the green component will be
+ * <tt>pixel[tjGreenOffset[TJ_BGRX]]</tt>.
+ */
+static const int tjGreenOffset[TJ_NUMPF] = {1, 1, 1, 1, 2, 2, 0, 1, 1, 2, 2};
+/**
+ * Blue offset (in bytes) for a given pixel format.  This specifies the number
+ * of bytes that the Blue component is offset from the start of the pixel.  For
+ * instance, if a pixel of format TJ_BGRX is stored in <tt>char pixel[]</tt>,
+ * then the blue component will be <tt>pixel[tjBlueOffset[TJ_BGRX]]</tt>.
+ */
+static const int tjBlueOffset[TJ_NUMPF] = {2, 0, 2, 0, 1, 3, 0, 2, 0, 1, 3};
+
+/**
+ * Pixel size (in bytes) for a given pixel format.
+ */
+static const int tjPixelSize[TJ_NUMPF] = {3, 3, 4, 4, 4, 4, 1, 4, 4, 4, 4};
 
 
+/**
+ * The uncompressed source/destination image is stored in bottom-up (Windows,
+ * OpenGL) order, not top-down (X11) order.
+ */
+#define TJFLAG_BOTTOMUP        2
+/**
+ * Turn off CPU auto-detection and force TurboJPEG to use MMX code (IPP and
+ * 32-bit libjpeg-turbo versions only.)
+ */
+#define TJFLAG_FORCEMMX        8
+/**
+ * Turn off CPU auto-detection and force TurboJPEG to use SSE code (32-bit IPP
+ * and 32-bit libjpeg-turbo versions only)
+ */
+#define TJFLAG_FORCESSE       16
+/**
+ * Turn off CPU auto-detection and force TurboJPEG to use SSE2 code (32-bit IPP
+ * and 32-bit libjpeg-turbo versions only)
+ */
+#define TJFLAG_FORCESSE2      32
+/**
+ * Turn off CPU auto-detection and force TurboJPEG to use SSE3 code (64-bit IPP
+ * version only)
+ */
+#define TJFLAG_FORCESSE3     128
+/**
+ * Use fast, inaccurate chrominance upsampling routines in the JPEG
+ * decompressor (libjpeg and libjpeg-turbo versions only)
+ */
+#define TJFLAG_FASTUPSAMPLE  256
+
+
+/**
+ * Scaling factor
+ */
+typedef struct
+{
+  /**
+   * Numerator
+   */
+  int num;
+  /**
+   * Denominator
+   */
+  int denom;
+} tjscalingfactor;
+
+
+/**
+ * TurboJPEG instance handle
+ */
 typedef void* tjhandle;
 
-#define TJPAD(p) (((p)+3)&(~3))
-#ifndef max
- #define max(a,b) ((a)>(b)?(a):(b))
-#endif
+
+/**
+ * Pad the given width to the nearest 32-bit boundary
+ */
+#define TJPAD(width) (((width)+3)&(~3))
+
+/**
+ * Compute the scaled value of <tt>dimension</tt> using the given scaling
+ * factor.  This macro performs the integer equivalent of <tt>ceil(dimension *
+ * scalingFactor)</tt>. 
+ */
+#define TJSCALED(dimension, scalingFactor) ((dimension * scalingFactor.num \
+  + scalingFactor.denom - 1) / scalingFactor.denom)
 
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-/* API follows */
-
 
-/*
-  tjhandle tjInitCompress(void)
+/**
+ * Create a TurboJPEG compressor instance.
+ *
+ * @return a handle to the newly-created instance, or NULL if an error
+ * occurred (see #tjGetErrorStr().)
+ */
+DLLEXPORT tjhandle DLLCALL tjInitCompress(void);
 
-  Creates a new JPEG compressor instance, allocates memory for the structures,
-  and returns a handle to the instance.  Most applications will only
-  need to call this once at the beginning of the program or once for each
-  concurrent thread.  Don't try to create a new instance every time you
-  compress an image, because this may cause performance to suffer in some
-  TurboJPEG implementations.
 
-  RETURNS: NULL on error
+/**
+ * Compress an RGB or grayscale image into a JPEG image.
+ *
+ * @param handle a handle to a TurboJPEG compressor or transformer instance
+ * @param srcBuf pointer to an image buffer containing RGB or grayscale pixels
+ *        to be compressed
+ * @param width width (in pixels) of the source image
+ * @param pitch bytes per line of the source image.  Normally, this should be
+ *        <tt>width * #tjPixelSize[pixelFormat]</tt> if the image is unpadded,
+ *        or <tt>#TJPAD(width * #tjPixelSize[pixelFormat])</tt> if each line of
+ *        the image is padded to the nearest 32-bit boundary, as is the case
+ *        for Windows bitmaps.  You can also be clever and use this parameter
+ *        to skip lines, etc.  Setting this parameter to 0 is the equivalent of
+ *        setting it to <tt>width * #tjPixelSize[pixelFormat]</tt>.
+ * @param height height (in pixels) of the source image
+ * @param pixelFormat pixel format of the source image (see @ref TJPF
+ *        "Pixel formats".)
+ * @param jpegBuf address of a pointer to an image buffer that will receive the
+ *        JPEG image.  TurboJPEG has the ability to reallocate the JPEG buffer
+ *        to accommodate the size of the JPEG image.  Thus, you can choose to:
+ *        -# pre-allocate the JPEG buffer with an arbitrary size using
+ *        #tjAlloc() and let TurboJPEG grow the buffer as needed,
+ *        -# set <tt>*jpegBuf</tt> to NULL to tell TurboJPEG to allocate the
+ *        buffer for you, or
+ *        -# pre-allocate the buffer to a "worst case" size determined by
+ *        calling #tjBufSize().  This should ensure that the buffer never has
+ *        to be re-allocated (setting #TJFLAG_NOREALLOC guarantees this.)
+ *        .
+ *        If you choose option 1, <tt>*jpegSize</tt> should be set to the
+ *        size of your pre-allocated buffer.  In any case, unless you have
+ *        set #TJFLAG_NOREALLOC, you should always check <tt>*jpegBuf</tt> upon
+ *        return from this function, as it may have changed.
+ * @param jpegSize pointer to an unsigned long variable that holds the size of
+ *        the JPEG image buffer.  If <tt>*jpegBuf</tt> points to a
+ *        pre-allocated buffer, then <tt>*jpegSize</tt> should be set to the
+ *        size of the buffer.  Upon return, <tt>*jpegSize</tt> will contain the
+ *        size of the JPEG image (in bytes.)
+ * @param jpegSubsamp the level of chrominance subsampling to be used when
+ *        generating the JPEG image (see @ref TJSAMP
+ *        "Chrominance subsampling options".)
+ * @param jpegQual the image quality of the generated JPEG image (1 = worst,
+          100 = best)
+ * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP
+ *        "flags".
+ *
+ * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr().)
 */
-DLLEXPORT tjhandle DLLCALL tjInitCompress(void);
+DLLEXPORT int DLLCALL tjCompress2(tjhandle handle, unsigned char *srcBuf,
+  int width, int pitch, int height, int pixelFormat, unsigned char **jpegBuf,
+  unsigned long *jpegSize, int jpegSubsamp, int jpegQual, int flags);
+
+
+/**
+ * The maximum size of the buffer (in bytes) required to hold a JPEG image with
+ * the given parameters.  The number of bytes returned by this function is
+ * larger than the size of the uncompressed source image.  The reason for this
+ * is that the JPEG format uses 16-bit coefficients, and it is thus possible
+ * for a very high-quality JPEG image with very high frequency content to
+ * expand rather than compress when converted to the JPEG format.  Such images
+ * represent a very rare corner case, but since there is no way to predict the
+ * size of a JPEG image prior to compression, the corner case has to be
+ * handled.
+ *
+ * @param width width of the image (in pixels)
+ * @param height height of the image (in pixels)
+ * @param jpegSubsamp the level of chrominance subsampling to be used when
+ *        generating the JPEG image (see @ref TJSAMP
+ *        "Chrominance subsampling options".)
+ *
+ * @return the maximum size of the buffer (in bytes) required to hold the
+ * image, or -1 if the arguments are out of bounds.
+ */
+DLLEXPORT unsigned long DLLCALL tjBufSize(int width, int height,
+  int jpegSubsamp);
 
 
-/*
-  int tjCompress(tjhandle j,
-     unsigned char *srcbuf, int width, int pitch, int height, int pixelsize,
-     unsigned char *dstbuf, unsigned long *size,
-     int jpegsubsamp, int jpegqual, int flags)
-
-  [INPUT] j = instance handle previously returned from a call to
-     tjInitCompress()
-  [INPUT] srcbuf = pointer to user-allocated image buffer containing RGB or
-     grayscale pixels to be compressed
-  [INPUT] width = width (in pixels) of the source image
-  [INPUT] pitch = bytes per line of the source image (width*pixelsize if the
-     bitmap is unpadded, else TJPAD(width*pixelsize) if each line of the bitmap
-     is padded to the nearest 32-bit boundary, such as is the case for Windows
-     bitmaps.  You can also be clever and use this parameter to skip lines,
-     etc.  Setting this parameter to 0 is the equivalent of setting it to
-     width*pixelsize.
-  [INPUT] height = height (in pixels) of the source image
-  [INPUT] pixelsize = size (in bytes) of each pixel in the source image
-     RGBX/BGRX/XRGB/XBGR: 4, RGB/BGR: 3, Grayscale: 1
-  [INPUT] dstbuf = pointer to user-allocated image buffer that will receive
-     the JPEG image.  Use the TJBUFSIZE(width, height) function to determine
-     the appropriate size for this buffer based on the image width and height.
-  [OUTPUT] size = pointer to unsigned long that receives the size (in bytes)
-     of the compressed image
-  [INPUT] jpegsubsamp = Specifies either 4:2:0, 4:2:2, 4:4:4, or grayscale
-     subsampling.  When the image is converted from the RGB to YCbCr colorspace
-     as part of the JPEG compression process, every other Cb and Cr
-     (chrominance) pixel can be discarded to produce a smaller image with
-     little perceptible loss of image clarity (the human eye is more sensitive
-     to small changes in brightness than small changes in color.)
-
-     TJ_420: 4:2:0 subsampling.  Discards every other Cb, Cr pixel in both
-        horizontal and vertical directions
-     TJ_422: 4:2:2 subsampling.  Discards every other Cb, Cr pixel only in
-        the horizontal direction
-     TJ_444: no subsampling
-     TJ_GRAYSCALE: Generate grayscale JPEG image
-
-  [INPUT] jpegqual = JPEG quality (an integer between 0 and 100 inclusive)
-  [INPUT] flags = the bitwise OR of one or more of the flags described in the
-     "Flags" section above
-
-  RETURNS: 0 on success, -1 on error
+/**
+ * Create a TurboJPEG decompressor instance.
+ *
+ * @return a handle to the newly-created instance, or NULL if an error
+ * occurred (see #tjGetErrorStr().)
 */
-DLLEXPORT int DLLCALL tjCompress(tjhandle j,
-	unsigned char *srcbuf, int width, int pitch, int height, int pixelsize,
-	unsigned char *dstbuf, unsigned long *size,
-	int jpegsubsamp, int jpegqual, int flags);
+DLLEXPORT tjhandle DLLCALL tjInitDecompress(void);
 
 
-/*
-  unsigned long TJBUFSIZE(int width, int height)
+/**
+ * Retrieve information about a JPEG image without decompressing it.
+ *
+ * @param handle a handle to a TurboJPEG decompressor or transformer instance
+ * @param jpegBuf pointer to a buffer containing a JPEG image
+ * @param jpegSize size of the JPEG image (in bytes)
+ * @param width pointer to an integer variable that will receive the width (in
+ *        pixels) of the JPEG image
+ * @param height pointer to an integer variable that will receive the height
+ *        (in pixels) of the JPEG image
+ * @param jpegSubsamp pointer to an integer variable that will receive the
+ *        level of chrominance subsampling used when compressing the JPEG image
+ *        (see @ref TJSAMP "Chrominance subsampling options".)
+ *
+ * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr().)
+*/
+DLLEXPORT int DLLCALL tjDecompressHeader2(tjhandle handle,
+  unsigned char *jpegBuf, unsigned long jpegSize, int *width, int *height,
+  int *jpegSubsamp);
 
-  Convenience function that returns the maximum size of the buffer required to
-  hold a JPEG image with the given width and height
 
-  RETURNS: -1 if arguments are out of bounds
+/**
+ * Returns a list of fractional scaling factors that the JPEG decompressor in
+ * this implementation of TurboJPEG supports.
+ *
+ * @param numscalingfactors pointer to an integer variable that will receive
+ *        the number of elements in the list
+ *
+ * @return a pointer to a list of fractional scaling factors, or NULL if an
+ * error is encountered (see #tjGetErrorStr().)
 */
-DLLEXPORT unsigned long DLLCALL TJBUFSIZE(int width, int height);
-
+DLLEXPORT tjscalingfactor* DLLCALL tjGetScalingFactors(int *numscalingfactors);
 
-/*
-  tjhandle tjInitDecompress(void)
 
-  Creates a new JPEG decompressor instance, allocates memory for the
-  structures, and returns a handle to the instance.  Most applications will
-  only need to call this once at the beginning of the program or once for each
-  concurrent thread.  Don't try to create a new instance every time you
-  decompress an image, because this may cause performance to suffer in some
-  TurboJPEG implementations.
+/**
+ * Decompress a JPEG image to an RGB or grayscale image.
+ *
+ * @param handle a handle to a TurboJPEG decompressor or transformer instance
+ * @param jpegBuf pointer to a buffer containing the JPEG image to decompress
+ * @param jpegSize size of the JPEG image (in bytes)
+ * @param dstBuf pointer to an image buffer that will receive the decompressed
+ *        image.  This buffer should normally be <tt>pitch * scaledHeight</tt>
+ *        bytes in size, where <tt>scaledHeight</tt> can be determined by
+ *        calling #TJSCALED() with the JPEG image height and one of the scaling
+ *        factors returned by #tjGetScalingFactors().  The dstBuf pointer may
+ *        also be used to decompress into a specific region of a larger buffer.
+ * @param width desired width (in pixels) of the destination image.  If this is
+ *        smaller than the width of the JPEG image being decompressed, then
+ *        TurboJPEG will use scaling in the JPEG decompressor to generate the
+ *        largest possible image that will fit within the desired width.  If
+ *        width is set to 0, then only the height will be considered when
+ *        determining the scaled image size.
+ * @param pitch bytes per line of the destination image.  Normally, this is
+ *        <tt>scaledWidth * #tjPixelSize[pixelFormat]</tt> if the decompressed
+ *        image is unpadded, else <tt>#TJPAD(scaledWidth *
+ *        #tjPixelSize[pixelFormat])</tt> if each line of the decompressed
+ *        image is padded to the nearest 32-bit boundary, as is the case for
+ *        Windows bitmaps.  (NOTE: <tt>scaledWidth</tt> can be determined by
+ *        calling #TJSCALED() with the JPEG image width and one of the scaling
+ *        factors returned by #tjGetScalingFactors().)  You can also be clever
+ *        and use the pitch parameter to skip lines, etc.  Setting this
+ *        parameter to 0 is the equivalent of setting it to <tt>scaledWidth
+ *        * #tjPixelSize[pixelFormat]</tt>.
+ * @param height desired height (in pixels) of the destination image.  If this
+ *        is smaller than the height of the JPEG image being decompressed, then
+ *        TurboJPEG will use scaling in the JPEG decompressor to generate the
+ *        largest possible image that will fit within the desired height.  If
+ *        height is set to 0, then only the width will be considered when
+ *        determining the scaled image size.
+ * @param pixelFormat pixel format of the destination image (see @ref
+ *        TJPF "Pixel formats".)
+ * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP
+ *        "flags".
+ *
+ * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr().)
+ */
+DLLEXPORT int DLLCALL tjDecompress2(tjhandle handle,
+  unsigned char *jpegBuf, unsigned long jpegSize, unsigned char *dstBuf,
+  int width, int pitch, int height, int pixelFormat, int flags);
 
-  RETURNS: NULL on error
-*/
-DLLEXPORT tjhandle DLLCALL tjInitDecompress(void);
 
+/**
+ * Destroy a TurboJPEG compressor, decompressor, or transformer instance.
+ *
+ * @param handle a handle to a TurboJPEG compressor, decompressor or
+ *        transformer instance
+ *
+ * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr().)
+ */
+DLLEXPORT int DLLCALL tjDestroy(tjhandle handle);
 
-/*
-  int tjDecompressHeader2(tjhandle j,
-     unsigned char *srcbuf, unsigned long size,
-     int *width, int *height, int *jpegsubsamp)
-
-  [INPUT] j = instance handle previously returned from a call to
-     tjInitDecompress()
-  [INPUT] srcbuf = pointer to a user-allocated buffer containing a JPEG image
-  [INPUT] size = size of the JPEG image buffer (in bytes)
-  [OUTPUT] width = width (in pixels) of the JPEG image
-  [OUTPUT] height = height (in pixels) of the JPEG image
-  [OUTPUT] jpegsubsamp = type of chrominance subsampling used when compressing
-     the JPEG image
-
-  RETURNS: 0 on success, -1 on error
-*/
-DLLEXPORT int DLLCALL tjDecompressHeader2(tjhandle j,
-	unsigned char *srcbuf, unsigned long size,
-	int *width, int *height, int *jpegsubsamp);
 
-/*
-  Legacy version of the above function
-*/
-DLLEXPORT int DLLCALL tjDecompressHeader(tjhandle j,
-	unsigned char *srcbuf, unsigned long size,
-	int *width, int *height);
+/**
+ * Returns a descriptive error message explaining why the last command failed.
+ *
+ * @return a descriptive error message explaining why the last command failed.
+ */
+DLLEXPORT char* DLLCALL tjGetErrorStr(void);
 
 
-/*
-  int tjDecompress(tjhandle j,
-     unsigned char *srcbuf, unsigned long size,
-     unsigned char *dstbuf, int width, int pitch, int height, int pixelsize,
-     int flags)
-
-  [INPUT] j = instance handle previously returned from a call to
-     tjInitDecompress()
-  [INPUT] srcbuf = pointer to a user-allocated buffer containing the JPEG image
-     to decompress
-  [INPUT] size = size of the JPEG image buffer (in bytes)
-  [INPUT] dstbuf = pointer to user-allocated image buffer that will receive
-     the bitmap image.  This buffer should normally be pitch*height
-     bytes in size, although this pointer may also be used to decompress into
-     a specific region of a larger buffer.
-  [INPUT] width = width (in pixels) of the destination image
-  [INPUT] pitch = bytes per line of the destination image (width*pixelsize if
-     the bitmap is unpadded, else TJPAD(width*pixelsize) if each line of the
-     bitmap is padded to the nearest 32-bit boundary, such as is the case for
-     Windows bitmaps.  You can also be clever and use this parameter to skip
-     lines, etc.  Setting this parameter to 0 is the equivalent of setting it
-     to width*pixelsize.
-  [INPUT] height = height (in pixels) of the destination image
-  [INPUT] pixelsize = size (in bytes) of each pixel in the destination image
-     RGBX/BGRX/XRGB/XBGR: 4, RGB/BGR: 3, Grayscale: 1
-  [INPUT] flags = the bitwise OR of one or more of the flags described in the
-     "Flags" section above.
-
-  RETURNS: 0 on success, -1 on error
-*/
-DLLEXPORT int DLLCALL tjDecompress(tjhandle j,
-	unsigned char *srcbuf, unsigned long size,
-	unsigned char *dstbuf, int width, int pitch, int height, int pixelsize,
-	int flags);
+/* Backward compatibility functions and macros (nothing to see here) */
+#define NUMSUBOPT TJ_NUMSAMP
+#define TJ_444 TJSAMP_444
+#define TJ_422 TJSAMP_422
+#define TJ_420 TJSAMP_420
+#define TJ_411 TJSAMP_420
+#define TJ_GRAYSCALE TJSAMP_GRAY
 
+#define TJ_BGR 1
+#define TJ_BOTTOMUP TJFLAG_BOTTOMUP
+#define TJ_FORCEMMX TJFLAG_FORCEMMX
+#define TJ_FORCESSE TJFLAG_FORCESSE
+#define TJ_FORCESSE2 TJFLAG_FORCESSE2
+#define TJ_ALPHAFIRST 64
+#define TJ_FORCESSE3 TJFLAG_FORCESSE3
+#define TJ_FASTUPSAMPLE TJFLAG_FASTUPSAMPLE
 
-/*
-  int tjDestroy(tjhandle h)
+DLLEXPORT unsigned long DLLCALL TJBUFSIZE(int width, int height);
 
-  Frees structures associated with a compression or decompression instance
-  
-  [INPUT] h = instance handle (returned from a previous call to
-     tjInitCompress() or tjInitDecompress()
+DLLEXPORT int DLLCALL tjCompress(tjhandle handle, unsigned char *srcBuf,
+  int width, int pitch, int height, int pixelSize, unsigned char *dstBuf,
+  unsigned long *compressedSize, int jpegSubsamp, int jpegQual, int flags);
 
-  RETURNS: 0 on success, -1 on error
-*/
-DLLEXPORT int DLLCALL tjDestroy(tjhandle h);
+DLLEXPORT int DLLCALL tjDecompressHeader(tjhandle handle,
+  unsigned char *jpegBuf, unsigned long jpegSize, int *width, int *height);
 
+DLLEXPORT int DLLCALL tjDecompress(tjhandle handle,
+  unsigned char *jpegBuf, unsigned long jpegSize, unsigned char *dstBuf,
+  int width, int pitch, int height, int pixelSize, int flags);
 
-/*
-  char *tjGetErrorStr(void)
-  
-  Returns a descriptive error message explaining why the last command failed
-*/
-DLLEXPORT char* DLLCALL tjGetErrorStr(void);
 
+/**
+ * @}
+ */
 
 #ifdef __cplusplus
 }
 #endif
+
+#endif