summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2013-11-18 14:11:13 +0100
committerwm4 <wm4@nowhere>2013-11-18 14:21:01 +0100
commit93852b08f37f630b994d126751b4b9740a13219f (patch)
tree217fed11845a1c0855e6919a6fe3ec96ff34de4f
parent75dd3ec2106701cb865f52966de66c51cb6f9204 (diff)
downloadmpv-93852b08f37f630b994d126751b4b9740a13219f.tar.bz2
mpv-93852b08f37f630b994d126751b4b9740a13219f.tar.xz
af: cleanup documentation comments
And by "cleanup", I mean "remove". Actually, only remove the parts that are redundant and doxygen noise. Move useful parts to the comment above the function's implementation in the C source file.
-rw-r--r--audio/filter/af.c10
-rw-r--r--audio/filter/af.h134
-rw-r--r--audio/filter/af_tools.c17
3 files changed, 22 insertions, 139 deletions
diff --git a/audio/filter/af.c b/audio/filter/af.c
index c315ea8f7c..03e85245e0 100644
--- a/audio/filter/af.c
+++ b/audio/filter/af.c
@@ -627,7 +627,7 @@ void af_destroy(struct af_stream *s)
/* Initialize the stream "s". This function creates a new filter list
if necessary according to the values set in input and output. Input
and output should contain the format of the current movie and the
- formate of the preferred output respectively. The function is
+ format of the preferred output respectively. The function is
reentrant i.e. if called with an already initialized stream the
stream will be reinitialized.
If one of the prefered output parameters is 0 the one that needs
@@ -691,7 +691,8 @@ struct af_instance *af_add(struct af_stream *s, char *name, char **args)
return new;
}
-// Filter data chunk through the filters in the list
+/* Filter data chunk through the filters in the list.
+ * Warning: input (audio data and struct fields) will be overwritten. */
struct mp_audio *af_play(struct af_stream *s, struct mp_audio *data)
{
struct af_instance *af = s->first;
@@ -719,7 +720,7 @@ double af_calc_filter_multiplier(struct af_stream *s)
return mul;
}
-/* Calculate the total delay [bytes output] caused by the filters */
+/* Calculate the total delay [seconds of output] caused by the filters */
double af_calc_delay(struct af_stream *s)
{
struct af_instance *af = s->first;
@@ -731,7 +732,8 @@ double af_calc_delay(struct af_stream *s)
return delay;
}
-// documentation in af.h
+/* Send control to all filters, starting with the last until one accepts the
+ * command with AF_OK. Return the accepting filter. */
struct af_instance *af_control_any_rev(struct af_stream *s, int cmd, void *arg)
{
int res = AF_UNKNOWN;
diff --git a/audio/filter/af.h b/audio/filter/af.h
index 7852fa09a6..3a56c4c081 100644
--- a/audio/filter/af.h
+++ b/audio/filter/af.h
@@ -87,10 +87,7 @@ struct af_stream {
struct MPOpts *opts;
};
-/*********************************************
- // Return values
- */
-
+// Return values
#define AF_DETACH 2
#define AF_OK 1
#define AF_TRUE 1
@@ -99,150 +96,23 @@ struct af_stream {
#define AF_ERROR -2
#define AF_FATAL -3
-
-
-/*********************************************
- // Export functions
- */
-
-/**
- * \defgroup af_chain Audio filter chain functions
- * \{
- * \param s filter chain
- */
-
struct af_stream *af_new(struct MPOpts *opts);
void af_destroy(struct af_stream *s);
-
-/**
- * \brief Initialize the stream "s".
- * \return 0 on success, -1 on failure
- *
- * This function creates a new filter list if necessary, according
- * to the values set in input and output. Input and output should contain
- * the format of the current movie and the format of the preferred output
- * respectively.
- * Filters to convert to the preferred output format are inserted
- * automatically, except when they are set to 0.
- * The function is reentrant i.e. if called with an already initialized
- * stream the stream will be reinitialized.
- */
int af_init(struct af_stream *s);
-
-/**
- * \brief Uninit and remove all filters from audio filter chain
- */
void af_uninit(struct af_stream *s);
-
-/**
- * \brief This function adds the filter "name" to the stream s.
- * \param name name of filter to add
- * \return pointer to the new filter, NULL if insert failed
- *
- * The filter will be inserted somewhere nice in the
- * list of filters (i.e. at the beginning unless the
- * first filter is the format filter (why??).
- */
struct af_instance *af_add(struct af_stream *s, char *name, char **args);
-
-/**
- * \brief filter data chunk through the filters in the list
- * \param data data to play
- * \return resulting data
- * \ingroup af_chain
- */
struct mp_audio *af_play(struct af_stream *s, struct mp_audio *data);
-
-/**
- * \brief send control to all filters, starting with the last until
- * one accepts the command with AF_OK.
- * \param cmd filter control command
- * \param arg argument for filter command
- * \return the accepting filter or NULL if none was found
- */
struct af_instance *af_control_any_rev(struct af_stream *s, int cmd, void *arg);
-/**
- * \brief calculate average ratio of filter output lenth to input length
- * \return the ratio
- */
double af_calc_filter_multiplier(struct af_stream *s);
-
-/**
- * \brief Calculate the total delay caused by the filters
- * \return delay in bytes of "missing" output
- */
double af_calc_delay(struct af_stream *s);
-/** \} */ // end of af_chain group
-
-// Helper functions and macros used inside the audio filters
-
-/**
- * \defgroup af_filter Audio filter helper functions
- * \{
- */
+int af_test_output(struct af_instance *af, struct mp_audio *out);
-/**
- * \brief convert dB to gain value
- * \param n number of values to convert
- * \param in [in] values in dB, <= -200 will become 0 gain
- * \param out [out] gain values
- * \param k input values are divided by this
- * \param mi minimum dB value, input will be clamped to this
- * \param ma maximum dB value, input will be clamped to this
- * \return AF_ERROR on error, AF_OK otherwise
- */
int af_from_dB(int n, float *in, float *out, float k, float mi, float ma);
-
-/**
- * \brief convert gain value to dB
- * \param n number of values to convert
- * \param in [in] gain values, 0 wil become -200 dB
- * \param out [out] values in dB
- * \param k output values will be multiplied by this
- * \return AF_ERROR on error, AF_OK otherwise
- */
int af_to_dB(int n, float *in, float *out, float k);
-
-/**
- * \brief convert milliseconds to sample time
- * \param n number of values to convert
- * \param in [in] values in milliseconds
- * \param out [out] sample time values
- * \param rate sample rate
- * \param mi minimum ms value, input will be clamped to this
- * \param ma maximum ms value, input will be clamped to this
- * \return AF_ERROR on error, AF_OK otherwise
- */
int af_from_ms(int n, float *in, int *out, int rate, float mi, float ma);
-
-/**
- * \brief convert sample time to milliseconds
- * \param n number of values to convert
- * \param in [in] sample time values
- * \param out [out] values in milliseconds
- * \param rate sample rate
- * \return AF_ERROR on error, AF_OK otherwise
- */
int af_to_ms(int n, int *in, float *out, int rate);
-
-/**
- * \brief test if output format matches
- * \param af audio filter
- * \param out needed format, will be overwritten by available
- * format if they do not match
- * \return AF_FALSE if formats do not match, AF_OK if they match
- *
- * compares the format, bps, rate and nch values of af->data with out
- */
-int af_test_output(struct af_instance *af, struct mp_audio *out);
-
-/**
- * \brief soft clipping function using sin()
- * \param a input value
- * \return clipped value
- */
float af_softclip(float a);
#endif /* MPLAYER_AF_H */
diff --git a/audio/filter/af_tools.c b/audio/filter/af_tools.c
index 77638ed9d6..c5f423ebf9 100644
--- a/audio/filter/af_tools.c
+++ b/audio/filter/af_tools.c
@@ -23,7 +23,7 @@
#include "af.h"
/* Convert to gain value from dB. Returns AF_OK if of and AF_ERROR if
- fail */
+ * fail. input <= -200dB will become 0 gain. */
int af_from_dB(int n, float* in, float* out, float k, float mi, float ma)
{
int i = 0;
@@ -41,7 +41,7 @@ int af_from_dB(int n, float* in, float* out, float k, float mi, float ma)
}
/* Convert from gain value to dB. Returns AF_OK if of and AF_ERROR if
- fail */
+ * fail. gain=0 will become -200 dB. k is just a multiplier. */
int af_to_dB(int n, float* in, float* out, float k)
{
int i = 0;
@@ -86,7 +86,18 @@ int af_to_ms(int n, int* in, float* out, int rate)
return AF_OK;
}
-/* Helper function for testing the output format */
+/*
+ * test if output format matches
+ * af: audio filter
+ * out: needed format, will be overwritten by available
+ * format if they do not match
+ * returns: AF_FALSE if formats do not match, AF_OK if they match
+ *
+ * compares the format, rate and nch values of af->data with out
+ * Note: logically, *out=*af->data always happens, because out contains the
+ * format only, no actual audio data or memory allocations. *out always
+ * contains the parameters from af->data after the function returns.
+ */
int af_test_output(struct af_instance* af, struct mp_audio* out)
{
if((af->data->format != out->format) ||