Wordsmithing

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

java/org/libjpegturbo/turbojpeg/TJ.java

@@ -192,18 +192,19 @@ public final class TJ {
    */
   public static final int PF_ARGB = 10;
   /**
-   * CMYK pixel format.  Unlike RGB, which is a display colorspace,
-   * CMYK (Cyan/Magenta/Yellow/Key) is a print colorspace in which the
-   * value of each color component corresponds to the amount of cyan, magenta,
-   * yellow, or black ink that is applied to a white background.  In order to
-   * convert between CMYK and RGB, it is necessary to use a color management
-   * system (CMS.)  A CMS will attempt to map colors within the printer's gamut
-   * to perceptually similar colors in the display's gamut and vice versa, but
-   * the mapping is typically not 1:1 or reversible, nor can it be defined with
-   * a simple formula.  Thus, such a conversion is out of scope for a codec
-   * library.  However, the TurboJPEG API allows for compressing CMYK pixels
-   * into a YCCK JPEG image (see {@link #CS_YCCK}) and decompressing YCCK JPEG
-   * images into CMYK pixels.
+   * CMYK pixel format.  Unlike RGB, which is an additive color model used
+   * primarily for display, CMYK (Cyan/Magenta/Yellow/Key) is a subtractive
+   * color model used primarily for printing.  In the CMYK color model, the
+   * value of each color component typically corresponds to an amount of cyan,
+   * magenta, yellow, or black ink that is applied to a white background.  In
+   * order to convert between CMYK and RGB, it is necessary to use a color
+   * management system (CMS.)  A CMS will attempt to map colors within the
+   * printer's gamut to perceptually similar colors in the display's gamut and
+   * vice versa, but the mapping is typically not 1:1 or reversible, nor can it
+   * be defined with a simple formula.  Thus, such a conversion is out of scope
+   * for a codec library.  However, the TurboJPEG API allows for compressing
+   * CMYK pixels into a YCCK JPEG image (see {@link #CS_YCCK}) and
+   * decompressing YCCK JPEG images into CMYK pixels.
    */
   public static final int PF_CMYK = 11;
 

java/org/libjpegturbo/turbojpeg/TJCompressor.java

@@ -155,7 +155,13 @@ public class TJCompressor {
 
   /**
    * Set the level of chrominance subsampling for subsequent compress/encode
-   * operations.
+   * operations.  When pixels are converted from RGB to YCbCr (see
+   * {@link TJ#CS_YCbCr}) or from CMYK to YCCK (see {@link TJ#CS_YCCK}) 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 to small changes in color.)
+   * This is called "chrominance subsampling".
    *
    * @param newSubsamp the new level of chrominance subsampling (one of
    * {@link TJ TJ.SAMP_*})
@@ -351,14 +357,18 @@ public class TJCompressor {
    * instance and output a YUV planar image to the given destination buffer.
    * This method uses the accelerated color conversion routines in TurboJPEG's
    * underlying codec but does not execute any of the other steps in the JPEG
-   * compression process.  The Y, U, and V image planes are stored sequentially
-   * into the destination buffer, and the size of each plane is determined by
-   * the width and height of the source image, as well as the specified padding
-   * and level of chrominance subsampling.  If the chrominance components are
-   * subsampled along the horizontal dimension, then the width of the luminance
-   * plane is padded to the nearest multiple of 2 in the output image (same
-   * goes for the height of the luminance plane, if the chrominance components
-   * are subsampled along the vertical dimension.)
+   * compression process.  The Y, U (Cb), and V (Cr) image planes are stored
+   * sequentially into the destination buffer, and the size of each plane is
+   * determined by the width and height of the source image, as well as the
+   * specified padding and level of chrominance subsampling.  If the
+   * chrominance components are subsampled along the horizontal dimension, then
+   * the width of the luminance plane is padded to the nearest multiple of 2 in
+   * the output image (same goes for the height of the luminance plane, if the
+   * chrominance components are subsampled along the vertical dimension.)
+   * <p>
+   * NOTE: Technically, the JPEG format uses the YCbCr colorspace, but per the
+   * convention of the digital video community, the TurboJPEG API uses "YUV" to
+   * refer to an image format consisting of Y, Cb, and Cr image planes.
    *
    * @param dstBuf buffer that will receive the YUV planar image.  Use
    * {@link TJ#bufSizeYUV} to determine the appropriate size for this buffer

java/org/libjpegturbo/turbojpeg/TJDecompressor.java

@@ -369,6 +369,10 @@ public class TJDecompressor {
    * that, if the width or height of the image is not an even multiple of the
    * MCU block size (see {@link TJ#getMCUWidth} and {@link TJ#getMCUHeight}),
    * then an intermediate buffer copy will be performed within TurboJPEG.
+   * <p>
+   * NOTE: Technically, the JPEG format uses the YCbCr colorspace, but per the
+   * convention of the digital video community, the TurboJPEG API uses "YUV" to
+   * refer to an image format consisting of Y, Cb, and Cr image planes.
    *
    * @param dstBuf buffer that will receive the YUV planar image.  Use
    * {@link TJ#bufSizeYUV} to determine the appropriate size for this buffer