[FFmpeg-devel] [PATCH] lavc/avcodec.h: document bitstream filter API

[Lou Logan]

This is only a review of the language.

On Wed, 26 Jun 2013 19:01:19 +0200, Stefano Sabatini wrote:

> ---
>  libavcodec/avcodec.h | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 49 insertions(+)
> 
> diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
> index c38b46d..12a11aa 100644
> --- a/libavcodec/avcodec.h
> +++ b/libavcodec/avcodec.h
> @@ -4620,14 +4620,63 @@ typedef struct AVBitStreamFilter {
>      struct AVBitStreamFilter *next;
>  } AVBitStreamFilter;
>  
> +/**
> + * Register the bitstream filter bsf.
> + *
> + * The filter will be accessible to the appliclation code through

typo: application

> + * av_bitstream_filter_next() or can be directly initialized with
> + * av_bitstream_filter_init().
> + *
> + * @see avcodec_register_all()
> + */
>  void av_register_bitstream_filter(AVBitStreamFilter *bsf);
> +
> +/**
> + * Create and initialize a bitstream filter context given a bitstream
> + * filter name.
> + *
> + * The returned context must be freed with av_bitstream_filter_close().
> + *
> + * @param name the name of the bitstream filter

Can this be spaced so it is easier to read? Also the others below are
also spaced.

@param name    the name of the bitstream filter

> + * @return a bitstream context if a corresponding filter was found and
> + * successfully initialized, NULL otherwise.
> + */
>  AVBitStreamFilterContext *av_bitstream_filter_init(const char *name);
> +
> +/**
> + * Filter bitstream.
> + *
> + * This function filters the buffer buf with size buf_size, and put the
> + * filtered buffer in the buffer pointed to by poutbuf.

s/put/places

> + *
> + * The output buffer must be freed by the caller.
> + *
> + * @param bsfc            bitstream filter context created by av_bitstream_filter_init()
> + * @param avctx           AVCodecContext accessed by the filter, may be NULL
> + * @param args            arguments which specify the filter behavior or configuration
> + * @param poutbuf         pointer which is updated to point to the filtered buffer
> + * @param poutbuf_size    pointer which is updated to the filtered buffer size in bytes
> + * @param buf             buffer containing the data to filter
> + * @param buf_size        size in bytes of buf
> + * @param keyframe        set to non-zero if the buffer to filter corresponds to a key-frame packet data
> + * @return >= 0 in case of success, a negative code in case of failure

@return >= 0 in case of success, or a negative code in case of failure

> + */
>  int av_bitstream_filter_filter(AVBitStreamFilterContext *bsfc,
>                                 AVCodecContext *avctx, const char *args,
>                                 uint8_t **poutbuf, int *poutbuf_size,
>                                 const uint8_t *buf, int buf_size, int keyframe);
> +
> +/**
> + * Release bitstream filter context bsf, which was created with
> + * av_bitstream_filter_init().
> + */
>  void av_bitstream_filter_close(AVBitStreamFilterContext *bsf);
>  
> +/**
> + * If f is NULL, return the first registered bitstream filter,
> + * if f is non-NULL, return the next registered bitstream filter
> + * after f, or NULL if f is the last one.

Excuse my ignorance, but what does "one" refer to?

> + */
>  AVBitStreamFilter *av_bitstream_filter_next(AVBitStreamFilter *f);
>  
>  /* memory */