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

[Reimar Döffinger]

On Sun, May 02, 2010 at 01:51:19PM +0200, Cyril Russo wrote:
> 
> >While I don't object to any clarification, I'd like to point out that this
> >is already documented:
> >@param[out] picture
> >picture is only an output parameter, not input.
> 
> I'm sorry to point out that this not clear at all.
> There is a difference between being an output parameter and
> allocating the parameter's internal buffers.
> Clearly, I understand the picture will be written onto (that's what
> output parameter means I think), and not that it'll be allocated by
> the method.

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.

>   * @param avctx the codec context
>   * @param[out] picture The AVFrame in which the decoded video frame will be stored.
> + *                     The function allocate the frame (don't call avpicture_alloc beforehand).

"allocates", and "do not".
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).
There is also the option of slightly changing the API so it must be zeroed and then
checking the pointer being NULL, but I am unsure that is a good idea.