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

[Stefano Sabatini]

On date Thursday 2013-07-04 21:03:21 +0200, Michael Niedermayer encoded:
> On Thu, Jul 04, 2013 at 07:35:31PM +0200, Stefano Sabatini wrote:
> > On date Friday 2013-06-28 17:06:42 -0800, Lou Logan encoded:
> > > 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(+)
> > [...]  
> > > > +/**
> > > > + * 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?
> > 
> > The last registered bitstream filter (text copied and edited from the
> > other corresponding doxies).
> > 
> > Updated with a more detailed discussion of the filter() return codes.
> > -- 
> > FFmpeg = Fascinating and Fancy Merciful Peaceless Enchanting Gorilla
> 
> >  avcodec.h |   62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 62 insertions(+)
> > 698259d9a72425f995dbcc275c503a61437f5294  0003-lavc-avcodec.h-document-bitstream-filter-API.patch
> > From da825e46e9cf9f9c644970d89433b8e32857ef99 Mon Sep 17 00:00:00 2001
> > From: Stefano Sabatini <stefasab at gmail.com>
> > Date: Wed, 26 Jun 2013 18:57:09 +0200
> > Subject: [PATCH] lavc/avcodec.h: document bitstream filter API
> > 
> > ---
> >  libavcodec/avcodec.h | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 62 insertions(+)
> > 
> > diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
> > index 3f3352f..7568e1d 100644
> > --- a/libavcodec/avcodec.h
> > +++ b/libavcodec/avcodec.h
> > @@ -4620,14 +4620,76 @@ typedef struct AVBitStreamFilter {
> >      struct AVBitStreamFilter *next;
> >  } AVBitStreamFilter;
> >  
> > +/**
> > + * Register the bitstream filter bsf.
> 
> i would avoid refering to the variable name from the prototype here in
> the first line
> 
> What does the function do?
> Register a bitstream filter

Works for me.

> > + *
> > + * The filter will be accessible to the application code through
> > + * 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
> > + * @return a bitstream context if a corresponding filter was found and
> > + * successfully initialized, NULL otherwise.
> 
> "a bitstream context" ?

What's the question?

> 
> > + */
> >  AVBitStreamFilterContext *av_bitstream_filter_init(const char *name);
> > +
> > +/**
> > + * Filter bitstream.
> > + *
> > + * This function filters the buffer buf with size buf_size, and places the
> > + * filtered buffer in the buffer pointed to by poutbuf.
> > + *
> > + * 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.
> > + *                        This must be the context of the encoder of the output stream
> > + *                        the packet is sent to.
> > + * @param args            arguments which specify the filter 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, or a negative code in case of failure.
> 
> negaive error code
> 
> 
> > + *
> > + * If the return value is positive, an output buffer is allocated
> > + * *poutbuf, and is distinct from the input buffer.
> > + *
> > + * In case the return value is 0, the output output buffer is not
> > + * allocated, the output buffer should be considered identical to the
> > + * input buffer or in case *poutbuf was set it points to the input
> > + * buffer (not necessarily to the starting address).
> > + */
> >  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().
> > + *
> > + * @param bsf the bitstream filter context created with
> > + * av_bitstream_filter_init(), can be NULL
> > + */
> >  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.
> 
> Can be used to iterate over all registered bitstream filters
> [example here maybe]
> 
> [...]
> 
> no more comments from me

git gt Fixed, will push it tomorrow unless I see more comments (Lou?).
-- 
FFmpeg = Free and Funny Muttering Proud Evil Gymnast
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0002-lavc-avcodec.h-document-bitstream-filter-API.patch
Type: text/x-diff
Size: 3737 bytes
Desc: not available
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20130705/45196612/attachment.bin>