From e36bdf8bf5fd732ca4c6cffd538b8836feecb07d Mon Sep 17 00:00:00 2001 From: Daniel Kristjansson Date: Tue, 28 Jun 2005 12:55:08 +0000 Subject: [PATCH] part of the 'libavformat/utils.c doxygen documentation' patch by (Daniel Kristjansson: danielk, cat nyu edu) Originally committed as revision 4405 to svn://svn.ffmpeg.org/ffmpeg/trunk --- libavformat/utils.c | 183 ++++++++++++++++++++++++++++++++------------ 1 file changed, 133 insertions(+), 50 deletions(-) diff --git a/libavformat/utils.c b/libavformat/utils.c index 5c812651856..d87795822a9 100644 --- a/libavformat/utils.c +++ b/libavformat/utils.c @@ -21,8 +21,16 @@ #undef NDEBUG #include +/** + * @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 @@ AVOutputFormat *guess_stream_format(const char *short_name, const char *filename } /** - * 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 @@ enum CodecID av_guess_codec(AVOutputFormat *fmt, const char *short_name, 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 @@ AVInputFormat *av_find_input_format(const char *short_name) /* memory handling */ /** - * Default packet destructor + * Default packet destructor. */ void av_destruct_packet(AVPacket *pkt) { @@ -274,7 +285,9 @@ int fifo_size(FifoBuffer *f, uint8_t *rptr) 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 @@ int fifo_read(FifoBuffer *f, uint8_t *buf, int buf_size, uint8_t **rptr_ptr) 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 @@ int filename_number_test(const char *filename) 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 @@ AVInputFormat *av_probe_input_format(AVProbeData *pd, int is_opened) /* 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 @@ AVFormatContext *av_alloc_format_context(void) 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 @@ int av_open_input_stream(AVFormatContext **ic_ptr, return err; } +/** Size of probe buffer, for guessing file type from file contents. */ #define PROBE_BUF_SIZE 2048 /** @@ -594,8 +616,10 @@ int av_open_input_file(AVFormatContext **ic_ptr, const char *filename, /*******************************************************/ /** - * 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 @@ int av_read_packet(AVFormatContext *s, AVPacket *pkt) /**********************************************************/ -/* 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 @@ static int get_audio_frame_size(AVCodecContext *enc, int size) } -/* 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 @@ static int av_read_frame_internal(AVFormatContext *s, AVPacket *pkt) } /** - * 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 @@ static int av_read_frame_internal(AVFormatContext *s, AVPacket *pkt) * 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 @@ int av_find_default_stream_index(AVFormatContext *s) return 0; } -/* flush the frame reader */ +/** + * Flush the frame reader. + */ static void av_read_frame_flush(AVFormatContext *s) { AVStream *st; @@ -1004,8 +1036,9 @@ static void av_read_frame_flush(AVFormatContext *s) } /** - * 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 @@ static void av_update_cur_dts(AVFormatContext *s, AVStream *ref_st, int64_t time } /** - * 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 @@ int av_add_index_entry(AVStream *st, 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 @@ static void av_build_index_raw(AVFormatContext *s) } } -/* 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 @@ static int is_raw_stream(AVFormatContext *s) } /** - * 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 @@ int av_seek_frame(AVFormatContext *s, int stream_index, int64_t timestamp, int f /*******************************************************/ -/* 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 @@ static int av_has_timings(AVFormatContext *ic) 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 @@ static int try_decode_frame(AVStream *st, const uint8_t *data, int size) #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 @@ int av_read_play(AVFormatContext *s) } /** - * 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 @@ int av_read_pause(AVFormatContext *s) } /** - * 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 @@ void av_close_input_file(AVFormatContext *s) } /** - * 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 @@ static void truncate_ts(AVStream *st, AVPacket *pkt){ } /** - * 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 @@ static int av_interleave_packet(AVFormatContext *s, AVPacket *out, AVPacket *in, } /** - * 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 @@ int av_interleaved_write_frame(AVFormatContext *s, AVPacket *pkt){ } /** - * 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 @@ static AbvEntry frame_abvs[] = { { "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 @@ int parse_image_size(int *width_ptr, int *height_ptr, const char *str) 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 @@ int parse_frame_rate(int *frame_rate, int *frame_rate_base, const char *arg) 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 @@ int64_t parse_date(const char *datestr, int duration) 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 @@ int find_info_tag(char *arg, int arg_size, const char *tag1, const char *info) 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 @@ void url_split(char *proto, int proto_size, } /** - * 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 @@ void av_set_pts_info(AVStream *s, int pts_wrap_bits, /* 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 @@ void av_frac_init(AVFrac *f, int64_t val, int64_t num, int64_t den) 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 @@ void av_frac_set(AVFrac *f, int64_t val) } /** - * 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 @@ void av_register_image_format(AVImageFormat *img_fmt) 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 @@ AVImageFormat *av_probe_image_format(AVProbeData *pd) return fmt; } +/** + * Guesses image format based on file name extensions. + */ AVImageFormat *guess_image_format(const char *filename) { AVImageFormat *fmt1; -- 2.39.2