Wordsmithing

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

3 files changed, 36 insertions, 21 deletions

diff --git a/java/doc/org/libjpegturbo/turbojpeg/TJ.html b/java/doc/org/libjpegturbo/turbojpeg/TJ.html
index b832cf8..3a94cba 100644
--- a/java/doc/org/libjpegturbo/turbojpeg/TJ.html
+++ b/java/doc/org/libjpegturbo/turbojpeg/TJ.html
@@ -807,18 +807,19 @@ PF_CMYK</H3>
 <PRE>
 public static final int <B>PF_CMYK</B></PRE>
 <DL>
-<DD>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 <A HREF="../../../org/libjpegturbo/turbojpeg/TJ.html#CS_YCCK"><CODE>CS_YCCK</CODE></A>) and decompressing YCCK JPEG
- images into CMYK pixels.
+<DD>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 <A HREF="../../../org/libjpegturbo/turbojpeg/TJ.html#CS_YCCK"><CODE>CS_YCCK</CODE></A>) and
+ decompressing YCCK JPEG images into CMYK pixels.
 <P>
 <DL>
 <DT><B>See Also:</B><DD><A HREF="../../../constant-values.html#org.libjpegturbo.turbojpeg.TJ.PF_CMYK">Constant Field Values</A></DL>
diff --git a/java/doc/org/libjpegturbo/turbojpeg/TJCompressor.html b/java/doc/org/libjpegturbo/turbojpeg/TJCompressor.html
index 30d5ff3..a41ea06 100644
--- a/java/doc/org/libjpegturbo/turbojpeg/TJCompressor.html
+++ b/java/doc/org/libjpegturbo/turbojpeg/TJCompressor.html
@@ -469,7 +469,13 @@ public void <B>setSubsamp</B>(int&nbsp;newSubsamp)
                 throws java.lang.Exception</PRE>
 <DL>
 <DD>Set the level of chrominance subsampling for subsequent compress/encode
- operations.
+ operations.  When pixels are converted from RGB to YCbCr (see
+ <A HREF="../../../org/libjpegturbo/turbojpeg/TJ.html#CS_YCbCr"><CODE>TJ.CS_YCbCr</CODE></A>) or from CMYK to YCCK (see <A HREF="../../../org/libjpegturbo/turbojpeg/TJ.html#CS_YCCK"><CODE>TJ.CS_YCCK</CODE></A>) 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".
 <P>
 <DD><DL>
 <DT><B>Parameters:</B><DD><CODE>newSubsamp</CODE> - the new level of chrominance subsampling (one of
@@ -609,14 +615,18 @@ public void <B>encodeYUV</B>(byte[]&nbsp;dstBuf,
  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.
 <P>
 <DD><DL>
 <DT><B>Parameters:</B><DD><CODE>dstBuf</CODE> - buffer that will receive the YUV planar image.  Use
diff --git a/java/doc/org/libjpegturbo/turbojpeg/TJDecompressor.html b/java/doc/org/libjpegturbo/turbojpeg/TJDecompressor.html
index 12a5e83..a3d3db5 100644
--- a/java/doc/org/libjpegturbo/turbojpeg/TJDecompressor.html
+++ b/java/doc/org/libjpegturbo/turbojpeg/TJDecompressor.html
@@ -887,6 +887,10 @@ public void <B>decompressToYUV</B>(byte[]&nbsp;dstBuf,
  that, if the width or height of the image is not an even multiple of the
  MCU block size (see <A HREF="../../../org/libjpegturbo/turbojpeg/TJ.html#getMCUWidth(int)"><CODE>TJ.getMCUWidth(int)</CODE></A> and <A HREF="../../../org/libjpegturbo/turbojpeg/TJ.html#getMCUHeight(int)"><CODE>TJ.getMCUHeight(int)</CODE></A>),
  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.
 <P>
 <DD><DL>
 <DT><B>Parameters:</B><DD><CODE>dstBuf</CODE> - buffer that will receive the YUV planar image.  Use