[FFmpeg-devel] [PATCH] Explicit avcodec_decode_video2 documentation about picture allocation

[Reimar Döffinger]

On Sun, May 02, 2010 at 03:20:47PM +0200, Cyril Russo wrote:
> >I didn't claim it to be obvious, however being only output parameter
> >(the whole AVFrame) means the function will not read from it - with
> >that promise there's no way it could know it is allocated.
> I'm not sure the code does what you're saying. Since I haven't
> checked all video decoders, I will consider to be the case.
> Anyway, it's not consistent with the rest of the api, for example
> with avcodec_decode_audio where "samples" is not allocated by the
> function, but marked as output too.

I think you're a bit confused there.
avcodec_decode_audio3 has an argument
int16_t *samples
Obviously it can't allocate "samples" (an array of int16_t) itself,
because it would have no way of returning the pointer, output parameter
means that *samples is never read but only written to.

avcodec_decode_video2 has an argument
AVFrame *picture
Exactly the same applies here: 
The function can't allocate "picture" (an AVFrame) since it could
not return the pointer, output parameter just means it will not
read (the original values of) *picture, it will only write to it.
Not reading from *picture means it can't access the picture->data
passed in to it, so allocating it beforehand makes no sense.

> >But I think it would be more consistent with e.g. the struct documentation to write
> >"Initialized and allocated by libavcodec" (or something better if you can think of anything).
> 
> I'm a bit confused between the mix in AVFrame and AVPicture in the
> API, with the example code converting from the former to the later
> everywhere.
> Adding "Initialized and allocated by libavcodec" to AVFrame struct
> documentation wouldn't improve this, IMHO, since even if you
> allocate with avpicture_alloc, it *does* initialize and allocate by
> libavcodec.

Let me clarify: I meant adding to the function documentation
"*picture is initialized and allocated by this function"
No idea if that is any clearer than your explanation.