From 1dfcea1340dd26639c9094523c46aee530d39c90 Mon Sep 17 00:00:00 2001
From: Josh Coalson <jcoalson@users.sourceforce.net>
Date: Fri, 6 Oct 2006 05:51:59 +0000
Subject: [PATCH] multichannel assignments in format and documentation

---
 doc/html/documentation.html   |  2 +-
 doc/html/format.html          | 12 +++++++++++-
 include/FLAC/stream_decoder.h |  6 +++---
 include/FLAC/stream_encoder.h |  8 ++++++++
 4 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/doc/html/documentation.html b/doc/html/documentation.html
index 8c3a6a16..f31c9bc9 100644
--- a/doc/html/documentation.html
+++ b/doc/html/documentation.html
@@ -143,7 +143,7 @@
 	</div>
 	<div class="box_header"></div>
 	<div class="box_body">
-		<span class="commandname">flac</span> is the command-line file encoder/decoder.  The encoder currently supports as input RIFF WAVE, AIFF, or FLAC format, or raw interleaved samples.  The decoder currently can output to RIFF WAVE or AIFF format, or raw interleaved samples.  <span class="commandname">flac</span> only supports linear PCM samples (in other words, no A-LAW, uLAW, etc.).  Another restriction (hopefully short-term) is that the input must be 8, 16, or 24 bits per sample.  This is not a limitation of the FLAC format, just the reference encoder/decoder.
+		<span class="commandname">flac</span> is the command-line file encoder/decoder.  The encoder currently supports as input RIFF WAVE, AIFF, or FLAC format, or raw interleaved samples.  The decoder currently can output to RIFF WAVE or AIFF format, or raw interleaved samples.  <span class="commandname">flac</span> only supports linear PCM samples (in other words, no A-LAW, uLAW, etc.), and the input must be between 4 and 24 bits per sample.  This is not a limitation of the FLAC format, just the reference encoder/decoder.
 		<br /><br />
 		<span class="commandname">flac</span> assumes that files ending in ".wav" or that have the RIFF WAVE header present are WAVE files, files ending in ".aif" or ".aiff" or have the AIFF header present are AIFF files, and files ending in ".flac" or have the FLAC header present are FLAC files.  This assumption may be overridden with a command-line option.  It also assumes that files ending in ".ogg" are Ogg FLAC files.  Other than this, <span class="commandname">flac</span> makes no assumptions about file extensions, though the convention is that FLAC files have the extension ".flac" (or ".fla" on ancient file systems like FAT-16).
 		<br /><br />
diff --git a/doc/html/format.html b/doc/html/format.html
index dc5cc2c7..415d0461 100644
--- a/doc/html/format.html
+++ b/doc/html/format.html
@@ -1214,7 +1214,17 @@
 				Channel assignment
 				<ul>
 				<li>
-					<tt>0000-0111</tt> : (number of independent channels)-1.  when == 0001, channel 0 is the left channel and channel 1 is the right
+					<tt>0000-0111</tt> : (number of independent channels)-1.  Where defined, the channel order follows SMPTE/ITU-R recommendations.  The assignments are as follows:
+					<ul>
+						<li>1 channel: mono</li>
+						<li>2 channels: left, right</li>
+						<li>3 channels: left, right, center</li>
+						<li>4 channels: left, right, back left, back right</li>
+						<li>5 channels: left, right, center, back/surround left, back/surround right</li>
+						<li>6 channels: left, right, center, LFE, back/surround left, back/surround right</li>
+						<li>7 channels: not defined</li>
+						<li>8 channels: not defined</li>
+					</ul>
 				</li>
 				<li>
 					<tt>1000</tt> : left/side stereo: channel 0 is the left channel, channel 1 is the side(difference) channel
diff --git a/include/FLAC/stream_decoder.h b/include/FLAC/stream_decoder.h
index 6762a69c..ce2b927d 100644
--- a/include/FLAC/stream_decoder.h
+++ b/include/FLAC/stream_decoder.h
@@ -574,9 +574,9 @@ typedef FLAC__bool (*FLAC__StreamDecoderEofCallback)(const FLAC__StreamDecoder *
  * \param  buffer   An array of pointers to decoded channels of data.
  *                  Each pointer will point to an array of signed
  *                  samples of length \a frame->header.blocksize.
- *                  Currently, the channel order has no meaning
- *                  except for stereo streams; in this case channel
- *                  0 is left and 1 is right.
+ *                  Channels will be ordered according to the FLAC
+ *                  specification; see the documentation for the
+ *                  <A HREF="../format.html#frame_header">frame header</A>.
  * \param  client_data  The callee's client data set through
  *                      FLAC__stream_decoder_init_*().
  * \retval FLAC__StreamDecoderWriteStatus
diff --git a/include/FLAC/stream_encoder.h b/include/FLAC/stream_encoder.h
index e57a6839..407b6ac8 100644
--- a/include/FLAC/stream_encoder.h
+++ b/include/FLAC/stream_encoder.h
@@ -1318,6 +1318,10 @@ FLAC_API void FLAC__stream_encoder_finish(FLAC__StreamEncoder *encoder);
  *  representing one channel.  The samples need not be block-aligned,
  *  but each channel should have the same number of samples.
  *
+ *  For applications where channel order is important, channels must
+ *  follow the order as described in the
+ *  <A HREF="../format.html#frame_header">frame header</A>.
+ *
  * \param  encoder  An initialized encoder instance in the OK state.
  * \param  buffer   An array of pointers to each channel's signal.
  * \param  samples  The number of samples in one channel.
@@ -1339,6 +1343,10 @@ FLAC_API FLAC__bool FLAC__stream_encoder_process(FLAC__StreamEncoder *encoder, c
  *  sample-aligned, i.e. the first value should be channel0_sample0
  *  and the last value channelN_sampleM.
  *
+ *  For applications where channel order is important, channels must
+ *  follow the order as described in the
+ *  <A HREF="../format.html#frame_header">frame header</A>.
+ *
  * \param  encoder  An initialized encoder instance in the OK state.
  * \param  buffer   An array of channel-interleaved data (see above).
  * \param  samples  The number of samples in one channel, the same as for