Update of /cvsroot/ffmpeg/ffmpeg/libavformat
In directory mail:/var2/tmp/cvs-serv11014
Modified Files:
utils.c
Log Message:
part of the 'libavformat/utils.c doxygen documentation' patch by (Daniel Kristjansson: danielk, cat nyu edu)
Index: utils.c
===================================================================
RCS file: /cvsroot/ffmpeg/ffmpeg/libavformat/utils.c,v
retrieving revision 1.153
retrieving revision 1.154
diff -u -d -r1.153 -r1.154
--- utils.c 27 Jun 2005 20:54:36 -0000 1.153
+++ utils.c 28 Jun 2005 12:55:08 -0000 1.154
@@ -21,8 +21,16 @@
#undef NDEBUG
#include <assert.h>
+/**
+ * @file libavformat/utils.c
+ * Various utility functions for using ffmpeg library.
+ */
+
+/** head of registered input format linked list. */
AVInputFormat *first_iformat = NULL;
+/** head of registered output format linked list. */
AVOutputFormat *first_oformat = NULL;
+/** head of registered image format linked list. */
AVImageFormat *first_image_format = NULL;
void av_register_input_format(AVInputFormat *format)
@@ -131,7 +139,7 @@
}
/**
- * guesses the codec id based upon muxer and filename.
+ * Guesses the codec id based upon muxer and filename.
*/
enum CodecID av_guess_codec(AVOutputFormat *fmt, const char *short_name,
const char *filename, const char *mime_type, enum CodecType type){
@@ -150,6 +158,9 @@
return CODEC_ID_NONE;
}
+/**
+ * finds AVInputFormat based on input format's short name.
+ */
AVInputFormat *av_find_input_format(const char *short_name)
{
AVInputFormat *fmt;
@@ -163,7 +174,7 @@
/* memory handling */
/**
- * Default packet destructor
+ * Default packet destructor.
*/
void av_destruct_packet(AVPacket *pkt)
{
@@ -274,7 +285,9 @@
return size;
}
-/* get data from the fifo (return -1 if not enough data) */
+/**
+ * Get data from the fifo (returns -1 if not enough data).
+ */
int fifo_read(FifoBuffer *f, uint8_t *buf, int buf_size, uint8_t **rptr_ptr)
{
uint8_t *rptr;
@@ -307,6 +320,9 @@
return 0;
}
+/**
+ * Resizes a FIFO.
+ */
void fifo_realloc(FifoBuffer *f, unsigned int new_size){
unsigned int old_size= f->end - f->buffer;
@@ -385,7 +401,9 @@
return get_frame_filename(buf, sizeof(buf), filename, 1);
}
-/* guess file format */
+/**
+ * Guess file format.
+ */
AVInputFormat *av_probe_input_format(AVProbeData *pd, int is_opened)
{
AVInputFormat *fmt1, *fmt;
@@ -416,9 +434,8 @@
/* input media file */
/**
- * open a media file from an IO stream. 'fmt' must be specified.
+ * Open a media file from an IO stream. 'fmt' must be specified.
*/
-
static const char* format_to_name(void* ptr)
{
AVFormatContext* fc = (AVFormatContext*) ptr;
@@ -438,6 +455,10 @@
return ic;
}
+/**
+ * Allocates all the structures needed to read an input stream.
+ * This does not open the needed codecs for decoding the stream[s].
+ */
int av_open_input_stream(AVFormatContext **ic_ptr,
ByteIOContext *pb, const char *filename,
AVInputFormat *fmt, AVFormatParameters *ap)
@@ -486,6 +507,7 @@
return err;
}
+/** Size of probe buffer, for guessing file type from file contents. */
#define PROBE_BUF_SIZE 2048
/**
@@ -594,8 +616,10 @@
/*******************************************************/
/**
- * Read a transport packet from a media file. This function is
- * absolete and should never be used. Use av_read_frame() instead.
+ * Read a transport packet from a media file.
+ *
+ * This function is absolete and should never be used.
+ * Use av_read_frame() instead.
*
* @param s media file handle
* @param pkt is filled
@@ -608,7 +632,9 @@
/**********************************************************/
-/* get the number of samples of an audio frame. Return (-1) if error */
+/**
+ * Get the number of samples of an audio frame. Return (-1) if error.
+ */
static int get_audio_frame_size(AVCodecContext *enc, int size)
{
int frame_size;
@@ -647,7 +673,9 @@
}
-/* return the frame duration in seconds, return 0 if not available */
+/**
+ * Return the frame duration in seconds, return 0 if not available.
+ */
static void compute_frame_duration(int *pnum, int *pden, AVStream *st,
AVCodecParserContext *pc, AVPacket *pkt)
{
@@ -906,7 +934,9 @@
}
/**
- * Return the next frame of a stream. The returned packet is valid
+ * Return the next frame of a stream.
+ *
+ * The returned packet is valid
* until the next av_read_frame() or until av_close_input_file() and
* must be freed with av_free_packet. For video, the packet contains
* exactly one frame. For audio, it contains an integer number of
@@ -920,7 +950,7 @@
* has B frames, so it is better to rely on pkt->dts if you do not
* decompress the payload.
*
- * Return 0 if OK, < 0 if error or end of file.
+ * @return 0 if OK, < 0 if error or end of file.
*/
int av_read_frame(AVFormatContext *s, AVPacket *pkt)
{
@@ -972,7 +1002,9 @@
return 0;
}
-/* flush the frame reader */
+/**
+ * Flush the frame reader.
+ */
static void av_read_frame_flush(AVFormatContext *s)
{
AVStream *st;
@@ -1004,8 +1036,9 @@
}
/**
- * updates cur_dts of all streams based on given timestamp and AVStream.
- * stream ref_st unchanged, others set cur_dts in their native timebase
+ * Updates cur_dts of all streams based on given timestamp and AVStream.
+ *
+ * Stream ref_st unchanged, others set cur_dts in their native timebase
* only needed for timestamp wrapping or if (dts not set and pts!=dts)
* @param timestamp new dts expressed in time_base of param ref_st
* @param ref_st reference stream giving time_base of param timestamp
@@ -1023,7 +1056,8 @@
}
/**
- * add a index entry into a sorted list updateing if it is already there.
+ * Add a index entry into a sorted list updateing if it is already there.
+ *
* @param timestamp timestamp in the timebase of the given stream
*/
int av_add_index_entry(AVStream *st,
@@ -1069,7 +1103,9 @@
return index;
}
-/* build an index for raw streams using a parser */
+/**
+ * build an index for raw streams using a parser.
+ */
static void av_build_index_raw(AVFormatContext *s)
{
AVPacket pkt1, *pkt = &pkt1;
@@ -1093,8 +1129,11 @@
}
}
-/* return TRUE if we deal with a raw stream (raw codec data and
- parsing needed) */
+/**
+ * Returns TRUE if we deal with a raw stream.
+ *
+ * Raw codec data and parsing needed.
+ */
static int is_raw_stream(AVFormatContext *s)
{
AVStream *st;
@@ -1108,7 +1147,7 @@
}
/**
- * gets the index for a specific timestamp.
+ * Gets the index for a specific timestamp.
* @param flags if AVSEEK_FLAG_BACKWARD then the returned index will correspond to
* the timestamp which is <= the requested one, if backward is 0
* then it will be >=
@@ -1406,7 +1445,11 @@
/*******************************************************/
-/* return TRUE if the stream has accurate timings for at least one component */
+/**
+ * Returns TRUE if the stream has accurate timings in any stream.
+ *
+ * @return TRUE if the stream has accurate timings for at least one component.
+ */
static int av_has_timings(AVFormatContext *ic)
{
int i;
@@ -1421,8 +1464,11 @@
return 0;
}
-/* estimate the stream timings from the one of each components. Also
- compute the global bitrate if possible */
+/**
+ * Estimate the stream timings from the one of each components.
+ *
+ * Also computes the global bitrate if possible.
+ */
static void av_update_stream_timings(AVFormatContext *ic)
{
int64_t start_time, start_time1, end_time, end_time1;
@@ -1713,7 +1759,7 @@
#define MAX_READ_SIZE 5000000
/* maximum duration until we stop analysing the stream */
-#define MAX_STREAM_DURATION ((int)(AV_TIME_BASE * 1.0))
+#define MAX_STREAM_DURATION ((int)(AV_TIME_BASE * 2.0))
/**
* Read the beginning of a media file to get stream information. This
@@ -1985,8 +2031,9 @@
}
/**
- * pause a network based stream (e.g. RTSP stream). Use av_read_play()
- * to resume it.
+ * Pause a network based stream (e.g. RTSP stream).
+ *
+ * Use av_read_play() to resume it.
*/
int av_read_pause(AVFormatContext *s)
{
@@ -1996,7 +2043,7 @@
}
/**
- * Close a media file (but not its codecs)
+ * Close a media file (but not its codecs).
*
* @param s media file handle
*/
@@ -2033,10 +2080,11 @@
}
/**
- * Add a new stream to a media file. Can only be called in the
- * read_header function. If the flag AVFMTCTX_NOHEADER is in the
- * format context, then new streams can be added in read_packet too.
+ * Add a new stream to a media file.
*
+ * Can only be called in the read_header() function. If the flag
+ * AVFMTCTX_NOHEADER is in the format context, then new streams
+ * can be added in read_packet too.
*
* @param s media file handle
* @param id file format dependent stream id
@@ -2212,8 +2260,9 @@
}
/**
- * Write a packet to an output media file. The packet shall contain
- * one audio or video frame.
+ * Write a packet to an output media file.
+ *
+ * The packet shall contain one audio or video frame.
*
* @param s media file handle
* @param pkt the packet, which contains the stream_index, buf/buf_size, dts/pts, ...
@@ -2305,8 +2354,9 @@
}
/**
- * Writes a packet to an output media file ensuring correct interleaving.
- * The packet shall contain one audio or video frame.
+ * Writes a packet to an output media file ensuring correct interleaving.
+ *
+ * The packet must contain one audio or video frame.
* If the packets are already correctly interleaved the application should
* call av_write_frame() instead as its slightly faster, its also important
* to keep in mind that completly non interleaved input will need huge amounts
@@ -2351,11 +2401,12 @@
}
/**
- * write the stream trailer to an output media file and and free the
- * file private data.
+ * @brief Write the stream trailer to an output media file and
+ * free the file private data.
*
* @param s media file handle
- * @return 0 if OK. AVERROR_xxx if error. */
+ * @return 0 if OK. AVERROR_xxx if error.
+ */
int av_write_trailer(AVFormatContext *s)
{
int ret, i;
@@ -2473,6 +2524,9 @@
{ "4cif", 704, 576, 0, 0 },
};
+/**
+ * parses width and height out of string str.
+ */
int parse_image_size(int *width_ptr, int *height_ptr, const char *str)
{
int i;
@@ -2501,6 +2555,13 @@
return 0;
}
+/**
+ * Converts frame rate from string to a fraction.
+ *
+ * First we try to get an exact integer or fractional frame rate.
+ * If this fails we convert the frame rate to a double and return
+ * an approximate fraction using the DEFAULT_FRAME_RATE_BASE.
+ */
int parse_frame_rate(int *frame_rate, int *frame_rate_base, const char *arg)
{
int i;
@@ -2537,14 +2598,20 @@
return 0;
}
-/* Syntax:
+/**
+ * Converts date string to number of seconds since Jan 1st, 1970.
+ *
+ * @code
+ * Syntax:
* - If not a duration:
* [{YYYY-MM-DD|YYYYMMDD}]{T| }{HH[:MM[:SS[.m...]]][Z]|HH[MM[SS[.m...]]][Z]}
* Time is localtime unless Z is suffixed to the end. In this case GMT
* Return the date in micro seconds since 1970
- * - If duration:
+ *
+ * - If a duration:
* HH[:MM[:SS[.m...]]]
* S+[.m...]
+ * @endcode
*/
int64_t parse_date(const char *datestr, int duration)
{
@@ -2654,8 +2721,12 @@
return negative ? -t : t;
}
-/* syntax: '?tag1=val1&tag2=val2...'. Little URL decoding is done. Return
- 1 if found */
+/**
+ * Attempts to find a specific tag in a URL.
+ *
+ * syntax: '?tag1=val1&tag2=val2...'. Little URL decoding is done.
+ * Return 1 if found.
+ */
int find_info_tag(char *arg, int arg_size, const char *tag1, const char *info)
{
const char *p;
@@ -2695,9 +2766,12 @@
return 0;
}
-/* Return in 'buf' the path with '%d' replaced by number. Also handles
- the '%0nd' format where 'n' is the total number of digits and
- '%%'. Return 0 if OK, and -1 if format error */
+/**
+ * Returns in 'buf' the path with '%d' replaced by number.
+ *
+ * Also handles the '%0nd' format where 'n' is the total number
+ * of digits and '%%'. Return 0 if OK, and -1 if format error.
+ */
int get_frame_filename(char *buf, int buf_size,
const char *path, int number)
{
@@ -2887,7 +2961,8 @@
}
/**
- * Set the pts for a given stream
+ * Set the pts for a given stream.
+ *
* @param s stream
* @param pts_wrap_bits number of bits effectively used by the pts
* (used for wrap control, 33 is the value for MPEG)
@@ -2905,8 +2980,9 @@
/* fraction handling */
/**
- * f = val + (num / den) + 0.5. 'num' is normalized so that it is such
- * as 0 <= num < den.
+ * f = val + (num / den) + 0.5.
+ *
+ * 'num' is normalized so that it is such as 0 <= num < den.
*
* @param f fractional number
* @param val integer value
@@ -2925,7 +3001,9 @@
f->den = den;
}
-/* set f to (val + 0.5) */
+/**
+ * Set f to (val + 0.5).
+ */
void av_frac_set(AVFrac *f, int64_t val)
{
f->val = val;
@@ -2933,7 +3011,7 @@
}
/**
- * Fractionnal addition to f: f = f + (incr / f->den)
+ * Fractionnal addition to f: f = f + (incr / f->den).
*
* @param f fractional number
* @param incr increment, can be positive or negative
@@ -2972,7 +3050,9 @@
img_fmt->next = NULL;
}
-/* guess image format */
+/**
+ * Guesses image format based on data in the image.
+ */
AVImageFormat *av_probe_image_format(AVProbeData *pd)
{
AVImageFormat *fmt1, *fmt;
@@ -2992,6 +3072,9 @@
return fmt;
}
+/**
+ * Guesses image format based on file name extensions.
+ */
AVImageFormat *guess_image_format(const char *filename)
{
AVImageFormat *fmt1;
