From 89a1620c423ad405faeee5438d5919b9d9e03c1b Mon Sep 17 00:00:00 2001
From: Martijn van Beurden <mvanb1@gmail.com>
Date: Sat, 17 Sep 2022 13:09:00 +0200
Subject: Update API and tool docs

---
 include/FLAC/format.h         |  3 +--
 include/FLAC/stream_encoder.h | 39 +++++++++++++++++++++++++++------------
 src/flac/main.c               | 12 ++++++------
 3 files changed, 34 insertions(+), 20 deletions(-)

diff --git a/include/FLAC/format.h b/include/FLAC/format.h
index 7835f839..99d637f0 100644
--- a/include/FLAC/format.h
+++ b/include/FLAC/format.h
@@ -120,8 +120,7 @@ extern "C" {
 #define FLAC__REFERENCE_CODEC_MAX_BITS_PER_SAMPLE (32u)
 
 /** The maximum sample rate permitted by the format.  The value is
- *  ((2 ^ 16) - 1) * 10; see <A HREF="../format.html">FLAC format</A>
- *  as to why.
+ *  ((2 ^ 20) - 1)
  */
 #define FLAC__MAX_SAMPLE_RATE (1048575u)
 
diff --git a/include/FLAC/stream_encoder.h b/include/FLAC/stream_encoder.h
index a39d0ed2..1d7bd258 100644
--- a/include/FLAC/stream_encoder.h
+++ b/include/FLAC/stream_encoder.h
@@ -311,8 +311,7 @@ typedef enum {
 
 	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BITS_PER_SAMPLE,
 	/**< The encoder has an invalid setting for bits-per-sample.
-	 * FLAC supports 4-32 bps but the reference encoder currently supports
-	 * only up to 24 bps.
+	 * FLAC supports 4-32 bps.
 	 */
 
 	FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_SAMPLE_RATE,
@@ -843,15 +842,15 @@ FLAC_API FLAC__bool FLAC__stream_encoder_set_sample_rate(FLAC__StreamEncoder *en
  *  <td>max residual partition order</td>
  *  <td>rice parameter search dist</td>
  * </tr>
- * <tr>  <td><b>0</b></td> <td>false</td> <td>false</td> <td>tukey(0.5)<td>                                     <td>0</td>  <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>3</td> <td>0</td> </tr>
- * <tr>  <td><b>1</b></td> <td>true</td>  <td>true</td>  <td>tukey(0.5)<td>                                     <td>0</td>  <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>3</td> <td>0</td> </tr>
- * <tr>  <td><b>2</b></td> <td>true</td>  <td>false</td> <td>tukey(0.5)<td>                                     <td>0</td>  <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>3</td> <td>0</td> </tr>
- * <tr>  <td><b>3</b></td> <td>false</td> <td>false</td> <td>tukey(0.5)<td>                                     <td>6</td>  <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>4</td> <td>0</td> </tr>
- * <tr>  <td><b>4</b></td> <td>true</td>  <td>true</td>  <td>tukey(0.5)<td>                                     <td>8</td>  <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>4</td> <td>0</td> </tr>
- * <tr>  <td><b>5</b></td> <td>true</td>  <td>false</td> <td>tukey(0.5)<td>                                     <td>8</td>  <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>5</td> <td>0</td> </tr>
- * <tr>  <td><b>6</b></td> <td>true</td>  <td>false</td> <td>tukey(0.5);partial_tukey(2)<td>                    <td>8</td>  <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>6</td> <td>0</td> </tr>
- * <tr>  <td><b>7</b></td> <td>true</td>  <td>false</td> <td>tukey(0.5);partial_tukey(2)<td>                    <td>12</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>6</td> <td>0</td> </tr>
- * <tr>  <td><b>8</b></td> <td>true</td>  <td>false</td> <td>tukey(0.5);partial_tukey(2);punchout_tukey(3)</td> <td>12</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>6</td> <td>0</td> </tr>
+ * <tr>  <td><b>0</b></td> <td>false</td> <td>false</td> <td>tukey(0.5)</td>         <td>0</td>  <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>3</td> <td>0</td> </tr>
+ * <tr>  <td><b>1</b></td> <td>true</td>  <td>true</td>  <td>tukey(0.5)</td>         <td>0</td>  <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>3</td> <td>0</td> </tr>
+ * <tr>  <td><b>2</b></td> <td>true</td>  <td>false</td> <td>tukey(0.5)</td>         <td>0</td>  <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>3</td> <td>0</td> </tr>
+ * <tr>  <td><b>3</b></td> <td>false</td> <td>false</td> <td>tukey(0.5)</td>         <td>6</td>  <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>4</td> <td>0</td> </tr>
+ * <tr>  <td><b>4</b></td> <td>true</td>  <td>true</td>  <td>tukey(0.5)</td>         <td>8</td>  <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>4</td> <td>0</td> </tr>
+ * <tr>  <td><b>5</b></td> <td>true</td>  <td>false</td> <td>tukey(0.5)</td>         <td>8</td>  <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>5</td> <td>0</td> </tr>
+ * <tr>  <td><b>6</b></td> <td>true</td>  <td>false</td> <td>subdivide_tukey(2)</td> <td>8</td>  <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>6</td> <td>0</td> </tr>
+ * <tr>  <td><b>7</b></td> <td>true</td>  <td>false</td> <td>subdivide_tukey(2)</td> <td>12</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>6</td> <td>0</td> </tr>
+ * <tr>  <td><b>8</b></td> <td>true</td>  <td>false</td> <td>subdivide_tukey(2)</td> <td>12</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>6</td> <td>0</td> </tr>
  * </table>
  *
  * \default \c 5
@@ -921,7 +920,7 @@ FLAC_API FLAC__bool FLAC__stream_encoder_set_loose_mid_side_stereo(FLAC__StreamE
  * \c blackman, \c blackman_harris_4term_92db, \c connes, \c flattop,
  * \c gauss(STDDEV), \c hamming, \c hann, \c kaiser_bessel, \c nuttall,
  * \c rectangle, \c triangle, \c tukey(P), \c partial_tukey(n[/ov[/P]]),
- * \c punchout_tukey(n[/ov[/P]]), \c welch.
+ * \c punchout_tukey(n[/ov[/P]]), \c subdivide_tukey(n[/P]), \c welch.
  *
  * For \c gauss(STDDEV), STDDEV specifies the standard deviation
  * (0<STDDEV<=0.5).
@@ -948,6 +947,20 @@ FLAC_API FLAC__bool FLAC__stream_encoder_set_loose_mid_side_stereo(FLAC__StreamE
  * and partial_tukey(3/0.3/0.5) are all valid. ov should be smaller than 1
  * and can be negative.
  *
+ * subdivide_tukey(n) is a more efficient reimplementation of
+ * partial_tukey and punchout_tukey taken together, recycling as much data
+ * as possible. It combines all possible non-redundant partial_tukey(n)
+ * and punchout_tukey(n) up to the n specified. Specifying
+ * subdivide_tukey(3) is equivalent to specifying tukey, partial_tukey(2),
+ * partial_tukey(3) and punchout_tukey(3), specifying subdivide_tukey(5)
+ * equivalently adds partial_tukey(4), punchout_tukey(4), partial_tukey(5)
+ * and punchout_tukey(5). To be able to reuse data as much as possible,
+ * the tukey taper is taken equal for all windows, and the P specified is
+ * applied for the smallest used window. In other words,
+ * subdivide_tukey(2/0.5) results in a taper equal to that of tukey(0.25)
+ * and subdivide_tukey(5) in a taper equal to that of tukey(0.1). The
+ * default P for subdivide_tukey when none is specified is 0.5.
+ *
  * Example specifications are \c "blackman" or
  * \c "hann;triangle;tukey(0.5);tukey(0.25);tukey(0.125)"
  *
@@ -963,6 +976,8 @@ FLAC_API FLAC__bool FLAC__stream_encoder_set_loose_mid_side_stereo(FLAC__StreamE
  * floating point array in which to store the window. Also note that the
  * values of P, STDDEV and ov are locale-specific, so if the comma
  * separator specified by the locale is a comma, a comma should be used.
+ * A locale-independent way is to specify using scientific notation,
+ * e.g. 5e-1 instad of 0.5 or 0,5.
  *
  * \default \c "tukey(0.5)"
  * \param  encoder        An encoder instance to set.
diff --git a/src/flac/main.c b/src/flac/main.c
index 2b9d8ca5..c6f79933 100644
--- a/src/flac/main.c
+++ b/src/flac/main.c
@@ -1297,11 +1297,11 @@ void show_help(void)
 	printf("  -4, --compression-level-4          Synonymous with -l 8 -b 4096 -M -r 4\n");
 	printf("  -5, --compression-level-5          Synonymous with -l 8 -b 4096 -m -r 5\n");
 	printf("  -6, --compression-level-6          Synonymous with -l 8 -b 4096 -m -r 6\n");
-	printf("                                        -A tukey(0.5) -A partial_tukey(2)\n");
+	printf("                                         -A subdivide_tukey(2)\n");
 	printf("  -7, --compression-level-7          Synonymous with -l 12 -b 4096 -m -r 6\n");
-	printf("                                         -A tukey(0.5) -A partial_tukey(2)\n");
+	printf("                                         -A subdivide_tukey(2)\n");
 	printf("  -8, --compression-level-8, --best  Synonymous with -l 12 -b 4096 -m -r 6\n");
-	printf("                    -A tukey(0.5) -A partial_tukey(2) -A punchout_tukey(3)\n");
+	printf("                                         -A subdivide_tukey(3)\n");
 	printf("  -b, --blocksize=#                  Specify blocksize in samples\n");
 	printf("  -m, --mid-side                     Try mid-side coding for each frame\n");
 	printf("  -M, --adaptive-mid-side            Adaptive mid-side coding for all frames\n");
@@ -1606,11 +1606,11 @@ void show_explain(void)
 	printf("  -5, --compression-level-5          Synonymous with -l 8 -b 4096 -m -r 5\n");
 	printf("                                     -5 is the default setting\n");
 	printf("  -6, --compression-level-6          Synonymous with -l 8 -b 4096 -m -r 6\n");
-	printf("                                        -A tukey(0.5) -A partial_tukey(2)\n");
+	printf("                                         -A subdivide_tukey(2)\n");
 	printf("  -7, --compression-level-7          Synonymous with -l 12 -b 4096 -m -r 6\n");
-	printf("                                         -A tukey(0.5) -A partial_tukey(2)\n");
+	printf("                                         -A subdivide_tukey(2)\n");
 	printf("  -8, --compression-level-8, --best  Synonymous with -l 12 -b 4096 -m -r 6\n");
-	printf("                    -A tukey(0.5) -A partial_tukey(2) -A punchout_tukey(3)\n");
+	printf("                                         -A subdivide_tukey(3)\n");
 	printf("  -m, --mid-side                     Try mid-side coding for each frame\n");
 	printf("                                     (stereo only)\n");
 	printf("  -M, --adaptive-mid-side            Adaptive mid-side coding for all frames\n");
-- 
cgit v1.2.1