From 01ced1e49ea1100c3c3edcb8972f705242d2f57d Mon Sep 17 00:00:00 2001 From: reimar Date: Sat, 1 Oct 2005 12:55:34 +0000 Subject: documentation-only patch: make doxygen compatible and create af_chain and af_filter doxygen modules. git-svn-id: svn://svn.mplayerhq.hu/mplayer/trunk@16628 b3059339-0415-0410-9bf9-f77b7e298cf2 --- libaf/af.c | 16 +++-- libaf/af.h | 220 ++++++++++++++++++++++++++++++++++++++++++++++--------------- 2 files changed, 178 insertions(+), 58 deletions(-) (limited to 'libaf') diff --git a/libaf/af.c b/libaf/af.c index e3f647d11c..9abf947f3d 100644 --- a/libaf/af.c +++ b/libaf/af.c @@ -628,11 +628,7 @@ inline int af_resize_local_buffer(af_instance_t* af, af_data_t* data) return AF_OK; } -/** - * \brief send control to all filters, starting with the last, until - * one responds with AF_OK - * \return The instance that accepted the command or NULL if none did. - */ +// documentation in af.h af_instance_t *af_control_any_rev (af_stream_t* s, int cmd, void* arg) { int res = AF_UNKNOWN; af_instance_t* filt = s->last; @@ -647,6 +643,8 @@ af_instance_t *af_control_any_rev (af_stream_t* s, int cmd, void* arg) { /** * \brief calculate greatest common divisior of a and b. + * \ingroup af_filter + * * Extended for negative and 0 values. If both are 0 the result is 1. * The sign of the result will be so that it has the same sign as b. */ @@ -669,6 +667,8 @@ int af_gcd(register int a, register int b) { /** * \brief cancel down a fraction f + * \param f fraction to cancel down + * \ingroup af_filter */ void af_frac_cancel(frac_t *f) { int gcd = af_gcd(f->n, f->d); @@ -678,7 +678,11 @@ void af_frac_cancel(frac_t *f) { /** * \brief multiply out by in and store result in out. - * the resulting fraction wil be cancelled down + * \param out [inout] fraction to multiply by in + * \param in [in] fraction to multiply out by + * \ingroup af_filter + * + * the resulting fraction will be cancelled down * if in and out were. */ void af_frac_mul(frac_t *out, const frac_t *in) { diff --git a/libaf/af.h b/libaf/af.h index d0911ceae4..a8c4ab2762 100644 --- a/libaf/af.h +++ b/libaf/af.h @@ -124,69 +124,126 @@ typedef struct af_stream_s // Export functions */ -/* 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 - reentrant i.e. if called with an already initialized stream the - stream will be reinitialized. If the binary parameter - "force_output" is set, the output format will be converted to the - format given in "s", otherwise the output fromat in the last filter - will be copied "s". The return value is 0 if success and -1 if - failure */ +/** + * \defgroup af_chain Audio filter chain functions + * \{ + * \param s filter chain + */ + +/** + * \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(af_stream_t* s); -// Uninit and remove all filters +/** + * \brief Uninit and remove all filters from audio filter chain + */ void af_uninit(af_stream_t* s); -/* Add filter during execution. This function adds the filter "name" - to the stream s. The filter will be inserted somewhere nice in the - list of filters. The return value is a pointer to the new filter, - If the filter couldn't be added the return value is NULL. */ +/** + * \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??). + */ af_instance_t* af_add(af_stream_t* s, char* name); -// Uninit and remove the filter "af" +/** + * \brief Uninit and remove the filter "af" + * \param af filter to remove + */ void af_remove(af_stream_t* s, af_instance_t* af); -/* Find filter in the dynamic filter list using it's name This - function is used for finding already initialized filters */ +/** + * \brief find filter in chain by name + * \param name name of the filter to find + * \return first filter with right name or NULL if not found + * + * This function is used for finding already initialized filters + */ af_instance_t* af_get(af_stream_t* s, char* name); -// Filter data chunk through the filters in the list +/** + * \brief filter data chunk through the filters in the list + * \param data data to play + * \return resulting data + * \ingroup af_chain + */ af_data_t* af_play(af_stream_t* s, af_data_t* data); -// send control to all filters, starting with the last until -// one accepts the command with AF_OK. -// Returns the accepting filter or NULL if none was found. +/** + * \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 + */ af_instance_t *af_control_any_rev (af_stream_t* s, int cmd, void* arg); -/* Calculate how long the output from the filters will be given the - input length "len". The calculated length is >= the actual - length */ +/** + * \brief Calculate how long the output from the filters will be for a given + * input length. + * \param len input lenght for which to calculate output length + * \return calculated output length, will always be >= the resulting + * length when actually calling af_play. + */ int af_outputlen(af_stream_t* s, int len); -/* Calculate how long the input to the filters should be to produce a - certain output length, i.e. the return value of this function is - the input length required to produce the output length "len". The - calculated length is <= the actual length */ +/** + * \brief Calculate how long the input to the filters should be to produce a + * certain output length + * \param len wanted output length + * \return input length required to produce the output length "len". Possibly + * smaller to avoid overflow of output buffer + */ int af_inputlen(af_stream_t* s, int len); -/* Calculate how long the input IN to the filters should be to produce +/** + * \brief calculate required input length for desired output size + * \param len desired minimum output length + * \param max_outsize maximum output length + * \param max_insize maximum input length + * \return input length or -1 on error + * + Calculate how long the input IN to the filters should be to produce a certain output length OUT but with the following three constraints: 1. IN <= max_insize, where max_insize is the maximum possible input block length 2. OUT <= max_outsize, where max_outsize is the maximum possible output block length 3. If possible OUT >= len. - Return -1 in case of error */ + */ int af_calc_insize_constrained(af_stream_t* s, int len, int max_outsize,int max_insize); -/* Calculate the total delay caused by the filters */ +/** + * \brief Calculate the total delay caused by the filters + * \return delay in seconds + */ double af_calc_delay(af_stream_t* s); +/** \} */ // end of af_chain group + // Helper functions and macros used inside the audio filters +/** + * \defgroup af_filter Audio filter helper functions + * \{ + */ + /* Helper function called by the macro with the same name only to be called from inside filters */ int af_resize_local_buffer(af_instance_t* af, af_data_t* data); @@ -196,31 +253,87 @@ int af_resize_local_buffer(af_instance_t* af, af_data_t* data); needed */ int af_lencalc(frac_t mul, af_data_t* data); -/* Helper function used to convert to gain value from dB. Returns - AF_OK if of and AF_ERROR if fail */ +/** + * \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); -/* Helper function used to convert from gain value to dB. Returns - AF_OK if of and AF_ERROR if fail */ + +/** + * \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); -/* Helper function used to convert from ms to sample time*/ + +/** + * \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); -/* Helper function used to convert from sample time to ms */ + +/** + * \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); -/* Helper function for testing the output format */ + +/** + * \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_s* af, af_data_t* out); +/** + * \brief soft clipping function using sin() + * \param a input value + * \return clipped value + */ float af_softclip(float a); +/** \} */ // end of af_filter group, but more functions of this group below + /** Print a list of all available audio filters */ void af_help(void); -/* Fill the missing parameters in the af_data_t structure. - Used for stuffing bps with a value based on format. */ +/** + * \brief fill the missing parameters in the af_data_t structure + * \param data structure to fill + * \ingroup af_filter + * + * Currently only sets bps based on format + */ void af_fix_parameters(af_data_t *data); -/* Memory reallocation macro: if a local buffer is used (i.e. if the +/** Memory reallocation macro: if a local buffer is used (i.e. if the filter doesn't operate on the incoming buffer this macro must be - called to ensure the buffer is big enough. */ + called to ensure the buffer is big enough. + * \ingroup af_filter + */ #define RESIZE_LOCAL_BUFFER(a,d)\ ((a->data->len < af_lencalc(a->mul,d))?af_resize_local_buffer(a,d):AF_OK) @@ -257,19 +370,22 @@ typedef struct af_msg_cfg_s extern af_msg_cfg_t af_msg_cfg; // Message -#define AF_MSG_FATAL -3 // Fatal error exit immediately -#define AF_MSG_ERROR -2 // Error return gracefully -#define AF_MSG_WARN -1 // Print warning but do not exit (can be suppressed) -#define AF_MSG_INFO 0 // Important information -#define AF_MSG_VERBOSE 1 // Print this if verbose is enabled -#define AF_MSG_DEBUG0 2 // Print if very verbose -#define AF_MSG_DEBUG1 3 // Print if very very verbose - -/* Macro for printing error messages */ +//! \addtogroup af_filter +//! \{ +#define AF_MSG_FATAL -3 ///< Fatal error exit immediately +#define AF_MSG_ERROR -2 ///< Error return gracefully +#define AF_MSG_WARN -1 ///< Print warning but do not exit (can be suppressed) +#define AF_MSG_INFO 0 ///< Important information +#define AF_MSG_VERBOSE 1 ///< Print this if verbose is enabled +#define AF_MSG_DEBUG0 2 ///< Print if very verbose +#define AF_MSG_DEBUG1 3 ///< Print if very very verbose + +//! Macro for printing error messages #ifndef af_msg #define af_msg(lev, args... ) \ (((lev)