mirror of
https://git.ffmpeg.org/ffmpeg.git
synced 2024-12-25 00:32:31 +00:00
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
This commit is contained in:
Daniel Kristjansson
Michael Niedermayer
parent
22e50022f2
commit
e36bdf8bf5
@ -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 @@ 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;
|
||||
|
||||
Loading…
Reference in New Issue
Block a user