From 22e77e44ddf53408e2e374a33ef04b883748f09b Mon Sep 17 00:00:00 2001 From: Diego Biurrun Date: Wed, 25 Feb 2009 19:10:39 +0000 Subject: [PATCH] spelling/wording/grammar cosmetics Originally committed as revision 17589 to svn://svn.ffmpeg.org/ffmpeg/trunk --- libavformat/avformat.h | 109 ++++++++++++++++++++--------------------- 1 file changed, 54 insertions(+), 55 deletions(-) diff --git a/libavformat/avformat.h b/libavformat/avformat.h index 7bc20c01ec..c454824458 100644 --- a/libavformat/avformat.h +++ b/libavformat/avformat.h @@ -79,24 +79,24 @@ typedef struct { typedef struct AVMetadata AVMetadata; /** - * gets a metadata element with matching key. - * @param prev set to the previous matching element to find the next. - * @param flags allows case as well as suffix insensitive comparisons. - * @return found tag or NULL, changing key or value leads to undefined behavior. + * Gets a metadata element with matching key. + * @param prev Set to the previous matching element to find the next. + * @param flags Allows case as well as suffix-insensitive comparisons. + * @return Found tag or NULL, changing key or value leads to undefined behavior. */ AVMetadataTag * av_metadata_get(AVMetadata *m, const char *key, const AVMetadataTag *prev, int flags); /** - * sets the given tag in m, overwriting an existing tag. - * @param key tag key to add to m (will be av_strduped). - * @param value tag value to add to m (will be av_strduped). - * @return >= 0 if success otherwise error code that is <0. + * Sets the given tag in m, overwriting an existing tag. + * @param key tag key to add to m (will be av_strduped) + * @param value tag value to add to m (will be av_strduped) + * @return >= 0 on success otherwise an error code <0 */ int av_metadata_set(AVMetadata **pm, const char *key, const char *value); /** - * Free all the memory allocated for an AVMetadata struct. + * Frees all the memory allocated for an AVMetadata struct. */ void av_metadata_free(AVMetadata **m); @@ -105,19 +105,18 @@ void av_metadata_free(AVMetadata **m); typedef struct AVPacket { /** - * Presentation timestamp in time_base units. - * This is the time at which the decompressed packet will be presented - * to the user. + * Presentation timestamp in time_base units; the time at which the + * decompressed packet will be presented to the user. * Can be AV_NOPTS_VALUE if it is not stored in the file. * pts MUST be larger or equal to dts as presentation cannot happen before * decompression, unless one wants to view hex dumps. Some formats misuse - * the terms dts and pts/cts to mean something different, these timestamps + * the terms dts and pts/cts to mean something different. Such timestamps * must be converted to true pts/dts before they are stored in AVPacket. */ int64_t pts; /** - * Decompression timestamp in time_base units. - * This is the time at which the packet is decompressed. + * Decompression timestamp in time_base units; the time at which the + * packet is decompressed. * Can be AV_NOPTS_VALUE if it is not stored in the file. */ int64_t dts; @@ -230,7 +229,7 @@ typedef struct AVProbeData { int buf_size; } AVProbeData; -#define AVPROBE_SCORE_MAX 100 ///< Maximum score, half of that is used for file-extension-based detection. +#define AVPROBE_SCORE_MAX 100 ///< maximum score, half of that is used for file-extension-based detection #define AVPROBE_PADDING_SIZE 32 ///< extra allocated bytes at the end of the probe buffer typedef struct AVFormatParameters { @@ -277,7 +276,7 @@ typedef struct AVOutputFormat { const char *long_name; const char *mime_type; const char *extensions; /**< comma-separated filename extensions */ - /** Size of private data so that it can be allocated in the wrapper. */ + /** size of private data so that it can be allocated in the wrapper */ int priv_data_size; /* output support */ enum CodecID audio_codec; /**< default audio codec */ @@ -294,7 +293,7 @@ typedef struct AVOutputFormat { /** * List of supported codec_id-codec_tag pairs, ordered by "better - * choice first". The arrays are all CODEC_ID_NONE terminated. + * choice first". The arrays are all terminated by CODEC_ID_NONE. */ const struct AVCodecTag * const *codec_tag; @@ -315,7 +314,7 @@ typedef struct AVInputFormat { /** Size of private data so that it can be allocated in the wrapper. */ int priv_data_size; /** - * Tell if a given file has a chance of being parsed by this format. + * Tell if a given file has a chance of being parsed as this format. * The buffer provided is guaranteed to be AVPROBE_PADDING_SIZE bytes * big so you do not have to check for that unless you need more. */ @@ -338,9 +337,9 @@ typedef struct AVInputFormat { /** * Seek to a given timestamp relative to the frames in * stream component stream_index. - * @param stream_index must not be -1 - * @param flags selects which direction should be preferred if no exact - * match is available + * @param stream_index Must not be -1. + * @param flags Selects which direction should be preferred if no exact + * match is available. * @return >= 0 on success (but not necessarily the new offset) */ int (*read_seek)(struct AVFormatContext *, @@ -418,11 +417,11 @@ typedef struct AVStream { int id; /**< format-specific stream ID */ AVCodecContext *codec; /**< codec context */ /** - * Real base frame rate of the stream. - * This is the lowest frame rate with which all timestamps can be + * Real base framerate of the stream. + * This is the lowest framerate with which all timestamps can be * represented accurately (it is the least common multiple of all - * frame rates in the stream). Note, this value is just a guess! - * For example if the time base is 1/90000 and all frames have either + * framerates in the stream). Note, this value is just a guess! + * For example, if the time base is 1/90000 and all frames have either * approximately 3600 or 1800 timer ticks, then r_frame_rate will be 50/1. */ AVRational r_frame_rate; @@ -436,7 +435,7 @@ typedef struct AVStream { /** * This is the fundamental unit of time (in seconds) in terms * of which frame timestamps are represented. For fixed-fps content, - * time base should be 1/frame rate and timestamp increments should be 1. + * time base should be 1/framerate and timestamp increments should be 1. */ AVRational time_base; int pts_wrap_bits; /**< number of bits in pts (used for wrapping control) */ @@ -596,7 +595,7 @@ typedef struct AVFormatContext { int64_t file_size; /** Decoding: total stream bitrate in bit/s, 0 if not available. Never set it directly if the file_size and the - duration are known as ffmpeg can compute it automatically. */ + duration are known as FFmpeg can compute it automatically. */ int bit_rate; /* av_read_frame() support */ @@ -622,12 +621,12 @@ typedef struct AVFormatContext { int loop_output; int flags; -#define AVFMT_FLAG_GENPTS 0x0001 ///< Generate pts if missing even if it requires parsing future frames. +#define AVFMT_FLAG_GENPTS 0x0001 ///< Generate missing pts even if it requires parsing future frames. #define AVFMT_FLAG_IGNIDX 0x0002 ///< Ignore index. #define AVFMT_FLAG_NONBLOCK 0x0004 ///< Do not block when reading packets from input. int loop_input; - /** Decoding: size of data to probe; encoding: unused. */ + /** decoding: size of data to probe; encoding: unused. */ unsigned int probesize; /** @@ -659,8 +658,8 @@ typedef struct AVFormatContext { enum CodecID subtitle_codec_id; /** - * Maximum amount of memory in bytes to use per stream for the index. - * If the needed index exceeds this size, entries will be discarded as + * Maximum amount of memory in bytes to use for the index of each stream. + * If the index exceeds this size, entries will be discarded as * needed to maintain a smaller size. This can lead to slower or less * accurate seeking (depends on demuxer). * Demuxers for which a full in-memory index is mandatory will ignore @@ -711,22 +710,22 @@ extern AVOutputFormat *first_oformat; /** * If f is NULL, returns the first registered input format, - * if f is non-NULL, returns the next registered input format after f, + * if f is non-NULL, returns the next registered input format after f * or NULL if f is the last one. */ AVInputFormat *av_iformat_next(AVInputFormat *f); /** * If f is NULL, returns the first registered output format, - * if f is non-NULL, returns the next registered output format after f, + * if f is non-NULL, returns the next registered output format after f * or NULL if f is the last one. */ AVOutputFormat *av_oformat_next(AVOutputFormat *f); enum CodecID av_guess_image2_codec(const char *filename); -/* XXX: use automatic init with either ELF sections or C file parser */ -/* modules */ +/* XXX: Use automatic init with either ELF sections or C file parser */ +/* modules. */ /* utils.c */ void av_register_input_format(AVInputFormat *format); @@ -863,7 +862,7 @@ AVFormatContext *avformat_alloc_context(void); /** * Read packets of a media file to get stream information. This * is useful for file formats with no headers such as MPEG. This - * function also computes the real frame rate in case of MPEG-2 repeat + * function also computes the real framerate in case of MPEG-2 repeat * frame mode. * The logical file position is not changed by this function; * examined packets may be buffered for later processing. @@ -899,7 +898,7 @@ int av_read_packet(AVFormatContext *s, AVPacket *pkt); * then it contains one frame. * * pkt->pts, pkt->dts and pkt->duration are always set to correct - * values in AVStream.timebase units (and guessed if the format cannot + * values in AVStream.time_base units (and guessed if the format cannot * provide them). pkt->pts can be AV_NOPTS_VALUE if the video format * has B-frames, so it is better to rely on pkt->dts if you do not * decompress the payload. @@ -909,7 +908,7 @@ int av_read_packet(AVFormatContext *s, AVPacket *pkt); int av_read_frame(AVFormatContext *s, AVPacket *pkt); /** - * Seek to the key frame at timestamp. + * Seek to the keyframe at timestamp. * 'timestamp' in 'stream_index'. * @param stream_index If stream_index is (-1), a default * stream is selected, and timestamp is automatically converted @@ -928,36 +927,36 @@ int av_seek_frame(AVFormatContext *s, int stream_index, int64_t timestamp, * can be presented successfully will be closest to ts and within min/max_ts. * Active streams are all streams that have AVStream.discard < AVDISCARD_ALL. * - * if flags contain AVSEEK_FLAG_BYTE then all timestamps are in byte and + * If flags contain AVSEEK_FLAG_BYTE, then all timestamps are in bytes and * are the file position (this may not be supported by all demuxers). - * if flags contain AVSEEK_FLAG_FRAME then all timestamps are in frames + * If flags contain AVSEEK_FLAG_FRAME, then all timestamps are in frames * in the stream with stream_index (this may not be supported by all demuxers). - * else all timestamps are in units of the stream selected by stream_index or - * if stream_index is -1, AV_TIME_BASE units. - * if flags contain AVSEEK_FLAG_ANY then non keyframes are treated as + * Otherwise all timestamps are in units of the stream selected by stream_index + * or if stream_index is -1, in AV_TIME_BASE units. + * If flags contain AVSEEK_FLAG_ANY, then non-keyframes are treated as * keyframes (this may not be supported by all demuxers). * - * @param stream_index index of the stream which is used as timebase reference. + * @param stream_index index of the stream which is used as time base reference * @param min_ts smallest acceptable timestamp * @param ts target timestamp * @param max_ts largest acceptable timestamp * @param flags flags * @returns >=0 on success, error code otherwise * - * @NOTE this is part of the new seek API which is still under construction - * thus do not use this yet it may change any time, dont expect ABI - * compatibility yet! + * @NOTE This is part of the new seek API which is still under construction. + * Thus do not use this yet. It may change at any time, do not expect + * ABI compatibility yet! */ int avformat_seek_file(AVFormatContext *s, int stream_index, int64_t min_ts, int64_t ts, int64_t max_ts, int flags); /** - * Start playing a network based stream (e.g. RTSP stream) at the + * Start playing a network-based stream (e.g. RTSP stream) at the * current position. */ int av_read_play(AVFormatContext *s); /** - * Pause a network based stream (e.g. RTSP stream). + * Pause a network-based stream (e.g. RTSP stream). * * Use av_read_play() to resume it. */ @@ -1035,7 +1034,7 @@ int av_index_search_timestamp(AVStream *st, int64_t timestamp, int flags); /** * Ensures the index uses less memory than the maximum specified in - * AVFormatContext.max_index_size, by discarding entries if it grows + * AVFormatContext.max_index_size by discarding entries if it grows * too large. * This function is not part of the public API and should only be called * by demuxers. @@ -1116,7 +1115,7 @@ int av_write_frame(AVFormatContext *s, AVPacket *pkt); * 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 + * If the packets are already correctly interleaved, the application should * call av_write_frame() instead as it is slightly faster. It is also important * to keep in mind that completely non-interleaved input will need huge amounts * of memory to interleave with this, so it is preferable to interleave at the @@ -1133,7 +1132,7 @@ int av_interleaved_write_frame(AVFormatContext *s, AVPacket *pkt); * Interleave a packet per dts in an output media file. * * Packets with pkt->destruct == av_destruct_packet will be freed inside this - * function, so they cannot be used after it, note calling av_free_packet() + * function, so they cannot be used after it. Note that calling av_free_packet() * on them is still safe. * * @param s media file handle @@ -1172,7 +1171,7 @@ attribute_deprecated int parse_image_size(int *width_ptr, int *height_ptr, const char *str); /** - * Converts frame rate from string to a fraction. + * Converts framerate from a string to a fraction. * @deprecated Use av_parse_video_frame_rate instead. */ attribute_deprecated int parse_frame_rate(int *frame_rate, int *frame_rate_base, @@ -1225,7 +1224,7 @@ void ffm_set_write_index(AVFormatContext *s, int64_t pos, int64_t file_size); int find_info_tag(char *arg, int arg_size, const char *tag1, const char *info); /** - * Returns in 'buf' the path with '%d' replaced by number. + * Returns in 'buf' the path with '%d' replaced by a number. * * Also handles the '%0nd' format where 'n' is the total number * of digits and '%%'.