Finish porting guide

4 files changed, 59 insertions, 18 deletions

diff --git a/include/FLAC/all.h b/include/FLAC/all.h
index 71ddd3c6..ee6e132c 100644
--- a/include/FLAC/all.h
+++ b/include/FLAC/all.h
@@ -369,12 +369,8 @@
  * - the function get_client_data_from_decoder has been renamed to
  *   FLAC__get_decoder_client_data
  * - some data types in the FLAC__Frame struct have changed
- * - the C functions FLAC__stream_encoder_init_file,
- *   FLAC__stream_encoder_init_ogg_file, FLAC__stream_decoder_init_file
- *   and  FLAC__stream_decoder_init_ogg_file and the C++ ::init and
- *   ::init_ogg class member functions of both the encoder and decoder
- *   now take UTF-8 encoded filenames on Windows instead of filenames in
- *   the current codepage
+ * - all functions accepting a filename now take UTF-8 encoded filenames
+ *   on Windows instead of filenames in the current codepage
  *
  * Furthermore, there have been the following additions
  * - the functions FLAC__stream_encoder_set_limit_min_bitrate,
@@ -388,7 +384,8 @@
  *
  * The function \b get_client_data_from_decoder was added in FLAC 1.3.3
  * but did not follow the API naming convention and was not properly
- * exported. The function is now renamed and properly integrated
+ * exported. The function is now renamed and properly integrated as
+ * FLAC__stream_decoder_get_client_data
  *
  * To accomodate encoding and decoding 32-bit int PCM, some data types
  * in the \b FLAC__frame struct were changed. Specifically, warmup
@@ -401,9 +398,29 @@
  * data_type, which clarifies whether the FLAC__int32 or FLAC__int64
  * array is in use.
  *
- * The last breaking change is that filenames in FLAC and FLAC++ encoder
- * and decoder must now have the UTF-8 character encoding instead of
- * using the current code page.
+ * The last breaking change is that all API functions taking a filename
+ * as an argument now, on Windows, must be supplied with that filename
+ * in the UTF-8 character encoding instead of using the current code
+ * page. libFLAC internally translates these UTF-8 encoded filenames to
+ * an appropriate representation to use with _wfopen. On all other
+ * systems, filename is passed to fopen without any translation, as it
+ * in libFLAC 1.3.4 and earlier.
+ *
+ * \section porting_1_3_4_to_1_4_0_additions Additions
+ *
+ * To aid in creating properly streamable FLAC files, a set of functions
+ * was added to make it possible to enfore a minimum bitrate to files
+ * created through libFLAC's stream_encoder.h interface. With this
+ * function enabled the resulting FLAC files have a minimum bitrate of
+ * 1bit/sample independent of the number of channels, i.e. 48kbit/s for
+ * 48kHz. This can be beneficial for streaming, as very low bitrates for
+ * silent sections compressed with 'constant' subframes can result in a
+ * bitrate of 1kbit/s, creating problems with clients that aren't aware
+ * of this possibility and buffer too much data.
+ *
+ * Finally, FLAC__STREAM_DECODER_ERROR_STATUS_BAD_METADATA was added to
+ * the FLAC__StreamDecoderErrorStatus enum to signal that the decoder
+ * encountered unreadable metadata.
  *
  */
 
diff --git a/include/FLAC/metadata.h b/include/FLAC/metadata.h
index 265f336b..aa369054 100644
--- a/include/FLAC/metadata.h
+++ b/include/FLAC/metadata.h
@@ -134,6 +134,11 @@ extern "C" {
  *  STREAMINFO, VORBIS_COMMENT, CUESHEET, and PICTURE blocks, requiring
  *  only a filename.
  *
+ *  On Windows, filename must be a UTF-8 encoded filename, which libFLAC
+ *  internally translates to an appropriate representation to use with
+ *  _wfopen. On all other systems, filename is passed to fopen without
+ *  any translation.
+ *
  *  They try to skip any ID3v2 tag at the head of the file.
  *
  * \{
@@ -387,6 +392,11 @@ FLAC_API FLAC__Metadata_SimpleIteratorStatus FLAC__metadata_simple_iterator_stat
 /** Initialize the iterator to point to the first metadata block in the
  *  given FLAC file.
  *
+ *  On Windows, filename must be a UTF-8 encoded filename, which libFLAC
+ *  internally translates to an appropriate representation to use with
+ *  _wfopen. On all other systems, filename is passed to fopen without
+ *  any translation.
+ *
  * \param iterator             A pointer to an existing iterator.
  * \param filename             The path to the FLAC file.
  * \param read_only            If \c true, the FLAC file will be opened
@@ -820,6 +830,11 @@ FLAC_API FLAC__Metadata_ChainStatus FLAC__metadata_chain_status(FLAC__Metadata_C
 
 /** Read all metadata from a FLAC file into the chain.
  *
+ *  On Windows, filename must be a UTF-8 encoded filename, which libFLAC
+ *  internally translates to an appropriate representation to use with
+ *  _wfopen. On all other systems, filename is passed to fopen without
+ *  any translation.
+ *
  * \param chain    A pointer to an existing chain.
  * \param filename The path to the FLAC file to read.
  * \assert
@@ -834,6 +849,11 @@ FLAC_API FLAC__bool FLAC__metadata_chain_read(FLAC__Metadata_Chain *chain, const
 
 /** Read all metadata from an Ogg FLAC file into the chain.
  *
+ *  On Windows, filename must be a UTF-8 encoded filename, which libFLAC
+ *  internally translates to an appropriate representation to use with
+ *  _wfopen. On all other systems, filename is passed to fopen without
+ *  any translation.
+ *
  * \note Ogg FLAC metadata data writing is not supported yet and
  * FLAC__metadata_chain_write() will fail.
  *
diff --git a/include/FLAC/stream_decoder.h b/include/FLAC/stream_decoder.h
index 02779c4c..2d285aec 100644
--- a/include/FLAC/stream_decoder.h
+++ b/include/FLAC/stream_decoder.h
@@ -1285,8 +1285,9 @@ FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_FILE(
  *  and provide callbacks for the I/O.
  *
  *  On Windows, filename must be a UTF-8 encoded filename, which libFLAC
- *  internally translates to a appropriate representation to use with
- *  _wfopen
+ *  internally translates to an appropriate representation to use with
+ *  _wfopen. On all other systems, filename is passed to fopen without
+ *  any translation.
  *
  *  This function should be called after FLAC__stream_decoder_new() and
  *  FLAC__stream_decoder_set_*() but before any of the
@@ -1330,8 +1331,9 @@ FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_file(
  *  and provide callbacks for the I/O.
  *
  *  On Windows, filename must be a UTF-8 encoded filename, which libFLAC
- *  internally translates to a appropriate representation to use with
- *  _wfopen
+ *  internally translates to an appropriate representation to use with
+ *  _wfopen. On all other systems, filename is passed to fopen without
+ *  any translation.
  *
  *  This function should be called after FLAC__stream_decoder_new() and
  *  FLAC__stream_decoder_set_*() but before any of the
diff --git a/include/FLAC/stream_encoder.h b/include/FLAC/stream_encoder.h
index d775d0c3..a39d0ed2 100644
--- a/include/FLAC/stream_encoder.h
+++ b/include/FLAC/stream_encoder.h
@@ -1662,8 +1662,9 @@ FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_ogg_FILE(FLAC__
  *  and provide callbacks for the I/O.
  *
  *  On Windows, filename must be a UTF-8 encoded filename, which libFLAC
- *  internally translates to a appropriate representation to use with
- *  _wfopen
+ *  internally translates to an appropriate representation to use with
+ *  _wfopen. On all other systems, filename is passed to fopen without
+ *  any translation.
  *
  *  This function should be called after FLAC__stream_encoder_new() and
  *  FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
@@ -1697,8 +1698,9 @@ FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_file(FLAC__Stre
  *  and provide callbacks for the I/O.
  *
  *  On Windows, filename must be a UTF-8 encoded filename, which libFLAC
- *  internally translates to a appropriate representation to use with
- *  _wfopen
+ *  internally translates to an appropriate representation to use with
+ *  _wfopen. On all other systems, filename is passed to fopen without
+ *  any translation.
  *
  *  This function should be called after FLAC__stream_encoder_new() and
  *  FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()