TurboJPEG: Numerous documentation improvements

- Wordsmithing, formatting, and grammar tweaks

- Various clarifications and corrections, including specifying whether
  a particular buffer or image is used as a source or destination

- Accommodate/mention features that were introduced since the API
  documentation was created.

- For clarity, use "packed-pixel" to describe uncompressed
  source/destination images that are not planar YUV.

- Use "row" rather than "line" to refer to a single horizontal group of
  pixels or component values, for consistency with the libjpeg API
  documentation.  (libjpeg also uses "scanline", which is a more archaic
  term.)

- Use "alignment" rather than "padding" to refer to the number of bytes
  by which a row's width is evenly divisible.  This consistifies the
  documention of the YUV functions and tjLoadImage().  ("Padding"
  typically refers to the number of bytes added to each row, which is
  not the same thing.)

- Remove all references to "the underlying codec."  Although the
  TurboJPEG API originated as a cross-platform wrapper for the Intel
  Integrated Performance Primitives, Sun mediaLib, QuickTime, and
  libjpeg, none of those TurboJPEG implementations has been maintained
  since 2009.  Nothing would prevent someone from implementing the
  TurboJPEG API without libjpeg-turbo, but such an implementation would
  not necessarily have an "underlying codec."  (It could be fully
  self-contained.)

- Use "destination image" rather than "output image", for consistency,
  or describe the type of image that will be output.

- Avoid the term "image buffer" and instead use "byte buffer" to
  refer to buffers that will hold JPEG images, or describe the type of
  image that will be contained in the buffer.  (The Java documentation
  doesn't use "byte buffer", because the buffer arrays literally have
  "byte" in front of them, and since Java doesn't have pointers, it is
  not possible for mere mortals to store any other type of data in those
  arrays.)

- C: Use "unified" to describe YUV images stored in a single buffer, for
  consistency with the Java documentation.

- Use "planar YUV" rather than "YUV planar".  Is is our convention to
  describe images using {component layout} {colorspace/pixel format}
  {image function}, e.g. "packed-pixel RGB source image" or "planar YUV
  destination image."

- C: Document the TurboJPEG API version in which a particular function
  or macro was introduced, and reorder the backward compatibility
  function stubs in turbojpeg.h alphabetically by API version.

- C: Use Markdown rather than HTML tags, where possible, in the Doxygen
  comments.

ChangeLog.md

@@ -29,9 +29,9 @@ jpegtran `-drop` and `-trim` options to losslessly transform a
 specially-crafted malformed JPEG image.
 
 5. Fixed an issue in `tjBufSizeYUV2()` whereby it returned a bogus result,
-rather than throwing an error, if the `pad` parameter was not a power of 2.
+rather than throwing an error, if the `align` parameter was not a power of 2.
 Fixed a similar issue in `tjCompressFromYUV()` whereby it generated a corrupt
-JPEG image in certain cases, rather than throwing an error, if the `pad`
+JPEG image in certain cases, rather than throwing an error, if the `align`
 parameter was not a power of 2.
 
 

doc/html/structtjtransform.html

@@ -84,7 +84,7 @@
 <tr class="memdesc:a2525aab4ba6978a1c273f74fef50e498"><td class="mdescLeft">&#160;</td><td class="mdescRight">One of the <a class="el" href="group___turbo_j_p_e_g.html#ga2de531af4e7e6c4f124908376b354866">transform operations</a>.  <a href="structtjtransform.html#a2525aab4ba6978a1c273f74fef50e498">More...</a><br /></td></tr>
 <tr class="separator:a2525aab4ba6978a1c273f74fef50e498"><td class="memSeparator" colspan="2">&#160;</td></tr>
 <tr class="memitem:ac0e74655baa4402209a21e1ae481c8f6"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structtjtransform.html#ac0e74655baa4402209a21e1ae481c8f6">options</a></td></tr>
-<tr class="memdesc:ac0e74655baa4402209a21e1ae481c8f6"><td class="mdescLeft">&#160;</td><td class="mdescRight">The bitwise OR of one of more of the <a class="el" href="group___turbo_j_p_e_g.html#ga9c771a757fc1294add611906b89ab2d2">transform options</a>.  <a href="structtjtransform.html#ac0e74655baa4402209a21e1ae481c8f6">More...</a><br /></td></tr>
+<tr class="memdesc:ac0e74655baa4402209a21e1ae481c8f6"><td class="mdescLeft">&#160;</td><td class="mdescRight">The bitwise OR of one of more of the <a class="el" href="group___turbo_j_p_e_g.html#ga153b468cfb905d0de61706c838986fe8">transform options</a>.  <a href="structtjtransform.html#ac0e74655baa4402209a21e1ae481c8f6">More...</a><br /></td></tr>
 <tr class="separator:ac0e74655baa4402209a21e1ae481c8f6"><td class="memSeparator" colspan="2">&#160;</td></tr>
 <tr class="memitem:a688fe8f1a8ecc12a538d9e561cf338e3"><td class="memItemLeft" align="right" valign="top">void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structtjtransform.html#a688fe8f1a8ecc12a538d9e561cf338e3">data</a></td></tr>
 <tr class="memdesc:a688fe8f1a8ecc12a538d9e561cf338e3"><td class="mdescLeft">&#160;</td><td class="mdescRight">Arbitrary data that can be accessed within the body of the callback function.  <a href="structtjtransform.html#a688fe8f1a8ecc12a538d9e561cf338e3">More...</a><br /></td></tr>
@@ -115,7 +115,7 @@ <h2 class="memtitle"><span class="permalink"><a href="#afd7fc262df33f741e120ef41
     <tr><td class="paramname">coeffs</td><td>pointer to an array of transformed DCT coefficients. (NOTE: this pointer is not guaranteed to be valid once the callback returns, so applications wishing to hand off the DCT coefficients to another function or library should make a copy of them within the body of the callback.)</td></tr>
     <tr><td class="paramname">arrayRegion</td><td><a class="el" href="structtjregion.html" title="Cropping region.">tjregion</a> structure containing the width and height of the array pointed to by <code>coeffs</code> as well as its offset relative to the component plane. TurboJPEG implementations may choose to split each component plane into multiple DCT coefficient arrays and call the callback function once for each array.</td></tr>
     <tr><td class="paramname">planeRegion</td><td><a class="el" href="structtjregion.html" title="Cropping region.">tjregion</a> structure containing the width and height of the component plane to which <code>coeffs</code> belongs</td></tr>
-    <tr><td class="paramname">componentID</td><td>ID number of the component plane to which <code>coeffs</code> belongs (Y, Cb, and Cr have, respectively, ID's of 0, 1, and 2 in typical JPEG images.)</td></tr>
+    <tr><td class="paramname">componentID</td><td>ID number of the component plane to which <code>coeffs</code> belongs. (Y, Cb, and Cr have, respectively, ID's of 0, 1, and 2 in typical JPEG images.)</td></tr>
     <tr><td class="paramname">transformID</td><td>ID number of the transformed image to which <code>coeffs</code> belongs. This is the same as the index of the transform in the <code>transforms</code> array that was passed to <a class="el" href="group___turbo_j_p_e_g.html#ga9cb8abf4cc91881e04a0329b2270be25" title="Losslessly transform a JPEG image into another JPEG image.">tjTransform()</a>.</td></tr>
     <tr><td class="paramname">transform</td><td>a pointer to a <a class="el" href="structtjtransform.html" title="Lossless transform.">tjtransform</a> structure that specifies the parameters and/or cropping region for this transform</td></tr>
   </table>
@@ -169,7 +169,7 @@ <h2 class="memtitle"><span class="permalink"><a href="#ac0e74655baa4402209a21e1a
       </table>
 </div><div class="memdoc">
 
-<p>The bitwise OR of one of more of the <a class="el" href="group___turbo_j_p_e_g.html#ga9c771a757fc1294add611906b89ab2d2">transform options</a>. </p>
+<p>The bitwise OR of one of more of the <a class="el" href="group___turbo_j_p_e_g.html#ga153b468cfb905d0de61706c838986fe8">transform options</a>. </p>
 
 </div>
 </div>

java/TJBench.java

@@ -1,6 +1,6 @@
 /*
- * Copyright (C)2009-2014, 2016-2019, 2021 D. R. Commander.
- *                                         All Rights Reserved.
+ * Copyright (C)2009-2014, 2016-2019, 2021, 2023 D. R. Commander.
+ *                                               All Rights Reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are met:
@@ -37,7 +37,7 @@ final class TJBench {
 
   private TJBench() {}
 
-  private static int flags = 0, quiet = 0, pf = TJ.PF_BGR, yuvPad = 1;
+  private static int flags = 0, quiet = 0, pf = TJ.PF_BGR, yuvAlign = 1;
   private static boolean compOnly, decompOnly, doTile, doYUV, write = true;
 
   static final String[] PIXFORMATSTR = {
@@ -192,7 +192,7 @@ static void decomp(byte[] srcBuf, byte[][] jpegBuf, int[] jpegSize,
       int width = doTile ? tilew : scaledw;
       int height = doTile ? tileh : scaledh;
 
-      yuvImage = new YUVImage(width, yuvPad, height, subsamp);
+      yuvImage = new YUVImage(width, yuvAlign, height, subsamp);
       Arrays.fill(yuvImage.getBuf(), (byte)127);
     }
 
@@ -212,7 +212,8 @@ static void decomp(byte[] srcBuf, byte[][] jpegBuf, int[] jpegSize,
             tjd.setSourceImage(jpegBuf[tile], jpegSize[tile]);
           } catch (TJException e) { handleTJException(e); }
           if (doYUV) {
-            yuvImage.setBuf(yuvImage.getBuf(), width, yuvPad, height, subsamp);
+            yuvImage.setBuf(yuvImage.getBuf(), width, yuvAlign, height,
+                            subsamp);
             try {
               tjd.decompressToYUV(yuvImage, flags);
             } catch (TJException e) { handleTJException(e); }
@@ -372,7 +373,7 @@ static void fullTest(byte[] srcBuf, int w, int h, int subsamp, int jpegQual,
       tjc.setSubsamp(subsamp);
 
       if (doYUV) {
-        yuvImage = new YUVImage(tilew, yuvPad, tileh, subsamp);
+        yuvImage = new YUVImage(tilew, yuvAlign, tileh, subsamp);
         Arrays.fill(yuvImage.getBuf(), (byte)127);
       }
 
@@ -393,7 +394,7 @@ static void fullTest(byte[] srcBuf, int w, int h, int subsamp, int jpegQual,
             if (doYUV) {
               double startEncode = getTime();
 
-              yuvImage.setBuf(yuvImage.getBuf(), width, yuvPad, height,
+              yuvImage.setBuf(yuvImage.getBuf(), width, yuvAlign, height,
                               subsamp);
               tjc.encodeYUV(yuvImage, flags);
               if (iter >= 0)
@@ -720,8 +721,8 @@ static void usage() throws Exception {
     System.out.println("-quiet = Output results in tabular rather than verbose format");
     System.out.println("-yuv = Test YUV encoding/decoding functions");
     System.out.println("-yuvpad <p> = If testing YUV encoding/decoding, this specifies the number of");
-    System.out.println("     bytes to which each row of each plane in the intermediate YUV image is");
-    System.out.println("     padded (default = 1)");
+    System.out.println("     bytes by which each row of each plane in the intermediate YUV image is");
+    System.out.println("     evenly divisible (default = 1)");
     System.out.println("-scale M/N = Scale down the width/height of the decompressed JPEG image by a");
     System.out.print("     factor of M/N (M/N = ");
     for (i = 0; i < nsf; i++) {
@@ -902,7 +903,7 @@ else if (argv[i].equalsIgnoreCase("-benchtime") &&
             } else
               usage();
           } else if (argv[i].equalsIgnoreCase("-yuv")) {
-            System.out.println("Testing YUV planar encoding/decoding\n");
+            System.out.println("Testing planar YUV encoding/decoding\n");
             doYUV = true;
           } else if (argv[i].equalsIgnoreCase("-yuvpad") &&
                      i < argv.length - 1) {
@@ -912,7 +913,7 @@ else if (argv[i].equalsIgnoreCase("-benchtime") &&
               temp = Integer.parseInt(argv[++i]);
             } catch (NumberFormatException e) {}
             if (temp >= 1)
-              yuvPad = temp;
+              yuvAlign = temp;
           } else if (argv[i].equalsIgnoreCase("-subsamp") &&
                      i < argv.length - 1) {
             i++;