aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMax Kellermann <max@duempel.org>2009-02-21 18:14:20 +0100
committerMax Kellermann <max@duempel.org>2009-02-21 18:14:20 +0100
commitf0554d9a75abab093fe5169bdab6b6b75ae4f97a (patch)
tree041e132660e2c6ea0865306d19d7a45314e0a7a8
parentcae7c160a3084acf9e68845b16bae34772d18e4e (diff)
downloadmpd-f0554d9a75abab093fe5169bdab6b6b75ae4f97a.tar.gz
mpd-f0554d9a75abab093fe5169bdab6b6b75ae4f97a.tar.xz
mpd-f0554d9a75abab093fe5169bdab6b6b75ae4f97a.zip
pcm: added API documentation
-rw-r--r--src/pcm_channels.h23
-rw-r--r--src/pcm_convert.h23
-rw-r--r--src/pcm_format.h23
-rw-r--r--src/pcm_mix.h13
-rw-r--r--src/pcm_resample.h35
-rw-r--r--src/pcm_volume.h14
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);