TJ doc: Density params require YCbCr or grayscale

Since libjpeg-turbo does not support Exif, the only way it can embed
density information in a JPEG image is by using the JFIF marker, which
is only written if the JPEG colorspace is YCbCr or grayscale.
(Referring to the conversation under #793, we may need to further
restrict that to 8-bit-per-sample JPEG images, because the JFIF spec
requires 8-bit data precision.)

doc/turbojpeg/group___turbo_j_p_e_g.html

@@ -1003,6 +1003,7 @@ scalingFactor)</code>. </p>
 <li>The JPEG image has (decompression) or will have (compression) the specified horizontal pixel density <em>[default for compression: <code>1</code>]</em>.</li>
 </ul>
 <p>This value is stored in or read from the JPEG header. It does not affect the contents of the JPEG image. Note that this parameter is set by <a class="el" href="group___turbo_j_p_e_g.html#ga884023536e70985616126a073f662001" title="Load a packed-pixel image with 2 to 8 bits of data precision per sample from disk into memory.">tj3LoadImage8()</a> when loading a Windows BMP file that contains pixel density information, and the value of this parameter is stored to a Windows BMP file by <a class="el" href="group___turbo_j_p_e_g.html#gaa4ec838988e469cc15618e4690cc8722" title="Save a packed-pixel image with 2 to 8 bits of data precision per sample from memory to disk.">tj3SaveImage8()</a> if the value of <a class="el" href="group___turbo_j_p_e_g.html#ggaa0f6be63ba78278299c9f5c12031fe82a4c045981bd8a303521a401dbbe1df208" title="JPEG pixel density units.">TJPARAM_DENSITYUNITS</a> is <code>2</code>.</p>
+<p>This parameter has no effect unless the JPEG colorspace (see <a class="el" href="group___turbo_j_p_e_g.html#ggaa0f6be63ba78278299c9f5c12031fe82a46a10d46309514907d0c39fcd86c324c" title="JPEG colorspace.">TJPARAM_COLORSPACE</a>) is <a class="el" href="group___turbo_j_p_e_g.html#gga4f83ad3368e0e29d1957be0efa7c3720a7389b8f65bb387ffedce3efd0d78ec75" title="YCbCr colorspace.">TJCS_YCbCr</a> or <a class="el" href="group___turbo_j_p_e_g.html#gga4f83ad3368e0e29d1957be0efa7c3720ab3e7d6a87f695e45b81c1b5262b5a50a" title="Grayscale colorspace.">TJCS_GRAY</a>.</p>
 <dl class="section see"><dt>See also</dt><dd><a class="el" href="group___turbo_j_p_e_g.html#ggaa0f6be63ba78278299c9f5c12031fe82a4c045981bd8a303521a401dbbe1df208" title="JPEG pixel density units.">TJPARAM_DENSITYUNITS</a> </dd></dl>
 </td></tr>
 <tr><td class="fieldname"><a id="ggaa0f6be63ba78278299c9f5c12031fe82abda48f2df7eb9b88e2b7621efb017eba" name="ggaa0f6be63ba78278299c9f5c12031fe82abda48f2df7eb9b88e2b7621efb017eba"></a>TJPARAM_YDENSITY&#160;</td><td class="fielddoc"><p>JPEG vertical pixel density. </p>
@@ -1010,6 +1011,7 @@ scalingFactor)</code>. </p>
 <li>The JPEG image has (decompression) or will have (compression) the specified vertical pixel density <em>[default for compression: <code>1</code>]</em>.</li>
 </ul>
 <p>This value is stored in or read from the JPEG header. It does not affect the contents of the JPEG image. Note that this parameter is set by <a class="el" href="group___turbo_j_p_e_g.html#ga884023536e70985616126a073f662001" title="Load a packed-pixel image with 2 to 8 bits of data precision per sample from disk into memory.">tj3LoadImage8()</a> when loading a Windows BMP file that contains pixel density information, and the value of this parameter is stored to a Windows BMP file by <a class="el" href="group___turbo_j_p_e_g.html#gaa4ec838988e469cc15618e4690cc8722" title="Save a packed-pixel image with 2 to 8 bits of data precision per sample from memory to disk.">tj3SaveImage8()</a> if the value of <a class="el" href="group___turbo_j_p_e_g.html#ggaa0f6be63ba78278299c9f5c12031fe82a4c045981bd8a303521a401dbbe1df208" title="JPEG pixel density units.">TJPARAM_DENSITYUNITS</a> is <code>2</code>.</p>
+<p>This parameter has no effect unless the JPEG colorspace (see <a class="el" href="group___turbo_j_p_e_g.html#ggaa0f6be63ba78278299c9f5c12031fe82a46a10d46309514907d0c39fcd86c324c" title="JPEG colorspace.">TJPARAM_COLORSPACE</a>) is <a class="el" href="group___turbo_j_p_e_g.html#gga4f83ad3368e0e29d1957be0efa7c3720a7389b8f65bb387ffedce3efd0d78ec75" title="YCbCr colorspace.">TJCS_YCbCr</a> or <a class="el" href="group___turbo_j_p_e_g.html#gga4f83ad3368e0e29d1957be0efa7c3720ab3e7d6a87f695e45b81c1b5262b5a50a" title="Grayscale colorspace.">TJCS_GRAY</a>.</p>
 <dl class="section see"><dt>See also</dt><dd><a class="el" href="group___turbo_j_p_e_g.html#ggaa0f6be63ba78278299c9f5c12031fe82a4c045981bd8a303521a401dbbe1df208" title="JPEG pixel density units.">TJPARAM_DENSITYUNITS</a> </dd></dl>
 </td></tr>
 <tr><td class="fieldname"><a id="ggaa0f6be63ba78278299c9f5c12031fe82a4c045981bd8a303521a401dbbe1df208" name="ggaa0f6be63ba78278299c9f5c12031fe82a4c045981bd8a303521a401dbbe1df208"></a>TJPARAM_DENSITYUNITS&#160;</td><td class="fielddoc"><p>JPEG pixel density units. </p>
@@ -1019,6 +1021,7 @@ scalingFactor)</code>. </p>
 <li><code>2</code> The pixel density of the JPEG image is expressed (decompression) or will be expressed (compression) in units of pixels/cm.</li>
 </ul>
 <p>This value is stored in or read from the JPEG header. It does not affect the contents of the JPEG image. Note that this parameter is set by <a class="el" href="group___turbo_j_p_e_g.html#ga884023536e70985616126a073f662001" title="Load a packed-pixel image with 2 to 8 bits of data precision per sample from disk into memory.">tj3LoadImage8()</a> when loading a Windows BMP file that contains pixel density information, and the value of this parameter is stored to a Windows BMP file by <a class="el" href="group___turbo_j_p_e_g.html#gaa4ec838988e469cc15618e4690cc8722" title="Save a packed-pixel image with 2 to 8 bits of data precision per sample from memory to disk.">tj3SaveImage8()</a> if the value is <code>2</code>.</p>
+<p>This parameter has no effect unless the JPEG colorspace (see <a class="el" href="group___turbo_j_p_e_g.html#ggaa0f6be63ba78278299c9f5c12031fe82a46a10d46309514907d0c39fcd86c324c" title="JPEG colorspace.">TJPARAM_COLORSPACE</a>) is <a class="el" href="group___turbo_j_p_e_g.html#gga4f83ad3368e0e29d1957be0efa7c3720a7389b8f65bb387ffedce3efd0d78ec75" title="YCbCr colorspace.">TJCS_YCbCr</a> or <a class="el" href="group___turbo_j_p_e_g.html#gga4f83ad3368e0e29d1957be0efa7c3720ab3e7d6a87f695e45b81c1b5262b5a50a" title="Grayscale colorspace.">TJCS_GRAY</a>.</p>
 <dl class="section see"><dt>See also</dt><dd><a class="el" href="group___turbo_j_p_e_g.html#ggaa0f6be63ba78278299c9f5c12031fe82a4de5c9d7cab5be806143a43c3b0e0877" title="JPEG horizontal pixel density.">TJPARAM_XDENSITY</a>, <a class="el" href="group___turbo_j_p_e_g.html#ggaa0f6be63ba78278299c9f5c12031fe82abda48f2df7eb9b88e2b7621efb017eba" title="JPEG vertical pixel density.">TJPARAM_YDENSITY</a> </dd></dl>
 </td></tr>
 <tr><td class="fieldname"><a id="ggaa0f6be63ba78278299c9f5c12031fe82a0de0a8281da45d1fc984edc8918f7dd2" name="ggaa0f6be63ba78278299c9f5c12031fe82a0de0a8281da45d1fc984edc8918f7dd2"></a>TJPARAM_MAXMEMORY&#160;</td><td class="fielddoc"><p>Memory limit for intermediate buffers. </p>

java/doc/org/libjpegturbo/turbojpeg/TJ.html

@@ -1865,7 +1865,10 @@ extends java.lang.Object</pre>
  loading a Windows BMP file that contains pixel density information, and
  the value of this parameter is stored to a Windows BMP file by
  <a href="TJDecompressor.html#saveImage(java.lang.String,java.lang.Object,int,int,int,int,int,int)"><code>TJDecompressor.saveImage()</code></a> if the value
- of <a href="#PARAM_DENSITYUNITS"><code>PARAM_DENSITYUNITS</code></a> is <code>2</code>.</div>
+ of <a href="#PARAM_DENSITYUNITS"><code>PARAM_DENSITYUNITS</code></a> is <code>2</code>.
+
+ <p>This parameter has no effect unless the JPEG colorspace (see
+ <a href="#PARAM_COLORSPACE"><code>PARAM_COLORSPACE</code></a>) is <a href="#CS_YCbCr"><code>CS_YCbCr</code></a> or <a href="#CS_GRAY"><code>CS_GRAY</code></a>.</div>
 <dl>
 <dt><span class="seeLabel">See Also:</span></dt>
 <dd><a href="#PARAM_DENSITYUNITS"><code>PARAM_DENSITYUNITS</code></a>, 
@@ -1895,7 +1898,10 @@ extends java.lang.Object</pre>
  loading a Windows BMP file that contains pixel density information, and
  the value of this parameter is stored to a Windows BMP file by
  <a href="TJDecompressor.html#saveImage(java.lang.String,java.lang.Object,int,int,int,int,int,int)"><code>TJDecompressor.saveImage()</code></a> if the value
- of <a href="#PARAM_DENSITYUNITS"><code>PARAM_DENSITYUNITS</code></a> is <code>2</code>.</div>
+ of <a href="#PARAM_DENSITYUNITS"><code>PARAM_DENSITYUNITS</code></a> is <code>2</code>.
+
+ <p>This parameter has no effect unless the JPEG colorspace (see
+ <a href="#PARAM_COLORSPACE"><code>PARAM_COLORSPACE</code></a>) is <a href="#CS_YCbCr"><code>CS_YCbCr</code></a> or <a href="#CS_GRAY"><code>CS_GRAY</code></a>.</div>
 <dl>
 <dt><span class="seeLabel">See Also:</span></dt>
 <dd><a href="#PARAM_DENSITYUNITS"><code>PARAM_DENSITYUNITS</code></a>, 
@@ -1930,7 +1936,10 @@ extends java.lang.Object</pre>
  loading a Windows BMP file that contains pixel density information, and
  the value of this parameter is stored to a Windows BMP file by
  <a href="TJDecompressor.html#saveImage(java.lang.String,java.lang.Object,int,int,int,int,int,int)"><code>TJDecompressor.saveImage()</code></a> if the value
- is <code>2</code>.</div>
+ is <code>2</code>.
+
+ <p>This parameter has no effect unless the JPEG colorspace (see
+ <a href="#PARAM_COLORSPACE"><code>PARAM_COLORSPACE</code></a>) is <a href="#CS_YCbCr"><code>CS_YCbCr</code></a> or <a href="#CS_GRAY"><code>CS_GRAY</code></a>.</div>
 <dl>
 <dt><span class="seeLabel">See Also:</span></dt>
 <dd><a href="#PARAM_XDENSITY"><code>PARAM_XDENSITY</code></a>, 

java/org/libjpegturbo/turbojpeg/TJ.java

@@ -873,6 +873,9 @@ public final class TJ {
    * {@link TJDecompressor#saveImage TJDecompressor.saveImage()} if the value
    * of {@link #PARAM_DENSITYUNITS} is <code>2</code>.
    *
+   * <p>This parameter has no effect unless the JPEG colorspace (see
+   * {@link #PARAM_COLORSPACE}) is {@link #CS_YCbCr} or {@link #CS_GRAY}.
+   *
    * @see #PARAM_DENSITYUNITS
    */
   public static final int PARAM_XDENSITY = 20;
@@ -894,6 +897,9 @@ public final class TJ {
    * {@link TJDecompressor#saveImage TJDecompressor.saveImage()} if the value
    * of {@link #PARAM_DENSITYUNITS} is <code>2</code>.
    *
+   * <p>This parameter has no effect unless the JPEG colorspace (see
+   * {@link #PARAM_COLORSPACE}) is {@link #CS_YCbCr} or {@link #CS_GRAY}.
+   *
    * @see #PARAM_DENSITYUNITS
    */
   public static final int PARAM_YDENSITY = 21;
@@ -920,6 +926,9 @@ public final class TJ {
    * {@link TJDecompressor#saveImage TJDecompressor.saveImage()} if the value
    * is <code>2</code>.
    *
+   * <p>This parameter has no effect unless the JPEG colorspace (see
+   * {@link #PARAM_COLORSPACE}) is {@link #CS_YCbCr} or {@link #CS_GRAY}.
+   *
    * @see #PARAM_XDENSITY
    * @see #PARAM_YDENSITY
    */

src/turbojpeg.h

@@ -848,6 +848,9 @@ enum TJPARAM {
    * Windows BMP file by #tj3SaveImage8() if the value of #TJPARAM_DENSITYUNITS
    * is `2`.
    *
+   * This parameter has no effect unless the JPEG colorspace (see
+   * #TJPARAM_COLORSPACE) is #TJCS_YCbCr or #TJCS_GRAY.
+   *
    * @see TJPARAM_DENSITYUNITS
    */
   TJPARAM_XDENSITY,
@@ -865,6 +868,9 @@ enum TJPARAM {
    * Windows BMP file by #tj3SaveImage8() if the value of #TJPARAM_DENSITYUNITS
    * is `2`.
    *
+   * This parameter has no effect unless the JPEG colorspace (see
+   * #TJPARAM_COLORSPACE) is #TJCS_YCbCr or #TJCS_GRAY.
+   *
    * @see TJPARAM_DENSITYUNITS
    */
   TJPARAM_YDENSITY,
@@ -886,6 +892,9 @@ enum TJPARAM {
    * density information, and the value of this parameter is stored to a
    * Windows BMP file by #tj3SaveImage8() if the value is `2`.
    *
+   * This parameter has no effect unless the JPEG colorspace (see
+   * #TJPARAM_COLORSPACE) is #TJCS_YCbCr or #TJCS_GRAY.
+   *
    * @see TJPARAM_XDENSITY, TJPARAM_YDENSITY
    */
   TJPARAM_DENSITYUNITS,