diff options
| author |  wm4 <wm4@mplayer2.org> | 2012-07-28 18:15:33 +0200 |
|---|---|---|
| committer | wm4 <wm4@mplayer2.org> | 2012-07-28 20:44:59 +0200 |
| commit | 5368c46453223acf87de7ef89a35a37402c2d8eb (patch) | |
| tree | 051bf39b80c5fbbb5212ecc93ef3531031194640 /DOCS/OUTDATED-tech | |
| parent | f606bb6d97cfdfb8f740259eb4ea683adddfd06b (diff) | |
Rename DOCS/tech/ to DOCS/OUTATED-tech/
While DOCS/tech/ contains lots of documentation about mplayer's
internals, most of it seems outdated, and hasn't been touched in many
years. On the other hand, there still might be useful things in there,
but it's hard to tell which parts.
Instead of deleting all it, rename the directory to "warn" potential
developers that the documentation is completely outdated.
Diffstat (limited to 'DOCS/OUTDATED-tech')
22 files changed, 4548 insertions, 0 deletions
diff --git a/DOCS/OUTDATED-tech/Doxyfile b/DOCS/OUTDATED-tech/Doxyfile new file mode 100644 index 0000000000..1a9a036bef --- /dev/null +++ b/DOCS/OUTDATED-tech/Doxyfile @@ -0,0 +1,1142 @@ +# Doxyfile 1.3.7 + +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project +# +# All text after a hash (#) is considered a comment and will be ignored +# The format is: +# TAG = value [value, ...] +# For lists items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (" ") + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- + +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded +# by quotes) that should identify the project. + +PROJECT_NAME = MPlayer + +# The PROJECT_NUMBER tag can be used to enter a project or revision number. +# This could be handy for archiving the generated documentation or +# if some version control system is used. + +PROJECT_NUMBER = + +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) +# base path where the generated documentation will be put. +# If a relative path is entered, it will be relative to the location +# where doxygen was started. If left blank the current directory will be used. + +OUTPUT_DIRECTORY = DOCS/tech/doxygen + +# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create +# 2 levels of 10 sub-directories under the output directory of each output +# format and will distribute the generated files over these directories. +# Enabling this option can be useful when feeding doxygen a huge amount of source +# files, where putting all generated files in the same directory would otherwise +# cause performance problems for the file system. + +CREATE_SUBDIRS = YES + +# The OUTPUT_LANGUAGE tag is used to specify the language in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all constant output in the proper language. +# The default language is English, other supported languages are: +# Brazilian, Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, Dutch, +# Finnish, French, German, Greek, Hungarian, Italian, Japanese, Japanese-en +# (Japanese with English messages), Korean, Korean-en, Norwegian, Polish, Portuguese, +# Romanian, Russian, Serbian, Slovak, Slovene, Spanish, Swedish, and Ukrainian. + +OUTPUT_LANGUAGE = English + +# This tag can be used to specify the encoding used in the generated output. +# The encoding is not always determined by the language that is chosen, +# but also whether or not the output is meant for Windows or non-Windows users. +# In case there is a difference, setting the USE_WINDOWS_ENCODING tag to YES +# forces the Windows encoding (this is the default for the Windows binary), +# whereas setting the tag to NO uses a Unix-style encoding (the default for +# all platforms other than Windows). + +USE_WINDOWS_ENCODING = NO + +# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will +# include brief member descriptions after the members that are listed in +# the file and class documentation (similar to JavaDoc). +# Set to NO to disable this. + +BRIEF_MEMBER_DESC = YES + +# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend +# the brief description of a member or function before the detailed description. +# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# brief descriptions will be completely suppressed. + +REPEAT_BRIEF = YES + +# This tag implements a quasi-intelligent brief description abbreviator +# that is used to form the text in various listings. Each string +# in this list, if found as the leading text of the brief description, will be +# stripped from the text and the result after processing the whole list, is used +# as the annotated text. Otherwise, the brief description is used as-is. If left +# blank, the following values are used ("$name" is automatically replaced with the +# name of the entity): "The $name class" "The $name widget" "The $name file" +# "is" "provides" "specifies" "contains" "represents" "a" "an" "the" + +ABBREVIATE_BRIEF = + +# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then +# Doxygen will generate a detailed section even if there is only a brief +# description. + +ALWAYS_DETAILED_SEC = NO + +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all inherited +# members of a class in the documentation of that class as if those members were +# ordinary class members. Constructors, destructors and assignment operators of +# the base classes will not be shown. + +INLINE_INHERITED_MEMB = YES + +# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full +# path before files name in the file list and in the header files. If set +# to NO the shortest path that makes the file name unique will be used. + +FULL_PATH_NAMES = YES + +# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag +# can be used to strip a user-defined part of the path. Stripping is +# only done if one of the specified strings matches the left-hand part of +# the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the +# path to strip. + +STRIP_FROM_PATH = + +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of +# the path mentioned in the documentation of a class, which tells +# the reader which header file to include in order to use a class. +# If left blank only the name of the header file containing the class +# definition is used. Otherwise one should specify the include paths that +# are normally passed to the compiler using the -I flag. + +STRIP_FROM_INC_PATH = + +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter +# (but less readable) file names. This can be useful is your file systems +# doesn't support long names like on DOS, Mac, or CD-ROM. + +SHORT_NAMES = NO + +# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen +# will interpret the first line (until the first dot) of a JavaDoc-style +# comment as the brief description. If set to NO, the JavaDoc +# comments will behave just like the Qt-style comments (thus requiring an +# explicit @brief command for a brief description. + +JAVADOC_AUTOBRIEF = NO + +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen +# treat a multi-line C++ special comment block (i.e. a block of //! or /// +# comments) as a brief description. This used to be the default behaviour. +# The new default is to treat a multi-line C++ comment block as a detailed +# description. Set this tag to YES if you prefer the old behaviour instead. + +MULTILINE_CPP_IS_BRIEF = NO + +# If the DETAILS_AT_TOP tag is set to YES then Doxygen +# will output the detailed description near the top, like JavaDoc. +# If set to NO, the detailed description appears after the member +# documentation. + +DETAILS_AT_TOP = NO + +# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented +# member inherits the documentation from any documented member that it +# re-implements. + +INHERIT_DOCS = YES + +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES, then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default +# all members of a group must be documented explicitly. + +DISTRIBUTE_GROUP_DOC = NO + +# The TAB_SIZE tag can be used to set the number of spaces in a tab. +# Doxygen uses this value to replace tabs by spaces in code fragments. + +TAB_SIZE = 8 + +# This tag can be used to specify a number of aliases that acts +# as commands in the documentation. An alias has the form "name=value". +# For example adding "sideeffect=\par Side Effects:\n" will allow you to +# put the command \sideeffect (or @sideeffect) in the documentation, which +# will result in a user-defined paragraph with heading "Side Effects:". +# You can put \n's in the value part of an alias to insert newlines. + +ALIASES = + +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources +# only. Doxygen will then generate output that is more tailored for C. +# For instance, some of the names that are used will be different. The list +# of all members will be omitted, etc. + +OPTIMIZE_OUTPUT_FOR_C = NO + +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java sources +# only. Doxygen will then generate output that is more tailored for Java. +# For instance, namespaces will be presented as packages, qualified scopes +# will look different, etc. + +OPTIMIZE_OUTPUT_JAVA = NO + +# Set the SUBGROUPING tag to YES (the default) to allow class member groups of +# the same type (for instance a group of public functions) to be put as a +# subgroup of that type (e.g. under the Public Functions section). Set it to +# NO to prevent subgrouping. Alternatively, this can be done per class using +# the \nosubgrouping command. + +SUBGROUPING = YES + +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- + +# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in +# documentation are documented, even if no documentation was available. +# Private class members and static file members will be hidden unless +# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES + +EXTRACT_ALL = YES + +# If the EXTRACT_PRIVATE tag is set to YES all private members of a class +# will be included in the documentation. + +EXTRACT_PRIVATE = YES + +# If the EXTRACT_STATIC tag is set to YES all static members of a file +# will be included in the documentation. + +EXTRACT_STATIC = YES + +# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) +# defined locally in source files will be included in the documentation. +# If set to NO only classes defined in header files are included. + +EXTRACT_LOCAL_CLASSES = YES + +# This flag is only useful for Objective-C code. When set to YES local +# methods, which are defined in the implementation section but not in +# the interface are included in the documentation. +# If set to NO (the default) only methods in the interface are included. + +EXTRACT_LOCAL_METHODS = NO + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all +# undocumented members of documented classes, files or namespaces. +# If set to NO (the default) these members will be included in the +# various overviews, but no documentation section is generated. +# This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_MEMBERS = NO + +# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. +# If set to NO (the default) these classes will be included in the various +# overviews. This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_CLASSES = NO + +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all +# friend (class|struct|union) declarations. +# If set to NO (the default) these declarations will be included in the +# documentation. + +HIDE_FRIEND_COMPOUNDS = NO + +# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any +# documentation blocks found inside the body of a function. +# If set to NO (the default) these blocks will be appended to the +# function's detailed documentation block. + +HIDE_IN_BODY_DOCS = NO + +# The INTERNAL_DOCS tag determines if documentation +# that is typed after a \internal command is included. If the tag is set +# to NO (the default) then the documentation will be excluded. +# Set it to YES to include the internal documentation. + +INTERNAL_DOCS = NO + +# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate +# file names in lower-case letters. If set to YES upper-case letters are also +# allowed. This is useful if you have classes or files whose names only differ +# in case and if your file system supports case sensitive file names. Windows +# users are advised to set this option to NO. + +CASE_SENSE_NAMES = YES + +# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen +# will show members with their full class and namespace scopes in the +# documentation. If set to YES the scope will be hidden. + +HIDE_SCOPE_NAMES = NO + +# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen +# will put a list of the files that are included by a file in the documentation +# of that file. + +SHOW_INCLUDE_FILES = YES + +# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] +# is inserted in the documentation for inline members. + +INLINE_INFO = YES + +# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen +# will sort the (detailed) documentation of file and class members +# alphabetically by member name. If set to NO the members will appear in +# declaration order. + +SORT_MEMBER_DOCS = YES + +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the +# brief documentation of file, namespace and class members alphabetically +# by member name. If set to NO (the default) the members will appear in +# declaration order. + +SORT_BRIEF_DOCS = NO + +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be +# sorted by fully-qualified names, including namespaces. If set to +# NO (the default), the class list will be sorted only by class name, +# not including the namespace part. +# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. +# Note: This option applies only to the class list, not to the +# alphabetical list. + +SORT_BY_SCOPE_NAME = NO + +# The GENERATE_TODOLIST tag can be used to enable (YES) or +# disable (NO) the todo list. This list is created by putting \todo +# commands in the documentation. + +GENERATE_TODOLIST = YES + +# The GENERATE_TESTLIST tag can be used to enable (YES) or +# disable (NO) the test list. This list is created by putting \test +# commands in the documentation. + +GENERATE_TESTLIST = YES + +# The GENERATE_BUGLIST tag can be used to enable (YES) or +# disable (NO) the bug list. This list is created by putting \bug +# commands in the documentation. + +GENERATE_BUGLIST = YES + +# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or +# disable (NO) the deprecated list. This list is created by putting +# \deprecated commands in the documentation. + +GENERATE_DEPRECATEDLIST= YES + +# The ENABLED_SECTIONS tag can be used to enable conditional +# documentation sections, marked by \if sectionname ... \endif. + +ENABLED_SECTIONS = + +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines +# the initial value of a variable or define consists of for it to appear in +# the documentation. If the initializer consists of more lines than specified +# here it will be hidden. Use a value of 0 to hide initializers completely. +# The appearance of the initializer of individual variables and defines in the +# documentation can be controlled using \showinitializer or \hideinitializer +# command in the documentation regardless of this setting. + +MAX_INITIALIZER_LINES = 30 + +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated +# at the bottom of the documentation of classes and structs. If set to YES the +# list will mention the files that were used to generate the documentation. + +SHOW_USED_FILES = YES + +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- + +# The QUIET tag can be used to turn on/off the messages that are generated +# by doxygen. Possible values are YES and NO. If left blank NO is used. + +QUIET = NO + +# The WARNINGS tag can be used to turn on/off the warning messages that are +# generated by doxygen. Possible values are YES and NO. If left blank +# NO is used. + +WARNINGS = YES + +# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings +# for undocumented members. If EXTRACT_ALL is set to YES then this flag will +# automatically be disabled. + +WARN_IF_UNDOCUMENTED = NO + +# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as not documenting some +# parameters in a documented function, or documenting parameters that +# don't exist or using markup commands wrongly. + +WARN_IF_DOC_ERROR = NO + +# The WARN_FORMAT tag determines the format of the warning messages that +# doxygen can produce. The string should contain the $file, $line, and $text +# tags, which will be replaced by the file and line number from which the +# warning originated and the warning text. + +WARN_FORMAT = "$file:$line: $text" + +# The WARN_LOGFILE tag can be used to specify a file to which warning +# and error messages should be written. If left blank the output is written +# to stderr. + +WARN_LOGFILE = + +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- + +# The INPUT tag can be used to specify the files and/or directories that contain +# documented source files. You may enter file names like "myfile.cpp" or +# directories like "/usr/src/myproject". Separate the files or directories +# with spaces. + +INPUT = + +# If the value of the INPUT tag contains directories, you can use the +# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank the following patterns are tested: +# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp +# *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm + +FILE_PATTERNS = + +# The RECURSIVE tag can be used to turn specify whether or not subdirectories +# should be searched for input files as well. Possible values are YES and NO. +# If left blank NO is used. + +RECURSIVE = YES + +# The EXCLUDE tag can be used to specify files and/or directories that should +# excluded from the INPUT source files. This way you can easily exclude a +# subdirectory from a directory tree whose root is specified with the INPUT tag. + +EXCLUDE = DOCS TOOLS + +# The EXCLUDE_SYMLINKS tag can be used select whether or not files or directories +# that are symbolic links (a Unix filesystem feature) are excluded from the input. + +EXCLUDE_SYMLINKS = NO + +# If the value of the INPUT tag contains directories, you can use the +# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude +# certain files from those directories. + +EXCLUDE_PATTERNS = + +# The EXAMPLE_PATH tag can be used to specify one or more files or +# directories that contain example code fragments that are included (see +# the \include command). + +EXAMPLE_PATH = + +# If the value of the EXAMPLE_PATH tag contains directories, you can use the +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank all files are included. + +EXAMPLE_PATTERNS = + +# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be +# searched for input files to be used with the \include or \dontinclude +# commands irrespective of the value of the RECURSIVE tag. +# Possible values are YES and NO. If left blank NO is used. + +EXAMPLE_RECURSIVE = NO + +# The IMAGE_PATH tag can be used to specify one or more files or +# directories that contain image that are included in the documentation (see +# the \image command). + +IMAGE_PATH = + +# The INPUT_FILTER tag can be used to specify a program that doxygen should +# invoke to filter for each input file. Doxygen will invoke the filter program +# by executing (via popen()) the command <filter> <input-file>, where <filter> +# is the value of the INPUT_FILTER tag, and <input-file> is the name of an +# input file. Doxygen will then use the output that the filter program writes +# to standard output. + +INPUT_FILTER = + +# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using +# INPUT_FILTER) will be used to filter the input files when producing source +# files to browse (i.e. when SOURCE_BROWSER is set to YES). + +FILTER_SOURCE_FILES = NO + +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- + +# If the SOURCE_BROWSER tag is set to YES then a list of source files will +# be generated. Documented entities will be cross-referenced with these sources. +# Note: To get rid of all source code in the generated output, make sure also +# VERBATIM_HEADERS is set to NO. + +SOURCE_BROWSER = YES + +# Setting the INLINE_SOURCES tag to YES will include the body +# of functions and classes directly in the documentation. + +INLINE_SOURCES = YES + +# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct +# doxygen to hide any special comment blocks from generated source code +# fragments. Normal C and C++ comments will always remain visible. + +STRIP_CODE_COMMENTS = YES + +# If the REFERENCED_BY_RELATION tag is set to YES (the default) +# then for each documented function all documented +# functions referencing it will be listed. + +REFERENCED_BY_RELATION = YES + +# If the REFERENCES_RELATION tag is set to YES (the default) +# then for each documented function all documented entities +# called/used by that function will be listed. + +REFERENCES_RELATION = YES + +# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen +# will generate a verbatim copy of the header file for each class for +# which an include is specified. Set to NO to disable this. + +VERBATIM_HEADERS = YES + +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- + +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index +# of all compounds will be generated. Enable this if the project +# contains a lot of classes, structs, unions or interfaces. + +ALPHABETICAL_INDEX = YES + +# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then +# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns +# in which this list will be split (can be a number in the range [1..20]) + +COLS_IN_ALPHA_INDEX = 2 + +# In case all classes in a project start with a common prefix, all +# classes will be put under the same header in the alphabetical index. +# The IGNORE_PREFIX tag can be used to specify one or more prefixes that +# should be ignored while generating the index headers. + +IGNORE_PREFIX = + +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- + +# If the GENERATE_HTML tag is set to YES (the default) Doxygen will +# generate HTML output. + +GENERATE_HTML = YES + +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `html' will be used as the default path. + +HTML_OUTPUT = html + +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for +# each generated HTML page (for example: .htm,.php,.asp). If it is left blank +# doxygen will generate files with .html extension. + +HTML_FILE_EXTENSION = .html + +# The HTML_HEADER tag can be used to specify a personal HTML header for +# each generated HTML page. If it is left blank doxygen will generate a +# standard header. + +HTML_HEADER = + +# The HTML_FOOTER tag can be used to specify a personal HTML footer for +# each generated HTML page. If it is left blank doxygen will generate a +# standard footer. + +HTML_FOOTER = + +# The HTML_STYLESHEET tag can be used to specify a user-defined cascading +# style sheet that is used by each HTML page. It can be used to +# fine-tune the look of the HTML output. If the tag is left blank doxygen +# will generate a default style sheet. Note that doxygen will try to copy +# the style sheet file to the HTML output directory, so don't put your own +# stylesheet in the HTML output directory as well, or it will be erased! + +HTML_STYLESHEET = + +# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, +# files or namespaces will be aligned in HTML using tables. If set to +# NO a bullet list will be used. + +HTML_ALIGN_MEMBERS = YES + +# If the GENERATE_HTMLHELP tag is set to YES, additional index files +# will be generated that can be used as input for tools like the +# Microsoft HTML help workshop to generate a compressed HTML help file (.chm) +# of the generated HTML documentation. + +GENERATE_HTMLHELP = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can +# be used to specify the file name of the resulting .chm file. You +# can add a path in front of the file if the result should not be +# written to the html output directory. + +CHM_FILE = + +# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can +# be used to specify the location (absolute path including file name) of +# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run +# the HTML help compiler on the generated index.hhp. + +HHC_LOCATION = + +# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag +# controls if a separate .chi index file is generated (YES) or that +# it should be included in the master .chm file (NO). + +GENERATE_CHI = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag +# controls whether a binary table of contents is generated (YES) or a +# normal table of contents (NO) in the .chm file. + +BINARY_TOC = NO + +# The TOC_EXPAND flag can be set to YES to add extra items for group members +# to the contents of the HTML help documentation and to the tree view. + +TOC_EXPAND = NO + +# The DISABLE_INDEX tag can be used to turn on/off the condensed index at +# top of each HTML page. The value NO (the default) enables the index and +# the value YES disables it. + +DISABLE_INDEX = NO + +# This tag can be used to set the number of enum values (range [1..20]) +# that doxygen will group on one line in the generated HTML documentation. + +ENUM_VALUES_PER_LINE = 4 + +# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be +# generated containing a tree-like index structure (just like the one that +# is generated for HTML Help). For this to work a browser that supports +# JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+, +# Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are +# probably better off using the HTML help feature. + +GENERATE_TREEVIEW = NO + +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be +# used to set the initial width (in pixels) of the frame in which the tree +# is shown. + +TREEVIEW_WIDTH = 250 + +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- + +# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will +# generate Latex output. + +GENERATE_LATEX = NO + +# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `latex' will be used as the default path. + +LATEX_OUTPUT = latex + +# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be +# invoked. If left blank `latex' will be used as the default command name. + +LATEX_CMD_NAME = latex + +# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to +# generate index for LaTeX. If left blank `makeindex' will be used as the +# default command name. + +MAKEINDEX_CMD_NAME = makeindex + +# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact +# LaTeX documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_LATEX = NO + +# The PAPER_TYPE tag can be used to set the paper type that is used +# by the printer. Possible values are: a4, a4wide, letter, legal and +# executive. If left blank a4wide will be used. + +PAPER_TYPE = a4wide + +# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX +# packages that should be included in the LaTeX output. + +EXTRA_PACKAGES = + +# The LATEX_HEADER tag can be used to specify a personal LaTeX header for +# the generated latex document. The header should contain everything until +# the first chapter. If it is left blank doxygen will generate a +# standard header. Notice: only use this tag if you know what you are doing! + +LATEX_HEADER = + +# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated +# is prepared for conversion to pdf (using ps2pdf). The pdf file will +# contain links (just like the HTML output) instead of page references +# This makes the output suitable for online browsing using a pdf viewer. + +PDF_HYPERLINKS = NO + +# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of +# plain latex in the generated Makefile. Set this option to YES to get a +# higher quality PDF documentation. + +USE_PDFLATEX = NO + +# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. +# command to the generated LaTeX files. This will instruct LaTeX to keep +# running if errors occur, instead of asking the user for help. +# This option is also used when generating formulas in HTML. + +LATEX_BATCHMODE = NO + +# If LATEX_HIDE_INDICES is set to YES then doxygen will not +# include the index chapters (such as File Index, Compound Index, etc.) +# in the output. + +LATEX_HIDE_INDICES = NO + +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- + +# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output +# The RTF output is optimized for Word 97 and may not look very pretty with +# other RTF readers or editors. + +GENERATE_RTF = NO + +# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `rtf' will be used as the default path. + +RTF_OUTPUT = rtf + +# If the COMPACT_RTF tag is set to YES Doxygen generates more compact +# RTF documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_RTF = NO + +# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated +# will contain hyperlink fields. The RTF file will +# contain links (just like the HTML output) instead of page references. +# This makes the output suitable for online browsing using WORD or other +# programs which support those fields. +# Note: wordpad (write) and others do not support links. + +RTF_HYPERLINKS = NO + +# Load stylesheet definitions from file. Syntax is similar to doxygen's +# config file, i.e. a series of assignments. You only have to provide +# replacements, missing definitions are set to their default value. + +RTF_STYLESHEET_FILE = + +# Set optional variables used in the generation of an rtf document. +# Syntax is similar to doxygen's config file. + +RTF_EXTENSIONS_FILE = + +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- + +# If the GENERATE_MAN tag is set to YES (the default) Doxygen will +# generate man pages + +GENERATE_MAN = NO + +# The MAN_OUTPUT tag is used to specify where the man pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `man' will be used as the default path. + +MAN_OUTPUT = man + +# The MAN_EXTENSION tag determines the extension that is added to +# the generated man pages (default is the subroutine's section .3) + +MAN_EXTENSION = .3 + +# If the MAN_LINKS tag is set to YES and Doxygen generates man output, +# then it will generate one additional man file for each entity +# documented in the real man page(s). These additional files +# only source the real man page, but without them the man command +# would be unable to find the correct page. The default is NO. + +MAN_LINKS = NO + +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- + +# If the GENERATE_XML tag is set to YES Doxygen will +# generate an XML file that captures the structure of +# the code including all documentation. + +GENERATE_XML = NO + +# The XML_OUTPUT tag is used to specify where the XML pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `xml' will be used as the default path. + +XML_OUTPUT = xml + +# The XML_SCHEMA tag can be used to specify an XML schema, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_SCHEMA = + +# The XML_DTD tag can be used to specify an XML DTD, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_DTD = + +# If the XML_PROGRAMLISTING tag is set to YES Doxygen will +# dump the program listings (including syntax highlighting +# and cross-referencing information) to the XML output. Note that +# enabling this will significantly increase the size of the XML output. + +XML_PROGRAMLISTING = YES + +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- + +# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will +# generate an AutoGen Definitions (see autogen.sf.net) file +# that captures the structure of the code including all +# documentation. Note that this feature is still experimental +# and incomplete at the moment. + +GENERATE_AUTOGEN_DEF = NO + +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- + +# If the GENERATE_PERLMOD tag is set to YES Doxygen will +# generate a Perl module file that captures the structure of +# the code including all documentation. Note that this +# feature is still experimental and incomplete at the +# moment. + +GENERATE_PERLMOD = NO + +# If the PERLMOD_LATEX tag is set to YES Doxygen will generate +# the necessary Makefile rules, Perl scripts and LaTeX code to be able +# to generate PDF and DVI output from the Perl module output. + +PERLMOD_LATEX = NO + +# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be +# nicely formatted so it can be parsed by a human reader. This is useful +# if you want to understand what is going on. On the other hand, if this +# tag is set to NO the size of the Perl module output will be much smaller +# and Perl will parse it just the same. + +PERLMOD_PRETTY = YES + +# The names of the make variables in the generated doxyrules.make file +# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. +# This is useful so different doxyrules.make files included by the same +# Makefile don't overwrite each other's variables. + +PERLMOD_MAKEVAR_PREFIX = + +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- + +# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will +# evaluate all C-preprocessor directives found in the sources and include +# files. + +ENABLE_PREPROCESSING = YES + +# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro +# names in the source code. If set to NO (the default) only conditional +# compilation will be performed. Macro expansion can be done in a controlled +# way by setting EXPAND_ONLY_PREDEF to YES. + +MACRO_EXPANSION = NO + +# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES +# then the macro expansion is limited to the macros specified with the +# PREDEFINED and EXPAND_AS_PREDEFINED tags. + +EXPAND_ONLY_PREDEF = NO + +# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files +# in the INCLUDE_PATH (see below) will be search if a #include is found. + +SEARCH_INCLUDES = YES + +# The INCLUDE_PATH tag can be used to specify one or more directories that +# contain include files that are not input files but should be processed by +# the preprocessor. + +INCLUDE_PATH = + +# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard +# patterns (like *.h and *.hpp) to filter out the header-files in the +# directories. If left blank, the patterns specified with FILE_PATTERNS will +# be used. + +INCLUDE_FILE_PATTERNS = + +# The PREDEFINED tag can be used to specify one or more macro names that +# are defined before the preprocessor is started (similar to the -D option of +# gcc). The argument of the tag is a list of macros of the form: name +# or name=definition (no spaces). If the definition and the = are +# omitted =1 is assumed. + +PREDEFINED = + +# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then +# this tag can be used to specify a list of macro names that should be expanded. +# The macro definition that is found in the sources will be used. +# Use the PREDEFINED tag if you want to use a different macro definition. + +EXPAND_AS_DEFINED = + +# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then +# doxygen's preprocessor will remove all function-like macros that are alone +# on a line, have an all uppercase name, and do not end with a semicolon. Such +# function macros are typically used for boiler-plate code, and will confuse the +# parser if not removed. + +SKIP_FUNCTION_MACROS = YES + +#--------------------------------------------------------------------------- +# Configuration::additions related to external references +#--------------------------------------------------------------------------- + +# The TAGFILES option can be used to specify one or more tagfiles. +# Optionally an initial location of the external documentation +# can be added for each tagfile. The format of a tag file without +# this location is as follows: +# TAGFILES = file1 file2 ... +# Adding location for the tag files is done as follows: +# TAGFILES = file1=loc1 "file2 = loc2" ... +# where "loc1" and "loc2" can be relative or absolute paths or +# URLs. If a location is present for each tag, the installdox tool +# does not have to be run to correct the links. +# Note that each tag file must have a unique name +# (where the name does NOT include the path) +# If a tag file is not located in the directory in which doxygen +# is run, you must also specify the path to the tagfile here. + +TAGFILES = + +# When a file name is specified after GENERATE_TAGFILE, doxygen will create +# a tag file that is based on the input files it reads. + +GENERATE_TAGFILE = + +# If the ALLEXTERNALS tag is set to YES all external classes will be listed +# in the class index. If set to NO only the inherited external classes +# will be listed. + +ALLEXTERNALS = NO + +# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed +# in the modules index. If set to NO, only the current project's groups will +# be listed. + +EXTERNAL_GROUPS = YES + +# The PERL_PATH should be the absolute path and name of the perl script +# interpreter (i.e. the result of `which perl'). + +PERL_PATH = /usr/bin/perl + +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- + +# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will +# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base or +# super classes. Setting the tag to NO turns the diagrams off. Note that this +# option is superseded by the HAVE_DOT option below. This is only a fallback. It is +# recommended to install and use dot, since it yields more powerful graphs. + +CLASS_DIAGRAMS = NO + +# If set to YES, the inheritance and collaboration graphs will hide +# inheritance and usage relations if the target is undocumented +# or is not a class. + +HIDE_UNDOC_RELATIONS = YES + +# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is +# available from the path. This tool is part of Graphviz, a graph visualization +# toolkit from AT&T and Lucent Bell Labs. The other options in this section +# have no effect if this option is set to NO (the default) + +HAVE_DOT = NO + +# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect inheritance relations. Setting this tag to YES will force the +# the CLASS_DIAGRAMS tag to NO. + +CLASS_GRAPH = YES + +# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect implementation dependencies (inheritance, containment, and +# class references variables) of the class with other documented classes. + +COLLABORATION_GRAPH = YES + +# If the UML_LOOK tag is set to YES doxygen will generate inheritance and +# collaboration diagrams in a style similar to the OMG's Unified Modeling +# Language. + +UML_LOOK = NO + +# If set to YES, the inheritance and collaboration graphs will show the +# relations between templates and their instances. + +TEMPLATE_RELATIONS = NO + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT +# tags are set to YES then doxygen will generate a graph for each documented +# file showing the direct and indirect include dependencies of the file with +# other documented files. + +INCLUDE_GRAPH = YES + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and +# HAVE_DOT tags are set to YES then doxygen will generate a graph for each +# documented header file showing the documented files that directly or +# indirectly include this file. + +INCLUDED_BY_GRAPH = YES + +# If the CALL_GRAPH and HAVE_DOT tags are set to YES then doxygen will +# generate a call dependency graph for every global function or class method. +# Note that enabling this option will significantly increase the time of a run. +# So in most cases it will be better to enable call graphs for selected +# functions only using the \callgraph command. + +CALL_GRAPH = NO + +# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen +# will graphical hierarchy of all classes instead of a textual one. + +GRAPHICAL_HIERARCHY = YES + +# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images +# generated by dot. Possible values are png, jpg, or gif +# If left blank png will be used. + +DOT_IMAGE_FORMAT = png + +# The tag DOT_PATH can be used to specify the path where the dot tool can be +# found. If left blank, it is assumed the dot tool can be found on the path. + +DOT_PATH = + +# The DOTFILE_DIRS tag can be used to specify one or more directories that +# contain dot files that are included in the documentation (see the +# \dotfile command). + +DOTFILE_DIRS = + +# The MAX_DOT_GRAPH_WIDTH tag can be used to set the maximum allowed width +# (in pixels) of the graphs generated by dot. If a graph becomes larger than +# this value, doxygen will try to truncate the graph, so that it fits within +# the specified constraint. Beware that most browsers cannot cope with very +# large images. + +MAX_DOT_GRAPH_WIDTH = 1024 + +# The MAX_DOT_GRAPH_HEIGHT tag can be used to set the maximum allows height +# (in pixels) of the graphs generated by dot. If a graph becomes larger than +# this value, doxygen will try to truncate the graph, so that it fits within +# the specified constraint. Beware that most browsers cannot cope with very +# large images. + +MAX_DOT_GRAPH_HEIGHT = 1024 + +# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the +# graphs generated by dot. A depth value of 3 means that only nodes reachable +# from the root by following a path via at most 3 edges will be shown. Nodes that +# lay further from the root node will be omitted. Note that setting this option to +# 1 or 2 may greatly reduce the computation time needed for large code bases. Also +# note that a graph may be further truncated if the graph's image dimensions are +# not sufficient to fit the graph (see MAX_DOT_GRAPH_WIDTH and MAX_DOT_GRAPH_HEIGHT). +# If 0 is used for the depth value (the default), the graph is not depth-constrained. + +MAX_DOT_GRAPH_DEPTH = 0 + +# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will +# generate a legend page explaining the meaning of the various boxes and +# arrows in the dot generated graphs. + +GENERATE_LEGEND = YES + +# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will +# remove the intermediate dot files that are used to generate +# the various graphs. + +DOT_CLEANUP = YES + +#--------------------------------------------------------------------------- +# Configuration::additions related to the search engine +#--------------------------------------------------------------------------- + +# The SEARCHENGINE tag specifies whether or not a search engine should be +# used. If set to NO the values of all tags below this one will be ignored. + +SEARCHENGINE = NO diff --git a/DOCS/OUTDATED-tech/codecs.conf.txt b/DOCS/OUTDATED-tech/codecs.conf.txt new file mode 100644 index 0000000000..75f480933f --- /dev/null +++ b/DOCS/OUTDATED-tech/codecs.conf.txt @@ -0,0 +1,214 @@ +Understanding MPlayer's etc/codecs.conf File + +Introduction +------------ +MPlayer features a very flexible codec architecture which allows it to +use its own open source codecs, as well as open source libraries, Win32 +codec DLLs and other binary codec modules. To the MPlayer user, the +most visible piece of this architecture is the etc/codecs.conf file. This +is a text-based configuration file that controls which MPlayer components +are in charge of handling particular compressed data formats. + +The codecs.conf file is stored either in a shared directory for all system +users to access, or in the .mplayer directory in a user's home +directory. When MPlayer starts, it first looks for a codecs.conf file in a +user's home directory. Failing that, it searches for the shared file. If +no codecs.conf file is found MPlayer falls back on its internal hardcoded +configuration. If the file is present but has syntax errors, MPlayer will +report the error. + +The codecs.conf file is really quite simple. It is simply a collection of +codec definition blocks that define how different media types should be +handled. There are a number of keywords that can occur in a block. Not all +of them are required and no particular order is enforced. + +Editing codecs.conf +------------------- +You can edit codecs.conf using your favorite text editor. Anything that +comes after a semicolon (;) on a line is regarded as a comment. For +example: +; this is a comment + format 0x34616d69 ; "ima4" (MOV files) + +The codec blocks can be in any order; the file parser doesn't +care. However, they are organized in a particular order for the benefit of +human readers. For example, all of the open source decoders that MPlayer +implements natively are grouped in one section. + +Release Number +-------------- +Your codecs.conf now requires a release number to avoid codec release +incompatibilities. The format is simple: (YYYYMMDD) + +release 20020520 + +Whenever changes are made to the codecs that *require* an updated +codecs.conf, then MPlayer will no longer accept outdated versions. +It is not recommended to change this line unless you know exactly +what you are doing. + +Video Codecs +------------ +Let's jump right in with an example. Here is an example video codec block: + +videocodec indeo5ds + info "Intel Indeo 5" + status working + fourcc IV50,iv50 + driver dshow + dll "ir50_32.dll" + guid 0x30355649, 0x0000, 0x0010, 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71 + out YV12 + out YUY2 + out BGR32,BGR24,BGR16,BGR15 + +This is a particularly full-featured video codec. The "videocodec" keyword +identifies the fact that this is the start of a new video +codec. "indeo5ds" is MPlayer's unique name for the codec. You have to use +this name with the -vc/-ac option. + +The next line has the keyword "info" which specifies a human-readable +comment accompanying this codec. This is printed by -vc help / -ac help. + +The "status" keyword carries information about the codec's functional +status. MPlayer currently recognizes 4 status levels: working, buggy, +crashing, and untested. When it gets to codec auto-selection, it tries +untested first (to force users to test it for us and report results :)), +then working and finally buggy ones. Codecs marked crashing won't be tried, +unless explicitly (-vc/-ac) selected. + +The next line lists 4-character codes (FOURCCs) that are associated with +this codec. There can be more than one FOURCC specified on a fourcc line +as long as they are separated with a comma. There can also be multiple +fourcc lines in the codec. A second fourcc can also be given, separated +with a space. MPlayer will replace the original fourcc in the headers with +this one before opening the codec. It's useful for win32 codecs checking for +the fourccs. + +The "driver" keyword associates this codec with an internal MPlayer +decoder module. MPlayer has a module named "dshow" that handles data +encoded by the codec. See -vfm help / -afm help for the available module list. + +The "dll" keyword specifies which Win32/XAnim/Real/Quicktime binary +module needs to be loaded. It's also used to specify which FFmpeg codec +to load. The list of FFmpeg codecs can be found in libavcodec/allcodecs.c. + +The "guid" keyword identifies a 16-byte Microsoft GUID that some media +files use to identify codecs. Used only for win32 dshow and DMO codecs. + +The "out" keyword identifies which output format the decoder is known +to provide. Just like the fourcc line, there can be multiple out lines or +multiple comma-separated output formats on the same line. The output +formats should be listed in order of preference. + +The outfmt values can be followed by one or more flags, like flip, noflip, +static, query. The flags are defined as follows: + +"flip": + If this flag is set for a given format, then o_bih->biHeight will NOT be + set to -bih->biHeight, i.e. the image will be decoded upside-down. + Used only by vfw and vfwex codecs. + +"noflip": + This flag is ignored (no effect) without "flip" being set! + If this flag is set, it means the codec doesn't decode upside-down, + although it's told to do so. + +"yuvhack": + This flag is required for the old win32 ms-mpeg4 vfw codecs, including + MP42 and DIV3 (DivX 3.11). These DLLs actually support YUV formats, + but the query/begin functions are buggy and don't accept YUV fourccs + (the decode function accepts it and works well!) + If this flag is set, then o_bih->biCompression will be set to 0 for + the initialization for the YUV modes. Used only by vfw/vfwex codecs. + +"query": + This flag is used to control VDCTRL_QUERY_FORMAT for vfw/vfewx codecs. + If this flag is set, the control() will query the codec for the csp + support, otherwise it will assume a constant csp table. Required for + some DLLs (like huffyuv, CRAM). + +"static", + This flag forces STATIC (instead of TEMP) buffer allocation for the codec. + Used for some very old DLLs like Indeo 3 and for some XAnim codecs like + cinepak. See dr-methods.txt for details on buffer types. + +The "in" keyword -- UNDOCUMENTED + +Audio Codecs +------------ +Here is an example of a rather full-featured audio codec block: + +audiocodec mp3 + info "MPEG layer-2, layer-3" + status working + comment "Optimized to MMX/SSE/3Dnow!" + format 0x50 + format 0x55 + format 0x33706d2e ; ".mp3" CBR/VBR MP3 (MOV files) + format 0x5500736d ; "ms\0\x55" older mp3 fcc (MOV files) + driver mp3lib + dll "mp3lib (mpglib)" + flags seekable + +Many of the keywords are the same as a video codec block. However, we see +a few that we haven't seen before. The "comment" keyword identifies +another human-readable note for this codec. + +The "format" keyword performs a similar job as the fourcc line. However, +since certain media file formats (notably AVI) identify audio formats with +16-bit numbers rather than 32-bit FOURCCs, it's necessary to use this +convention to accommodate them. However, as shown in this example, FOURCCs +can also be specified with the format keyword as long as they're converted +to their hex representation. It's important to note that this can be +useful for video codecs as well if a FOURCC contains a space (such as +Apple's "rle " codec). + +The "flags" keywords identifies any additional abilities of this +codec. Currently, seekable is the only supported flag. + + +Adding FFmpeg Codecs +------------------- +example codec: + +videocodec ffmdec + info "FFmpeg Sony PlayStation MDEC (Motion DECoder)" + status working + fourcc MDEC ; internal MPlayer FourCC + driver ffmpeg + dll mdec + out YV12 + +The "videocodec" name should start with ff to differentiate it from other +libraries or binary codecs. + +The "dll" name comes from the codec source file or the libavcodec/allcodecs.c +file. + +The "out" colorspace can be found in the codec source file in the PIX_FMT +struct. Note that some codecs may have several pix_fmt structs. +The pix_fmt can be converted to the codecs.conf "out" format by reading +the fmt-conversion.c file. + +If there are BE and LE versions of a pix_fmt, ignore them and use the short +native format instead. e.g. 422P16_LE becomes out 422P16. also to note that +underscores cause parse errors, so 422P16_LE becomes out 422P16LE. + +libmpdemux/mp_taglists.c +-------------- +Sometimes the lavf demuxer will not pass on a fourcc (mostly video game +formats or other containers that do not support isom/riff tags). You will have +to make one based on the codec_id listed in the codec source file. + +Note that it is a good idea to mark any fourcc you create as +' ; internal MPlayer FourCC'. In case another codec uses that fourcc, +you can easily change the internal one. Also this will stop other projects +from thinking of the internal tag as a real fourcc found in the wild. + +libmpdemux/demuxer.c +-------------- +Some audio codecs require a parser, you can see which ones do +by reading the parsers section in libavcodec/allcodecs.c. + +EOF diff --git a/DOCS/OUTDATED-tech/colorspaces.txt b/DOCS/OUTDATED-tech/colorspaces.txt new file mode 100644 index 0000000000..eaf9d221e4 --- /dev/null +++ b/DOCS/OUTDATED-tech/colorspaces.txt @@ -0,0 +1,158 @@ +In general +========== + +There are planar and packed modes. +- Planar mode means: You have 3 separate images, one for each component, +each image 8 bits/pixel. To get the real colored pixel, you have to +mix the components from all planes. The resolution of planes may differ! +- Packed mode means: you have all components mixed/interleaved together, +so you have small "packs" of components in a single, big image. + +There are RGB and YUV colorspaces. +- RGB: Red, Green and Blue components. Used by analog VGA monitors. +- YUV: Luminance (Y) and Chrominance (U,V) components. Used by some + video systems, like PAL. Also most M(J)PEG/DCT based codecs use this. + +With YUV, they used to reduce the resolution of U,V planes: +The most common YUV formats: +FOURCC: bpp: IEEE: plane sizes: (w=width h=height of original image) +444P 24 YUV 4:4:4 Y: w * h U,V: w * h +YUY2,UYVY 16 YUV 4:2:2 Y: w * h U,V: (w/2) * h [MJPEG] +YV12,I420 12 YUV 4:2:0 Y: w * h U,V: (w/2) * (h/2) [MPEG, H.263] +411P 12 YUV 4:1:1 Y: w * h U,V: (w/4) * h [DV-NTSC, CYUV] +YVU9,IF09 9 YUV 4:1:0 Y: w * h U,V: (w/4) * (h/4) [Sorenson, Indeo] + +The YUV a:b:c naming style means: for <a> samples of Y there are <b> samples +of UV in odd lines and <c> samples of UV in even lines. + +conversion: (some cut'n'paste from www and maillist) + +RGB to YUV Conversion: + Y = (0.257 * R) + (0.504 * G) + (0.098 * B) + 16 + Cr = V = (0.439 * R) - (0.368 * G) - (0.071 * B) + 128 + Cb = U = -(0.148 * R) - (0.291 * G) + (0.439 * B) + 128 +YUV to RGB Conversion: + B = 1.164(Y - 16) + 2.018(U - 128) + G = 1.164(Y - 16) - 0.813(V - 128) - 0.391(U - 128) + R = 1.164(Y - 16) + 1.596(V - 128) + +In both these cases, you have to clamp the output values to keep them in +the [0-255] range. Rumour has it that the valid range is actually a subset +of [0-255] (I've seen an RGB range of [16-235] mentioned) but clamping the +values into [0-255] seems to produce acceptable results to me. + +Julien (sorry, I can't recall his surname) suggests that there are +problems with the above formula and proposes the following instead: + Y = 0.299R + 0.587G + 0.114B + Cb = U'= (B-Y)*0.565 + Cr = V'= (R-Y)*0.713 +with reciprocal versions: + R = Y + 1.403V' + G = Y - 0.344U' - 0.714V' + B = Y + 1.770U' +Note: This formula doesn't contain the +128 offsets of U,V values! + +Conclusion: +Y = luminance, the weighted average of R G B components. (0=black 255=white) +U = Cb = blue component (0=green 128=grey 255=blue) +V = Cr = red component (0=green 128=grey 255=red) + + +Huh. The planar YUV modes. +========================== + +The most misunderstood thingie... + +In MPlayer, we usually have 3 pointers to the Y, U and V planes, so it +doesn't matter what the order of the planes in the memory is: + for mp_image_t and libvo's draw_slice(): + planes[0] = Y = luminance + planes[1] = U = Cb = blue + planes[2] = V = Cr = red + Note: planes[1] is ALWAYS U, and planes[2] is V, the FOURCC + (YV12 vs. I420) doesn't matter here! So, every codec using 3 pointers + (not only the first one) normally supports YV12 and I420 (=IYUV), too! + +But there are some codecs (VfW, dshow) and vo drivers (xv) ignoring the 2nd +and 3rd pointer that use only a single pointer to the planar YUV image. In +this case we must know the right order and alignment of planes in the memory! + +from the webartz fourcc list: +YV12: 12 bpp, full sized Y plane followed by 2x2 subsampled V and U planes +I420: 12 bpp, full sized Y plane followed by 2x2 subsampled U and V planes +IYUV: the same as I420 +YVU9: 9 bpp, full sized Y plane followed by 4x4 subsampled V and U planes + +Huh 2. RGB vs. BGR ? +==================== + +The 2nd most misunderstood thingie... + +You know, there are Intel and Motorola, and they use different byteorder. +There are also others, like MIPS or Alpha, but all follow either Intel +or Motorola byteorder. +Unfortunately, the packed colorspaces depend on CPU byteorder. So, RGB +on Intel and Motorola means different order of bytes. + +In MPlayer, we have constants IMGFMT_RGBxx and IMGFMT_BGRxx. +Unfortunately, some codecs and vo drivers follow Intel, some follow Motorola +byteorder, so they are incompatible. We had to find a stable base, so long +time ago I've chosen OpenGL, as it's a wide-spreaded standard, and it well +defines what RGB is and what BGR is. So, MPlayer's RGB is compatible with +OpenGL's GL_RGB on all platforms, and the same goes for BGR - GL_BGR. +Unfortunately, most of the x86 codecs call our BGR RGB, so it sometimes +confuses developers. + +memory order: name +lowest address .. highest address +RGBA IMGFMT_RGBA +ARGB IMGFMT_ARGB +BGRA IMGFMT_BGRA +ABGR IMGFMT_ABGR +RGB IMGFMT_RGB24 +BGR IMGFMT_BGR24 + +order in an int name +most significant .. least significant bit +8A8R8G8B IMGFMT_BGR32 +8A8B8G8R IMGFMT_RGB32 +5R6G5B IMGFMT_BGR16 +5B6G5R IMGFMT_RGB16 +1A5R5G5B IMGFMT_BGR15 +1A5B5G5R IMGFMT_RGB15 + +The following are palettized formats, the palette is in the second plane. +When they come out of the swscaler (this can be different when they +come from a codec!), their palette is organized in such a way +that you actually get: + +3R3G2B IMGFMT_BGR8 +2B3G3R IMGFMT_RGB8 +1R2G1B IMGFMT_BGR4_CHAR +1B2G1R IMGFMT_RGB4_CHAR +1R2G1B1R2G1B IMGFMT_BGR4 +1B2G1R1B2G1R IMGFMT_RGB4 + +Depending upon the CPU being little- or big-endian, different 'in memory' and +'in register' formats will be equal (LE -> BGRA == BGR32 / BE -> ARGB == BGR32) + +Practical coding guide: + +The 4, 8, 15, and 16 bit formats are defined so that the portable way to +access them is to load the pixel into an integer and use bitmasks. + +The 24 bit formats are defined so that the portable way to access them is +to address the 3 components as separate bytes, as in ((uint8_t *)pixel)[0], +((uint8_t *)pixel)[1], ((uint8_t *)pixel)[2]. + +When a 32-bit format is identified by the four characters A, R, G, and B in +some order, the portable way to access it is by addressing the 4 components +as separate bytes. + +When a 32-bit format is identified by the 3 characters R, G, and B in some +order followed by the number 32, the portable way to access it is to load +the pixel into an integer and use bitmasks. + +When the above portable access methods are not used, you will need to write +2 versions of your code, and use #if HAVE_BIGENDIAN to choose the correct +one. diff --git a/DOCS/OUTDATED-tech/dr-methods.txt b/DOCS/OUTDATED-tech/dr-methods.txt new file mode 100644 index 0000000000..c8eac2aae3 --- /dev/null +++ b/DOCS/OUTDATED-tech/dr-methods.txt @@ -0,0 +1,129 @@ +DIRECT RENDERING METHODS -- by A'rpi +======================== (based on a mail to -dev-eng) + +Ok. It seems none of you really knows what direct rendering means... +I'll try to explain now! :) + +At first, there are 2 different way, both called direct rendering. +The main point is the same, but they work different. + +method 1: decoding directly to externally provided buffers. +so, the codec decodes macroblocks directly to the buffer provided by the +caller. as this buffer will be read later (for MC of next frame) it's not +a good idea to place such buffers in slow video ram. but. +there are many video out drivers using buffers in system ram, and using some +way of memcpy or DMA to blit it to video ram at display time. +for example, Xv and X11 (normal and Shm too) are such thingie. +XImage will be a buffer in system ram (!) and X*PutImage will copy it to +video ram. Only nvidia and ati rage128 Xv drivers use DMA, others just +memcpy it. Also some opengl drivers (including Matrox) uses DMA to copy from +texsubimage to video ram. +The current mplayer way mean: codec allocates some buffer, and decode image +to that buffer. then this buffer is copied to X11's buffer. then Xserver +copies this buffer to video ram. So one more memcpy than required... +direct rendering can remove this extra memcpy, and use Xserver's memory +buffers for decoding buffer. Note again: it helps only if the external +buffer is in fast system ram. + +method 2: decoding to internal buffers, but blit after each macroblocks, +including optional colorspace conversion. +advantages: it can blit into video ram, as it keeps the copy in its internal +buffers for next frame's MC. skipped macroblocks won't be copied again to +video ram (except if video buffer address changes between frames -> hw +double/triple buffering) +Just avoiding blitting of skipped MBs mean about 100% speedup (2 times +faster) for low bitrate (<700kbit) divxes. It even makes possible to watch +VCD resolution divx on p200mmx with DGA. +how does it work? the codec works as normally, decodes macroblocks into its +internal buffer. but after each decoded macroblock, it immediatelly copies +this macroblock to the video ram. it's in the L1 cache, so it will be fast. +skipped macroblocks can be skipped easily -> less vram write -> more speedup. +but, as it copies directly to video ram, it must do colorspace conversion if +needed (for example divx -> rgb DGA), and cannot be used with scaling. +another interesting question of such direct rendering is the planar formats. +Eugene K. of Divx4 told me that he experienced worse performance blittig +yv12 blocks (copied 3 blocks to 3 different (Y,U,V) buffers) than doing +(really unneeded) yv12->yuy2 conversion on-the-fly. +so, divx4 codec (with -vc divx4 api) converts from its internal yv12 buffer +to the external yuy2. + +method 2a: +libmpeg2 already uses simplified variation of this: when it finish decoding a +slice (a horizontal line of MBs) it copies it to external (video ram) buffer +(using callback to libvo), so at least it copies from L2 cache instead of +slow ram. for non-predictive (B) frames it can re-use this cached memory +for the next slice - so it uses less memory and has better cache utilization: +it gave me 23% -> 20% VOB decoding speedup on p3. libavcodec supports +per-slice callbacks too, but no slice-memory reusing for B frames yet. + +method 2b: +some codecs (indeo vfw 3/4 using IF09, and libavcodec) can export the 'bitmap' +of skipped macroblocks - so libvo driver can do selective blitting: copy only +the changed macroblocks to slow vram. + +so, again: the main difference between method 1 and 2: +method1 stores decoded data only once: in the external read/write buffer. +method2 stores decoded data twice: in its internal read/write buffer (for +later reading) and in the write-only slow video ram. + +both methods can make big speedup, depending on codec behaviour and libvo +driver. for example, IPB mpegs could combine these, use method 2 for I/P +frames and method 1 for B frams. mpeg2dec does already this. +for I-only type video (like mjpeg) method 1 is better. for I/P type video +with MC (like divx, h263 etc) method 2 is the best choice. +for I/P type videos without MC (like FLI, CVID) could use method 1 with +static buffer or method 2 with double/triple buffering. + +i hope it is clear now. +and i hope even nick understand what are we talking about... + +ah, and at the end, the abilities of codecs: +libmpeg2,libavcodec: can do method 1 and 2 (but slice level copy, not MB level) +vfw, dshow: can do method 2, with static or variable address external buffer +odivx, and most native codecs like fli, cvid, rle: can do method 1 +divx4: can do method 2 (with old odivx api it does method 1) +xanim: they currently can't do DR, but they exports their +internal buffers. but it's very easy to implement menthod 1 support, +and a bit harder but possible without any rewrite to do method 2. + +so, dshow and divx4 already implements all requirements of method 2. +libmpeg2 and libavcodec implements method 1 and 2a (lavc 2b too) + +anyway, in the ideal world, we need all codecs support both methods. +anyway 2: in ideal world, there are no libvo drivers having buffer in system +ram and memcpy to video ram... +anyway 3: in our really ideal world, all libvo driver has its buffers in +fast sytem ram and does blitting with DMA... :) + +============================================================================ +MPlayer NOW! -- The libmpcodecs way. + +libmpcodecs replaced old draw callbacks with mpi (mplayer image) struct. +steps of decoding with libmpcodecs: +1. codec requests an mpi from libmpcodecs core (vd.c) +2. vd creates an mpi struct filled by codec's requirements (size, stride, + colorspace, flags, type) +3. vd asks libvo (control(VOCTRL_GET_IMAGE)), if it can provide such buffer: + - if it can -> do direct rendering + - it it can not -> allocate system ram area with memalign()/malloc() + Note: codec may request EXPORT buffer, it means buffer allocation is + done inside the codec, so we cannot do DR :( +4. codec decodes one frame to the mpi struct (system ram or direct rendering) +5. if it isn't DR, we call libvo's draw functions to blit image to video ram + +current possible buffer setups: +- EXPORT - codec handles buffer allocation and it exports its buffer pointers + used for opendivx, xanim and libavcodec +- STATIC - codec requires a single static buffer with constant preserved content + used by codecs which do partial updating of image, but doesn't require reading + of previous frame. most rle-based codecs, like cvid, rle8, qtrle, qtsmc etc. +- TEMP - codec requires a buffer, but it doesn't depend on previous frame at all + used for I-only codecs (like mjpeg) and for codecs supporting method-2 direct + rendering with variable buffer address (vfw, dshow, divx4). +- IP - codec requires 2 (or more) read/write buffers. it's for codecs supporting + method-1 direct rendering but using motion compensation (ie. reading from + previous frame buffer). could be used for libavcodec (divx3/4,h263). + IP buffer stays from 2 (or more) STATIC buffers. +- IPB - similar to IP, but also have one (or more) TEMP buffers for B frames. + it will be used for libmpeg2 and libavcodec (mpeg1/2/4). + IPB buffer stays from 2 (or more) STATIC buffers and 1 (or more) TEMP buffer. diff --git a/DOCS/OUTDATED-tech/formats.txt b/DOCS/OUTDATED-tech/formats.txt new file mode 100644 index 0000000000..ee4aa8f6ba --- /dev/null +++ b/DOCS/OUTDATED-tech/formats.txt @@ -0,0 +1,160 @@ +1. Input layer, supported devices, methods: + - plain file, with seeking + - STDIN, without seeking backward + - network streaming (currently plain wget-like HTTP and MMS (.asx)) + - VCD (Video CD) track, by direct CDROM device access (not requires mounting disc) + - DVD titles using .IFO structure, by direct DVD device access (not requires mounting disc) + - DVD titles using menu navigation (experimental/alpha, not yet finished!!!) + - CDDA - raw audio from audio CD-ROM discs (using cdparanoia libs) + - RTP streaming (mpeg-ps over multicast only) + - LIVE555 streaming - support SDP/RTSP (using the LIVE555 libs) + - SMB - file access over samba (experimental) + +2. Demuxer/parser layer, supported file/media formats: + + - MPEG streams (ES,PES,PS. no TS support yet) + note: mpeg demuxer silently ignore non-mpeg content, and find mpeg packets + in arbitrary streams. it means you can play directly VCD images (for example + CDRwin's .BIN files) without extracting mpeg files first (with tools like vcdgear) + It accepts all PES variants, including files created by VDR. + Note: VOB (video object) is simple mpeg stream, but it usually has 01BD + packets which may contain subtitles and non-mpeg audio. Usually found on DVD discs. + + Headers: mpeg streams has no global header. each frame sequence (also called GOP, + group of pictures) contains an sequence header, it describes that block. + In normal mpeg 1/2 content there are groups of 12-15 frames (24/30 fps). + It means you can freely seek in mpeg streams, and even can cut it to + small parts with standard file tools (dd, cut) without destroying it. + + Codecs: video is always mpeg video (mpeg1, mpeg2 or mpeg4). + audio is usually mpeg audio (any layer allowed, but it's layer 2 in most files) + but 01BD packets may contain AC3, DTS or LPCM too. + + FPS: mpeg2 content allows variable framerate, in form of delayed frames. + It's mostly used for playback 24fps content at 29.97/30 fps (NTSC) rate. + (so called Telecine or 3:2 pulldown effect) + It means you see 30 frames per second, but there are only 24 different + pictures and some of them are shown longer to fill 30 frame time. + If you encode such files with mencoder, using -ofps 24 or -ofps 23.976 + is recommended. + + - AVI streams. + Two kind of RIFF AVI files exists: + 1. interleaved: audio and video content is interleaved. it's faster and + requires only 1 reading thread, so it's recommended (and mostly used). + 2. non-interleaved: audio and video aren't interleaved, i mean first come + whole video followed by whole audio. it requires 2 reading process or + 1 reading with lots of seeking. very bad for network or cdrom. + 3. badly interleaved streams: mplayer detects interleaving at startup and + enables -ni option if it finds non-interleaved content. but sometimes + the stream seems to be interleaved, but with bad sync so it should be + played as non-interleaved otherwise you get a-v desync or buffer overflow. + + MPlayer supports 2 kind of timing for AVI files: + - bps-based: it is based on bitrate/samplerate of video/audio stream. + this method is used by most players, including avifile and wmp. + files with broken headers, and files created with VBR audio but not + vbr-compliant encoder will result a-v desync with this method. + (mostly at seeking). + - interleaving-based: note: it can't be used togethwer with -ni + it doesn't use bitrate stuff of header, it uses the relative position + of interleaved audio and video chunks. makes some badly encoded file + with vbr audio playable. + + Headers: AVI files has a mandatory header at the begin of the file, + describing video parameters (resolution, fps) and codecs. Optionally + they have an INDEX block at the end of the file. It's optional, but + most files has such block, because it's REQUIRED for seeking. + Btw usually it can be rebuilt from file content, mplayer does it with + the -idx switch. MPlayer can recreate broken index blocks using -forceidx. + As AVI files needs index for random access, broken files with no index + are usually unplayable. + Of course, cutting/joining AVI files needs special programs. + + Codecs: any audio and video codecs allowed, but I note that VBR audio is + not well supported by most players. The file format makes it possible to + use VBR audio, but most players expect CBR audio and fails with VBR, + as VBR is unusual, and Microsoft's AVI specs only describe CBR audio. + I also note, that most AVI encoders/multiplexers create bad files if + using VBR audio. only 2 exception (known by me): NaNDub and MEncoder. + + FPS: only constant framerate allowed, but it's possible to skip frames. + + - ASF streams: + ASF (active streaming format) comes from Microsoft. they developed two + variant of ASF, v1.0 and v2.0. v1.0 is used by their media tools (wmp and + wme) and v2.0 is published and patented :). of course, they differ, + no compatibility at all. (it's just a legality game) + MPlayer supports only v1.0, as nobody ever seen v2.0 files :) + Note, that .ASF files are nowdays come with extension .WMA or .WMV. + UPDATE: MS recently released the ASF v1.0 specs too, but it has some + restrictions making it illegal to read by us :) + + Headers: Stream headers (codecs parameters) can be everywhere (in theory), + but all files i've seen had it at the beginning of the file. + Asf uses fixed packet size, so it is seekable without any INDEX block, + and broken files are playable well. + + Codecs: video is mostly microsoft's mpeg4 variants: MP42, MP43 (aka DivX), + WMV1 and WMV2. but any codecs allowed. + audio is usually wma or voxware, sometimes mp3, but any codecs allowed. + + FPS: no fixed fps, every video frame has an exact timestamp instead. + I've got stream with up to 3 sec frame display times. + + - QuickTime / MOV files: + They come from Mac users, usually with .mov or .qt extension, but as + MPEG Group chose quicktime as recommended file format for MPEG4, + sometimes you meet quicktime files with .mpg or .mp4 extension. + + At first look, it's a mixture of ASF and AVI. + It requires INDEX block for random access and seeking, and even for + playback, like AVI, but uses timestamps instead of constant framerate + and has more flexible stream options (including network stuff) like ASF. + + Headers: header can be placed at the beginning or at the end of file. + About half of my files have it at the beginning, others have it at the end. + Broken files are only playable if they have header at the beginning! + + Codecs: any codecs allowed, both CBR and VBR. + Note: most new mov files use Sorenson video and QDesign Music audio, + they are patented, closed, secret, (TM)-ed etc formats, only Apple's + quicktime player is able to playback these files (on win/mac only). + + - VIVO files: + They are funny streams. They have a human-readable ascii header at + the beginning, followed by interleaved audio and video chunks. + It has no index block, has no fixed packetsize or sync bytes, and most + files even has no keyframes, so forget seeking! + Video is standard h.263 (in vivo/2.0 files it's modified, non-standard + h.263), audio is either standard g.723 or Vivo Siren codec. + + Note, that microsoft licensed vivo stuff, and included in their netshow + v2.0 program, so there are VfW/ACM codecs for vivo video and audio. + + - RealMedia files: + A mixture of AVI and ASF features. It has mandatory headers at the + beginning and an optional INDEX (missing in most files). + The file is constructed of variable size chunks, with small header + telling the stream ID, timestamp, flags (keyframe...) and size. + But it has some features found in ASF files: + The video is actually double-muxed, the video chunks are really + appended fragments of the video frame. RV30+ supports B frames, so + you have to parse some bits of the first fragment to get the real PTS. + The audio frames are fixed size (CBR) but using the same scrambling + (out-of-order interleaving) as in the ASF files. + + Codecs: Audio is either COOK(er), SIPR(o), ATRAC3 or DNET. + The DNET is actually a byte-swapped low-bitrate Dolby AC3 variant :) + Video is RV10 (h263 variant), RV20 (rp G2), RV30 (rp v8) or RV40 (rp v9). + + FPS: variable, just like in ASF. + + Note, that similarity of real and asf has some background - they worked + together on the (never finished/used) ASF v2 spec for some time. + + - GIF files: + The GIF format is a common format for web graphics that supports + animation. These are read through libungif or compatible library. + Variable frame delays are supported, but seeking is not supported. + Seeking will be supported once an index of gif frames can be built. diff --git a/DOCS/OUTDATED-tech/general.txt b/DOCS/OUTDATED-tech/general.txt new file mode 100644 index 0000000000..36a584b746 --- /dev/null +++ b/DOCS/OUTDATED-tech/general.txt @@ -0,0 +1,228 @@ +So, I'll describe how this stuff works. + +The main modules: + +1. stream.c: this is the input layer, this reads the input media (file, stdin, + vcd, dvd, network etc). what it has to know: appropriate buffering by + sector, seek, skip functions, reading by bytes, or blocks with any size. + The stream_t (stream.h) structure describes the input stream, file/device. + + There is a stream cache layer (cache2.c), it's a wrapper for the stream + API. It does fork(), then emulates stream driver in the parent process, + and stream user in the child process, while proxying between them using + preallocated big memory chunk for FIFO buffer. + +2. demuxer.c: this does the demultiplexing (separating) of the input to + audio, video or dvdsub channels, and their reading by buffered packages. + The demuxer.c is basically a framework, which is the same for all the + input formats, and there are parsers for each of them (mpeg-es, + mpeg-ps, avi, avi-ni, asf), these are in the demux_*.c files. + The structure is the demuxer_t. There is only one demuxer. + +2.a. demux_packet_t, that is DP. + Contains one chunk (avi) or packet (asf,mpg). They are stored in memory as + in linked list, cause of their different size. + +2.b. demuxer stream, that is DS. + Struct: demux_stream_t + Every channel (a/v/s) has one. This contains the packets for the stream + (see 2.a). For now, there can be 3 for each demuxer : + - audio (d_audio) + - video (d_video) + - DVD subtitle (d_dvdsub) + +2.c. stream header. There are 2 types (for now): sh_audio_t and sh_video_t + This contains every parameter essential for decoding, such as input/output + buffers, chosen codec, fps, etc. There are each for every stream in + the file. At least one for video, if sound is present then another, + but if there are more, then there'll be one structure for each. + These are filled according to the header (avi/asf), or demux_mpg.c + does it (mpg) if it founds a new stream. If a new stream is found, + the ====> Found audio/video stream: <id> messages is displayed. + + The chosen stream header and its demuxer are connected together + (ds->sh and sh->ds) to simplify the usage. So it's enough to pass the + ds or the sh, depending on the function. + + For example: we have an asf file, 6 streams inside it, 1 audio, 5 + video. During the reading of the header, 6 sh structs are created, 1 + audio and 5 video. When it starts reading the packet, it chooses the + stream for the first found audio & video packet, and sets the sh + pointers of d_audio and d_video according to them. So later it reads + only these streams. Of course the user can force choosing a specific + stream with + -vid and -aid switches. + A good example for this is the DVD, where the english stream is not + always the first, so every VOB has different language :) + That's when we have to use for example the -aid 128 switch. + + Now, how this reading works? + - demuxer.c/demux_read_data() is called, it gets how many bytes, + and where (memory address), would we like to read, and from which + DS. The codecs call this. + - this checks if the given DS's buffer contains something, if so, it + reads from there as much as needed. If there isn't enough, it calls + ds_fill_buffer(), which: + - checks if the given DS has buffered packages (DP's), if so, it moves + the oldest to the buffer, and reads on. If the list is empty, it + calls demux_fill_buffer() : + - this calls the parser for the input format, which reads the file + onward, and moves the found packages to their buffers. + Well it we'd like an audio package, but only a bunch of video + packages are available, then sooner or later the: + DEMUXER: Too many (%d in %d bytes) audio packets in the buffer + error shows up. + +2.d. video.c: this file/function handle the reading and assembling of the + video frames. each call to video_read_frame() should read and return a + single video frame, and it's duration in seconds (float). + The implementation is splitted to 2 big parts - reading from mpeg-like + streams and reading from one-frame-per-chunk files (avi, asf, mov). + Then it calculates duration, either from fixed FPS value, or from the + PTS difference between and after reading the frame. + +2.e. other utility functions: there are some useful code there, like + AVI muxer, or mp3 header parser, but leave them for now. + +So everything is ok 'till now. It can be found in libmpdemux/ library. +It should compile outside of mplayer tree, you just have to implement few +simple functions, like mp_msg() to print messages, etc. +See libmpdemux/test.c for example. + +See also formats.txt, for description of common media file formats and their +implementation details in libmpdemux. + +Now, go on: + +3. mplayer.c - ooh, he's the boss :) + Its main purpose is connecting the other modules, and maintaining A/V + sync. + + The given stream's actual position is in the 'timer' field of the + corresponding stream header (sh_audio / sh_video). + + The structure of the playing loop : + while(not EOF) { + fill audio buffer (read & decode audio) + increase a_frame + read & decode a single video frame + increase v_frame + sleep (wait until a_frame>=v_frame) + display the frame + apply A-V PTS correction to a_frame + handle events (keys,lirc etc) -> pause,seek,... + } + + When playing (a/v), it increases the variables by the duration of the + played a/v. + - with audio this is played bytes / sh_audio->o_bps + Note: i_bps = number of compressed bytes for one second of audio + o_bps = number of uncompressed bytes for one second of audio + (this is = bps*samplerate*channels) + - with video this is usually == 1.0/fps, but I have to note that + fps doesn't really matters at video, for example asf doesn't have that, + instead there is "duration" and it can change per frame. + MPEG2 has "repeat_count" which delays the frame by 1-2.5 ... + Maybe only AVI and MPEG1 has fixed fps. + + So everything works right until the audio and video are in perfect + synchronity, since the audio goes, it gives the timing, and if the + time of a frame passed, the next frame is displayed. + But what if these two aren't synchronized in the input file? + PTS correction kicks in. The input demuxers read the PTS (presentation + timestamp) of the packages, and with it we can see if the streams + are synchronized. Then MPlayer can correct the a_frame, within + a given maximal bounder (see -mc option). The summary of the + corrections can be found in c_total . + + Of course this is not everything, several things suck. + For example the soundcards delay, which has to be corrected by + MPlayer! The audio delay is the sum of all these: + - bytes read since the last timestamp: + t1 = d_audio->pts_bytes/sh_audio->i_bps + - if Win32/ACM then the bytes stored in audio input buffer + t2 = a_in_buffer_len/sh_audio->i_bps + - uncompressed bytes in audio out buffer + t3 = a_buffer_len/sh_audio->o_bps + - not yet played bytes stored in the soundcard's (or DMA's) buffer + t4 = get_audio_delay()/sh_audio->o_bps + + From this we can calculate what PTS we need for the just played + audio, then after we compare this with the video's PTS, we have + the difference! + + Life didn't get simpler with AVI. There's the "official" timing + method, the BPS-based, so the header contains how many compressed + audio bytes or chunks belong to one second of frames. + In the AVI stream header there are 2 important fields, the + dwSampleSize, and dwRate/dwScale pairs: + - If the dwSampleSize is 0, then it's VBR stream, so its bitrate + isn't constant. It means that 1 chunk stores 1 sample, and + dwRate/dwScale gives the chunks/sec value. + - If the dwSampleSize is >0, then it's constant bitrate, and the + time can be measured this way: time = (bytepos/dwSampleSize) / + (dwRate/dwScale) (so the sample's number is divided with the + samplerate). Now the audio can be handled as a stream, which can + be cut to chunks, but can be one chunk also. + + The other method can be used only for interleaved files: from + the order of the chunks, a timestamp (PTS) value can be calculated. + The PTS of the video chunks are simple: chunk number * fps + The audio is the same as the previous video chunk was. + We have to pay attention to the so called "audio preload", that is, + there is a delay between the audio and video streams. This is + usually 0.5-1.0 sec, but can be totally different. + The exact value was measured until now, but now the demux_avi.c + handles it: at the audio chunk after the first video, it calculates + the A/V difference, and take this as a measure for audio preload. + +3.a. audio playback: + Some words on audio playback: + Not the playing is hard, but: + 1. knowing when to write into the buffer, without blocking + 2. knowing how much was played of what we wrote into + The first is needed for audio decoding, and to keep the buffer + full (so the audio will never skip). And the second is needed for + correct timing, because some soundcards delay even 3-7 seconds, + which can't be forgotten about. + To solve this, the OSS gives several possibilities: + - ioctl(SNDCTL_DSP_GETODELAY): tells how many unplayed bytes are in + the soundcard's buffer -> perfect for timing, but not all drivers + support it :( + - ioctl(SNDCTL_DSP_GETOSPACE): tells how much can we write into the + soundcard's buffer, without blocking. If the driver doesn't + support GETODELAY, we can use this to know how much the delay is. + - select(): should tell if we can write into the buffer without + blocking. Unfortunately it doesn't say how much we could :(( + Also, doesn't/badly works with some drivers. + Only used if none of the above works. + +4. Codecs. Consists of libmpcodecs/* and separate files or libs, + for example libmpeg2, loader, mp3lib. + + mplayer.c doesn't call them directly, but through the dec_audio.c and + dec_video.c files, so the mplayer.c doesn't have to know anything about + the codecs. + + libmpcodecs contains wrapper for every codecs, some of them include the + codec function implementation, some calls functions from other files + included with mplayer, some calls optional external libraries. + file naming convention in libmpcodecs: + ad_*.c - audio decoder (called through dec_audio.c) + vd_*.c - video decoder (called through dec_video.c) + ve_*.c - video encoder (used by mencoder) + vf_*.c - video filter (see option -vf) + + On this topic, see also: + libmpcodecs.txt - The structure of the codec-filter path, with explanation + dr-methods.txt - Direct rendering, MPI buffer management for video codecs + codecs.conf.txt - How to write/edit codec configuration file (codecs.conf) + codec-devel.txt - Mike's hints about codec development - a bit OUTDATED + hwac3.txt - about SP/DIF audio passthrough + +5. libvo: this displays the frame. + + for details on this, read libvo.txt + +6. libao2: this control audio playing +6.a audio plugins + + for details on this, read libao2.txt diff --git a/DOCS/OUTDATED-tech/hwac3.txt b/DOCS/OUTDATED-tech/hwac3.txt new file mode 100644 index 0000000000..25a2c5bc7a --- /dev/null +++ b/DOCS/OUTDATED-tech/hwac3.txt @@ -0,0 +1,145 @@ +mails by A'rpi and Marcus Blomenkamp <Marcus.Blomenkamp@epost.de> +describing how this ac3-passtrough hack work under linux and mplayer... +----------------------------------------------------------------------- +Hi, + +> I received the following patch from Steven Brookes <stevenjb@mda.co.uk>. +> He is working on fixing the digital audio output of the dxr3 driver and +> told me he fixed some bugs in mplayer along the way. I don't know shit +> about hwac3 output so all I did was to make sure the patch applied +> against latest cvs. +> This is from his e-mail to me: +> +> "Secondly there is a patch to dec_audio.c and +> ac3-iec958 to fix the -ac hwac3 codec stuff and to use liba52 to sync it. + +> Seems to work for everything I've thrown at and maintains sync for all audio +> types through the DXR3." + +patch applied (with some comments added and an unwanted change (in software +a52 decoder) removed) + +now i understand how this whole hwac3 mess work. +it's very very tricky. it virtually decodes ac3 to LPCM packets, but really +it keeps the original compressed data padded by zeros. this way it's +constant bitrate, and sync is calculated just like for stereo PCM. +(so it bypass LPCM-capable media converters...) + +so, every ac3 frame is translated to 6144 byte long tricky LPCM packet. +6144 = 4*(6*256) = 4 * samples_per_ac3_frame = LPCM size of uncompressed ac3 +frame. + +i wanna know if it works for sblive and other ac3-capable cards too? +(i can't test it, lack of ac3 decoder) + +A'rpi / Astral & ESP-team + +----------------------------------------------------------------------- +Hi folks. +I spend some time fiddling with ac3 passthrough in mplayer. The +traditional way of setting the output format to AFMT_AC3 was no ideal +solution since not all digital io cards/drivers supported this format or +honoured it to set the spdif non-audio bit. To make it short, it only +worked with oss sblive driver IIRC. + +Inspired by alsa's ac3dec program I found an alternative way by +inspecting to which format the alsa device had been set. Suprise: it was +simple 16bit_le 2_channel pcm. So setting the non-audio bit doesn't +necessarily mean the point. The only important thing seems to be +bit-identical output at the correct samplerate. Modern AV-Receivers seem +to be quite tolerant/compatible. + +So I changed the output format of hwac3 from + +AFMT_AC3 channels=1 + to +AFMT_S16_LE channels=2 + +and corrected the absolute time calculation. That was all to get it +running for me. + +----------------------------------------------------------------------- +Hi there. + +Perhaps I can clear up some mystification about AC3 passthrough in +general and mplayer in special: + +To get the external decoder solution working, it must be fed with data +which is bitidentical to the chunks in the source ac3 file (compressed +data is very picky about bit errors). Additionally - or better to say +'historically' - the non-audio bit should be set in the spdif status +fields to prevent old spdif hardware from reproducing ugly scratchy +noise. Note: for current decoders (probably those with DTS capability) +this safety bit isn't needed anymore. At least I can state that for my +Sherwood RVD-6095RDS. I think it is due to DTS because DTS sound can +reside on a ordinary AudioCD and an ordinary AudioCD-Player will always +have it's audio-bit set. + +The sample format of the data must be 2channel 16bit (little endian +IIRC). Samplerates are 48kHz - although my receiver also accepts +44100Hz. I do not know if this is due to an over-compatability of my +receiver or if 44100 is also possible in the ac3 specs. For safety's +sake lets keep this at 48000Hz. AC3 data chunks are inserted into the +stream every 0x1600 bytes (don't bite me on that, look into +'ac3-iec958.c': 'ac3_iec958_build_burst'). + +To come back to the problem: data must be played bit-identically through +the soundcard at the correct samplerate and should optionally have it's +non-audio bit set. There are two ways to accomplish this: + +1) Some OSS guy invented the format AFMT_AC3. Soundcard drivers +implementing this format should therefore adjust it's mixers and +switches to produce the desired output. Unfortunately some soundcard +drivers do not support this format correctly and most do not even +support it at all (including ALSA). + +2) The alternative approach currently in mplayer CVS is to simply set +the output format to 48kHz16bitLE and rely on the user to have the +soundcard mixers adjusted properly. + +I do have two soundcards with digital IO facilities (CMI8738 and +Trident4DWaveNX based) plus the mentioned decoder. I'm currently running +Linux-2.4.17. Following configurations are happily running here: + +1. Trident with ALSA drivers (OSS does not support Hoontech's dig. IO) +2. CMI with ALSA drivers +3. CMI with OSS drivers + +For Linux I'd suggest using ALSA because of it's cleaner architecture +and more consitent user interface. Not to mention that it'll be the +standard sound support in Linux soon. + +For those who want to stick to OSS drivers: The CMI8738 drivers works +out-of-the-box, if the PCM/Wave mixer is set to 100%. + +For ALSA I'd suggest using its OSS emulation. More on that later. +ALSA-0.9 invented the idea of cards, devices and dubdevices. You can +reach the digital interface of all supported cards consitently by using +the device 'hw:x,2' (x counting from 0 is the number of your soundcard). +So most people would end up at 'hw:0,2'. This device can only be opened +in sample formats and rates which are directly supported in hardware +hence no samplerate conversion is done keeping the stream as-is. However +most consumer soundcards do not support 44kHz so it would definitively +be a bad idea to use this as your standard device if you wanted to +listen to some mp3s (most of them are 44kHz due to CD source). Here the +OSS comes to play again. You can configure which OSS device (/dev/dsp +and /dev/adsp) uses which ALSA device. So I'd suggest pointing the +standard '/dev/dsp' to standard 'hw:0,0' which suports mixing and +samplerate conversion. No further reconfiguration would be needed for +your sound apps. For movies I'd point '/dev/adsp' to 'hw:0,2' and +configure mplayer to use adsp instead of dsp. The samplerate constrain +is no big deal here since movies usually are in 48Khz anyway. The +configuration in '/etc/modules.conf' is no big deal also: + +alias snd-card-0 snd-card-cmipci # insert your card here +alias snd-card-1 snd-pcm-oss # load OSS emulation +options snd-pcm-oss snd_dsp_map=0 snd_adsp_map=2 # do the mapping + +This works flawlessly in combination with alsa's native +SysVrc-init-script 'alsasound'. Be sure to disable any distribution +dependent script (e.g. Mandrake-8.1 has an 'alsa' script which depends +on ALSA-0.5). + +Sorry for you *BSD'lers out there. I have no grasp on sound support there. + +HTH Marcus diff --git a/DOCS/OUTDATED-tech/libao2.txt b/DOCS/OUTDATED-tech/libao2.txt new file mode 100644 index 0000000000..49cb0284f7 --- /dev/null +++ b/DOCS/OUTDATED-tech/libao2.txt @@ -0,0 +1,56 @@ +6. libao2: this control audio playing + + As in libvo (see 5.) also here are some drivers, based on the same API: + +static int control(int cmd, int arg); + This is for reading/setting driver-specific and other special parameters. + Not really used for now. + +static int init(int rate,int channels,int format,int flags); + The init of driver, opens device, sets sample rate, channels, sample format + parameters. + Sample format: usually AFMT_S16_LE or AFMT_U8, for more definitions see + dec_audio.c and linux/soundcards.h files! + +static void uninit(void); + Guess what. + Ok I help: closes the device, not (yet) called when exit. + +static void reset(void); + Resets device. To be exact, it's for deleting buffers' contents, + so after reset() the previously received stuff won't be output. + (called if pause or seek) + +static int get_space(void); + Returns how many bytes can be written into the audio buffer without + blocking (making caller process wait). MPlayer occasionally checks the + remaining space and tries to fill the buffer with play() if there's free + space. The buffer size used should be sane; a buffer that is too small + could run empty before MPlayer tries filling it again (normally once per + video frame), a buffer that is too big would force MPlayer decode the file + far ahead trying to find enough audio data to fill it. + +static int play(void* data,int len,int flags); + Plays a bit of audio, which is received throught the "data" memory area, with + a size of "len". It has to copy the data, because they can be overwritten + after the call is made. Doesn't have to use all the bytes; it has to + return the number of bytes used used (copied to buffer). If + flags|AOPLAY_FINAL_CHUNK is true then this is the last audio in the file. + The purpose of this flag is to tell aos that round down the audio played + from "len" to a multiple of some chunksize that this "len" should not be + rounded down to 0 or the data will never be played (as MPlayer will never + call play() with a larger len). + +static float get_delay(void); + Returns how long time it will take to play the data currently in the + output buffer. Be exact, if possible, since the whole timing depends + on this! In the worst case, return the maximum delay. + +!!! Because the video is synchronized to the audio (card), it's very important +!!! that the get_delay function is correctly implemented! + +static void audio_pause(void); + Pause playing but do not delete buffered data if possible. + +static void audio_resume(void); + Continue playing after audio_pause(). diff --git a/DOCS/OUTDATED-tech/libmpcodecs.txt b/DOCS/OUTDATED-tech/libmpcodecs.txt new file mode 100644 index 0000000000..b79df93d78 --- /dev/null +++ b/DOCS/OUTDATED-tech/libmpcodecs.txt @@ -0,0 +1,384 @@ +NOTE: If you want to implement a new native codec, please add it to +libavcodec. libmpcodecs is considered mostly deprecated, except for wrappers +around external libraries and codecs requiring binary support. + +The libMPcodecs API details, hints - by A'rpi +================================== + +See also: colorspaces.txt, codec-devel.txt, dr-methods.txt, codecs.conf.txt + +The VIDEO path: +=============== + + [MPlayer core] + | (1) + ______V______ (2) /~~~~~~~~~~\ (3,4) |~~~~~~| + | | -----> | vd_XXX.c | -------> | vd.c | + | dec_video | \__________/ <-(3a)-- |______| + | | -----, ,.............(3a,4a).....: + ~~~~~~~~~~~~~ (6) V V + /~~~~~~~~\ /~~~~~~~~\ (8) + | vf_X.c | --> | vf_Y.c | ----> vf_vo.c / ve_XXX.c + \________/ \________/ + | ^ + (7) | |~~~~~~| : (7a) + `-> | vf.c |...: + |______| + +Short description of video path: +1. MPlayer/MEncoder core requests the decoding of a compressed video frame: + calls dec_video.c::decode_video(). + +2. decode_video() calls the video codec previously selected in init_video(). + (vd_XXX.c file, where XXX == vfm name, see the 'driver' line of codecs.conf) + +3. The codec should initialize the output device before decoding the first + frame. It may happen in init() or at the middle of the first decode(), see + 3a. It means calling vd.c::mpcodecs_config_vo() with the image dimensions, + and the _preferred_ (meaning: internal, native, best) colorspace. + NOTE: This colorspace may not be equal to the colorspace that is actually + used. It's just a _hint_ for the colorspace matching algorithm and mainly + used as input format of the converter, but _only_ when colorspace + conversion is required, + +3a. Selecting the best output colorspace: + The vd.c::mpcodecs_config_vo() function will go through the outfmt list + defined by the 'out' lines in codecs.conf and query both vd (codec) and + vo (output device/filter/encoder) if the format is supported or not. + + For the vo, it calls the query_format() function of vf_XXX.c or ve_XXX.c. + It should return a set of feature flags, the most important ones for this + stage are: VFCAP_CSP_SUPPORTED (colorspace supported directly or by + conversion) and VFCAP_CSP_SUPPORTED_BY_HW (colorspace supported + WITHOUT any conversion). + + For the vd (codec), control() with VDCTRL_QUERY_FORMAT will be called. + If it does not implement VDCTRL_QUERY_FORMAT, (i.e. answers CONTROL_UNKNOWN + or CONTROL_NA), it is assumed to be CONTROL_TRUE (colorspace supported)! + + So, by default, if the list of supported colorspaces is constant and does + not depend on the actual file/stream header, then it is enough to list the + formats in codecs.conf ('out' field) and not implement VDCTRL_QUERY_FORMAT. + This is the case for most codecs. + + If the supported colorspace list depends on the file being decoded, list + the possible out formats (colorspaces) in codecs.conf and implement the + VDCTRL_QUERY_FORMAT to test the availability of the given colorspace for + the given video file/stream. + + The vd.c core will find the best matching colorspace, depending on the + VFCAP_CSP_SUPPORTED_BY_HW flag (see vfcap.h). If no match can be found, + it will try again with the 'scale' filter inserted between vd and vo. + If this is unsuccessful, it will fail :( + +4. Requesting buffer for the decoded frame: + The codec has to call mpcodecs_get_image() with proper imgtype & imgflag. + It will find the optimal buffering setup (preferred stride, alignment etc) + and return a pointer to the allocated and filled up mpi (mp_image_t*) struct. + The 'imgtype' controls the buffering setup, i.e. STATIC (just one buffer that + 'remembers' its content between frames), TEMP (write-only, full update), + EXPORT (memory allocation is done by the codec, not recommended) and so on. + The 'imgflags' set up the limits for the buffer, i.e. stride limitations, + readability, remembering content etc. See mp_image.h for the short + description. See dr-methods.txt for the explanation of buffer + importing and mpi imgtypes. + + Always try to implement stride support! (stride == bytes per line) + If no stride support, then stride==bytes_per_pixel*image_width. + If you have stride support in your decoder, use the mpi->stride[] value + for the byte_per_line for each plane. + Also take care of other imgflags, like MP_IMGFLAG_PRESERVE and + MP_IMGFLAG_READABLE, MP_IMGFLAG_COMMON_STRIDE and MP_IMGFLAG_COMMON_PLANE! + The file mp_image.h contains flag descriptions in comments, read it! + Ask for help on dev-eng, describing the behavior of your codec, if unsure. + +4.a. buffer allocation, vd.c::mpcodecs_get_image(): + If the requested buffer imgtype!=EXPORT, then vd.c will try to do + direct rendering, i.e. ask the next filter/vo for the buffer allocation. + It's done by calling get_image() of the vf_XXX.c file. + If it was successful, the imgflag MP_IMGFLAG_DIRECT will be set, and one + memcpy() will be saved when passing the data from vd to the next filter/vo. + See dr-methods.txt for details and examples. + +5. Decode the frame, to the mpi structure requested in 4., then return the mpi + to decvideo.c. Return NULL if the decoding failed or skipped the frame. + +6. decvideo.c::decode_video() will now pass the 'mpi' to the next filter (vf_X). + +7. The filter's (vf_X) put_image() then requests a new mpi buffer by calling + vf.c::vf_get_image(). + +7.a. vf.c::vf_get_image() will try to get direct rendering by asking the + next filter to do the buffer allocation (calls vf_Y's get_image()). + If it fails, it will fall back on normal system memory allocation. + +8. When we're past the whole filter chain (multiple filters can be connected, + even the same filter multiple times) then the last, 'leaf' filters will be + called. The only difference between leaf and non-leaf filters is that leaf + filters have to implement the whole filter API. + Currently leaf filters are: vf_vo.c (wrapper over libvo) and ve_XXX.c + (video encoders used by MEncoder). + + +Video Filters +============= + +Video filters are plugin-like code modules implementing the interface +defined in vf.h. + +Basically it means video output manipulation, i.e. these plugins can +modify the image and the image properties (size, colorspace, etc) between +the video decoders (vd.h) and the output layer (libvo or video encoders). + +The actual API is a mixture of the video decoder (vd.h) and libvo +(video_out.h) APIs. + +main differences: +- vf plugins may be "loaded" multiple times, with different parameters + and context - it's new in MPlayer, old APIs weren't reentrant. +- vf plugins don't have to implement all functions - all functions have a + 'fallback' version, so the plugins only override these if wanted. +- Each vf plugin has its own get_image context, and they can interchange + images/buffers using these get_image/put_image calls. + + +The VIDEO FILTER API: +===================== +filename: vf_FILTERNAME.c + +vf_info_t* info; + pointer to the filter description structure: + + const char *info; // description of the filter + const char *name; // short name of the filter, must be FILTERNAME + const char *author; // name and email/URL of the author(s) + const char *comment; // comment, URL to papers describing algorithm etc. + int (*open)(struct vf_instance *vf,char* args); + // pointer to the open() function: + +Sample: + +vf_info_t vf_info_foobar = { + "Universal Foo and Bar filter", + "foobar", + "Ms. Foo Bar", + "based on algorithm described at http://www.foo-bar.org", + open +}; + +The open() function: + + open() is called when the filter is appended/inserted in the filter chain. + It'll receive the handler (vf) and the optional filter parameters as + char* string. Note that encoders (ve_*) and vo wrapper (vf_vo.c) have + non-string arg, but it's specially handled by MPlayer/MEncoder. + + The open() function should fill the vf_instance_t structure with the + implemented functions' pointers (see below). + It can optionally allocate memory for its internal data (vf_priv_t) and + store the pointer in vf->priv. + + The open() function should parse (or at least check syntax of) parameters, + and fail (return 0) on error. + +Sample: + +static int open(vf_instance_t *vf, char* args) +{ + vf->query_format = query_format; + vf->config = config; + vf->put_image = put_image; + // allocate local storage: + vf->priv = malloc(sizeof(struct vf_priv_s)); + vf->priv->w = + vf->priv->h = -1; + if(args) // parse args: + if(sscanf(args, "%d:%d", &vf->priv->w, &vf->priv->h)!=2) return 0; + return 1; +} + +Functions in vf_instance: + +NOTE: All these are optional, their function pointer is either NULL or points +to a default implementation. If you implement them, don't forget to set +vf->FUNCNAME in your open() ! + + int (*query_format)(struct vf_instance *vf, unsigned int fmt); + +The query_format() function is called one or more times before the config(), +to find out the capabilities and/or support status of a given colorspace (fmt). +For the return values, see vfcap.h! +Normally, a filter should return at least VFCAP_CSP_SUPPORTED for all supported +colorspaces it accepts as input, and 0 for the unsupported ones. +If your filter does linear conversion, it should query the next filter, +and merge in its capability flags. Note: You should always ensure that the +next filter will accept at least one of your possible output colorspaces! + +Sample: + +static int query_format(struct vf_instance *vf, unsigned int fmt) +{ + switch(fmt){ + case IMGFMT_YV12: + case IMGFMT_I420: + case IMGFMT_IYUV: + case IMGFMT_422P: + return vf_next_query_format(vf,IMGFMT_YUY2) & (~VFCAP_CSP_SUPPORTED_BY_HW); + } + return 0; +} + +For the more complex case, when you have an N -> M colorspace mapping matrix, +see vf_scale or vf_format for examples. + + + int (*config)(struct vf_instance *vf, + int width, int height, int d_width, int d_height, + unsigned int flags, unsigned int outfmt); + +The config() is called to initialize/configure the filter before using it. +Its parameters are already well-known from libvo: + width, height: size of the coded image + d_width, d_height: wanted display size (usually aspect corrected w/h) + Filters should use width, height as input image dimension, but the + resizing filters (crop, expand, scale, rotate, etc) should update + d_width/d_height (display size) to preserve the correct aspect ratio! + Filters should not rely on d_width, d_height as input parameters, + the only exception is when a filter replaces some libvo functionality + (like -vf scale with -zoom, or OSD rendering with -vf expand). + flags: the "good" old libvo flag set: + 0x01 - force fullscreen (-fs) + 0x02 - allow mode switching (-vm) + 0x04 - allow software scaling (-zoom) + 0x08 - flipping (-flip) + (Usually you don't have to worry about flags, just pass it to next config.) + outfmt: the selected colorspace/pixelformat. You'll receive images in this + format. + +Sample: + +static int config(struct vf_instance *vf, + int width, int height, int d_width, int d_height, + unsigned int flags, unsigned int outfmt) +{ + // use d_width/d_height if not set by the user: + if (vf->priv->w == -1) + vf->priv->w = d_width; + if (vf->priv->h == -1) + vf->priv->h = d_height; + // initialize your filter code + ... + // OK now config the rest of the filter chain, with our output parameters: + return vf_next_config(vf,vf->priv->w,vf->priv->h,d_width,d_height,flags,outfmt); +} + + void (*uninit)(struct vf_instance *vf); + +Okay, uninit() is the simplest, it's called at the end. You can free your +private buffers etc here. + + int (*put_image)(struct vf_instance *vf, mp_image_t *mpi); + +Ah, put_image(). This is the main filter function, it should convert/filter/ +transform the image data from one format/size/color/whatever to another. +Its input parameter is an mpi (mplayer image) structure, see mp_image.h. +Your filter has to request a new image buffer for the output, using the +vf_get_image() function. NOTE: Even if you don't want to modify the image, +just pass it to the next filter, you have to either +- not implement put_image() at all - then it will be skipped +- request a new image with type==EXPORT and copy the pointers +NEVER pass the mpi as-is, it's local to the filters and may cause trouble. + +If you completely copy/transform the image, then you probably want this: + + dmpi = vf_get_image(vf->next,mpi->imgfmt, MP_IMGTYPE_TEMP, + MP_IMGFLAG_ACCEPT_STRIDE, vf->priv->w, vf->priv->h); + +It will allocate a new image and return an mp_image structure filled by +buffer pointers and stride (bytes per line) values, in size of vf->priv->w +times vf->priv->h. If your filter cannot handle stride, then leave out +MP_IMGFLAG_ACCEPT_STRIDE. Note that you can do this, but it isn't recommended, +the whole video path is designed to use strides to get optimal throughput. +If your filter allocates output image buffers, then use MP_IMGTYPE_EXPORT +and fill the returned dmpi's planes[], stride[] with your buffer parameters. +Note, it is not recommended (no direct rendering), so if you can, use +vf_get_image() for buffer allocation! +For other image types and flags see mp_image.h, it has comments. +If you are unsure, feel free to ask on the dev-eng mailing list. Please +describe the behavior of your filter, and its limitations, so we can +suggest the optimal buffer type + flags for your code. + +Now that you have the input (mpi) and output (dmpi) buffers, you can do +the conversion. If you didn't notice yet, mp_image has some useful info +fields. They may help you a lot creating if() or for() structures: + flags: MP_IMGFLAG_PLANAR, MP_IMGFLAG_YUV, MP_IMGFLAG_SWAPPED + helps you to handle various pixel formats in single code. + bpp: bits per pixel + WARNING! It's number of bits _allocated_ to store a pixel, + it is not the number of bits actually used to keep colors! + So it's 16 for both 15 and 16 bit color depth, and is 32 for + 32bpp (actually 24 bit color depth) mode! + It's 1 for 1bpp, 9 for YVU9, and is 12 for YV12 mode. Get it? + For planar formats, you also have chroma_width, chroma_height and + chroma_x_shift, chroma_y_shift too, they specify the chroma subsampling + for YUV formats: + chroma_width = luma_width >> chroma_x_shift; + chroma_height = luma_height >> chroma_y_shift; + +If you're done, call the rest of the filter chain to process your output +image: + return vf_next_put_image(vf,dmpi); + + +Ok, the rest is for advanced functionality only: + + int (*control)(struct vf_instance *vf, int request, void* data); + +You can control the filter at runtime from MPlayer/MEncoder/dec_video: +#define VFCTRL_QUERY_MAX_PP_LEVEL 4 /* test for postprocessing support (max level) */ +#define VFCTRL_SET_PP_LEVEL 5 /* set postprocessing level */ +#define VFCTRL_SET_EQUALIZER 6 /* set color options (brightness,contrast etc) */ +#define VFCTRL_GET_EQUALIZER 8 /* get color options (brightness,contrast etc) */ +#define VFCTRL_DRAW_OSD 7 +#define VFCTRL_CHANGE_RECTANGLE 9 /* Change the rectangle boundaries */ + + + void (*get_image)(struct vf_instance *vf, mp_image_t *mpi); + +This is for direct rendering support, works the same way as in libvo drivers. +It makes in-place pixel modifications possible. +If you implement it (vf->get_image!=NULL), then it will be called to do the +buffer allocation. You SHOULD check the buffer restrictions (stride, type, +readability etc) and if everything is OK, then allocate the requested buffer +using the vf_get_image() function and copying the buffer pointers. + +NOTE: You HAVE TO save the dmpi pointer, as you'll need it in put_image() +later on. It is not guaranteed that you'll get the same mpi for put_image() as +in get_image() (think of out-of-order decoding, get_image is called in decoding +order, while put_image is called for display) so the only safe place to save +it is in the mpi struct itself: mpi->priv=(void*)dmpi; + + + void (*draw_slice)(struct vf_instance *vf, unsigned char** src, + int* stride, int w,int h, int x, int y); + +It's the good old draw_slice callback, already known from libvo. +If your filter can operate on partial images, you can implement this one +to improve performance (cache utilization). + +Ah, and there are two sets of capability/requirement flags (vfcap.h type) +in vf_instance_t, used by the default query_format() implementation, and by +the automatic colorspace/stride matching code (vf_next_config()). + + // caps: + unsigned int default_caps; // used by default query_format() + unsigned int default_reqs; // used by default config() + +BTW, you should avoid using global or static variables to store filter instance +specific stuff, as filters might be used multiple times and in the future even +multiple streams might be possible. + + +The AUDIO path: +=============== +TODO!!! diff --git a/DOCS/OUTDATED-tech/libvo.txt b/DOCS/OUTDATED-tech/libvo.txt new file mode 100644 index 0000000000..245d29eade --- /dev/null +++ b/DOCS/OUTDATED-tech/libvo.txt @@ -0,0 +1,173 @@ +libvo --- the library to handle video output by A'rpi, 2002.04 +============================================ + +Note: before start on this, read colorspaces.txt ! + +The constants for different pixelformats are defined in img_format.h, +their usage is mandatory. + +WARNING: Please keep in mind that some of this information may be out-dated, +so if you are working on a new vo, consider submitting preliminary patches +very early on. Currently vo_gl is one of the more up-to-date VOs to use +as reference if you are unsure about something and do not want to ask on the +list. +vo_vdpau and vo_direct3d may be a good choice, too, they use different +approaches closer to the sometimes convoluted way DirectX works. + +Each vo driver _has_ to implement these: + + preinit(): + init the video system (to support querying for supported formats) + + uninit(): + Uninit the whole system, this is on the same "level" as preinit. + + control(): + Current controls (VOCTRL_QUERY_FORMAT must be implemented, + VOCTRL_DRAW_IMAGE, VOCTRL_FULLSCREEN, VOCTRL_UPDATE_SCREENINFO + should be implemented): + VOCTRL_QUERY_FORMAT - queries if a given pixelformat is supported. + It also returns various flags decsirbing the capabilities + of the driver with teh given mode. for the flags, see + file vfcaps.h ! + the most important flags, every driver must properly report + these: + 0x1 - supported (with or without conversion) + 0x2 - supported without conversion (define 0x1 too!) + 0x100 - driver/hardware handles timing (blocking) + also SET sw/hw scaling and osd support flags, and flip, + and accept_stride if you implement VOCTRL_DRAW_IMAGE (see bellow) + NOTE: VOCTRL_QUERY_FORMAT may be called _before_ first config() + but is always called between preinit() and uninit() + VOCTRL_GET_IMAGE + libmpcodecs Direct Rendering interface + You need to update mpi (mp_image.h) structure, for example, + look at vo_x11, vo_sdl, vo_xv or mga_common. + VOCTRL_DRAW_IMAGE + replacement for the current draw_slice/draw_frame way of + passing video frames. by implementing SET_IMAGE, you'll get + image in mp_image struct instead of by calling draw_*. + unless you return VO_TRUE for VOCTRL_DRAW_IMAGE call, the + old-style draw_* functils will be called! + Note: draw_slice is still mandatory, for per-slice rendering! + VOCTRL_RESET - reset the video device + This is sent on seeking and similar and is useful if you are + using a device which prebuffers frames that need to flush them + before refilling audio/video buffers. + VOCTRL_PAUSE + VOCTRL_RESUME + VOCTRL_GUISUPPORT + return true only if driver supports co-operation with + MPlayer's GUI (not yet used by GUI) + VOCTRL_SET_EQUALIZER + set the video equalizer to the given values + two arguments are provided: item and value + item is a string, the possible values are (currently): + brightness, contrast, saturation, hue + VOCTRL_GET_EQUALIZER + get the current video equalizer values + two arguments are provided: item and value + item is a string, the possible values are (currently): + brightness, contrast, saturation, hue + VOCTRL_ONTOP + Makes the player window stay-on-top. Only supported (currently) + by drivers which use X11, except SDL, as well as directx and + gl2 under Windows. + VOCTRL_BORDER + Makes the player window borderless. + VOCTRL_FULLSCREEN + Switch from and to fullscreen mode + VOCTRL_GET_PANSCAN + VOCTRL_SET_PANSCAN + Needed to implement pan-scan support ('w' and 'e' keys during + playback in fullscreen mode) + VOCTRL_START_SLICE + Called before the first draw_slice of each frame, useful if + you need to do some set-up work. + VOCTRL_DRAW_EOSD + Required for EOSD (ASS subtitle) support. Provides all + information necessary to draw the EOSD for the current video + frame. + VOCTRL_GET_EOSD_RES + Required for EOSD (ASS subtitle) support. Informs the ASS + renderer about the properties of the drawing area (size, + borders). + VOCTRL_SET_DEINTERLACE + VOCTRL_GET_DEINTERLACE + Get or set deinterlacing status for VOs that support some kind + of deinterlacing. + VOCTRL_UPDATE_SCREENINFO + Should set the xinerama_x, xinerama_y, vo_screenwidth and + vo_screenheight appropriately for the currently used + monitor and -xineramascreen option. + Usually should simply call the w32_update_xinerama_info or + update_xinerama_info function. + By supporting this, the VO also requests the newer API + that sets vo_dx, vo_dy etc. appropriately before config() + is called. + + config(): + Set up the video system. You get the dimensions and flags. + width, height: size of the source image + d_width, d_height: wanted scaled/display size (it's a hint) + Flags: + 0x01 - force fullscreen (-fs) + 0x02 - allow mode switching (-vm) + 0x04 - allow software scaling (-zoom) + 0x08 - flipping (-flip) + They're defined as VOFLAG_* (see libvo/video_out.h) + + IMPORTANT NOTE: config() may be called 0 (zero), 1 or more (2,3...) + times between preinit() and uninit() calls. You MUST handle it, and + you shouldn't crash at second config() call or at uninit() without + any config() call! To make your life easier, vo_config_count is + set to the number of previous config() call, counted from preinit(). + It's set by the caller (vf_vo.c), you don't have to increase it! + So, you can check for vo_config_count>0 in uninit() when freeing + resources allocated in config() to avoid crash! + + You should implement VOCTRL_UPDATE_SCREENINFO so that vo_dx, vo_dy, + vo_dwidth and vo_dheight are already pre-set to values that take + aspect and -geometry into account. It is also necessary to properly + support multi-monitor setups (if based on x11_common, w32_common). + + draw_slice(): this displays YV12 pictures (3 planes, one full sized that + contains brightness (Y), and 2 quarter-sized which the colour-info + (U,V). MPEG codecs (libmpeg2, opendivx) use this. This doesn't have + to display the whole frame, only update small parts of it. + If this is not supported, it must be signaled in QUERY_FORMAT with + VOCAP_NOSLICES. + + draw_frame(): this is the older interface, this displays only complete + frames, and can do only packed format (YUY2, RGB/BGR). + Win32 codecs use this (DivX, Indeo, etc). + If you implement VOCTRL_DRAW_IMAGE, you do not need to implement draw_frame. + + draw_osd(): this displays subtitles and OSD. + It's a bit tricky to use it, since it's a callback-style stuff. + It should call vo_draw_text() with screen dimension and your + draw_alpha implementation for the pixelformat (function pointer). + The vo_draw_text() checks the characters to draw, and calls + draw_alpha() for each. As a help, osd.c contains draw_alpha for + each pixelformats, use this if possible! + Note that if you do not draw directly onto the video you should + use vo_draw_text_ext() which allows you to specify the border + values etc. needed to draw DVD menu highlights at the correct place. + If you do not want to implement this, you can still use -vf + expand=osd=1 to draw the OSD, or even implement code to insert + this filter automatically. + Make sure you set VFCAP_OSD depending on whether you implemented it + or not. + + NOTE: This one will be obsolete soon! But it's still useful when + you want to do tricks, like rendering osd _after_ hardware scaling + (tdfxfb) or render subtitles under of the image (vo_mpegpes, sdl) + + NOTE2: above NOTE is probably wrong, there are currently no plans to + obsolete draw_osd, though there is the more advanced EOSD support for + ASS subtitles. + + flip_page(): this is called after each frame, this displays the buffer for + real. This is 'swapbuffers' when doublebuffering. + Try to do as little work here as possible, since that affect jitter/ + A-V sync. diff --git a/DOCS/OUTDATED-tech/manpage.txt b/DOCS/OUTDATED-tech/manpage.txt new file mode 100644 index 0000000000..f3ad7fd355 --- /dev/null +++ b/DOCS/OUTDATED-tech/manpage.txt @@ -0,0 +1,283 @@ +======================================== +A documentation about MPlayer's man page +======================================== + + +About the documentation +----------------------- + +Yes it's true: This is the documentation of the documentation (man page). +This guide should be used as a reference for questions about the man page +structure. It's not a strict guide but we recommend following it to get a +uniform man page. + + + +What belongs in the man page? +----------------------------- + + - option descriptions (all) + - usage (options, configuration files, controls) + - basic examples + + + +What doesn't belong in the man page? +------------------------------------ + + - instructions for installation, encoding and similar processes + - detailed evaluations or hints + - tutorials, guides + + + +How should patches look like? +----------------------------- + +Follow the rules in patches.txt, they apply to the man page, too. +Exceptions are: + + - Cosmetic patches are allowed but should be done separately from the real + changes, be marked as cosmetic changes and shouldn't change the general + style without reasons/permissions. + - The same applies to spell checking. + + + +How do I create an HTML, text or other version of the man page? +--------------------------------------------------------------- + +The man page was more or less designed for groff as it is the main tool for +it. Therefore only groff produces acceptable results without changes. +Additionally, the SS variable should be set to either very low or very high +values to produce a better groff HTML output (Due to a bug of groff2html?). +A setting of 4 should look readable. Here's an overview again: + + - groff: + groff is the "official" tool to convert man pages. To get good results you + need a recent version (1.18.2). + groff -mman -Thtml mplayer.1 > mplayer.1.html + groff -mman -Tlatin1 -rLL=78n mplayer.1 | col -bxp > mplayer.1.txt + The groff man page lists other output formats to use with -T. + + Unfortunately groff is not able to handle UTF-8 input as of version 1.19.2. + groff-utf8 is a wrapper that works around these deficiencies: + http://www.haible.de/bruno/packages-groff-utf8.html + + - man2html: + You can view it through a CGI script: + http://localhost/cgi-bin/man2html?mplayer + The output is unusable as the script doesn't seem to support the macro + definitions. Maybe manually changing all leads to acceptable results. + + - rman: + rman -f html mplayer.1 > man_page.rman.html + The output is ugly as rman doesn't understand many of the macros used. + + - troffcvt: + troff2html -man mplayer.1 > man_page.tcvt.html + The (good) output is similar to groff but simplified... + + + +The structure +------------- + +The option descriptions are divided into sections. Inside a section options are +alphabetically sorted. The sections are: + +(Header) + not visible, copyright and author information +(Macro definitions) + not visible, some macro definitions +NAME + The man page is used for both mplayer and mencoder. +SYNOPSIS + a description of MPlayer's playtree +DESCRIPTION + a general description of MPlayer, MEncoder, GMPlayer and their features +INTERACTIVE CONTROL + description of MPlayer's input system and interactive controls +USAGE + some general notes about usage +CONFIGURATION FILES + description of the configuration file format +GENERAL OPTIONS + General options that are common to both MPlayer and MEncoder. +PLAYER OPTIONS (MPLAYER ONLY) + user interface option descriptions (MPlayer only) +DEMUXER/STREAM OPTIONS + demuxer and stream layer option descriptions +OSD/SUBTITLE OPTIONS + This section is special in that it contains all subtitle and OSD option + descriptions even if they might belong to one of the other sections. It + was created because of its size. +AUDIO OUTPUT OPTIONS (MPLAYER ONLY) + audio output layer (ao) option descriptions (MPlayer only) +AUDIO OUTPUT DRIVERS (MPLAYER ONLY) + audio output driver description (ao) +VIDEO OUTPUT OPTIONS (MPLAYER ONLY) + video output layer (vo) option descriptions (MPlayer only) +VIDEO OUTPUT DRIVERS (MPLAYER ONLY) + video output driver description (vo) +DECODING/FILTERING OPTIONS + decoding/filtering layer options (ad, vd, pl) +VIDEO FILTERS + video filter description (vf) +GENERAL ENCODING OPTIONS (MENCODER ONLY) + Encoding option descriptions (ve) (MEncoder only). +CODEC SPECIFIC ENCODING OPTIONS (MENCODER ONLY) + Codec specific option descriptions (lavc,divx4,xvid,lame) (MEncoder only). +FILES + a list and description of all installed/used files/directories +EXAMPLES OF MPLAYER USAGE + basic examples, again: no long descriptions/processes +EXAMPLES OF MENCODER USAGE + basic examples, again: no long descriptions/processes +BUGS +AUTHORS + + + +The man page/groff format +------------------------- + +Just read this and RTFS: + + man 7 roff + http://www.tldp.org/HOWTO/mini/Man-Page.html + man 7 man + man 7 groff + + + +"Style" guidelines +------------------ + +This section was kept simple but there are certain guidelines/rules to get a +uniform man page. The best way is to read (and understand) the source. + + +General: + + - No line should contain more than 79 characters. + - used commands: .TH, .SH, .TP, .IP, .PP, .[R]B, .I, .br, .RS, .RE, .na, + .nh, .ad, .hy, macro definitions, comments and some more + - Don't forget the quotation marks around expressions, etc... + - Each new sentence should start on a line of its own. + - There is a typographical difference between a hyphen, a minus and an + en-dash or em-dash. For the man page this means that you should put a + backslash before a '-' if it denotes a range (1\-10), an option (\-fs), + stdin (\-), a dash (mplayer \- movie player) or a minus (\-1). Use just + '-' if it is a hyphen (A-V). + - Don't start a line with "'" or ".", nroff treats them specially. + - To quickly check a manual page for markup errors, just run + man DOCS/man/XX/mplayer.1 > /dev/null + + +Option descriptions: + + - Options should be in alphabetical order. + - Option and/or suboption parameters should be short, descriptive and put + in angular brackets (e.g. \-vo <driver>). + - If the option has a parameter in a certain range, specify it right after + the option (e.g. \-subpos <0\-100>). + - Optional things should be put in square brackets ([]). + - Obsolete options are followed by (OBSOLETE), beta options by + (BETA CODE), etc. + - MPlayer-only options in a section which isn't marked this way + are followed by (MPlayer only). + - Add references to other options if they belong to each other, e.g. + '(\-vo zr only)' or '(also see \-alang)' or are commonly used together. + - If a nontrivial default parameter exists, mention it, e.g. (default: 24). + - Put examples and notes at the end of the description (before suboptions). + - The end of the suboptions _always_ has to be followed by a paragraph + (BUG). + - For flag options just document the non-default one of \-XXX and \-noXXX. + If the option is not a flag, describe both, one below the other (this is + an exception to the alphabetical order). + + +Macro definitions (see beginning of man page): + + - .SS starting value of the suboption column + - .IPs Add new suboption (we use .TP for normal options and .IP for + the rest). + - .RSs begin of suboptions, end with .RE + - .RSss begin of suboptions in a suboption + - .REss end of suboptions in a suboption + + +Options, suboptions, examples structure: + + - Normal options (note the '<' and '>'): + + [...] + .TP + .B \-option <parameter> + description + [...] + + - Long suboptions: + + [...] + description. Available options are: + . + .RSs + .IPs "subopt1=<value>" + description1 + .IPs "subopt2=<value>" + description2 + [...] + .IPs "last subopt=<value>" + last description + .RE + . + [...] + + - Short suboptions: + + [...] + description. Available options are: + + .PD 0 + .RSs + .IPs "subopt1=<value>" + description1 + .IPs "subopt2=<value>" + description2 + [...] + .IPs "last subopt=<value>" + last description + .RE + .PD 1 + . + [...] + + - Suboptions in suboptions: + + [...] + .IPs "subopt1=<value>" + description1 + .RSss + subsubopt1: description1 + .br + subsubopt2: description2 + [...] + .REss + [...] + + - Examples: + + [...] + + .I EXAMPLE: + .PD 0 + .RSs + .IP "\-option used parameters" + description + [...] + .RE + .PD 1 + . + [...] diff --git a/DOCS/OUTDATED-tech/mpsub.sub b/DOCS/OUTDATED-tech/mpsub.sub new file mode 100644 index 0000000000..df09438211 --- /dev/null +++ b/DOCS/OUTDATED-tech/mpsub.sub @@ -0,0 +1,100 @@ +TITLE=Weird Al Yankovic - The Saga Begins (clip) + # just to be informative (maybe future + # use?) +FILE=14233792,7972c637f619e01854ecb453b7339e3f # size,md5 +AUTHOR=Gabucino +TYPE=VIDEO # maybe AUDIO in future (for displaying + # mp3 lyrics while playing or whatever) +FORMAT=TIME # this file contains measures based on + # TIME, not frames. + +# if FORMAT is a number, then it's frame based, i.e.: +# FORMAT=25 + +NOTE=MPlayerSub test file v0.1 + +# first number : wait this much after previous subtitle disappeared +# second number : display the current subtitle for this many seconds + +15 3 +A long, long time ago... + +0 3 +in a galaxy far away... + +0 3 +Naboo was under an attack. + +1 2.5 +And I thought me and +Qui-Gon Jinn could + +0 2.5 +talk the Federation into + +0 4 +...maybe cutting them a +little slack. + +2 3 +But their response, it +didn't thrill us, + +0 3 +They locked the doors, +and tried to kill us. + +0 2.5 +We escaped from that gas, + +0 3.5 +then met Jar-jar and +Boss-Nass. + +1 6 +We took a bongo from the +scene and we went to +Theed to see the Queen. + +0 5 +We all wound' up on +Tatooine. + +0 6 +That's where, we've found +this boy. + +0 4 +Oh my, my this here +Anakin guy, + +0 5 +maybe Vader someday +later now he's just +a small fry. + +0 4 +And he left his home and +kissed his mommy goodbye, + +0 5 +singing "Soon I'm gonna be +a Jedi!" + +6 6 +Did you know this junkyard +slave isn't even old enough +to shave, + +0 3 +but he can use the Force, +they say. + +1 6 +Ahh, do you see him hitting +on the queen though he's +just nine and she's fourteen + +0 6 +yeah, he's probably gonna +marry her, someday! diff --git a/DOCS/OUTDATED-tech/playtree b/DOCS/OUTDATED-tech/playtree new file mode 100644 index 0000000000..2aaf5a175e --- /dev/null +++ b/DOCS/OUTDATED-tech/playtree @@ -0,0 +1,123 @@ + +How work the playtree ? + +Good question, I try to explain but note that it's the first doc +I write :) + +First there is two things. The playtree itself and the iterator. +The playtree represent the data and the iterator is used by +mplayer to go from entry to entry. + +First the play_tree struct : + + +struct play_tree { + play_tree_t* parent; + play_tree_t* child; + play_tree_t* next; + play_tree_t* prev; + + play_tree_param_t* params; + int loop; + char** files; + int entry_type; +}; + +The play_tree_t* hold the links in the 4 directions, the params hold +all parameters of this entry, loop is obvious (loop < 0 mean infint loop), +files hold all the files of this entry and entry_type obviously tell the +type of this entry (Node, file, dvd, vcd ot tv). + +An entry can hold more than one file, why ? + +Because an entry can be a network stream and usually you have more than +one server. But all send the same thing, so it's only on entry with sevral +sources. + +Then how do I use this stuff ? + +First you create an entry using the play_tree_new func. This create the struct +and fill it with defaults values. +Then this can become a node or a leaf. It will become a node as soon as you link it +to another one using either play_tree_set_child or play_tree_set_parent. +Or it will become a leaf as soon as you use play_tree_add_file on it. +If an entry contain at least one file it can't become an node (an assert will be +raised) and if en entry has a child you can't add file to (here also an assert will +be raised). +Then to create a list of entry you should use play_tree_append_entry, +play_tree_prepend_entry or play_tree_insert_entry. +In all this function you can use any entry of the the list as first argument, +no need that it's the first one. The same apply when you set the child of a node, +the child argument can be any entry in a list. +To remove an entry from the tree use play_tree_remove. If the second arg (free_it) +is true it will also free it, if the entry should be freed and the third +arg is true it will also free the children. + +When your tree is ready you can then use play_tree_cleanup to remove all unuseful +entries. + +If you want to load a playlist you can use parse_playtree which take a stream_t +as argument or parse_playlist_file which take a filename as argument. +Both function will return NULL in case of failure or a new (cleaned) tree that +you can add somewhere in your tree. + +How do I add DVD, VCD or TV entry to the tree ? + +You should use some virtual URL as filename like : + dvd://x where x is the title number. + vcd://x where x is the track number + tv://x where x is the channel + + +My playtree is ready now, what with this play_tree_iter ? + +This is an iterator used to go trough the tree. It handle itself +loop of list and setting mplayer config according to the params +of each entry. +It's created with play_tree_iter_new which take as argument a play_tree_t +and an m_config_t which is then used to set/unset the params of each entry. +After creation the iter point to nothing, you should init with a first step. +To go to another entry in the list you should use play_tree_iter_step. The +second argument is the direction of the step : positive value go frontward, +negative go backward and 0 don't move. The third tell if must care of +node or not. If it's true, the iterator will stop on nodes, otherwise it go +to the next valid entry. +This function return different values : +PLAY_TREE_ITER_ERROR : obvious +PLAY_TREE_ITER_ENTRY : we are now on an entry +PLAY_TREE_ITER_NODE : we are now on a node +PLAY_TREE_ITER_END : we are now at end +(( Note : I must add a PLAY_TREE_ITER_BEGINNING for the beginning. Don't know +what it will return in a such case. PLAY_TREE_ITER_ERROR ? )) + +There is also play_tree_iter_up_step which can be used to break a loop or skip +the current list. The argument are the same than play_tree_iter_step. The +difference is that it go back to parent of the current list, and then step according +to the arguments. + +Then when your iter returned PLAY_TREE_ITER_ENTRY you can use +play_tree_iter_get_file to get the file. If you call it more than one time +it will return the next file for this entry or loop trough the list if no more +file are available. You can now how many files are available using +iter->num_files and which one it returned using iter->file. +In case the entry is a DVD, VCD or TV channel the returned string is not a filename +but "DVD title x", "VCD track x" or "TV channel x". +To distinc those case from a normal file you can check iter->tree->entry_type. +It will contain one of PLAY_TREE_ENTRY_DVD, PLAY_TREE_ENTRY_VCD, +PLAY_TREE_ENTRY_TV or PLAY_TREE_ENTRY_FILE. + +If you need to make some check with the iter, such as will next entry be valid, etc +You must create a clone with play_tree_iter_new_copy. This iter will not affect +the config, so you can do all you want with it. + +Then when you have finish with the iter free it with play_tree_iter_free. + + +Ok, that's all for now. To have some exemples look into mplayer.c ;) +First just after config parsing, the iterator is created there. Also +after stream opening, in case the stream is a playlist it replace the +entry which contained the playlist by the result of the parsing. +In the event handling it check if a step can be done, etc. And finnaly +at the end it go the next entry. + +Suggestion, flames, etc about this doc must go to albeu@free.fr diff --git a/DOCS/OUTDATED-tech/realcodecs/TODO b/DOCS/OUTDATED-tech/realcodecs/TODO new file mode 100644 index 0000000000..5ba035bfdd --- /dev/null +++ b/DOCS/OUTDATED-tech/realcodecs/TODO @@ -0,0 +1,22 @@ +TODO: + +- more docs are coming as I find the time to write them down +- use RV20toYUV420Free() +- audio support - nearly DONE (look below) +- internet streaming support +- searching - we need to take care of the audio interleaving - + haven't taken steps to locate audio key frames (does such thing + exist?) +- some media files can't be played (mplayer crashes/fails) because + it asks for decoded audio data, but the buffer in the audio + demuxer packets are empty/missing. It seems that the necessary + audio packets haven't been decoded completely (incomplete interleaving) + the audio stream packets may get mixed with video stream packet - DONE ??? +- put variables for audio streaming inside real_priv_t +- audio support for other formats than COOK - use a switch + (like -forcereal) to activate it - no switch needed, win32 codecs + doens't work (it was a nonworking attempt) +- postprocessing support (see rp8 preferences->performance->cpu usage, + also statistics->streams->video->POST FILTER: ON + (i've found that custommessage calls differ wiht pp on/off, but adding + these calls to mplayer didn't make a pixel difference between outputs) diff --git a/DOCS/OUTDATED-tech/realcodecs/audio-codecs.txt b/DOCS/OUTDATED-tech/realcodecs/audio-codecs.txt new file mode 100644 index 0000000000..fd28ab2a16 --- /dev/null +++ b/DOCS/OUTDATED-tech/realcodecs/audio-codecs.txt @@ -0,0 +1,155 @@ +all audio codecs (cook,atrk,14_4,28_8,dnet,sipr) have the same interface, +but i have only analyzed the cook codec + + +audio properties (hex) + +00 short text/description of the format (bitrate, when to use) +01 bitrate (bits/s) //avg. bytes/sec output +02 ulong: ? + ulong: samples per second + ushort: bits/sample + ushort: number of channels +03 same as 02 //constant 2 +04 long description +05 constant 1 (always?) +06 ulong: block align (input frame size for RADecode) +07 string: minimum player version +08 n/a +09 n/a +0A n/a +0B n/a +0C n/a +0D ? +0E ? leaf size +0F ? +10 ? +11 ? +12 ? +13 min. output buffer size? max. number of samples? +14 ? + + + + +functions: + +ulong result=RAOpenCodec2(ra_main_t *raMain); + +ulong result=RAInitDecoder(ra_main_t *raMain, ra_init_struct *raInit); +struct ra_init_struct { + ulong sample_rate; + ushort bits_per_sample; // unused by RAInitDecoder + ushort number_of_channels; + ushort unknown1; // 0 + ushort unknown2; // also unused (100) + ulong leaf_size; // leaf size (used for interleaving, but + // exists in audio stream description header (ASDH)) + ulong block_align; // packet size + ulong bits_per_sample; // unused (always 16) + char *ext_data; // 16 bytes located at the end of the + // ASDH +}; + +There are some information missing that you usually need for playback, +like bits per sample (the fileds aren't read by RAInitDecoder()). These +are hard coded in the "flavors", i.e. the sub formats. A flavor is an entry +in the list of available format variations like bitrate, number of channels, +decoding algorithm, and so on.We can get those information with the +following command: + + + +void *GetRAFlavorProperty(ra_main_t *raMain, ulong flavor, ulong property, + short *property_length_in_bytes); +returns property data for a specific data + +This is not important, because it's just a read only function. +These flavor properties don't seem to exist in + + +ulong RADecode(ra_main_t *raMain, char *input_buffer, + ulong input_buffer_size, char *output_buffer, + ulong *decoded_bytes, ulong p6=-1); + +RAFreeDecoder(ra_main_t *); + +RACloseCodec(ra_main_t *); + + +ulong RASetFlavor(ra_main_t *ra_main, ulong flavor); + +Set the flavor of the stream. + +a flavor is an entry in the list of available format variations like +bitrate, number of channels, decoding algorithm, and so on + + +audio data storage: +------------------- + +With Real Audio V5 (or earlier?), the audio streams can be interleaved, +i.e. the stream is striped amongst several data packets. The packets +(which have a fixed size packet_len) are split up into a fixed number +of num_parts equally sized parts - I call them leaves in lack of +better name. The leaves have the size leaf_size = packet_len / num_parts. + +To create a bunch of packets, you need 2*num_parts stream packets. +The first part of the first stream packet is stored in leaf number 0, +the first part of the second into leaf number num_parts, the one of the +next one into leaf number 1 etc. The following part of a stream packet +is stored 2*num_packets behind the current part of the same stream packet. + +In short words: when you have a matrix with the leaves as the values, +it's a transposition in conjunction with a permutation. + +packet | leaf | stream packet, part no. +-------+---------------+------------------------ +0 | 0 | (0,0) +0 | 1 | (2,0) +. | . | . +. | . | . +0 | num_parts-1 | (2*num_parts-2,0) +0 | num_parts | (1,0) +0 | num_parts+1 | (3,0) +. | . | . +. | . | . +0 | 2*num_parts-1 | (2*num_parts-1,0) +1 | 0 | (0,1) +. | . | . +. | . | . + + +sequence of calls: +------------------ + +RAOpenCodec2() + +RAInitDecoder() + +RASetFlavor() + +RAGetFlavorProperty(0xE) + +sequence of RADecode()s + +once a RAGetFlavorProperty(0xE) after some RADecode()s + +and occasionally the following sequence: +RAGetFlavorProperty(0) +RAGetFlavorProperty(7) +which is rather pointless because they only return +cleartext audio descriptions + +RAFreeDecoder() + +RACloseCodec() + + + +RAFlush(ra_main_t *raMain, char *output_buffer, ulong *retval) +will be called when seeking +output_buffer points to the output buffer from the last +decode operation. +retval is unknown, returning always 0x18 in a specific sample +-> further investigation needed diff --git a/DOCS/OUTDATED-tech/realcodecs/streaming.txt b/DOCS/OUTDATED-tech/realcodecs/streaming.txt new file mode 100644 index 0000000000..a4af485b9b --- /dev/null +++ b/DOCS/OUTDATED-tech/realcodecs/streaming.txt @@ -0,0 +1,58 @@ +In the RV30 format, another encapsulated data layer for the video stream +has been introduced. In lack of a name I'll call them sub packets, the +normal packets which exist in RV10 I'll call - well - packets. The stream +of bytes which is put in one memory block is named block. + +The format extension has been * by wild guessing and comparing the +received data between the original viewer and the demuxer. + + + +Every packet may contain one or more sub packets, and one block may +be contained inside one or more adjacent (sub) packets. +A sub packet (fragment) starts with a small header (two letters are one byte): + + +aa(bb)[cccc{gggg}dddd{eeee}ff] + +aa: indicates the type of header + the 2MSB indicate the header type (mask C0) + C0: the [] part exists, but not () -> whole packet (not fragmented) + 00, 80: the data block is encapsulated inside multiple packets. + bb contains the sequence number, beginning with 1. + 80 indicates the last sub packet containing data for the + current block. no C0 or 40 sub packet follows until + the block has been finished with a 80 sub packet. + No packet with another stream than the current video stream + is inside the sub packet chain, at least I haven't seen + such case - the demuxer will shout in this case. + 40: [] does not exist, the meaning of bb is unknown to me + data follows to the end of the packet + mask 3F: unknown +bb: sub-seq - mask 0x7f: the sequence number of the _fragment_ + mask 0x80: unknown, seems to alternating between 00 and 80 +cccc: mask 3FFF: _total_ length of the packet + mask C000: unknown, seems to be always 4000 + when it's all 0000, it indicates value >=0x4000, you should read {gggg} + and use all 16 bits of it. dunno what happens when length>=65536... +dddd: when it's 0, {} exists (only in this case) + mask 3FFF: offset of fragment inside the whole packet. it's counted + from the beginning of the packet, except when hdr&0x80, + hten it's relative to the _end_ of the packet, so it's + equal to fragment size! + mask C000: like cccc, except the first case (always 4000) + when it's all 0000, it indicates value >=0x4000, you should read {eeee} + and use all 16 bits of it. dunno what happens when length>=65536... +ff: sequence number of the assembled (defragmented) packets, beginning with 0 + +NOTE: the demuxer should build a table of the subpacket offsets relative to the +start of whole packet, it's required by the rv20/rv30 video decoders. + + +packet header: + +ushort unknown +ulong blocksize +ushort streamid +uchar reserved +uchar flags 1=reliable, 2=keyframe diff --git a/DOCS/OUTDATED-tech/realcodecs/video-codecs.txt b/DOCS/OUTDATED-tech/realcodecs/video-codecs.txt new file mode 100644 index 0000000000..af2152061a --- /dev/null +++ b/DOCS/OUTDATED-tech/realcodecs/video-codecs.txt @@ -0,0 +1,185 @@ +The work has been based on the RV30 codec, but since RV20 has the same +interface, it might work for it as well. + + + + +error codes (the software uses redmond originated error codes) + +1. internal code (1-10) +2. result + +0 00000000 success +1 80004005 E_FAIL +2 8007000E E_OUTOFMEMORY +3,9 80004001 E_NOTIMPL +4,5 80070005 E_ACCESSDENIED +6 80004003 E_POINTER +7,10 80070057 E_INVALIDREG +8 80040FC1 (or 1FC?: CO_E_OBJISREG) - never occurred here + + + + + +I think the only relevant file is the decoder drv[23].so.6.0 +The rv[23]0 ones are just for streaming. We do this ourselves. + + +The codec consists of several functions. The relevant ones are: + +RV20toYUV420Init() +RV20toYUV420Transform() +RV20toYUV420CustomMessage() +RV20toYUV420Free() + + +The others are irrelevant (seems to me). HiveMessage doesn't manipulate +anything and is only called in the beginning. + +result=RV20toYUV420Init(struct init_data *, struct rvyuvMain **); + +struct init_data { + short constant=0xb; + short width, height; + short 0, 0, 0; + ulong format1; + long 1; + ulong format2; +}; + +format1 and format2 are stored in the .rm file's stream headers. +(format1>>16)&3 seems to be a sub-codec id/selector, at least for rv30 +it's the only difference between low and high bitrate files. + +result=RV20toYUV420Transform(char *input_stream, char *output_data, + struct transin *, struct transout *, struct rvyuvMain *); + +struct transin { + ulong length_of_input_data; + ulong null; + ulong num_sub_packets_in_block_minus_one; + ulong *sub_packets_list; + ulong another_null; + ulong timestamp_from_stream; +}; + +struct transout { + ulong flag1; // ((var_94&2!=0)&&(result==0))?1:0 + ulong flag2; // 4 LBS from var_94 + ulong zero; + ulong width, height; +}; + +The length of output_stream is 1.5*width*height (I420 planar yuv 4:2:0). +input_stream is the exact data from the data block for one frame. + +sub_packets_list is a list of num_sub_packets pairs of long values, in form: +1, 0, +1, offset_2nd, +1, offset_3rd, +1, offset_4th, +... + +where offset_* are the offsets or sub-packets relative to input_stream. + + +result=RV20toYUV420CustomMessage(ulong *msg, struct rvyuvMain *); + +Messages used by RV30: + +A message is a triplet (cmd,val,ext) of ulong. + +NOTE: +rv30 only requires the (0x24,2|3,{w,h,w,h}) message. others can be left out! +rv20 only requires the (0x11,2,0) message in rp8, before each transform call. + +(3,2,0) +returns always(?) an error, since a global variable inside the codec +(which points to a function similar to custommessage), is always NULL + +(0x11,0|1|2,0) +val=0|1: sets intern2 to val, when intern1 is non-zero + return 3 when intern1 is zero and val is 1 + else returns 0 +val=2: return intern2 +what does intern[1,2] mean? + +(0x12,...) +used by rv20, function unknown, can be ignored + +(0x1e,2|3,1) +calls a subroutine and returns the result, purpose has to be detemined + +(0x24,subcodec,{...}) +copies 4 dwords to rvyuvMain+07c: { width, height, 0, 0 } +subcodec must be 2 (low-bitrate) or 3 (high-bitrate) for rv30. +the codec type (low vs high) can be determined from 1+((format1>>16)&3) +for rv20, this call should be ignored! (makes codec crashing) + +(0x1c,a,b) - called inside transform +to be analyzed + +(105,...) +used by rv20, function unknown, can be ignored + + +structure of rvyuvMain: +----------------------- + +DWORDS (the entries are not always constant) +there are two w/h pairs at 05C. the first is the size of the +unscaled video stream, the second possibly image size + +000 1 6 3 1 +010 1 0 AEBFC0D1(magic) 0 +020 0 ptr->? 0 0 +030 0 0 ->rvyuvMain+0x050 ? +040 width height 0x17 0x479 +050 ->rvyuvMain 0x17 0x17 width +060 height width height 0 +070 0 1 0 0 +080 0 0xb w h +090 w h 0 0 +0A0 1 0xb0(w?) 0x58 0x58 +0B0 ptr->? 0 0 1 +0C0 0x32 1 0 0 +0D0 0 0 0 0 +0E0 0 0 0 0 +0F0 0 0 0 0 +100 0 0 0 0 +110 p p p p p are pointers to several function, for +120 p p p p example to the actual public functions +130 p p p p (except init, the others are some kind of +140 p p p p interfaces) +150 p 0 0 0 +160 0 0x2000 1 0 +170 0 0 0 0 +180 1 1 0 0 +190 0 0 0 0 +1A0 0 0 0 0 +1B0 1 0 ptr->? ptr->? +1C0 1 0 0 0 +1D0 0 0 0 0 +1E0 0 0 0 0 +... + + + + +Order of calls: +--------------- + +Init +(0x11,0,0) +(0x24,2,{...}) + +[ +(3,2,0)->80004001 +(0x11,1,0) +(0x1e,3,1) +Transform (internally calls (0x1c,x,y)) +(11,2,0) +] + +Free diff --git a/DOCS/OUTDATED-tech/slave.txt b/DOCS/OUTDATED-tech/slave.txt new file mode 100644 index 0000000000..6bb1dc53c4 --- /dev/null +++ b/DOCS/OUTDATED-tech/slave.txt @@ -0,0 +1,586 @@ +SLAVE MODE PROTOCOL +------------------- + +The -slave option switches on slave mode, in which MPlayer works as a backend +for other programs. Instead of intercepting keyboard events, MPlayer will read +commands separated by a newline (\n) from stdin. + +To try slave mode out by hand, run + + mplayer -slave -quiet <movie> + +and type slave commands into the console window. + +You can also use a fifo file (named pipe): + + mkfifo </tmp/fifofile> + mplayer -slave -input file=</tmp/fifofile> <movie> + +Most slave mode commands are equivalent to command line options, though not +necessarily under the same name. Detailed descriptions can be found in the +man page. + +NOTE: the following paragraph is mostly obsolete; tricky pause handling +was required in old MPlayer versions where all commands unpaused by default. +Now running commands does not require leaving pause state any more, and +the prefixes described here should not be required in normal use. +All commands can be prefixed with one of "pausing ", "pausing_keep ", or +"pausing_toggle ". "pausing " tells MPlayer to pause as soon as possible +after processing the command. "pausing_keep " tells MPlayer to do so only if +it was already in paused mode. "pausing_toggle " tells MPlayer to do so +only if it was not already in paused mode. Please note that "as soon as +possible" can be before the command is fully executed. +As a temporary hack, there is also the _experimental_ "pausing_keep_force " +prefix, with which MPlayer will not exit the pause loop at all. +Like this you can avoid the "frame stepping" effect of "pausing_keep " +but most commands will either not work at all or behave in unexpected ways. +For "set_mouse_pos" and "key_down_event", "pausing_keep_force" is the default +since other values do not make much sense for them. + + +Various tips and tricks (please help expand it!): + +- To ensure the user can't control MPlayer "behind your back" use + something like -input nodefault-bindings -noconfig all + + +Available commands ('mplayer -input cmdlist' will print a list): + +af_add <filter_arguments_list> (comma separated list of audio filters with parameters) + (experimental) Load the given list of audio filters. + +af_clr + (experimental) Unload all loaded audio filters. + +af_cmdline <filter_name> <filter_arguments> + (experimental) Send new command-line options to a filter with the given name. + +af_del <filter_name_list> (comma separated list of audio filter's names) + (experimental) Unload the first occurrence of the filters, if loaded. + +af_switch <filter_arguments_list> (comma separated list of audio filters with parameters) + (experimental) Remove all the audio filters and replace them with the given list. + +alt_src_step <value> (ASX playlist only) + When more than one source is available it selects the next/previous one. + +audio_delay <value> [abs] + Set/adjust the audio delay. + If [abs] is not given or is zero, adjust the delay by <value> seconds. + If [abs] is nonzero, set the delay to <value> seconds. + +[brightness|contrast|gamma|hue|saturation] <value> [abs] + Set/adjust video parameters. + If [abs] is not given or is zero, modifies parameter by <value>. + If [abs] is non-zero, parameter is set to <value>. + <value> is in the range [-100, 100]. + +capturing [value] + Toggle/set capturing the primary stream like -dumpstream. + Requires the -capture parameter to be given. + +change_rectangle <val1> <val2> + Change the position of the rectangle filter rectangle. + <val1> + Must be one of the following: + 0 = width + 1 = height + 2 = x position + 3 = y position + <val2> + If <val1> is 0 or 1: + Integer amount to add/subtract from the width/height. + Positive values add to width/height and negative values + subtract from it. + If <val1> is 2 or 3: + Relative integer amount by which to move the upper left + rectangle corner. Positive values move the rectangle + right/down and negative values move the rectangle left/up. + +dvb_set_channel <channel_number> <card_number> + Set DVB channel. + +dvdnav <button_name> + Press the given dvdnav button. + up + down + left + right + menu + select + prev + mouse + +edl_mark + Write the current position into the EDL file. + +frame_drop [value] + Toggle/set frame dropping mode. + +get_audio_bitrate + Print out the audio bitrate of the current file. + +get_audio_codec + Print out the audio codec name of the current file. + +get_audio_samples + Print out the audio frequency and number of channels of the current file. + +get_file_name + Print out the name of the current file. + +get_meta_album + Print out the 'Album' metadata of the current file. + +get_meta_artist + Print out the 'Artist' metadata of the current file. + +get_meta_comment + Print out the 'Comment' metadata of the current file. + +get_meta_genre + Print out the 'Genre' metadata of the current file. + +get_meta_title + Print out the 'Title' metadata of the current file. + +get_meta_track + Print out the 'Track Number' metadata of the current file. + +get_meta_year + Print out the 'Year' metadata of the current file. + +get_percent_pos + Print out the current position in the file, as integer percentage [0-100). + +get_property <property> + Print out the current value of a property. + +get_sub_visibility + Print out subtitle visibility (1 == on, 0 == off). + +get_time_length + Print out the length of the current file in seconds. + +get_time_pos + Print out the current position in the file in seconds, as float. + +get_vo_fullscreen + Print out fullscreen status (1 == fullscreened, 0 == windowed). + +get_video_bitrate + Print out the video bitrate of the current file. + +get_video_codec + Print out the video codec name of the current file. + +get_video_resolution + Print out the video resolution of the current file. + +screenshot <each_frame> <full_window> + Take a screenshot. Requires the screenshot filter to be loaded. + each_frame: + 0 Take a single screenshot. (Default.) + 1 Start/stop taking screenshot of each frame. + full_window: + 0 Save the video image, in its original resolution. Typically without + OSD or subtitles. (Default.) + 1 Save the contents of the mplayer window. Typically with OSD and + subtitles. If not available (no VO support), this may act as if 0 was + passed. + +key_down_event <value> + Inject <value> key code event into MPlayer. + +loadfile <file|url> <append> + Load the given file/URL, stopping playback of the current file/URL. + If <append> is nonzero playback continues and the file/URL is + appended to the current playlist instead. + +loadlist <file> <append> + Load the given playlist file, stopping playback of the current file. + If <append> is nonzero playback continues and the playlist file is + appended to the current playlist instead. + +loop <value> [abs] + Adjust/set how many times the movie should be looped. -1 means no loop, + and 0 forever. + +mute [value] + Toggle sound output muting or set it to [value] when [value] >= 0 + (1 == on, 0 == off). + +osd [level] + Toggle OSD mode or set it to [level] when [level] >= 0. + +osd_show_progression + Show the progression bar, the elapsed time and the total duration of the + movie on the OSD. + +osd_show_property_text <string> [duration] [level] + Show an expanded property string on the OSD, see -playing-msg for a + description of the available expansions. If [duration] is >= 0 the text + is shown for [duration] ms. [level] sets the minimum OSD level needed + for the message to be visible (default: 0 - always show). + +osd_show_text <string> [duration] [level] + Show <string> on the OSD. + +panscan <-1.0 - 1.0> | <0.0 - 1.0> <abs> + Increase or decrease the pan-and-scan range by <value>, 1.0 is the maximum. + Negative values decrease the pan-and-scan range. + If <abs> is != 0, then the pan-and scan range is interpreted as an + absolute range. + +pause + Pause/unpause the playback (use "set_property pause X" to set a particular + value regardless of whether the player is already paused or not). + +frame_step + Play one frame, then pause again. + +pt_step <value> [force] + Go to the next/previous entry in the playtree. The sign of <value> tells + the direction. If no entry is available in the given direction it will do + nothing unless [force] is non-zero. + +pt_up_step <value> [force] + Similar to pt_step but jumps to the next/previous entry in the parent list. + Useful to break out of the inner loop in the playtree. + +quit [value] + Quit MPlayer. The optional integer [value] is used as the return code + for the mplayer process (default: 0). + +radio_set_channel <channel> + Switch to <channel>. The 'channels' radio parameter needs to be set. + +radio_set_freq <frequency in MHz> + Set the radio tuner frequency. + +radio_step_channel <-1|1> + Step forwards (1) or backwards (-1) in channel list. Works only when the + 'channels' radio parameter was set. + +radio_step_freq <value> + Tune frequency by the <value> (positive - up, negative - down). + +run <value> + Run <value> as shell command. + +seek <value> [type] [hr-seek] + Seek to some place in the movie. + type = 0 is a relative seek of +/- <value> seconds (default). + type = 1 is a seek to <value> % in the movie. + type = 2 is a seek to an absolute position of <value> seconds. + The hr-seek parameter controls whether to use precise seeks (not limited + to keyframe positions in video). + hr-seek = 0 means use default set with option -hr-seek (default). + hr-seek = 1 means force precise seek if possible. + hr-seek = -1 means force non-precise seek. + +seek_chapter <value> [type] + Seek to the start of a chapter. + 0 is a relative seek of +/- <value> chapters (default). + 1 is a seek to chapter <value>. + +switch_angle <value> + Switch to the angle with the ID [value]. Cycle through the + available angles if [value] is omitted or negative. + +set_mouse_pos <x> <y> + Tells MPlayer the coordinates of the mouse in the window. + This command doesn't move the mouse! + +set_property <property> <value> + Set a property. + +set_property_osd <property> <value> + Same as above, but show the new value on the OSD in the standard + manner defined for that property (if any). + +speed_incr <value> + Add <value> to the current playback speed. + +speed_mult <value> + Multiply the current speed by <value>. + +speed_set <value> + Set the speed to <value>. + +step_property <property> [value] [direction] + Change a property by value, or increase by a default if value is + not given or zero. The direction is reversed if direction is less + than zero. + +step_property_osd <property> [value] [direction] + Same as above, but show the new value on the OSD in the standard + manner defined for that property (if any). + +stop + Stop playback. + +sub_alignment [value] + Toggle/set subtitle alignment. + 0 top alignment + 1 center alignment + 2 bottom alignment + +sub_delay <value> [abs] + Adjust the subtitle delay by +/- <value> seconds or set it to <value> + seconds when [abs] is nonzero. + +sub_load <subtitle_file> + Loads subtitles from <subtitle_file>. + +sub_log + Logs the current or last displayed subtitle together with filename + and time information to ~/.mplayer/subtitle_log. Intended purpose + is to allow convenient marking of bogus subtitles which need to be + fixed while watching the movie. + +sub_pos <value> [abs] + Adjust/set subtitle position. + +sub_remove [value] + If the [value] argument is present and non-negative, removes the subtitle + file with index [value]. If the argument is omitted or negative, removes + all subtitle files. + +sub_select [value] + Display subtitle with index [value]. Turn subtitle display off if + [value] is -1 or greater than the highest available subtitle index. + Cycle through the available subtitles if [value] is omitted or less + than -1 (forward or backward respectively). + Supported subtitle sources are -sub options on the command + line, VOBsubs, DVD subtitles, and Ogg and Matroska text streams. + This command is mainly for cycling all subtitles, if you want to set + a specific subtitle, use sub_file, sub_vob, or sub_demux. + +sub_source [source] + Display first subtitle from [source]. Here [source] is an integer: + SUB_SOURCE_SUBS (0) for file subs + SUB_SOURCE_VOBSUB (1) for VOBsub files + SUB_SOURCE_DEMUX (2) for subtitle embedded in the media file or DVD subs. + If [source] is -1, will turn off subtitle display. + If [value] is omitted or less than -1, will cycle between the first subtitle + of each currently available source (forward or backward respectively). + +sub_file [value] + Display subtitle specifid by [value] for file subs. The [value] is + corresponding to ID_FILE_SUB_ID values reported by '-identify'. + If [value] is -1, will turn off subtitle display. + If [value] is omitted or less than -1, will cycle all file subs + (forward or backward respectively). + +sub_vob [value] + Display subtitle specifid by [value] for vobsubs. The [value] is + corresponding to ID_VOBSUB_ID values reported by '-identify'. + If [value] is -1, will turn off subtitle display. + If [value] is omitted or less than -1, will cycle all vobsubs + (forward or backward respectively). + +sub_demux [value] + Display subtitle specifid by [value] for subtitles from DVD or embedded + in media file. The [value] is corresponding to ID_SUBTITLE_ID values + reported by '-identify'. If [value] is -1, will turn off subtitle display. + If [value] is omitted or less than -1, will cycle all DVD subs or embedded subs + (forward or backward respectively). + +sub_scale <value> [abs] + Adjust the subtitle size by +/- <value> or set it to <value> when [abs] + is nonzero. + +vobsub_lang + This is a stub linked to sub_select for backwards compatibility. + +sub_step <value> + Step forward in the subtitle list by <value> steps or backwards if <value> + is negative. + +sub_visibility [value] + Toggle/set subtitle visibility. + +forced_subs_only [value] + Toggle/set forced subtitles only. + +switch_audio [value] (currently MPEG*, AVI, Matroska and streams handled by libavformat) + Switch to the audio track with the ID [value]. Cycle through the + available tracks if [value] is omitted or negative. + +switch_angle [value] (DVDs only) + Switch to the DVD angle with the ID [value]. Cycle through the + available angles if [value] is omitted or negative. + +switch_ratio [value] + Change aspect ratio at runtime. [value] is the new aspect ratio expressed + as a float (e.g. 1.77778 for 16/9). + There might be problems with some video filters. + +switch_title [value] (DVDNAV only) + Switch to the DVD title with the ID [value]. Cycle through the + available titles if [value] is omitted or negative. + +switch_vsync [value] + Toggle vsync (1 == on, 0 == off). If [value] is not provided, + vsync status is inverted. + +teletext_add_digit <value> + Enter/leave teletext page number editing mode and append given digit to + previously entered one. + 0..9 - Append apropriate digit. (Enables editing mode if called from normal + mode, and switches to normal mode when third digit is entered.) + - - Delete last digit from page number. (Backspace emulation, works only + in page number editing mode.) + +teletext_go_link <1-6> + Follow given link on current teletext page. + +tv_start_scan + Start automatic TV channel scanning. + +tv_step_channel <channel> + Select next/previous TV channel. + +tv_step_norm + Change TV norm. + +tv_step_chanlist + Change channel list. + +tv_set_channel <channel> + Set the current TV channel. + +tv_last_channel + Set the current TV channel to the last one. + +tv_set_freq <frequency in MHz> + Set the TV tuner frequency. + +tv_step_freq <frequency offset in MHz> + Set the TV tuner frequency relative to current value. + +tv_set_norm <norm> + Set the TV tuner norm (PAL, SECAM, NTSC, ...). + +tv_set_brightness <-100 - 100> [abs] + Set TV tuner brightness or adjust it if [abs] is set to 0. + +tv_set_contrast <-100 -100> [abs] + Set TV tuner contrast or adjust it if [abs] is set to 0. + +tv_set_hue <-100 - 100> [abs] + Set TV tuner hue or adjust it if [abs] is set to 0. + +tv_set_saturation <-100 - 100> [abs] + Set TV tuner saturation or adjust it if [abs] is set to 0. + +use_master + Switch volume control between master and PCM. + +vo_border [value] + Toggle/set borderless display. + +vo_fullscreen [value] + Toggle/set fullscreen mode. + +vo_ontop [value] + Toggle/set stay-on-top. + +vo_rootwin [value] + Toggle/set playback on the root window. + +volume <value> [abs] + Increase/decrease volume or set it to <value> if [abs] is nonzero. + + +Available properties: + +name type min max get set step comment +================================================================= + +osdlevel int 0 3 X X X as -osdlevel +speed float 0.01 100 X X X as -speed +loop int -1 X X X as -loop +hr_seek string X X X as -hr-seek +pts_association_mode string X X X as -pts-association-mode +pause flag 0 1 X 1 if paused +filename string X file playing wo path +path string X file playing +demuxer string X demuxer used +stream_pos pos 0 X X position in stream +stream_start pos 0 X start pos in stream +stream_end pos 0 X end pos in stream +stream_length pos 0 X (end - start) +stream_time_pos time 0 X present position in stream (in seconds) +chapter int 0 X X X select chapter +chapters int X number of chapters +angle int 0 X X X select angle +length time X length of file in seconds +percent_pos int 0 100 X X X position in percent +time_pos time 0 X X X position in seconds +metadata str list X list of metadata key/value +metadata/* string X metadata values +volume float 0 100 X X X change volume +balance float -1 1 X X X change audio balance +mute flag 0 1 X X X +audio_delay float -100 100 X X X +audio_format int X +audio_codec string X +audio_bitrate int X +samplerate int X +channels int X +switch_audio int -2 255 X X X select audio stream +switch_angle int -2 255 X X X select DVD angle +switch_title int -2 255 X X X select DVD title +capturing flag 0 1 X X X dump primary stream if enabled +fullscreen flag 0 1 X X X +deinterlace flag 0 1 X X X +ontop flag 0 1 X X X +rootwin flag 0 1 X X X +border flag 0 1 X X X +framedropping int 0 2 X X X 1 = soft, 2 = hard +gamma int -100 100 X X X +brightness int -100 100 X X X +contrast int -100 100 X X X +saturation int -100 100 X X X +hue int -100 100 X X X +panscan float 0 1 X X X +vsync flag 0 1 X X X +colormatrix choice X X X as --colormatrix +colormatrix_input_range choice X X X as --colormatrix-input-range +colormatrix_output_range choice X X X as --colormatrix-output-range +video_format int X +video_codec string X +video_bitrate int X +width int X "display" width +height int X "display" height +fps float X +aspect float X +switch_video int -2 255 X X X select video stream +switch_program int -1 65535 X X X (see TAB default keybind) +sub int -1 X X X select subtitle stream +sub_source int -1 2 X X X select subtitle source +sub_file int -1 X X X select file subtitles +sub_vob int -1 X X X select vobsubs +sub_demux int -1 X X X select subs from demux +sub_delay float X X X +sub_pos int 0 100 X X X subtitle position +sub_alignment int 0 2 X X X subtitle alignment +sub_visibility flag 0 1 X X X show/hide subtitles +sub_forced_only flag 0 1 X X X +sub_scale float 0 100 X X X subtitles font size +ass_vsfilter_aspect_compat flag 0 1 X X X SSA/ASS aspect ratio correction +tv_brightness int -100 100 X X X +tv_contrast int -100 100 X X X +tv_saturation int -100 100 X X X +tv_hue int -100 100 X X X +teletext_page int 0 799 X X X +teletext_subpage int 0 64 X X X +teletext_mode flag 0 1 X X X 0 - off, 1 - on +teletext_format int 0 3 X X X 0 - opaque, + 1 - transparent, + 2 - opaque inverted, + 3 - transp. inv. +teletext_half_page int 0 2 X X X 0 - off, 1 - top half, + 2- bottom half diff --git a/DOCS/OUTDATED-tech/subcp.txt b/DOCS/OUTDATED-tech/subcp.txt new file mode 100644 index 0000000000..50d9cc69f9 --- /dev/null +++ b/DOCS/OUTDATED-tech/subcp.txt @@ -0,0 +1,42 @@ +Ascii Subtitle / Font CODEPAGEs +=============================== + +The subtitle encoding issue seems a bit confusing, so I'll try to +summarize it here. + +There are 2 approaches: + +1. (preferred) You can generate Unicode subtitles with: + subfont --unicode <signle-byte encoding known by iconv> ... +or + subfont --unicode <path to custom encoding file> ... + (this custom encoding file could list all iso-8859-* characters to create +single font file for common encodings) + +and then run mplayer this way (-subcp and -utf8 expect Unicode font!): + mplayer -subcp <any encoding known by iconv> ... +or + mplayer -utf8 ... + +2. (current) Generate subtitles for some specific encoding with: + subfont <signle-byte encoding known by iconv> ... +or + subfont <path to custom signle-byte or EUC encoding file> ... + +and then run mplayer without any encoding options for signle-byte +encodings, or with -unicode option for EUC (and the like) encodings +(which is only partially implemented in mplayer). + +AFAIK, CJK encodings: EUC-*, BIG5 and GB2312 work more or less this way: +- 0x8e (SINGLE-SHIFT TWO, SS2) begins a 2-byte character, +- 0x8f (SINGLE-SHIFT THREE, SS3) begins a 3-byte character, +- 0xa0-0xff begin 2-byte characters, +- other characters are single-byte. + + +I tested charmap2enc script only with /usr/share/i18n/charmaps/EUC-KR.gz +(on RedHat). It wasn't intended to be perfect. + + +-- +Artur Zaprzala diff --git a/DOCS/OUTDATED-tech/swscaler_filters.txt b/DOCS/OUTDATED-tech/swscaler_filters.txt new file mode 100644 index 0000000000..11e2aa4017 --- /dev/null +++ b/DOCS/OUTDATED-tech/swscaler_filters.txt @@ -0,0 +1,19 @@ +software scaler filter docs + +-ssf cgb=<float> chrominance gaussian blur + useful for videos with some chroma (color) noise (TV captures, VHS, ...) + +-ssf lgb=<float> -> luminance gaussian blur + hmm, mostly special effect, could be used as lame noise reducer though + +-ssf chs=<int> -> shift chrominance horizontally +-ssf cvs=<int> -> shift chrominance vertically + useful if the luma & chroma are not aligned exactly + +-ssf cs=<float> -> chrominance sharpen +-ssf ls=<float> -> luminance sharpen + simple sharpening filter + +note: these will only work if the swscaler is used at all (use -vf scale) + +example: mplayer foobar.avi -vf scale -ssf lgb=3.0 diff --git a/DOCS/OUTDATED-tech/swscaler_methods.txt b/DOCS/OUTDATED-tech/swscaler_methods.txt new file mode 100644 index 0000000000..24d2b11835 --- /dev/null +++ b/DOCS/OUTDATED-tech/swscaler_methods.txt @@ -0,0 +1,68 @@ + +artifact types: +--------------------------------------------------------------------- +ringing + wave or noise like patterns around sharp edges + bad: sinc, lanczos (with high filter length) + acceptable: lanczos (with low filter length), cubic, spline + ok: area, (fast)blinear, gauss, point + +blur + loss of detail / high frequency + bad: gauss with high variance + acceptable: (fast)bilinear, area + ok: others + +aliasing (only downscale) + straight lines look like staircases + areas of high detail look worse + regular patterns turn into a funny looking mess (moire patterns) + bad: fast bilinear, point, gauss with low variance + acceptable: area + ok: others + +blocky (upscale only) + looks like the image is made of rectangular blocks like a mosaic + bad: point + ok: others + +recommendations: (based upon my personal opinion many ppl might disagree ...) +--------------------------------------------------------------------- + +the recommended scalers for upscaling: +fast_bilinear, point if speed is important +cubic, spline, lanczos if quality is important + +the recommended scalers for downscaling: +fast_bilinear, point if speed is important +gauss, bilinear if quality is important +cubic, spline, lanczos if a sharper picture is important + +note: when encoding at a limited amount of bits (not constant quantizer) +then a slightly blurred input might look better after decoding than a slightly +sharpened one, especially for lower bitrates + +sws numbers / names / artifact types +------------------------------------------------------------------------- +r ringing +b blurry +a aliasing (downscale only) +m mosaic (blocky) (upscale only) + +-sws 0 fast bilinear bA +-sws 1 bilinear b +-sws 2 bicubic high sharpness r + low sharpness b +-sws 3 experimental ???? +-sws 4 nearest neighbour AM +-sws 5 area ba +-sws 6 luma bicubic / chroma bilinear r +-sws 7 gauss low sharpness B + high sharpness AM +-sws 8 sinc R +-sws 9 lanczos long filter R + short filter b +-sws 10 bicubic spline r + +Notes: + area upscale is identical to bilinear diff --git a/DOCS/OUTDATED-tech/win32-codec-howto.txt b/DOCS/OUTDATED-tech/win32-codec-howto.txt new file mode 100644 index 0000000000..458a9191b3 --- /dev/null +++ b/DOCS/OUTDATED-tech/win32-codec-howto.txt @@ -0,0 +1,118 @@ +============================ +Win32 codecs importing HOWTO +============================ + +This document describes how to extract the information necessary to hook +up Win32 binary codecs in MPlayer from a Windows system. Different methods +exist depending on which video API your codec uses and which Windows +version you have. + +If you have gathered all the necessary information (fourcc, GUID, codec file, +sample file) as described below, notify the mplayer-dev-eng mailing list. +If you want to add a codec yourself, read DOCS/tech/codecs.conf.txt. + + + +VfW codecs +~~~~~~~~~~ + +VfW (Video for Windows) is the old video API for Windows. Its codecs have +the '.dll' or (rarely) '.drv' extension. If MPlayer fails at playing your +AVI with this kind of message: + +VIDEO: [HFYU] 352x288 24bpp 25.000 fps 4321.0 kbps (527.5 kbyte/s) +Cannot find codec matching selected -vo and video format 0x55594648. + +It means your AVI is encoded with a codec which has the HFYU fourcc (HFYU = +HuffYUV codec, DIV3 = DivX Low Motion, etc.). Now that you know this, you +have to find out which DLL Windows loads in order to play this file. +You can find the VfW codec by searching the internet for e.g. VIDC.HFYU. + +In our case, the 'system.ini' also contains this information in a line that reads: + +VIDC.HFYU=huffyuv.dll + +So you need the 'huffyuv.dll' file. + + + +ACM Codecs: +~~~~~~~~~~~~ +MPlayer may fail at playing the audio in your file with this message: + +Cannot find codec for audio format 0x55. +Audio: no sound + +MPlayer calls this the TwoCC format identifier. From the TwoCC list we find: + +0x0055 MPEG-1 Layer 3 (MP3) + +If you are lucky, you can then just search the internet for "codec acm" +e.g. "mp3 acm". Or if the codec is already installed on Windows, +it will show up in the system.ini as: + +msacm.l3acm=L3codeca.acm + +Note that the audio codecs are specified by the MSACM prefix: + + + +DirectShow codecs: +~~~~~~~~~~~~~~~~~~ + +DirectShow is the newer video API, which is even worse than its predecessor. +Things are harder with DirectShow, since 'system.ini' does not contain the +needed information, instead it is stored in the registry and we need the +GUID of the codec. + + +New Method: +----------- + +Using Microsoft GraphEdit (fast) + +- Get GraphEdit from the Microsoft SDK, DirectX SDK or doom9. +- Start 'graphedit.exe'. +- From the menu select "Graph -> Insert Filters". +- Expand item "DirectShow Filters". +- Select the right codec name and expand item. +- In the entry "DisplayName" look at the text in winged brackets after the + backslash and write it down (five dash-delimited blocks, the GUID). +- The codec binary is the file specified in the "Filename" entry. + +If there is no "Filename" and "DisplayName" contains something like +'device:dmo', then it is a DMO-Codec. + + +Old Method: +----------- + +Take a deep breath and start searching the registry... + +- Start 'regedit'. +- Press "Ctrl-F", disable the first two checkboxes, and enable the third. + Type in the fourcc of the codec (e.g. "TM20"). +- You should see a field which contains the path and the filename (e.g. + "C:\WINDOWS\SYSTEM\TM20DEC.AX"). +- Now that you have the file, we need the GUID. Try searching again, but + now search for the codec's name, not the fourcc. Its name can be acquired + when Media Player is playing the file, by checking + "File -> Properties -> Advanced". + If not, you are out of luck. Try guessing (e.g. search for TrueMotion). +- If the GUID is found you should see a "FriendlyName" and a "CLSID" field. + Write down the 16 byte CLSID, this is the GUID we need. + +If searching fails, try enabling all the checkboxes. You may have +false hits, but you may get lucky... + + + +Tips: +~~~~~~~ +If you get an error loading a new codec, it may need some more files to work. +Start the filemon utility before loading MPlayer to find out which DLLs are +trying to be loaded. + +Your codec may load some external DLL libraries. If the codec is already +installed in Windows, run listdlls wmplayer.exe while Windows Media +Player is playing your file to find out which. |