pcm: added API documentation

6 files changed, 130 insertions, 1 deletions

diff --git a/src/pcm_channels.h b/src/pcm_channels.h
index b4699ed8f..25c13d839 100644
--- a/src/pcm_channels.h
+++ b/src/pcm_channels.h
@@ -24,12 +24,35 @@
 
 struct pcm_buffer;
 
+/**
+ * Changes the number of channels in 16 bit PCM data.
+ *
+ * @param buffer the destination pcm_buffer object
+ * @param dest_channels the number of channels requested
+ * @param src_channels the number of channels in the source buffer
+ * @param src the source PCM buffer
+ * @param src_size the number of bytes in #src
+ * @param dest_size_r returns the number of bytes of the destination buffer
+ * @return the destination buffer
+ */
 const int16_t *
 pcm_convert_channels_16(struct pcm_buffer *buffer,
 			int8_t dest_channels,
 			int8_t src_channels, const int16_t *src,
 			size_t src_size, size_t *dest_size_r);
 
+/**
+ * Changes the number of channels in 24 bit PCM data (aligned at 32
+ * bit boundaries).
+ *
+ * @param buffer the destination pcm_buffer object
+ * @param dest_channels the number of channels requested
+ * @param src_channels the number of channels in the source buffer
+ * @param src the source PCM buffer
+ * @param src_size the number of bytes in #src
+ * @param dest_size_r returns the number of bytes of the destination buffer
+ * @return the destination buffer
+ */
 const int32_t *
 pcm_convert_channels_24(struct pcm_buffer *buffer,
 			int8_t dest_channels,
diff --git a/src/pcm_convert.h b/src/pcm_convert.h
index 18a1dbc49..35bbdad5c 100644
--- a/src/pcm_convert.h
+++ b/src/pcm_convert.h
@@ -25,6 +25,11 @@
 
 struct audio_format;
 
+/**
+ * This object is statically allocated (within another struct), and
+ * holds buffer allocations and the state for all kinds of PCM
+ * conversions.
+ */
 struct pcm_convert_state {
 	struct pcm_resample_state resample;
 
@@ -37,10 +42,28 @@ struct pcm_convert_state {
 	struct pcm_buffer channels_buffer;
 };
 
+/**
+ * Initializes a pcm_convert_state object.
+ */
 void pcm_convert_init(struct pcm_convert_state *state);
 
+/**
+ * Deinitializes a pcm_convert_state object and frees allocated
+ * memory.
+ */
 void pcm_convert_deinit(struct pcm_convert_state *state);
 
+/**
+ * Converts PCM data between two audio formats.
+ *
+ * @param state an initialized pcm_convert_state object
+ * @param src_format the source audio format
+ * @param src the source PCM buffer
+ * @param src_size the size of #src in bytes
+ * @param dest_format the requested destination audio format
+ * @param dest_size_r returns the number of bytes of the destination buffer
+ * @return the destination buffer
+ */
 const void *
 pcm_convert(struct pcm_convert_state *state,
 	    const struct audio_format *src_format,
diff --git a/src/pcm_format.h b/src/pcm_format.h
index 628155dd4..32279faef 100644
--- a/src/pcm_format.h
+++ b/src/pcm_format.h
@@ -25,11 +25,34 @@
 struct pcm_buffer;
 struct pcm_dither_24;
 
+/**
+ * Converts PCM samples to 16 bit.  If the source format is 24 bit,
+ * then dithering is applied.
+ *
+ * @param buffer a pcm_buffer object
+ * @param dither a pcm_dither_24 object for 24-to-16 conversion
+ * @param bits the number of in the source buffer
+ * @param src the source PCM buffer
+ * @param src_size the size of #src in bytes
+ * @param dest_size_r returns the number of bytes of the destination buffer
+ * @return the destination buffer
+ */
 const int16_t *
 pcm_convert_to_16(struct pcm_buffer *buffer, struct pcm_dither_24 *dither,
 		  uint8_t bits, const void *src,
 		  size_t src_size, size_t *dest_size_r);
 
+/**
+ * Converts PCM samples to 24 bit (32 bit alignment).
+ *
+ * @param buffer a pcm_buffer object
+ * @param dither a pcm_dither_24 object for 24-to-16 conversion
+ * @param bits the number of in the source buffer
+ * @param src the source PCM buffer
+ * @param src_size the size of #src in bytes
+ * @param dest_size_r returns the number of bytes of the destination buffer
+ * @return the destination buffer
+ */
 const int32_t *
 pcm_convert_to_24(struct pcm_buffer *buffer,
 		  uint8_t bits, const void *src,
diff --git a/src/pcm_mix.h b/src/pcm_mix.h
index f3fe3c365..28b338f23 100644
--- a/src/pcm_mix.h
+++ b/src/pcm_mix.h
@@ -23,6 +23,19 @@
 
 struct audio_format;
 
+/*
+ * Linearly mixes two PCM buffers.  Both must have the same length and
+ * the same audio format.  The formula is:
+ *
+ *   s1 := s1 * portion1 + s2 * (1 - portion1)
+ *
+ * @param buffer1 the first PCM buffer, and the destination buffer
+ * @param buffer2 the second PCM buffer
+ * @param size the size of both buffers in bytes
+ * @param format the audio format of both buffers
+ * @param portion1 a number between 0.0 and 1.0 specifying the portion
+ * of the first buffer in the mix; portion2 = (1.0 - portion1)
+ */
 void
 pcm_mix(void *buffer1, const void *buffer2, size_t size,
 	const struct audio_format *format, float portion1);
diff --git a/src/pcm_resample.h b/src/pcm_resample.h
index 66a746ae2..5042f4c99 100644
--- a/src/pcm_resample.h
+++ b/src/pcm_resample.h
@@ -31,6 +31,10 @@
 #include <samplerate.h>
 #endif
 
+/**
+ * This object is statically allocated (within another struct), and
+ * holds buffer allocations and the state for the resampler.
+ */
 struct pcm_resample_state {
 #ifdef HAVE_LIBSAMPLERATE
 	SRC_STATE *state;
@@ -50,10 +54,29 @@ struct pcm_resample_state {
 	struct pcm_buffer buffer;
 };
 
+/**
+ * Initializes a pcm_resample_state object.
+ */
 void pcm_resample_init(struct pcm_resample_state *state);
 
+/**
+ * Deinitializes a pcm_resample_state object and frees allocated
+ * memory.
+ */
 void pcm_resample_deinit(struct pcm_resample_state *state);
 
+/**
+ * Resamples 16 bit PCM data.
+ *
+ * @param state an initialized pcm_resample_state object
+ * @param channels the number of channels
+ * @param src_rate the source sample rate
+ * @param src the source PCM buffer
+ * @param src_size the size of #src in bytes
+ * @param dest_rate the requested destination sample rate
+ * @param dest_size_r returns the number of bytes of the destination buffer
+ * @return the destination buffer
+ */
 const int16_t *
 pcm_resample_16(struct pcm_resample_state *state,
 		uint8_t channels,
@@ -62,6 +85,18 @@ pcm_resample_16(struct pcm_resample_state *state,
 		unsigned dest_rate,
 		size_t *dest_size_r);
 
+/**
+ * Resamples 24 bit PCM data.
+ *
+ * @param state an initialized pcm_resample_state object
+ * @param channels the number of channels
+ * @param src_rate the source sample rate
+ * @param src the source PCM buffer
+ * @param src_size the size of #src in bytes
+ * @param dest_rate the requested destination sample rate
+ * @param dest_size_r returns the number of bytes of the destination buffer
+ * @return the destination buffer
+ */
 const int32_t *
 pcm_resample_24(struct pcm_resample_state *state,
 		uint8_t channels,
diff --git a/src/pcm_volume.h b/src/pcm_volume.h
index 44ced88af..1b5e7fb0e 100644
--- a/src/pcm_volume.h
+++ b/src/pcm_volume.h
@@ -40,6 +40,10 @@ pcm_float_to_volume(float volume)
 	return volume * PCM_VOLUME_1 + 0.5;
 }
 
+/**
+ * Returns the next volume dithering number, between -511 and +511.
+ * This number is taken from a global PRNG, see pcm_prng().
+ */
 static inline int
 pcm_volume_dither(void)
 {
@@ -51,8 +55,16 @@ pcm_volume_dither(void)
 	return (r & 511) - ((r >> 9) & 511);
 }
 
+/**
+ * Adjust the volume of the specified PCM buffer.
+ *
+ * @param buffer the PCM buffer
+ * @param length the length of the PCM buffer
+ * @param format the audio format of the PCM buffer
+ * @param volume the volume between 0 and #PCM_VOLUME_1
+ */
 void
-pcm_volume(void *buffer, int bufferSize,
+pcm_volume(void *buffer, int length,
 	   const struct audio_format *format,
 	   int volume);