Reformat TurboJPEG C API documentation to improve ease of maintenance and to make it more consistent with the javadoc formatting; fix minor error in tjCompressFromYUV() prototype.

git-svn-id: svn+ssh://svn.code.sf.net/p/libjpeg-turbo/code/trunk@1344 632fc199-4ca6-4c93-a231-07263d6284db

doc/html/group___turbo_j_p_e_g.html

@@ -232,9 +232,9 @@ Functions</h2></td></tr>
 <tr class="memitem:ga0b931126c7a615ddc3bbd0cca6698d67"><td class="memItemLeft" align="right" valign="top">DLLEXPORT int DLLCALL&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group___turbo_j_p_e_g.html#ga0b931126c7a615ddc3bbd0cca6698d67">tjCompressFromYUV</a> (<a class="el" href="group___turbo_j_p_e_g.html#ga758d2634ecb4949de7815cba621f5763">tjhandle</a> handle, unsigned char *srcBuf, int width, int pad, int height, int subsamp, unsigned char **jpegBuf, unsigned long *jpegSize, int jpegQual, int flags)</td></tr>
 <tr class="memdesc:ga0b931126c7a615ddc3bbd0cca6698d67"><td class="mdescLeft">&#160;</td><td class="mdescRight">Compress a YUV planar image into a JPEG image.  <a href="#ga0b931126c7a615ddc3bbd0cca6698d67">More...</a><br/></td></tr>
 <tr class="separator:ga0b931126c7a615ddc3bbd0cca6698d67"><td class="memSeparator" colspan="2">&#160;</td></tr>
-<tr class="memitem:gab87b2b19ee8bdd8dba395b74d66a4835"><td class="memItemLeft" align="right" valign="top">DLLEXPORT int DLLCALL&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group___turbo_j_p_e_g.html#gab87b2b19ee8bdd8dba395b74d66a4835">tjCompressFromYUVPlanes</a> (<a class="el" href="group___turbo_j_p_e_g.html#ga758d2634ecb4949de7815cba621f5763">tjhandle</a> handle, unsigned char **srcBufs, int width, int *strides, int height, int subsamp, unsigned char **jpegBuf, unsigned long *jpegSize, int jpegQual, int flags)</td></tr>
+<tr class="memitem:gaa89a1982cb4556b12ae7af4439991af6"><td class="memItemLeft" align="right" valign="top">DLLEXPORT int DLLCALL&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group___turbo_j_p_e_g.html#gaa89a1982cb4556b12ae7af4439991af6">tjCompressFromYUVPlanes</a> (<a class="el" href="group___turbo_j_p_e_g.html#ga758d2634ecb4949de7815cba621f5763">tjhandle</a> handle, unsigned char **srcPlanes, int width, int *strides, int height, int subsamp, unsigned char **jpegBuf, unsigned long *jpegSize, int jpegQual, int flags)</td></tr>
-<tr class="memdesc:gab87b2b19ee8bdd8dba395b74d66a4835"><td class="mdescLeft">&#160;</td><td class="mdescRight">Compress a set of Y, U (Cb), and V (Cr) image planes into a JPEG image.  <a href="#gab87b2b19ee8bdd8dba395b74d66a4835">More...</a><br/></td></tr>
+<tr class="memdesc:gaa89a1982cb4556b12ae7af4439991af6"><td class="mdescLeft">&#160;</td><td class="mdescRight">Compress a set of Y, U (Cb), and V (Cr) image planes into a JPEG image.  <a href="#gaa89a1982cb4556b12ae7af4439991af6">More...</a><br/></td></tr>
-<tr class="separator:gab87b2b19ee8bdd8dba395b74d66a4835"><td class="memSeparator" colspan="2">&#160;</td></tr>
+<tr class="separator:gaa89a1982cb4556b12ae7af4439991af6"><td class="memSeparator" colspan="2">&#160;</td></tr>
 <tr class="memitem:gaccc5bca7f12fcdcc302e6e1c6d4b311b"><td class="memItemLeft" align="right" valign="top">DLLEXPORT unsigned long DLLCALL&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group___turbo_j_p_e_g.html#gaccc5bca7f12fcdcc302e6e1c6d4b311b">tjBufSize</a> (int width, int height, int jpegSubsamp)</td></tr>
 <tr class="memdesc:gaccc5bca7f12fcdcc302e6e1c6d4b311b"><td class="mdescLeft">&#160;</td><td class="mdescRight">The maximum size of the buffer (in bytes) required to hold a JPEG image with the given parameters.  <a href="#gaccc5bca7f12fcdcc302e6e1c6d4b311b">More...</a><br/></td></tr>
 <tr class="separator:gaccc5bca7f12fcdcc302e6e1c6d4b311b"><td class="memSeparator" colspan="2">&#160;</td></tr>
@@ -1110,7 +1110,7 @@ If you choose option 1, <code>*jpegSize</code> should be set to the size of your
 
 </div>
 </div>
-<a class="anchor" id="gab87b2b19ee8bdd8dba395b74d66a4835"></a>
+<a class="anchor" id="gaa89a1982cb4556b12ae7af4439991af6"></a>
 <div class="memitem">
 <div class="memproto">
       <table class="memname">
@@ -1124,7 +1124,7 @@ If you choose option 1, <code>*jpegSize</code> should be set to the size of your
           <td class="paramkey"></td>
           <td></td>
           <td class="paramtype">unsigned char **&#160;</td>
-          <td class="paramname"><em>srcBufs</em>, </td>
+          <td class="paramname"><em>srcPlanes</em>, </td>
         </tr>
         <tr>
           <td class="paramkey"></td>

doc/html/search/all_74.js

@@ -10,7 +10,7 @@ var searchData=
   ['tjbufsizeyuv2',['tjBufSizeYUV2',['../group___turbo_j_p_e_g.html#gaf451664a62c1f6c7cc5a6401f32908c9',1,'turbojpeg.h']]],
   ['tjcompress2',['tjCompress2',['../group___turbo_j_p_e_g.html#gaba62b7a98f960839b588579898495cf2',1,'turbojpeg.h']]],
   ['tjcompressfromyuv',['tjCompressFromYUV',['../group___turbo_j_p_e_g.html#ga0b931126c7a615ddc3bbd0cca6698d67',1,'turbojpeg.h']]],
-  ['tjcompressfromyuvplanes',['tjCompressFromYUVPlanes',['../group___turbo_j_p_e_g.html#gab87b2b19ee8bdd8dba395b74d66a4835',1,'turbojpeg.h']]],
+  ['tjcompressfromyuvplanes',['tjCompressFromYUVPlanes',['../group___turbo_j_p_e_g.html#gaa89a1982cb4556b12ae7af4439991af6',1,'turbojpeg.h']]],
   ['tjcs',['TJCS',['../group___turbo_j_p_e_g.html#ga4f83ad3368e0e29d1957be0efa7c3720',1,'turbojpeg.h']]],
   ['tjcs_5fcmyk',['TJCS_CMYK',['../group___turbo_j_p_e_g.html#gga4f83ad3368e0e29d1957be0efa7c3720a6c8b636152ac8195b869587db315ee53',1,'turbojpeg.h']]],
   ['tjcs_5fgray',['TJCS_GRAY',['../group___turbo_j_p_e_g.html#gga4f83ad3368e0e29d1957be0efa7c3720ab3e7d6a87f695e45b81c1b5262b5a50a',1,'turbojpeg.h']]],

doc/html/search/functions_74.js

@@ -5,7 +5,7 @@ var searchData=
   ['tjbufsizeyuv2',['tjBufSizeYUV2',['../group___turbo_j_p_e_g.html#gaf451664a62c1f6c7cc5a6401f32908c9',1,'turbojpeg.h']]],
   ['tjcompress2',['tjCompress2',['../group___turbo_j_p_e_g.html#gaba62b7a98f960839b588579898495cf2',1,'turbojpeg.h']]],
   ['tjcompressfromyuv',['tjCompressFromYUV',['../group___turbo_j_p_e_g.html#ga0b931126c7a615ddc3bbd0cca6698d67',1,'turbojpeg.h']]],
-  ['tjcompressfromyuvplanes',['tjCompressFromYUVPlanes',['../group___turbo_j_p_e_g.html#gab87b2b19ee8bdd8dba395b74d66a4835',1,'turbojpeg.h']]],
+  ['tjcompressfromyuvplanes',['tjCompressFromYUVPlanes',['../group___turbo_j_p_e_g.html#gaa89a1982cb4556b12ae7af4439991af6',1,'turbojpeg.h']]],
   ['tjdecodeyuv',['tjDecodeYUV',['../group___turbo_j_p_e_g.html#ga132ae2c2cadcf64c8bb0f3bdf69da3ed',1,'turbojpeg.h']]],
   ['tjdecodeyuvplanes',['tjDecodeYUVPlanes',['../group___turbo_j_p_e_g.html#ga6cb5b0e1101a2b20edea576e11faf93d',1,'turbojpeg.h']]],
   ['tjdecompress2',['tjDecompress2',['../group___turbo_j_p_e_g.html#gada69cc6443d1bb493b40f1626259e5e9',1,'turbojpeg.h']]],

turbojpeg.h

@@ -550,24 +550,27 @@ typedef struct tjtransform
    * to be applied in the frequency domain.
    *
    * @param coeffs pointer to an array of transformed DCT coefficients.  (NOTE:
-   *        this pointer is not guaranteed to be valid once the callback
+   * this pointer is not guaranteed to be valid once the callback returns, so
-   *        returns, so applications wishing to hand off the DCT coefficients
+   * applications wishing to hand off the DCT coefficients to another function
-   *        to another function or library should make a copy of them within
+   * or library should make a copy of them within the body of the callback.)
-   *        the body of the callback.)
+   *
    * @param arrayRegion #tjregion structure containing the width and height of
-   *        the array pointed to by <tt>coeffs</tt> as well as its offset
+   * the array pointed to by <tt>coeffs</tt> as well as its offset relative to
-   *        relative to the component plane.  TurboJPEG implementations may
+   * the component plane.  TurboJPEG implementations may choose to split each
-   *        choose to split each component plane into multiple DCT coefficient
+   * component plane into multiple DCT coefficient arrays and call the callback
-   *        arrays and call the callback function once for each array.
+   * function once for each array.
+   *
    * @param planeRegion #tjregion structure containing the width and height of
    * the component plane to which <tt>coeffs</tt> belongs
+   *
    * @param componentID ID number of the component plane to which
-   *        <tt>coeffs</tt> belongs (Y, Cb, and Cr have, respectively, ID's of
+   * <tt>coeffs</tt> belongs (Y, Cb, and Cr have, respectively, ID's of 0, 1,
-   *        0, 1, and 2 in typical JPEG images.)
+   * and 2 in typical JPEG images.)
+   *
    * @param transformID ID number of the transformed image to which
-   *        <tt>coeffs</tt> belongs.  This is the same as the index of the
+   * <tt>coeffs</tt> belongs.  This is the same as the index of the transform
-   *        transform in the <tt>transforms</tt> array that was passed to
+   * in the <tt>transforms</tt> array that was passed to #tjTransform().
-   *        #tjTransform().
+   *
    * @param transform a pointer to a #tjtransform structure that specifies the
    * parameters and/or cropping region for this transform
    *
@@ -616,44 +619,54 @@ DLLEXPORT tjhandle DLLCALL tjInitCompress(void);
  * Compress an RGB, grayscale, or CMYK 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, grayscale, or
  * CMYK 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,
+ * <tt>width * #tjPixelSize[pixelFormat]</tt> if the image is unpadded, or
- *        or <tt>#TJPAD(width * #tjPixelSize[pixelFormat])</tt> if each line of
+ * <tt>#TJPAD(width * #tjPixelSize[pixelFormat])</tt> if each line of the image
- *        the image is padded to the nearest 32-bit boundary, as is the case
+ * is padded to the nearest 32-bit boundary, as is the case for Windows
- *        for Windows bitmaps.  You can also be clever and use this parameter
+ * bitmaps.  You can also be clever and use this parameter to skip lines, etc.
- *        to skip lines, etc.  Setting this parameter to 0 is the equivalent of
+ * Setting this parameter to 0 is the equivalent of setting it to
- *        setting it to <tt>width * #tjPixelSize[pixelFormat]</tt>.
+ * <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
+ * -# pre-allocate the JPEG buffer with an arbitrary size using #tjAlloc() and
- *        #tjAlloc() and let TurboJPEG grow the buffer as needed,
+ * let TurboJPEG grow the buffer as needed,
- *        -# set <tt>*jpegBuf</tt> to NULL to tell TurboJPEG to allocate the
+ * -# set <tt>*jpegBuf</tt> to NULL to tell TurboJPEG to allocate the buffer
- *        buffer for you, or
+ * for you, or
- *        -# pre-allocate the buffer to a "worst case" size determined by
+ * -# pre-allocate the buffer to a "worst case" size determined by calling
- *        calling #tjBufSize().  This should ensure that the buffer never has
+ * #tjBufSize().  This should ensure that the buffer never has to be
- *        to be re-allocated (setting #TJFLAG_NOREALLOC guarantees this.)
+ * re-allocated (setting #TJFLAG_NOREALLOC guarantees this.)
  * .
- *        If you choose option 1, <tt>*jpegSize</tt> should be set to the
+ * If you choose option 1, <tt>*jpegSize</tt> should be set to the size of your
- *        size of your pre-allocated buffer.  In any case, unless you have
+ * pre-allocated buffer.  In any case, unless you have set #TJFLAG_NOREALLOC,
- *        set #TJFLAG_NOREALLOC, you should always check <tt>*jpegBuf</tt> upon
+ * you should always check <tt>*jpegBuf</tt> upon return from this function, as
- *        return from this function, as it may have changed.
+ * 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
+ * the JPEG image buffer.  If <tt>*jpegBuf</tt> points to a pre-allocated
- *        pre-allocated buffer, then <tt>*jpegSize</tt> should be set to the
+ * buffer, then <tt>*jpegSize</tt> should be set to the size of the buffer.
- *        size of the buffer.  Upon return, <tt>*jpegSize</tt> will contain the
+ * Upon return, <tt>*jpegSize</tt> will contain the size of the JPEG image (in
- *        size of the JPEG image (in bytes.)
+ * 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)
+ * 100 = best)
+ *
  * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP
  * "flags".
  *
@@ -668,45 +681,54 @@ DLLEXPORT int DLLCALL tjCompress2(tjhandle handle, unsigned char *srcBuf,
  * Compress a YUV planar image into a JPEG image.
  *
  * @param handle a handle to a TurboJPEG compressor or transformer instance
+ *
  * @param srcBuf pointer to an image buffer containing a YUV planar image to be
- *        compressed.  The size of this buffer should match the value returned
+ * compressed.  The size of this buffer should match the value returned by
- *        by #tjBufSizeYUV2() for the given image width, height, padding, and
+ * #tjBufSizeYUV2() for the given image width, height, padding, and level of
- *        level of chrominance subsampling.  The Y, U (Cb), and V (Cr) image
+ * chrominance subsampling.  The Y, U (Cb), and V (Cr) image planes should be
- *        planes should be stored sequentially in the source buffer (refer to
+ * stored sequentially in the source buffer (refer to @ref YUVnotes
- *        @ref YUVnotes "YUV Image Format Notes".)
+ * "YUV Image Format Notes".)
+ *
  * @param width width (in pixels) of the source image.  If the width is not an
- *        even multiple of the MCU block width (see #tjMCUWidth), then an
+ * even multiple of the MCU block width (see #tjMCUWidth), then an intermediate
- *        intermediate buffer copy will be performed within TurboJPEG.
+ * buffer copy will be performed within TurboJPEG.
+ *
  * @param pad the line padding used in the source image.  For instance, if each
- *        line in each plane of the YUV image is padded to the nearest multiple
+ * line in each plane of the YUV image is padded to the nearest multiple of 4
- *        of 4 bytes, then <tt>pad</tt> should be set to 4.
+ * bytes, then <tt>pad</tt> should be set to 4.
+ *
  * @param height height (in pixels) of the source image.  If the height is not
  * an even multiple of the MCU block height (see #tjMCUHeight), then an
  * intermediate buffer copy will be performed within TurboJPEG.
+ *
  * @param subsamp the level of chrominance subsampling used in the source
  * image (see @ref TJSAMP "Chrominance subsampling options".)
+ *
  * @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
+ * JPEG image.  TurboJPEG has the ability to reallocate the JPEG buffer to
- *        to accommodate the size of the JPEG image.  Thus, you can choose to:
+ * accommodate the size of the JPEG image.  Thus, you can choose to:
- *        -# pre-allocate the JPEG buffer with an arbitrary size using
+ * -# pre-allocate the JPEG buffer with an arbitrary size using #tjAlloc() and
- *        #tjAlloc() and let TurboJPEG grow the buffer as needed,
+ * let TurboJPEG grow the buffer as needed,
- *        -# set <tt>*jpegBuf</tt> to NULL to tell TurboJPEG to allocate the
+ * -# set <tt>*jpegBuf</tt> to NULL to tell TurboJPEG to allocate the buffer
- *        buffer for you, or
+ * for you, or
- *        -# pre-allocate the buffer to a "worst case" size determined by
+ * -# pre-allocate the buffer to a "worst case" size determined by calling
- *        calling #tjBufSize().  This should ensure that the buffer never has
+ * #tjBufSize().  This should ensure that the buffer never has to be
- *        to be re-allocated (setting #TJFLAG_NOREALLOC guarantees this.)
+ * re-allocated (setting #TJFLAG_NOREALLOC guarantees this.)
  * .
- *        If you choose option 1, <tt>*jpegSize</tt> should be set to the
+ * If you choose option 1, <tt>*jpegSize</tt> should be set to the size of your
- *        size of your pre-allocated buffer.  In any case, unless you have
+ * pre-allocated buffer.  In any case, unless you have set #TJFLAG_NOREALLOC,
- *        set #TJFLAG_NOREALLOC, you should always check <tt>*jpegBuf</tt> upon
+ * you should always check <tt>*jpegBuf</tt> upon return from this function, as
- *        return from this function, as it may have changed.
+ * 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
+ * the JPEG image buffer.  If <tt>*jpegBuf</tt> points to a pre-allocated
- *        pre-allocated buffer, then <tt>*jpegSize</tt> should be set to the
+ * buffer, then <tt>*jpegSize</tt> should be set to the size of the buffer.
- *        size of the buffer.  Upon return, <tt>*jpegSize</tt> will contain the
+ * Upon return, <tt>*jpegSize</tt> will contain the size of the JPEG image (in
- *        size of the JPEG image (in bytes.)
+ * bytes.)
+ *
  * @param jpegQual the image quality of the generated JPEG image (1 = worst,
-          100 = best)
+ * 100 = best)
+ *
  * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP
  * "flags".
  *
@@ -721,58 +743,66 @@ DLLEXPORT int DLLCALL tjCompressFromYUV(tjhandle handle, unsigned char *srcBuf,
  * Compress a set of Y, U (Cb), and V (Cr) image planes into a JPEG image.
  *
  * @param handle a handle to a TurboJPEG compressor or transformer instance
+ *
  * @param srcPlanes an array of pointers to Y, U (Cb), and V (Cr) image planes
- *        (or just a Y plane, if compressing a grayscale image) that contain a
+ * (or just a Y plane, if compressing a grayscale image) that contain a YUV
- *        YUV image to be compressed.  These planes can be contiguous or
+ * image to be compressed.  These planes can be contiguous or non-contiguous in
- *        non-contiguous in memory.  Each plane should be at least
+ * memory.  Each plane should be at least
- *        <b><i>{component stride} * {component height}</i></b> bytes in size.
+ * <b><i>{component stride} * {component height}</i></b> bytes in size.  (See
- *        (See below for a description of stride, and refer to @ref YUVnotes
+ * below for a description of stride, and refer to @ref YUVnotes
  * "YUV Image Format Notes" for a description of component height.)
+ *
  * @param width width (in pixels) of the source image.  If the width is not an
- *        even multiple of the MCU block width (see #tjMCUWidth), then an
+ * even multiple of the MCU block width (see #tjMCUWidth), then an intermediate
- *        intermediate buffer copy will be performed within TurboJPEG.
+ * buffer copy will be performed within TurboJPEG.
+ *
  * @param strides an array of integers, each specifying the number of bytes per
- *        line in the corresponding plane of the YUV source image.  Setting the
+ * line in the corresponding plane of the YUV source image.  Setting the stride
- *        stride for any plane to 0 is the same as setting it to the component
+ * for any plane to 0 is the same as setting it to the component width for the
- *        width for the plane.  If <tt>stride</tt> is NULL, then the strides
+ * plane.  If <tt>stride</tt> is NULL, then the strides for all planes will be
- *        for all planes will be set to their respective component widths.  You
+ * set to their respective component widths.  You can adjust the strides in
- *        can adjust the strides in order to specify an arbitrary amount of
+ * order to specify an arbitrary amount of line padding in each plane or to
- *        line padding in each plane or to create a JPEG image from a subregion
+ * create a JPEG image from a subregion of a larger YUV planar image.
- *        of a larger YUV planar image.
+ *
  * @param height height (in pixels) of the source image.  If the height is not
  * an even multiple of the MCU block height (see #tjMCUHeight), then an
  * intermediate buffer copy will be performed within TurboJPEG.
+ *
  * @param subsamp the level of chrominance subsampling used in the source
  * image (see @ref TJSAMP "Chrominance subsampling options".)
+ *
  * @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
+ * JPEG image.  TurboJPEG has the ability to reallocate the JPEG buffer to
- *        to accommodate the size of the JPEG image.  Thus, you can choose to:
+ * accommodate the size of the JPEG image.  Thus, you can choose to:
- *        -# pre-allocate the JPEG buffer with an arbitrary size using
+ * -# pre-allocate the JPEG buffer with an arbitrary size using #tjAlloc() and
- *        #tjAlloc() and let TurboJPEG grow the buffer as needed,
+ * let TurboJPEG grow the buffer as needed,
- *        -# set <tt>*jpegBuf</tt> to NULL to tell TurboJPEG to allocate the
+ * -# set <tt>*jpegBuf</tt> to NULL to tell TurboJPEG to allocate the buffer
- *        buffer for you, or
+ * for you, or
- *        -# pre-allocate the buffer to a "worst case" size determined by
+ * -# pre-allocate the buffer to a "worst case" size determined by calling
- *        calling #tjBufSize().  This should ensure that the buffer never has
+ * #tjBufSize().  This should ensure that the buffer never has to be
- *        to be re-allocated (setting #TJFLAG_NOREALLOC guarantees this.)
+ * re-allocated (setting #TJFLAG_NOREALLOC guarantees this.)
  * .
- *        If you choose option 1, <tt>*jpegSize</tt> should be set to the
+ * If you choose option 1, <tt>*jpegSize</tt> should be set to the size of your
- *        size of your pre-allocated buffer.  In any case, unless you have
+ * pre-allocated buffer.  In any case, unless you have set #TJFLAG_NOREALLOC,
- *        set #TJFLAG_NOREALLOC, you should always check <tt>*jpegBuf</tt> upon
+ * you should always check <tt>*jpegBuf</tt> upon return from this function, as
- *        return from this function, as it may have changed.
+ * 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
+ * the JPEG image buffer.  If <tt>*jpegBuf</tt> points to a pre-allocated
- *        pre-allocated buffer, then <tt>*jpegSize</tt> should be set to the
+ * buffer, then <tt>*jpegSize</tt> should be set to the size of the buffer.
- *        size of the buffer.  Upon return, <tt>*jpegSize</tt> will contain the
+ * Upon return, <tt>*jpegSize</tt> will contain the size of the JPEG image (in
- *        size of the JPEG image (in bytes.)
+ * bytes.)
+ *
  * @param jpegQual the image quality of the generated JPEG image (1 = worst,
-          100 = best)
+ * 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 int DLLCALL tjCompressFromYUVPlanes(tjhandle handle,
-	unsigned char **srcBufs, int width, int *strides, int height, int subsamp,
+	unsigned char **srcPlanes, int width, int *strides, int height, int subsamp,
 	unsigned char **jpegBuf, unsigned long *jpegSize, int jpegQual, int flags);
 
 
@@ -788,7 +818,9 @@ DLLEXPORT int DLLCALL tjCompressFromYUVPlanes(tjhandle handle,
  * 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".)
@@ -805,9 +837,12 @@ DLLEXPORT unsigned long DLLCALL tjBufSize(int width, int height,
  * the given parameters.
  *
  * @param width width of the image (in pixels)
+ *
  * @param pad the width of each line in each plane of the image is padded to
  * the nearest multiple of this number of bytes (must be a power of 2.)
+ *
  * @param height height of the image (in pixels)
+ *
  * @param subsamp level of chrominance subsampling in the image (see
  * @ref TJSAMP "Chrominance subsampling options".)
  *
@@ -825,34 +860,42 @@ DLLEXPORT unsigned long DLLCALL tjBufSizeYUV2(int width, int pad, int height,
  * process.  
  *
  * @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 encoded
+ *
  * @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,
+ * <tt>width * #tjPixelSize[pixelFormat]</tt> if the image is unpadded, or
- *        or <tt>#TJPAD(width * #tjPixelSize[pixelFormat])</tt> if each line of
+ * <tt>#TJPAD(width * #tjPixelSize[pixelFormat])</tt> if each line of the image
- *        the image is padded to the nearest 32-bit boundary, as is the case
+ * is padded to the nearest 32-bit boundary, as is the case for Windows
- *        for Windows bitmaps.  You can also be clever and use this parameter
+ * bitmaps.  You can also be clever and use this parameter to skip lines, etc.
- *        to skip lines, etc.  Setting this parameter to 0 is the equivalent of
+ * Setting this parameter to 0 is the equivalent of setting it to
- *        setting it to <tt>width * #tjPixelSize[pixelFormat]</tt>.
+ * <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 dstBuf pointer to an image buffer that will receive the YUV image.
- *        Use #tjBufSizeYUV2() to determine the appropriate size for this
+ * Use #tjBufSizeYUV2() to determine the appropriate size for this buffer based
- *        buffer based on the image width, height, padding, and level of
+ * on the image width, height, padding, and level of chrominance subsampling.
- *        chrominance subsampling.  The Y, U (Cb), and V (Cr) image planes will
+ * The Y, U (Cb), and V (Cr) image planes will be stored sequentially in the
- *        be stored sequentially in the buffer (refer to @ref YUVnotes
+ * buffer (refer to @ref YUVnotes "YUV Image Format Notes".)
- *        "YUV Image Format Notes".)
+ *
  * @param pad the width of each line in each plane of the YUV image will be
- *        padded to the nearest multiple of this number of bytes (must be a
+ * padded to the nearest multiple of this number of bytes (must be a power of
- *        power of 2.)  To generate images suitable for X Video, <tt>pad</tt>
+ * 2.)  To generate images suitable for X Video, <tt>pad</tt> should be set to
- *        should be set to 4.
+ * 4.
+ *
  * @param subsamp the level of chrominance subsampling to be used when
  * generating the YUV image (see @ref TJSAMP
- *        "Chrominance subsampling options".)  To generate images suitable for
+ * "Chrominance subsampling options".)  To generate images suitable for X
- *        X Video, <tt>subsamp</tt> should be set to @ref TJSAMP_420.  This
+ * Video, <tt>subsamp</tt> should be set to @ref TJSAMP_420.  This produces an
- *        produces an image compatible with the I420 (AKA "YUV420P") format.
+ * image compatible with the I420 (AKA "YUV420P") format.
+ *
  * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP
  * "flags".
  *
@@ -870,39 +913,47 @@ DLLEXPORT int DLLCALL tjEncodeYUV3(tjhandle handle,
  * compression process.
  *
  * @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 encoded
+ *
  * @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,
+ * <tt>width * #tjPixelSize[pixelFormat]</tt> if the image is unpadded, or
- *        or <tt>#TJPAD(width * #tjPixelSize[pixelFormat])</tt> if each line of
+ * <tt>#TJPAD(width * #tjPixelSize[pixelFormat])</tt> if each line of the image
- *        the image is padded to the nearest 32-bit boundary, as is the case
+ * is padded to the nearest 32-bit boundary, as is the case for Windows
- *        for Windows bitmaps.  You can also be clever and use this parameter
+ * bitmaps.  You can also be clever and use this parameter to skip lines, etc.
- *        to skip lines, etc.  Setting this parameter to 0 is the equivalent of
+ * Setting this parameter to 0 is the equivalent of setting it to
- *        setting it to <tt>width * #tjPixelSize[pixelFormat]</tt>.
+ * <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 dstPlanes an array of pointers to Y, U (Cb), and V (Cr) image planes
- *        (or just a Y plane, if generating a grayscale image) that will
+ * (or just a Y plane, if generating a grayscale image) that will receive the
- *        receive the encoded image.  These planes can be contiguous or
+ * encoded image.  These planes can be contiguous or non-contiguous in memory.
- *        non-contiguous in memory.  Each plane should be at least
+ * Each plane should be at least
  * <b><i>{component stride} * {component height}</i></b> bytes in size.
  * (See below for a description of stride, and refer to @ref YUVnotes
  * "YUV Image Format Notes" for a description of component height.)
+ *
  * @param strides an array of integers, each specifying the number of bytes per
- *        line in the corresponding plane of the output image.  Setting the
+ * line in the corresponding plane of the output image.  Setting the stride for
- *        stride for any plane to 0 is the same as setting it to the component
+ * any plane to 0 is the same as setting it to the component width for the
- *        width for the plane.  If <tt>stride</tt> is NULL, then the strides
+ * plane.  If <tt>stride</tt> is NULL, then the strides for all planes will be
- *        for all planes will be set to their respective component widths.  You
+ * set to their respective component widths.  You can adjust the strides in
- *        can adjust the strides in order to add an arbitrary amount of line
+ * order to add an arbitrary amount of line padding to each plane or to encode
- *        padding to each plane or to encode an RGB or grayscale image into a
+ * an RGB or grayscale image into a subregion of a larger YUV planar image.
- *        subregion of a larger YUV planar image.
+ *
  * @param subsamp the level of chrominance subsampling to be used when
  * generating the YUV image (see @ref TJSAMP
- *        "Chrominance subsampling options".)  To generate images suitable for
+ * "Chrominance subsampling options".)  To generate images suitable for X
- *        X Video, <tt>subsamp</tt> should be set to @ref TJSAMP_420.  This
+ * Video, <tt>subsamp</tt> should be set to @ref TJSAMP_420.  This produces an
- *        produces an image compatible with the I420 (AKA "YUV420P") format.
+ * image compatible with the I420 (AKA "YUV420P") format.
+ *
  * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP
  * "flags".
  *
@@ -926,18 +977,24 @@ DLLEXPORT tjhandle DLLCALL tjInitDecompress(void);
  * 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
+ * level of chrominance subsampling used when compressing the JPEG image (see
- *        (see @ref TJSAMP "Chrominance subsampling options".)
+ * @ref TJSAMP "Chrominance subsampling options".)
+ *
  * @param jpegColorspace pointer to an integer variable that will receive one
- *        of the JPEG colorspace constants, indicating the colorspace of the
+ * of the JPEG colorspace constants, indicating the colorspace of the JPEG
- *        JPEG image (see @ref TJCS "JPEG colorspaces".)
+ * image (see @ref TJCS "JPEG colorspaces".)
  *
  * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr().)
 */
@@ -963,40 +1020,46 @@ DLLEXPORT tjscalingfactor* DLLCALL tjGetScalingFactors(int *numscalingfactors);
  * Decompress a JPEG image to an RGB, grayscale, or CMYK 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>
+ * image.  This buffer should normally be <tt>pitch * scaledHeight</tt> bytes
- *        bytes in size, where <tt>scaledHeight</tt> can be determined by
+ * in size, where <tt>scaledHeight</tt> can be determined by calling
- *        calling #TJSCALED() with the JPEG image height and one of the scaling
+ * #TJSCALED() with the JPEG image height and one of the scaling factors
- *        factors returned by #tjGetScalingFactors().  The <tt>dstBuf</tt>
+ * returned by #tjGetScalingFactors().  The <tt>dstBuf</tt> pointer may also be
- *        pointer may also be used to decompress into a specific region of a
+ * used to decompress into a specific region of a larger buffer.
- *        larger buffer.
+ *
  * @param width desired width (in pixels) of the destination image.  If this is
  * different than the width of the JPEG image being decompressed, then
- *        TurboJPEG will use scaling in the JPEG decompressor to generate the
+ * TurboJPEG will use scaling in the JPEG decompressor to generate the largest
- *        largest possible image that will fit within the desired width.  If
+ * possible image that will fit within the desired width.  If <tt>width</tt> is
- *        <tt>width</tt> is set to 0, then only the height will be considered
+ * set to 0, then only the height will be considered when determining the
- *        when determining the scaled image size.
+ * scaled image size.
+ *
  * @param pitch bytes per line of the destination image.  Normally, this is
- *        <tt>scaledWidth * #tjPixelSize[pixelFormat]</tt> if the decompressed
+ * <tt>scaledWidth * #tjPixelSize[pixelFormat]</tt> if the decompressed image
- *        image is unpadded, else <tt>#TJPAD(scaledWidth *
+ * is unpadded, else <tt>#TJPAD(scaledWidth * #tjPixelSize[pixelFormat])</tt>
- *        #tjPixelSize[pixelFormat])</tt> if each line of the decompressed
+ * if each line of the decompressed image is padded to the nearest 32-bit
- *        image is padded to the nearest 32-bit boundary, as is the case for
+ * boundary, as is the case for Windows bitmaps.  (NOTE: <tt>scaledWidth</tt>
- *        Windows bitmaps.  (NOTE: <tt>scaledWidth</tt> can be determined by
+ * can be determined by calling #TJSCALED() with the JPEG image width and one
- *        calling #TJSCALED() with the JPEG image width and one of the scaling
+ * of the scaling factors returned by #tjGetScalingFactors().)  You can also be
- *        factors returned by #tjGetScalingFactors().)  You can also be clever
+ * clever and use the pitch parameter to skip lines, etc.  Setting this
- *        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 different than the height of the JPEG image being decompressed,
+ * is different than the height of the JPEG image being decompressed, then
- *        then TurboJPEG will use scaling in the JPEG decompressor to generate
+ * TurboJPEG will use scaling in the JPEG decompressor to generate the largest
- *        the largest possible image that will fit within the desired height.
+ * possible image that will fit within the desired height.  If <tt>height</tt>
- *        If <tt>height</tt> is set to 0, then only the width will be
+ * is set to 0, then only the width will be considered when determining the
- *        considered when determining the scaled image size.
+ * 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".
  *
@@ -1013,34 +1076,40 @@ DLLEXPORT int DLLCALL tjDecompress2(tjhandle handle,
  * image is generated instead of an RGB 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 YUV image.
- *        Use #tjBufSizeYUV2() to determine the appropriate size for this
+ * Use #tjBufSizeYUV2() to determine the appropriate size for this buffer based
- *        buffer based on the image width, height, padding, and level of
+ * on the image width, height, padding, and level of subsampling.  The Y,
- *        subsampling.  The Y, U (Cb), and V (Cr) image planes will be stored
+ * U (Cb), and V (Cr) image planes will be stored sequentially in the buffer
- *        sequentially in the buffer (refer to @ref YUVnotes
+ * (refer to @ref YUVnotes "YUV Image Format Notes".)
- *        "YUV Image Format Notes".)
+ *
  * @param width desired width (in pixels) of the YUV image.  If this is
  * different than the width of the JPEG image being decompressed, then
- *        TurboJPEG will use scaling in the JPEG decompressor to generate the
+ * TurboJPEG will use scaling in the JPEG decompressor to generate the largest
- *        largest possible image that will fit within the desired width.  If
+ * possible image that will fit within the desired width.  If <tt>width</tt> is
- *        <tt>width</tt> is set to 0, then only the height will be considered
+ * set to 0, then only the height will be considered when determining the
- *        when determining the scaled image size.  If the scaled width is not
+ * scaled image size.  If the scaled width is not an even multiple of the MCU
- *        an even multiple of the MCU block width (see #tjMCUWidth), then an
+ * block width (see #tjMCUWidth), then an intermediate buffer copy will be
- *        intermediate buffer copy will be performed within TurboJPEG.
+ * performed within TurboJPEG.
+ *
  * @param pad the width of each line in each plane of the YUV image will be
- *        padded to the nearest multiple of this number of bytes (must be a
+ * padded to the nearest multiple of this number of bytes (must be a power of
- *        power of 2.)  To generate images suitable for X Video, <tt>pad</tt>
+ * 2.)  To generate images suitable for X Video, <tt>pad</tt> should be set to
- *        should be set to 4.
+ * 4.
+ *
  * @param height desired height (in pixels) of the YUV image.  If this is
  * different than the height of the JPEG image being decompressed, then
- *        TurboJPEG will use scaling in the JPEG decompressor to generate the
+ * TurboJPEG will use scaling in the JPEG decompressor to generate the largest
- *        largest possible image that will fit within the desired height.  If
+ * possible image that will fit within the desired height.  If <tt>height</tt>
- *        <tt>height</tt> is set to 0, then only the width will be considered
+ * is set to 0, then only the width will be considered when determining the
- *        when determining the scaled image size.  If the scaled height is not
+ * scaled image size.  If the scaled height is not an even multiple of the MCU
- *        an even multiple of the MCU block height (see #tjMCUHeight), then an
+ * block height (see #tjMCUHeight), then an intermediate buffer copy will be
- *        intermediate buffer copy will be performed within TurboJPEG.
+ * performed within TurboJPEG.
+ *
  * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP
  * "flags".
  *
@@ -1057,40 +1126,45 @@ DLLEXPORT int DLLCALL tjDecompressToYUV2(tjhandle handle,
  * conversion step, so a planar YUV image is generated instead of an RGB 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 dstPlanes an array of pointers to Y, U (Cb), and V (Cr) image planes
- *        (or just a Y plane, if decompressing a grayscale image) that will
+ * (or just a Y plane, if decompressing a grayscale image) that will receive
- *        receive the YUV image.  These planes can be contiguous or
+ * the YUV image.  These planes can be contiguous or non-contiguous in memory.
- *        non-contiguous in memory.  Each plane should be at least
+ * Each plane should be at least
- *        <b><i>{component stride} * {scaled component height}</i></b> bytes in
+ * <b><i>{component stride} * {scaled component height}</i></b> bytes in size.
- *        size.  (See below for a description of stride, and refer to @ref
+ * (See below for a description of stride, and refer to @ref YUVnotes
- *        YUVnotes "YUV Image Format Notes" for a description of component
+ * "YUV Image Format Notes" for a description of component height.)
- *        height.)
+ *
  * @param width desired width (in pixels) of the YUV image.  If this is
  * different than the width of the JPEG image being decompressed, then
- *        TurboJPEG will use scaling in the JPEG decompressor to generate the
+ * TurboJPEG will use scaling in the JPEG decompressor to generate the largest
- *        largest possible image that will fit within the desired width.  If
+ * possible image that will fit within the desired width.  If <tt>width</tt> is
- *        <tt>width</tt> is set to 0, then only the height will be considered
+ * set to 0, then only the height will be considered when determining the
- *        when determining the scaled image size.  If the scaled width is not
+ * scaled image size.  If the scaled width is not an even multiple of the MCU
- *        an even multiple of the MCU block width (see #tjMCUWidth), then an
+ * block width (see #tjMCUWidth), then an intermediate buffer copy will be
- *        intermediate buffer copy will be performed within TurboJPEG.
+ * performed within TurboJPEG.
+ *
  * @param strides an array of integers, each specifying the number of bytes per
- *        line in the corresponding plane of the output image.  Setting the
+ * line in the corresponding plane of the output image.  Setting the stride for
- *        stride for any plane to 0 is the same as setting it to the scaled
+ * any plane to 0 is the same as setting it to the scaled component width for
- *        component width for the plane.  If <tt>stride</tt> is NULL, then the
+ * the plane.  If <tt>stride</tt> is NULL, then the strides for all planes will
- *        strides for all planes will be set to their respective scaled
+ * be set to their respective scaled component widths.  You can adjust the
- *        component widths.  You can adjust the strides in order to add an
+ * strides in order to add an arbitrary amount of line padding to each plane or
- *        arbitrary amount of line padding to each plane or to decompress the
+ * to decompress the JPEG image into a subregion of a larger YUV planar image.
- *        JPEG image into a subregion of a larger YUV planar image.
+ *
  * @param height desired height (in pixels) of the YUV image.  If this is
  * different than the height of the JPEG image being decompressed, then
- *        TurboJPEG will use scaling in the JPEG decompressor to generate the
+ * TurboJPEG will use scaling in the JPEG decompressor to generate the largest
- *        largest possible image that will fit within the desired height.  If
+ * possible image that will fit within the desired height.  If <tt>height</tt>
- *        <tt>height</tt> is set to 0, then only the width will be considered
+ * is set to 0, then only the width will be considered when determining the
- *        when determining the scaled image size.  If the scaled height is not
+ * scaled image size.  If the scaled height is not an even multiple of the MCU
- *        an even multiple of the MCU block height (see #tjMCUHeight), then an
+ * block height (see #tjMCUHeight), then an intermediate buffer copy will be
- *        intermediate buffer copy will be performed within TurboJPEG.
+ * performed within TurboJPEG.
+ *
  * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP
  * "flags".
  *
@@ -1108,34 +1182,41 @@ DLLEXPORT int DLLCALL tjDecompressToYUVPlanes(tjhandle handle,
  * process.
  *
  * @param handle a handle to a TurboJPEG decompressor or transformer instance
+ *
  * @param srcBuf pointer to an image buffer containing a YUV planar image to be
- *        decoded.  The size of this buffer should match the value returned
+ * decoded.  The size of this buffer should match the value returned by
- *        by #tjBufSizeYUV2() for the given image width, height, padding, and
+ * #tjBufSizeYUV2() for the given image width, height, padding, and level of
- *        level of chrominance subsampling.  The Y, U (Cb), and V (Cr) image
+ * chrominance subsampling.  The Y, U (Cb), and V (Cr) image planes should be
- *        planes should be stored sequentially in the source buffer (refer to
+ * stored sequentially in the source buffer (refer to @ref YUVnotes
- *        @ref YUVnotes "YUV Image Format Notes".)
+ * "YUV Image Format Notes".)
+ *
  * @param pad Use this parameter to specify that the width of each line in each
- *        plane of the YUV source image is padded to the nearest multiple of
+ * plane of the YUV source image is padded to the nearest multiple of this
- *        this number of bytes (must be a power of 2.)
+ * number of bytes (must be a power of 2.)
+ *
  * @param subsamp the level of chrominance subsampling used in the YUV source
  * image (see @ref TJSAMP "Chrominance subsampling options".)
+ *
  * @param dstBuf pointer to an image buffer that will receive the decoded
- *        image.  This buffer should normally be <tt>pitch * height</tt>
+ * image.  This buffer should normally be <tt>pitch * height</tt> bytes in
- *        bytes in size, but the <tt>dstBuf</tt> pointer can also be used to
+ * size, but the <tt>dstBuf</tt> pointer can also be used to decode into a
- *        decode into a specific region of a larger buffer.
+ * specific region of a larger buffer.
+ *
  * @param width width (in pixels) of the source and destination images
+ *
  * @param pitch bytes per line of the destination image.  Normally, this should
- *        be <tt>width * #tjPixelSize[pixelFormat]</tt> if the destination
+ * be <tt>width * #tjPixelSize[pixelFormat]</tt> if the destination image is
- *        image is unpadded, or <tt>#TJPAD(width *
+ * unpadded, or <tt>#TJPAD(width * #tjPixelSize[pixelFormat])</tt> if each line
- *        #tjPixelSize[pixelFormat])</tt> if each line of the destination
+ * of the destination image should be padded to the nearest 32-bit boundary, as
- *        image should be padded to the nearest 32-bit boundary, as is the case
+ * is the case for Windows bitmaps.  You can also be clever and use the pitch
- *        for Windows bitmaps.  You can also be clever and use the pitch
+ * parameter to skip lines, etc.  Setting this parameter to 0 is the equivalent
- *        parameter to skip lines, etc.  Setting this parameter to 0 is the
+ * of setting it to <tt>width * #tjPixelSize[pixelFormat]</tt>.
- *        equivalent of setting it to <tt>width *
+ *
- *        #tjPixelSize[pixelFormat]</tt>.
  * @param height height (in pixels) of the source and destination images
+ *
  * @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".
  *
@@ -1153,40 +1234,46 @@ DLLEXPORT int DLLCALL tjDecodeYUV(tjhandle handle, unsigned char *srcBuf,
  * decompression process.
  *
  * @param handle a handle to a TurboJPEG decompressor or transformer instance
+ *
  * @param srcPlanes an array of pointers to Y, U (Cb), and V (Cr) image planes
- *        (or just a Y plane, if decoding a grayscale image) that contain a
+ * (or just a Y plane, if decoding a grayscale image) that contain a YUV image
- *        YUV image to be decoded.  These planes can be contiguous or
+ * to be decoded.  These planes can be contiguous or non-contiguous in memory.
- *        non-contiguous in memory.  Each plane should be at least
+ * Each plane should be at least
  * <b><i>{component stride} * {component height}</i></b> bytes in size.
  * (See below for a description of stride, and refer to @ref YUVnotes
  * "YUV Image Format Notes" for a description of component height.)
+ *
  * @param strides an array of integers, each specifying the number of bytes per
- *        line in the corresponding plane of the YUV source image.  Setting the
+ * line in the corresponding plane of the YUV source image.  Setting the stride
- *        stride for any plane to 0 is the same as setting it to the component
+ * for any plane to 0 is the same as setting it to the component width for the
- *        width for the plane.  If <tt>stride</tt> is NULL, then the strides
+ * plane.  If <tt>stride</tt> is NULL, then the strides for all planes will be
- *        for all planes will be set to their respective component widths.  You
+ * set to their respective component widths.  You can adjust the strides in
- *        can adjust the strides in order to specify an arbitrary amount of
+ * order to specify an arbitrary amount of line padding in each plane or to
- *        line padding in each plane or to decode a subregion of a larger YUV
+ * decode a subregion of a larger YUV planar image.
- *        planar image.
+ *
  * @param subsamp the level of chrominance subsampling used in the YUV source
  * image (see @ref TJSAMP "Chrominance subsampling options".)
+ *
  * @param dstBuf pointer to an image buffer that will receive the decoded
- *        image.  This buffer should normally be <tt>pitch * height</tt>
+ * image.  This buffer should normally be <tt>pitch * height</tt> bytes in
- *        bytes in size, but the <tt>dstBuf</tt> pointer can also be used to
+ * size, but the <tt>dstBuf</tt> pointer can also be used to decode into a
- *        decode into a specific region of a larger buffer.
+ * specific region of a larger buffer.
+ *
  * @param width width (in pixels) of the source and destination images
+ *
  * @param pitch bytes per line of the destination image.  Normally, this should
- *        be <tt>width * #tjPixelSize[pixelFormat]</tt> if the destination
+ * be <tt>width * #tjPixelSize[pixelFormat]</tt> if the destination image is
- *        image is unpadded, or <tt>#TJPAD(width *
+ * unpadded, or <tt>#TJPAD(width * #tjPixelSize[pixelFormat])</tt> if each line
- *        #tjPixelSize[pixelFormat])</tt> if each line of the destination
+ * of the destination image should be padded to the nearest 32-bit boundary, as
- *        image should be padded to the nearest 32-bit boundary, as is the case
+ * is the case for Windows bitmaps.  You can also be clever and use the pitch
- *        for Windows bitmaps.  You can also be clever and use the pitch
+ * parameter to skip lines, etc.  Setting this parameter to 0 is the equivalent
- *        parameter to skip lines, etc.  Setting this parameter to 0 is the
+ * of setting it to <tt>width * #tjPixelSize[pixelFormat]</tt>.
- *        equivalent of setting it to <tt>width *
+ *
- *        #tjPixelSize[pixelFormat]</tt>.
  * @param height height (in pixels) of the source and destination images
+ *
  * @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".
  *
@@ -1220,36 +1307,41 @@ DLLEXPORT tjhandle DLLCALL tjInitTransform(void);
  * source coefficients multiple times.
  *
  * @param handle a handle to a TurboJPEG transformer instance
+ *
  * @param jpegBuf pointer to a buffer containing the JPEG image to transform
+ *
  * @param jpegSize size of the JPEG image (in bytes)
+ *
  * @param n the number of transformed JPEG images to generate
+ *
  * @param dstBufs pointer to an array of n image buffers.  <tt>dstBufs[i]</tt>
- *        will receive a JPEG image that has been transformed using the
+ * will receive a JPEG image that has been transformed using the parameters in
- *        parameters in <tt>transforms[i]</tt>.  TurboJPEG has the ability to
+ * <tt>transforms[i]</tt>.  TurboJPEG has the ability to reallocate the JPEG
- *        reallocate the JPEG buffer to accommodate the size of the JPEG image.
+ * buffer to accommodate the size of the JPEG image.  Thus, you can choose to:
- *        Thus, you can choose to:
+ * -# pre-allocate the JPEG buffer with an arbitrary size using #tjAlloc() and
- *        -# pre-allocate the JPEG buffer with an arbitrary size using
+ * let TurboJPEG grow the buffer as needed,
- *        #tjAlloc() and let TurboJPEG grow the buffer as needed,
+ * -# set <tt>dstBufs[i]</tt> to NULL to tell TurboJPEG to allocate the buffer
- *        -# set <tt>dstBufs[i]</tt> to NULL to tell TurboJPEG to allocate the
+ * for you, or
- *        buffer for you, or
+ * -# pre-allocate the buffer to a "worst case" size determined by calling
- *        -# pre-allocate the buffer to a "worst case" size determined by
+ * #tjBufSize() with the transformed or cropped width and height.  This should
- *        calling #tjBufSize() with the transformed or cropped width and
+ * ensure that the buffer never has to be re-allocated (setting
- *        height.  This should ensure that the buffer never has to be
+ * #TJFLAG_NOREALLOC guarantees this.)
- *        re-allocated (setting #TJFLAG_NOREALLOC guarantees this.)
  * .
- *        If you choose option 1, <tt>dstSizes[i]</tt> should be set to
+ * If you choose option 1, <tt>dstSizes[i]</tt> should be set to the size of
- *        the size of your pre-allocated buffer.  In any case, unless you have
+ * your pre-allocated buffer.  In any case, unless you have set
- *        set #TJFLAG_NOREALLOC, you should always check <tt>dstBufs[i]</tt>
+ * #TJFLAG_NOREALLOC, you should always check <tt>dstBufs[i]</tt> upon return
- *        upon return from this function, as it may have changed.
+ * from this function, as it may have changed.
+ *
  * @param dstSizes pointer to an array of n unsigned long variables that will
- *        receive the actual sizes (in bytes) of each transformed JPEG image.
+ * receive the actual sizes (in bytes) of each transformed JPEG image.  If
- *        If <tt>dstBufs[i]</tt> points to a pre-allocated buffer, then
+ * <tt>dstBufs[i]</tt> points to a pre-allocated buffer, then
- *        <tt>dstSizes[i]</tt> should be set to the size of the buffer.  Upon
+ * <tt>dstSizes[i]</tt> should be set to the size of the buffer.  Upon return,
- *        return, <tt>dstSizes[i]</tt> will contain the size of the JPEG image
+ * <tt>dstSizes[i]</tt> will contain the size of the JPEG image (in bytes.)
- *        (in bytes.)
+ *
  * @param transforms pointer to an array of n #tjtransform structures, each of
- *        which specifies the transform parameters and/or cropping region for
+ * which specifies the transform parameters and/or cropping region for the
- *        the corresponding transformed output image.
+ * corresponding transformed output image.
+ *
  * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP
  * "flags".
  *