[Ffmpeg-devel] [PATCH] avcodec_open Doxygen docs

[Michael Niedermayer]

Hi

On Wed, Feb 21, 2007 at 04:45:27PM +0100, Panagiotis Issaris wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> Hi,
> 
> Panagiotis Issaris schreef:
> > Hi,
> > 
> > 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

[...]
> +/**
> + * 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


> + *
> + * @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


[...]
> -/* 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?

and the 32/64 input padding applies to audio too!
[...]
-- 
Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB

I do not agree with what you have to say, but I'll defend to the death your
right to say it. -- Voltaire
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://lists.mplayerhq.hu/pipermail/ffmpeg-devel/attachments/20070221/560017b7/attachment.pgp>