[FFmpeg-devel] [PATCH] swr: general doxy text about swr and example code.

[Clément Bœsch]

On Mon, Nov 19, 2012 at 11:55:54PM +0100, Michael Niedermayer wrote:
> Based on doxy from avr
> Signed-off-by: Michael Niedermayer <michaelni at gmx.at>
> ---
>  libswresample/swresample.h |   73 ++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 71 insertions(+), 2 deletions(-)
> 
> diff --git a/libswresample/swresample.h b/libswresample/swresample.h
> index 2ce666e..4a92268 100644
> --- a/libswresample/swresample.h
> +++ b/libswresample/swresample.h
> @@ -18,13 +18,78 @@
>   * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
>   */
>  
> +#ifndef SWRESAMPLE_SWRESAMPLE_H
> +#define SWRESAMPLE_SWRESAMPLE_H
> +
>  /**
>   * @file
>   * libswresample public header
>   */
>  
> -#ifndef SWRESAMPLE_SWRESAMPLE_H
> -#define SWRESAMPLE_SWRESAMPLE_H
> +/**
> + * @defgroup lswr Libswresample
> + * @{
> + *
> + * Libswresample (lswr) is a library that handles audio resampling, sample
> + * format conversion and mixing.
> + *
> + * Interaction with lswr is done through SwrContext, which is
> + * allocated with swr_alloc() or swr_alloc_set_opts(). It is opaque, so all parameters
> + * must be set with the @ref avoptions API.
> + *
> + * For example the following code will setup conversion from planar float sample
> + * format to interleaved signed 16-bit integer, downsampling from 48kHz to
> + * 44.1kHz and downmixing from 5.1 channels to stereo (using the default mixing
> + * matrix):
> + * @code
> + * SwrContext *swr = swr_alloc();
> + * av_opt_set_int(swr, "in_channel_layout",  AV_CH_LAYOUT_5POINT1, 0);
> + * av_opt_set_int(swr, "out_channel_layout", AV_CH_LAYOUT_STEREO,  0);
> + * av_opt_set_int(swr, "in_sample_rate",     48000,                0);
> + * av_opt_set_int(swr, "out_sample_rate",    44100,                0);
> + * av_opt_set_int(swr, "in_sample_fmt",      AV_SAMPLE_FMT_FLTP,   0);
> + * av_opt_set_int(swr, "out_sample_fmt,      AV_SAMPLE_FMT_S16,    0);
> + * @endcode
> + *
> + * Once all values have been set, it must be initialized with swr_init(). If
> + * you need to change the conversion parameters, you can change the parameters
> + * as described above, then call swr_init() again.
> + *

or calling swr_alloc_set_opts() again?

can we reset to default all the options just like the state after a
swr_alloc()? (using av_opt_set_defaults on swr I guess?)

> + * The conversion itself is done by repeatedly calling swr_convert().
> + * Note that the samples may get buffered in swr if you provide insufficient
> + * output space or if sample rate conversion is done, which requires "future"
> + * samples. Samples that do not require future input can be retrieved at any
> + * time by using swr_convert() (in_count can be set to 0).
> + * At the end of conversion the resampling buffer can be flushed by calling
> + * swr_convert() with NULL in and 0 in_count.
> + *
> + * The delay between input and output, can at any time be found by using
> + * swr_get_delay().
> + *
> + * The following code demonstrates the conversion loop assuming the parameters
> + * from above and caller-defined functions get_input() and handle_output():
> + * @code
> + * uint8_t **input;
> + * int in_linesize, in_samples;
> + *
> + * while (get_input(&input, &in_linesize, &in_samples)) {
> + *     uint8_t *output
> + *     int out_linesize;
> + *     int out_samples = av_rescale_rnd(swr_get_delay(swr, 48000) +
> + *                                      in_samples, 44100, 48000, AV_ROUND_UP);
> + *     av_samples_alloc(&output, &out_linesize, 2, out_samples,
> + *                      AV_SAMPLE_FMT_S16, 0);

If out_linesize can be NULL, we can simplify that example (and remove as
well in_linesize). AFAIK it was in the example because lavr actually needs
that duplicated information. lswr looks smarter, and doesn't need it. If
you think the user might want such information, I'd better mention
av_get_bytes_per_sample() in the doxy.

OTOH, some clarifications about the out_samples computation would be
welcome; for example I'm curious in what case you would want to get a
delay with a parameter different than the output sample rate (though, that
is quiet unrelated to this example).

> + *     out_samples = swr_convert(swr, &output, out_samples,
> + *                                      input, in_samples);
> + *     handle_output(output, out_linesize, out_samples);
> + *     av_freep(&output);
> + *  }
> + *  @endcode
> + *
> + *  When the conversion is finished and the FIFOs are flushed if required, the

The "if required" makes the sentence hard to understand here. I'd suggest
to break it, maybe "When the conversion is finished, the conversion
context and everything associated with it must be freed with swr_free().
There will be no memory leak if the data is not completely flushed before
swr_free()."

> + *  conversion context and everything associated with it must be freed with
> + *  swr_free().
> + */
>  
>  #include <inttypes.h>

unrelated: stdint.h is not enough?

>  #include "libavutil/samplefmt.h"
> @@ -217,4 +282,8 @@ const char *swresample_configuration(void);
>   */
>  const char *swresample_license(void);
>  
> +/**
> + * @}
> + */
> +
>  #endif /* SWRESAMPLE_SWRESAMPLE_H */

Thanks a lot for the patch, apply anytime you think it's OK.

-- 
Clément B.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 490 bytes
Desc: not available
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20121120/bca38c24/attachment.asc>