[Ffmpeg-devel] [PATCH] avcodec_open Doxygen docs

[Michael Niedermayer]

Hi

On Thu, Feb 22, 2007 at 12:50:52AM +0100, Panagiotis Issaris wrote:
[...]
> >>+ *
> >>+ * @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?

see avcodec.h AVERROR*


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

the true alignment requirements depend for every buffer on the cpu that
is if the cpu has no alignment requirements then it all might work fine
with no alignment at all though maybe slower (that again depends on the cpu)

in practice though the bitstream should have 4byte alignment at minimum and
all sample data be it audio or video should be 16byte aligned unless the
cpu doesnt need it (altivec/sse do) that also means if the linesize is not
a multiple of 16 then theres no sense in aligning the buffer start to 16

[...]
> @@ -2493,24 +2493,93 @@ extern AVCodec *first_avcodec;
>  unsigned avcodec_version(void);
>  /* returns LIBAVCODEC_BUILD constant */
>  unsigned avcodec_build(void);
> +
> +/**
> + * Initializes libavcodec.
> + *
> + * @warning This function \e must be called before any other functions.
> + */
>  void avcodec_init(void);

this is not good if taken literally, it should rather be any other libavcodec
function or something similar


> +/**
> + * Find a decoder with a matching codec ID.

my engrish is shitty but something says that this should be "findS"


> + *
> + * @param id CodecID of the requested decoder.
> + * @return An decoder if one was found, NULL otherwise.

and here my feeling says "a decoder"

[...]
> +/**
> + * Sets its fields of the given AVFrame to default values.

s/its/the/


[...]
> +/**
> + * Checks if the given dimension of a picture is valid.
> + *

at this point noone will have learnt what the function does, what is "valid"

because 80000x80000 is valid in some sense ...


[...]
>                           uint8_t *buf, int buf_size);
> +
>  /**

cosmetic :)


> - * Decode an audio frame.
> + * Decodes an audio frame from \p buf into \p samples.
> + * 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 \p avctx using avcodec_open(). The
> + * resulting decoded frame is stored in output buffer \p samples.  If no frame
> + * could be decompressed, \p frame_size_ptr is zero. Otherwise, it is the
> + * decompressed frame size in \e bytes.
> + *
> + * @warning You \e must set \p frame_size_ptr to the allocated size of the
> + * output buffer before calling avcodec_decode_audio2().
> + *
> + * @warning The input buffer must be \c FF_INPUT_BUFFER_PADDING_SIZE larger than
> + * the actual read bytes because some optimized bitstream readers read 32 or 64
> + * bits at once and could read over the end.
>   *
> - * @param avctx the codec context.
> - * @param samples output buffer, 16 byte aligned
> - * @param frame_size_ptr the output buffer size in bytes (you MUST set this to the allocated size before calling avcodec_decode_audio2()), zero if no frame could be compressed
> - * @param buf input buffer, 16 byte aligned
> - * @param buf_size the input buffer size
> - * @return 0 if successful, -1 if not.


> + * @warning The end of the input buffer \p buf should be set to 0 to ensure that
> + * no overreading happens for damaged MPEG streams.

this trick is limited to video i _think_ though of course it does no harm
for audio

[...]

-- 
Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB

Everything should be made as simple as possible, but not simpler.
-- Albert Einstein
-------------- 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/20070222/5e761910/attachment.pgp>