Further doc tweaks

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

1 files changed, 30 insertions, 28 deletions

diff --git a/turbojpeg.h b/turbojpeg.h
index a61cc1a..3fc6c39 100644
--- a/turbojpeg.h
+++ b/turbojpeg.h
@@ -53,8 +53,8 @@
 
 /**
  * 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
+ * When an image is converted from the RGB to the YUV colorspace as part of
+ * the JPEG compression process, some of the U and V (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
@@ -246,10 +246,11 @@ static const int tjPixelSize[TJ_NUMPF] = {3, 3, 4, 4, 4, 4, 1, 4, 4, 4, 4};
  */
 #define TJFLAG_FORCESSE3     128
 /**
- * When decompressing, use the fastest chrominance upsampling algorithm
- * available in the underlying codec.  The default is to use smooth upsampling,
- * which creates a smooth transition between neighboring chrominance components
- * in order to reduce upsampling artifacts in the decompressed image.
+ * When decompressing an image that was compressed using chrominance
+ * subsampling, use the fastest chrominance upsampling algorithm available in
+ * the underlying codec.  The default is to use smooth upsampling, which
+ * creates a smooth transition between neighboring chrominance components in
+ * order to reduce upsampling artifacts in the decompressed image.
  */
 #define TJFLAG_FASTUPSAMPLE  256
 /**
@@ -281,7 +282,7 @@ static const int tjPixelSize[TJ_NUMPF] = {3, 3, 4, 4, 4, 4, 1, 4, 4, 4, 4};
 
 
 /**
- * Number of transform operations
+ * The number of transform operations
  */
 #define TJ_NUMXOP 8
 
@@ -455,11 +456,11 @@ typedef struct tjtransform
    * @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, U, and V have, respectively, ID's of
    *        0, 1, 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
-   *        transform in the transforms array that was passed to
+   *        transform in the <tt>transforms</tt> array that was passed to
    *        #tjTransform().
    * @param transform a pointer to a #tjtransform structure that specifies the
    *        parameters and/or cropping region for this transform
@@ -562,7 +563,7 @@ DLLEXPORT int DLLCALL tjCompress2(tjhandle handle, unsigned char *srcBuf,
  * 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
+ * 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
@@ -694,14 +695,15 @@ DLLEXPORT tjscalingfactor* DLLCALL tjGetScalingFactors(int *numscalingfactors);
  *        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.
+ *        factors returned by #tjGetScalingFactors().  The <tt>dstBuf</tt>
+ *        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
  *        different 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.
+ *        <tt>width</tt> 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 *
@@ -717,8 +719,8 @@ DLLEXPORT tjscalingfactor* DLLCALL tjGetScalingFactors(int *numscalingfactors);
  *        is different 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.
+ *        If <tt>height</tt> 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
@@ -735,7 +737,7 @@ DLLEXPORT int DLLCALL tjDecompress2(tjhandle handle,
  * Decompress a JPEG image to a YUV planar image.  This function performs JPEG
  * decompression but leaves out the color conversion step, so a planar YUV
  * image is generated instead of an RGB image.  The padding of the planes in
- * this image is the same as the images generated by #tjEncodeYUV2().  Note
+ * this image is the same as in the images generated by #tjEncodeYUV2().  Note
  * that, if the width or height of the image is not an even multiple of the MCU
  * block size (see #tjMCUWidth and #tjMCUHeight), then an intermediate buffer
  * copy will be performed within TurboJPEG.
@@ -744,7 +746,7 @@ DLLEXPORT int DLLCALL tjDecompress2(tjhandle handle,
  * @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 #tjBufSizeYUV to determine the appropriate size for this buffer
+ *        Use #tjBufSizeYUV() to determine the appropriate size for this buffer
  *        based on the image width, height, and level of subsampling.
  * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP
  *        "flags".
@@ -771,12 +773,12 @@ DLLEXPORT tjhandle DLLCALL tjInitTransform(void);
  * to another without altering the values of the coefficients.  While this is
  * typically faster than decompressing the image, transforming it, and
  * re-compressing it, lossless transforms are not free.  Each lossless
- * transform requires reading and Huffman decoding all of the coefficients in
- * the source image, regardless of the size of the destination image.  Thus,
- * this function provides a means of generating multiple transformed images
- * from the same source or of applying multiple transformations simultaneously,
- * in order to eliminate the need to read the source coefficients multiple
- * times.
+ * transform requires reading and performing Huffman decoding on all of the
+ * coefficients in the source image, regardless of the size of the destination
+ * image.  Thus, this function provides a means of generating multiple
+ * transformed images from the same source or  applying multiple
+ * transformations simultaneously, in order to eliminate the need to read the
+ * 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
@@ -792,9 +794,9 @@ DLLEXPORT tjhandle DLLCALL tjInitTransform(void);
  *        -# set <tt>dstBufs[i]</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() with the cropped width and height.  This should
- *        ensure that the buffer never has to be re-allocated (setting
- *        #TJFLAG_NOREALLOC guarantees this.)
+ *        calling #tjBufSize() with the transformed or cropped width and
+ *        height.  This should ensure that the buffer never has to be
+ *        re-allocated (setting #TJFLAG_NOREALLOC guarantees this.)
  *        .
  *        If you choose option 1, <tt>dstSizes[i]</tt> should be set to
  *        the size of your pre-allocated buffer.  In any case, unless you have
@@ -806,7 +808,7 @@ DLLEXPORT tjhandle DLLCALL tjInitTransform(void);
  *        <tt>dstSizes[i]</tt> should be set to the size of the buffer.  Upon
  *        return, <tt>dstSizes[i]</tt> will contain the size of the JPEG image
  *        (in bytes.)
- * @param transforms pointer to an array of n tjtransform structures, each of
+ * @param transforms pointer to an array of n #tjtransform structures, each of
  *        which specifies the transform parameters and/or cropping region for
  *        the corresponding transformed output image.
  * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP