From 8c6a326e9f78cd5e7513de51dca28c8690b4e26f Mon Sep 17 00:00:00 2001 From: Moritz Bunkus Date: Tue, 16 Nov 2004 09:53:09 +0000 Subject: [PATCH] Documentation update. --- src/common/chapters.cpp | 41 +++++++++++++++++++++++++-------- src/common/mm_io.cpp | 2 +- src/common/mpeg4_common.cpp | 5 +++-- src/common/mpeg4_common.h | 45 +++++++++++++++++++++++++++++-------- 4 files changed, 72 insertions(+), 21 deletions(-) diff --git a/src/common/chapters.cpp b/src/common/chapters.cpp index c59b36c37..1ba52859e 100644 --- a/src/common/chapters.cpp +++ b/src/common/chapters.cpp @@ -167,8 +167,8 @@ probe_simple_chapters(mm_text_io_c *in) { * end timecodes after the timerange check has been made. * \param language This language is added as the \c KaxChapterLanguage * for all entries. - * \param country This country is added as the \c KaxChapterCountry for - * all entries. + * \param charset The charset the chapters are supposed to be it. The entries + * will be converted to UTF-8 if necessary. * \param exception_on_error If set to \c true then an exception is thrown * if an error occurs. Otherwise \c NULL will be returned. * @@ -307,13 +307,35 @@ parse_simple_chapters(mm_text_io_c *in, /** \brief Probe a file for different chapter formats and parse the file. * * The file \a file_name is opened and checked for supported chapter formats. + * These include simple OGM style chapters, CUE sheets and mkvtoolnix' own + * XML chapter format. * * Its parameters don't have to be checked for validity. * - * \see ::parse_chapters(mm_text_io_c *in,int64_t min_tc,int64_t max_tc, int64_t offset,const string &language,const string &charset,bool exception_on_error,bool *is_simple_format,KaxTags **tags) - * for a full description of its parameters and return values. + * \param file_name The name of the text file to read from. + * \param min_tc An optional timecode. If both \a min_tc and \a max_tc are + * given then only those chapters that lie in the timerange + * [min_tc..max_tc] are kept. + * \param max_tc An optional timecode. If both \a min_tc and \a max_tc are + * given then only those chapters that lie in the timerange + * [min_tc..max_tc] are kept. + * \param offset An optional offset that is subtracted from all start and + * end timecodes after the timerange check has been made. + * \param language This language is added as the \c KaxChapterLanguage + * for entries that don't specifiy it. + * \param charset The charset the chapters are supposed to be it. The entries + * will be converted to UTF-8 if necessary. This parameter is ignored for XML + * chapter files. + * \param exception_on_error If set to \c true then an exception is thrown + * if an error occurs. Otherwise \c NULL will be returned. + * \param is_simple_format This boolean will be set to \c true if the chapter + * format is either the OGM style format or a CUE sheet. + * \param tags When parsing a CUE sheet tags will be created along with the + * chapter entries. These tags will be stored in this parameter. * - * \param file_name The file name that is to be opened. + * \return The chapters parsed from the file or \c NULL if an error occured. + * + * \see ::parse_chapters(mm_text_io_c *in,int64_t min_tc,int64_t max_tc, int64_t offset,const string &language,const string &charset,bool exception_on_error,bool *is_simple_format,KaxTags **tags) */ KaxChapters * parse_chapters(const string &file_name, @@ -367,8 +389,9 @@ parse_chapters(const string &file_name, * end timecodes after the timerange check has been made. * \param language This language is added as the \c KaxChapterLanguage * for entries that don't specifiy it. - * \param country This country is added as the \c KaxChapterCountry for - * entries that don't specifiy it. + * \param charset The charset the chapters are supposed to be it. The entries + * will be converted to UTF-8 if necessary. This parameter is ignored for XML + * chapter files. * \param exception_on_error If set to \c true then an exception is thrown * if an error occurs. Otherwise \c NULL will be returned. * \param is_simple_format This boolean will be set to \c true if the chapter @@ -488,8 +511,8 @@ get_chapter_uid(KaxChapterAtom &atom) { * The Matroska specs and \c libmatroska say that several elements are * mandatory. This function makes sure that they all exist by adding them * with their default values if they're missing. It works recursively. See - * \url http://www.matroska.org/technical/specs/chapters/index.html - * for a list or mandatory elements. + * + * the Matroska chapter specs for a list or mandatory elements. * * The parameters are checked for validity. * diff --git a/src/common/mm_io.cpp b/src/common/mm_io.cpp index 9e6e3d4e3..97672bc14 100644 --- a/src/common/mm_io.cpp +++ b/src/common/mm_io.cpp @@ -943,7 +943,7 @@ mm_text_io_c::get_byte_order() { } void -mm_text_io_c::setFilePointer(int64_t offset, +mm_text_io_c::setFilePointer(int64 offset, seek_mode mode) { if ((offset == 0) && (mode == seek_beginning)) mm_proxy_io_c::setFilePointer(bom_len, seek_beginning); diff --git a/src/common/mpeg4_common.cpp b/src/common/mpeg4_common.cpp index f884c9a18..a438ab6ba 100644 --- a/src/common/mpeg4_common.cpp +++ b/src/common/mpeg4_common.cpp @@ -1,4 +1,5 @@ /** MPEG video helper functions (MPEG 1, 2 and 4) + * * mkvmerge -- utility for splicing together matroska files * from component media subtypes * @@ -110,10 +111,10 @@ mpeg4_extract_par(const unsigned char *buffer, * a dummy frame) then \a frames will contain no elements. */ void -mpeg4_find_frame_types(const unsigned char *buf, +mpeg4_find_frame_types(const unsigned char *buffer, int size, vector &frames) { - bit_cursor_c bits(buf, size); + bit_cursor_c bits(buffer, size); uint32_t marker, frame_type; bool first_frame; video_frame_t frame; diff --git a/src/common/mpeg4_common.h b/src/common/mpeg4_common.h index 6d0765733..6fe80446e 100644 --- a/src/common/mpeg4_common.h +++ b/src/common/mpeg4_common.h @@ -1,4 +1,5 @@ -/* +/** MPEG video helper functions (MPEG 1, 2 and 4) + * * mkvmerge -- utility for splicing together matroska files * from component media subtypes * @@ -6,11 +7,10 @@ * see the file COPYING for details * or visit http://www.gnu.org/copyleft/gpl.html * - * $Id$ + * \file + * \version $Id$ * - * MPEG1, 2 and 4 video helper functions - * - * Written by Moritz Bunkus . + * \author Written by Moritz Bunkus . */ #ifndef __MPEG4_COMMON_H @@ -38,21 +38,48 @@ /** MPEG-1/-2 frame rate: 60 frames per second */ #define MPEGVIDEO_FPS_60 0x08 +/** Pointers to MPEG4 video frames and their data + * + * MPEG4 video can be stored in a "packed" format, e.g. in AVI. This means + * that one AVI chunk may contain more than one video frame. This is + * usually the case with B frames due to limitations in how AVI and + * Windows' media frameworks work. With ::mpeg4_find_frame_types + * such packed frames can be analyzed. The results are stored in these + * structures: one structure for one frame in the analyzed chunk. + */ typedef struct { + /** The beginning of the frame data. This is a pointer into an existing + buffer handed over to ::mpeg4_find_frame_types. */ unsigned char *data; - int size, pos; + /** The size of the frame in bytes. */ + int size; + /** The position of the frame in the original buffer. */ + int pos; + /** The frame type: \c 'I', \c 'P' or \c 'B'. */ char type; + /** Private data. */ unsigned char *priv; - int64_t timecode, duration, bref, fref; + /** The timecode of the frame in \c ns. */ + int64_t timecode; + /** The duration of the frame in \c ns. */ + int64_t duration; + /** The frame's backward reference in \c ns relative to its + \link video_frame_t::timecode timecode \endlink. + This value is only set for P and B frames. */ + int64_t bref; + /** The frame's forward reference in \c ns relative to its + \link video_frame_t::timecode timecode \endlink. + This value is only set for B frames. */ + int64_t fref; } video_frame_t; bool MTX_DLL_API mpeg4_extract_par(const unsigned char *buffer, int size, uint32_t &par_num, uint32_t &par_den); -void MTX_DLL_API mpeg4_find_frame_types(const unsigned char *buf, int size, +void MTX_DLL_API mpeg4_find_frame_types(const unsigned char *buffer, int size, vector &frames); int MTX_DLL_API mpeg1_2_extract_fps_idx(const unsigned char *buffer, - int size); + int size); double MTX_DLL_API mpeg1_2_get_fps(int idx); #endif /* __MPEG4_COMMON_H */