[Ffmpeg-devel] [PATCH] avcodec_open Doxygen docs

[Panagiotis Issaris]

Hi,

Michael Niedermayer schreef:
> On Wed, Feb 21, 2007 at 04:45:27PM +0100, Panagiotis Issaris wrote:
>   
>> Panagiotis Issaris schreef:
>>     
>>> The attached patch extends the Doxygen documentation for the
>>> avcodec_open() function.
>>>
>>>
>>>  avcodec.h |    4 ----
>>>  utils.c   |   13 +++++++++++++
>>>  2 files changed, 13 insertions(+), 4 deletions(-)
>>>
>>> With friendly regards,
>>> Takis
>>>       
>> Here's an updated patch which adds more Doxygen documentation. It also
>> adds an inline little piece of example code. I am not sure if it is a
>> bit to distracting to have the example code inline though...
>>     
>
> yes, please put * infront of the lines
>   
Fixed.
> [...]
>   
>> +/**
>> + * Initialize the AVCodecContext to use the given AVCodec. Prior to using this
>> + * function the context has to be allocated and the codec retrieved using
>> + * avcodec_find_decoder_by_name, avcodec_find_encoder_by_name,
>> + * avcodec_find_decoder or avcodec_find_encoder.
>>     
>
> how the user gets the AVCodec doesnt matter, it will also work fine if
> the user builds his own AVCodec and uses that
>   
I rephrased it like this:
...
2594  * function the context has to be allocated.
2595  *
2596  * The functions avcodec_find_decoder_by_name(), 
avcodec_find_encoder_by_name(),
2597  * avcodec_find_decoder() and avcodec_find_encoder() provide an 
easy way for
2598  * retrieving a codec.


>   
>> + *
>> + * @warning This function is not thread save!
>> + *
>> + * @code
>> +codec = avcodec_find_decoder(CODEC_ID_H264);
>> +if (!codec)
>> +    exit(1);
>> +
>> +context = avcodec_alloc_context();
>> +
>> +if (avcodec_open(context, codec) < 0)
>> +    exit(1);
>> + * @endcode
>> + *
>> + * @param avctx The context which will be setup to use the given codec.
>> + * @param codec The codec to use within the context.
>> + * @return Zero on success, -1 on error.
>>     
>
>   
>> =0 on success <0 on error, and this is true for almost all functions
>>     
> there is no gurantee that future lavc implementations might not return
> a richer set of error codes or success codes
>   
Fixed.
In fact, I'd like to start adding such error codes. Where should they 
go? avcodec.h or some separate file
like av_error.h?
> [...]
>   
>> -/* decode an audio frame. return -1 if error, otherwise return the
>> -   *number of bytes used. If no frame could be decompressed,
>> -   *frame_size_ptr is zero. Otherwise, it is the decompressed frame
>> -   *size in BYTES. */
>> +/**
>> + * Decodes an audio frame.
>> + * The avcodec_decode_audio2 function decodes a frame of audio from the input buffer
>> + * \p buf of size \p buf_size. To decode it, it makes use of the audiocodec
>> + * which was coupled with the AVCodecContext. The resulting decoded frame is
>> + * stored in output buffer \p samples.
>> + * If no frame could be decompressed, frame_size_ptr is zero. Otherwise, it is
>> + * the decompressed frame size in \e bytes.
>> + *
>> + * @warning You \e must set frame_size_ptr to the allocated size before calling avcodec_decode_audio2.
>> + *
>>     
>
> the the allocated size of what?
>   
Size of the output buffer?
> and the 32/64 input padding applies to audio too!
>   
Fixed.

Does the output and input buffer also have to be aligned on a 16 byte 
boundary for avcodec_decode_video()?

Thanks for reviewing!

With friendly regards,
Takis
-------------- next part --------------
A non-text attachment was scrubbed...
Name: pi-20070222T004650-ffmpeg-avcodec_dox4.diff
Type: text/x-patch
Size: 15832 bytes
Desc: not available
URL: <http://lists.mplayerhq.hu/pipermail/ffmpeg-devel/attachments/20070222/b68d95e7/attachment.bin>