[xiph-commits] r8990 - in experimental/derf/theora-exp: doc
include/theora
tterribe at motherfish-iii.xiph.org
tterribe at motherfish-iii.xiph.org
Sat Feb 26 14:11:59 PST 2005
Author: tterribe
Date: 2005-02-26 14:11:56 -0800 (Sat, 26 Feb 2005)
New Revision: 8990
Added:
experimental/derf/theora-exp/doc/Doxyfile
Modified:
experimental/derf/theora-exp/include/theora/theora.h
Log:
Added Doxygen documentation for the public API.
Added: experimental/derf/theora-exp/doc/Doxyfile
===================================================================
--- experimental/derf/theora-exp/doc/Doxyfile 2005-02-26 11:15:49 UTC (rev 8989)
+++ experimental/derf/theora-exp/doc/Doxyfile 2005-02-26 22:11:56 UTC (rev 8990)
@@ -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 = Theora
+
+# 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 = Experimental
+
+# 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 = libtheora
+
+# 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 = NO
+
+# 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 = NO
+
+# 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 = NO
+
+# 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 = YES
+
+# 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 = YES
+
+# 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 = NO
+
+# If the EXTRACT_PRIVATE tag is set to YES all private members of a class
+# will be included in the documentation.
+
+EXTRACT_PRIVATE = NO
+
+# If the EXTRACT_STATIC tag is set to YES all static members of a file
+# will be included in the documentation.
+
+EXTRACT_STATIC = NO
+
+# 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 = YES
+
+# 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 = YES
+
+# 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 = ../include/theora
+
+# 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 = NO
+
+# 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 =
+
+# 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 = NO
+
+# Setting the INLINE_SOURCES tag to YES will include the body
+# of functions and classes directly in the documentation.
+
+INLINE_SOURCES = NO
+
+# 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 = NO
+
+# 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 = 5
+
+# 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 = YES
+
+# 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 = YES
+
+# 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
Modified: experimental/derf/theora-exp/include/theora/theora.h
===================================================================
--- experimental/derf/theora-exp/include/theora/theora.h 2005-02-26 11:15:49 UTC (rev 8989)
+++ experimental/derf/theora-exp/include/theora/theora.h 2005-02-26 22:11:56 UTC (rev 8990)
@@ -15,6 +15,20 @@
********************************************************************/
+/**\mainpage
+ *
+ * \section intro Introduction
+ *
+ * This is the documentation for the libtheora C API.
+ * libtheora is the reference implementation for
+ * <a href="http://www.theora.org/">Theora</a>, a free video codec.
+ * Theora is derived from On2's VP3 codec with improved features and
+ * integration for Ogg multimedia formats by
+ * <a href="http://www.xiph.org/">Xiph.Org</a>.*/
+
+/**\file
+ * The libtheora C API.*/
+
#if !defined(_O_THEORA_H_)
# define _O_THEORA_H_ (1)
# include <ogg/ogg.h>
@@ -25,236 +39,328 @@
-/*Possible error codes.*/
-/*An invalid pointer was provided.*/
+/**\name Error codes*/
+/*@{*/
+/**An invalid pointer was provided.*/
#define OC_FAULT (-1)
-/*An invalid argument was provided.*/
+/**An invalid argument was provided.*/
#define OC_EINVAL (-10)
-/*The contents of the header were incomplete, invalid, or unexpected.*/
+/**The contents of the header were incomplete, invalid, or unexpected.*/
#define OC_BADHEADER (-20)
-/*The header does not belong to a Theora stream.*/
+/**The header does not belong to a Theora stream.*/
#define OC_NOTFORMAT (-21)
-/*The bitstream version is too high.*/
+/**The bitstream version is too high.*/
#define OC_VERSION (-22)
-/*The specified function is not implemented.*/
+/**The specified function is not implemented.*/
#define OC_IMPL (-23)
-/*There were errors in the video data packet.*/
+/**There were errors in the video data packet.*/
#define OC_BADPACKET (-24)
+/*@}*/
-
-/*The currently defined color space tags.
- See doc/color.html for exact details on the meaning of each of these color
- spaces.*/
+/**The currently defined color space tags.
+ * See <a href="http://www.theora.org/doc/Theora_I_spec.pdf">the Theora
+ * specification</a>, Chapter 4, for exact details on the meaning of each of
+ * these color spaces.*/
typedef enum{
+ /**The color space was not specified at the encoder.
+ It may be conveyed by an external means.*/
OC_CS_UNSPECIFIED,
+ /**A colorspace designed for NTSC content.*/
OC_CS_ITU_REC_470M,
+ /**A colorspace designed for PAL/SECAM content.*/
OC_CS_ITU_REC_470BG,
- /*The total number of currently defined color spaces:*/
+ /**The total number of currently defined color spaces.*/
OC_CS_NSPACES
}theora_colorspace;
-/*The currently defined pixel format tags.
- See the Theora specification, Section 4.4, for details on the precise sample
- locations.*/
+/**The currently defined pixel format tags.
+ * See <a href="http://www.theora.org/doc/Theora_I_spec.pdf">the Theora
+ * specification</a>, Section 4.4, for details on the precise sample
+ * locations.*/
typedef enum{
- /*Chroma decimation by 2 in both the X and Y directions.*/
+ /**Chroma decimation by 2 in both the X and Y directions (4:2:0).*/
OC_PF_420,
- /*Currently reserved.*/
+ /**Currently reserved.*/
OC_PF_RSVD,
- /*Chroma decimation by 2 in the X direction.*/
+ /**Chroma decimation by 2 in the X direction (4:2:2).*/
OC_PF_422,
- /*No chroma decimation.*/
+ /**No chroma decimation (4:4:4).*/
OC_PF_444,
- /*The total number of currently defined pixel formats.*/
+ /**The total number of currently defined pixel formats.*/
OC_PF_NFORMATS
}theora_pixel_fmt;
-/*theora_encode_ctl codes.
- By convention, these are even, to distinguish them from decoder control
- codes.
- Keep any experimental or vendor-specific values above 0x8000.*/
+/**\name theora_encode_ctl() Codes
+ * By convention, these are even, to distinguish them from decoder control
+ * codes.
+ * Keep any experimental or vendor-specific values above \c 0x8000.*/
+/*@{*/
-/*Sets the Huffman tables to use.
- The tables are copied, not of stored by reference, so they can be freed after
- this call.
- NULL may be specified to revert to the default tables.
-
- arg: [in] theora_huff_code[OC_NHUFFMAN_TABLES][OC_NDCT_TOKENS]
- Return: OC_FAULT: _enc_ctx is NULL.
- OC_EINVAL: Encodng has already begun or one or more of the given
- tables is not full or prefix-free, _buf is NULL and
- _buf_sz is not zero, or _buf is non-NULL and _buf_sz is
- not sizeof(theora_huff_code)*OC_NHUFFMAN_TABLES*
- OC_NDCT_TOKENS.
- OC_IMPL: Not supported by this implementation. */
+/**Sets the Huffman tables to use.
+ * The tables are copied, not of stored by reference, so they can be freed
+ * after this call.
+ * <tt>NULL</tt> may be specified to revert to the default tables.
+ *
+ * \param[in] _buf <tt>theora_huff_code[#OC_NHUFFMAN_TABLES][#OC_NDCT_TOKENS]</tt>
+ * \retval OC_FAULT \a _enc_ctx is <tt>NULL</tt>.
+ * \retval OC_EINVAL Encodng has already begun or one or more of the given
+ * tables is not full or prefix-free, \a _buf is
+ * <tt>NULL</tt> and \a _buf_sz is not zero, or \a _buf is
+ * non-<tt>NULL</tt> and \a _buf_sz is not
+ * <tt>sizeof(#theora_huff_code)*#OC_NHUFFMAN_TABLES*#OC_NDCT_TOKENS</tt>.
+ * \retval OC_IMPL Not supported by this implementation.*/
#define OC_ENCCTL_SET_HUFFMAN_CODES (0)
-/*Sets the quantization parameters to use.
- The parameters are copied, not stored by reference, so they can be freed
- after this call.
- NULL may be specified to revert to the default parameters.
- For the current encoder, scale[ci!=0][qi] must be <= scale[ci!=0][qi-1] and
- base[qti][pli][qi][ci] must be <= base[qti][pli][qi-1][ci].
- These two conditions ensure that the actual quantizer for a given qti, pli
- and ci does not increase as qi increases.
-
- arg: [in] theora_quant_info
- Return: OC_FAULT: _enc_ctx is NULL.
- OC_EINVAL: Encodng has already begun or the quantization parameters
- does not meet one of the above stated conditions, _buf is
- NULL and _buf_sz is not zero, or _buf is non-NULL and
- _buf_sz is not sizeof(theora_quant_info).
- OC_IMPL: Not supported by this implementation. */
+/**Sets the quantization parameters to use.
+ * The parameters are copied, not stored by reference, so they can be freed
+ * after this call.
+ * <tt>NULL</tt> may be specified to revert to the default parameters.
+ * For the current encoder, <tt>scale[ci!=0][qi]</tt> must be no greater than
+ * <tt>scale[ci!=0][qi-1]</tt> and <tt>base[qti][pli][qi][ci]</tt> must be no
+ * greater than <tt>base[qti][pli][qi-1][ci]</tt>.
+ * These two conditions ensure that the actual quantizer for a given \a qti,
+ * \a pli, and \a ci does not increase as \a qi increases.
+ *
+ * \param[in] _buf #theora_quant_info
+ * \retval OC_FAULT \a _enc_ctx is <tt>NULL</tt>.
+ * \retval OC_EINVAL Encodng has already begun, the quantization parameters
+ * do not meet one of the above stated conditions, \a _buf
+ * is <tt>NULL</tt> and \a _buf_sz is not zero, or \a _buf
+ * is non-<tt>NULL</tt> and \a _buf_sz is not
+ * <tt>sizeof(#theora_quant_info)</tt>.
+ * \retval OC_IMPL Not supported by this implementation.*/
#define OC_ENCCTL_SET_QUANT_PARAMS (2)
-/*Sets the maximum distance between key frames.
- This can be changed during an encode, but will be bounded by
- 1<<keyframe_granule_shift.
- If it is set before encoding begins, keyframe_granule_shift will be enlarged
- appropriately.
-
- arg: [in] ogg_uint32_t: The maximum distance between key frames.
- [out] ogg_uint32_t: The actual maximum distance set.
- Return: OC_FAULT: _enc_ctx or _buf is NULL.
- OC_EINVAL: _buf_sz is not sizeof(ogg_uint32_t).
- OC_IMPL: Not supported by this implementation.*/
+/**Sets the maximum distance between key frames.
+ * This can be changed during an encode, but will be bounded by
+ * <tt>1<<theora_info#keyframe_granule_shift</tt>.
+ * If it is set before encoding begins, theora_info#keyframe_granule_shift will
+ * be enlarged appropriately.
+ *
+ * \param[in] _buf ogg_uint32_t: The maximum distance between key frames.
+ * \param[out] _buf ogg_uint32_t: The actual maximum distance set.
+ * \retval OC_FAULT \a _enc_ctx or \a _buf is <tt>NULL</tt>.
+ * \retval OC_EINVAL \a _buf_sz is not <tt>sizeof(ogg_uint32_t)</tt>.
+ * \retval OC_IMPL Not supported by this implementation.*/
#define OC_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE (4)
+/*@}*/
-/*theora_decode_ctl codes.
- By convention, these are odd, to distinguish them from encoder control codes.
- Keep any experimental or vendor-specific values above 0x8000.*/
+/**\name theora_decode_ctl() Codes
+ * By convention, these are odd, to distinguish them from encoder control
+ * codes.
+ * Keep any experimental or vendor-specific values above \c 0x8000.*/
+/*@{*/
-/*Gets the maximum post-processing level.
-
- arg: [out] int: The maximum post-processing level.
- Return: OC_FAULT: _dec_ctx or _buf is NULL.
- OC_EINVAL: _buf_sz is not sizeof(int).
- OC_IMPL: Not supported by this implementation.*/
+/**Gets the maximum post-processing level.
+ *
+ * \param[out] _buf int: The maximum post-processing level.
+ * \retval OC_FAULT \a _dec_ctx or \a _buf is <tt>NULL</tt>.
+ * \retval OC_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>.
+ * \retval OC_IMPL Not supported by this implementation.*/
#define OC_DECCTL_GET_PPLEVEL_MAX (1)
-/*Sets the post-processing level.
- By default, post-processing is disabled.
-
- arg: [in] int: The new post-processing level.
- 0 to disable; larger values use more CPU.
- Return: OC_FAULT: _dec_ctx or _buf is NULL.
- OC_EINVAL: _buf_sz is not sizeof(int), or the post-processing level
- is out of bounds.
- OC_IMPL: Not supported by this implementation. */
+/**Sets the post-processing level.
+ * By default, post-processing is disabled.
+ *
+ * \param[in] _buf int: The new post-processing level.
+ * 0 to disable; larger values use more CPU.
+ * \retval OC_FAULT \a _dec_ctx or \a _buf is <tt>NULL</tt>.
+ * \retval OC_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>, or the
+ * post-processing level is out of bounds.
+ * The maximum post-processing level may be
+ * implementation-specific, and can be obtained via
+ * #OC_DECCTL_GET_PPLEVEL_MAX.
+ * \retval OC_IMPL Not supported by this implementation.*/
#define OC_DECCTL_SET_PPLEVEL (3)
-/*Sets the granule position.
- Call this after a seek, before decoding the first frame, to ensure that the
- proper granule position is returned for all subsequent frames.
-
- arg: [in] ogg_int64_t: The granule position of the next frames.
- Return: OC_FAULT: _dec_ctx or _buf is NULL.
- OC_EINVAL: _buf_sz is not sizeof(ogg_int64_t), or the granpos is
- negative.*/
+/**Sets the granule position.
+ * Call this after a seek, before decoding the first frame, to ensure that the
+ * proper granule position is returned for all subsequent frames.
+ *
+ * \param[in] _buf ogg_int64_t: The granule position of the next frames.
+ * \retval OC_FAULT \a _dec_ctx or \a _buf is <tt>NULL</tt>.
+ * \retval OC_EINVAL \a _buf_sz is not <tt>sizeof(ogg_int64_t)</tt>, or the
+ * granule position is negative.*/
#define OC_DECCTL_SET_GRANPOS (5)
-/*Sets the striped decode callback function.
- If set, this function will be called as each piece of a frame is fully
- decoded.
- You can pass in a theora_stripe_callback struct with stripe_decoded set to
- NULL to disable the callbacks at any point.
-
- arg: [in] theora_stripe_callback: The callback parameters.
- Return: OC_FAULT: _dec_ctx or _buf is NULL.
- OC_EINVAL: _buf_sz is not sizeof(theora_stripe_callback).*/
+/**Sets the striped decode callback function.
+ * If set, this function will be called as each piece of a frame is fully
+ * decoded.
+ * You can pass in a #theora_stripe_callback with
+ * theora_stripe_callback#stripe_decoded set to <tt>NULL</tt> to disable the
+ * callbacks at any point.
+ *
+ * \param[in] _buf #theora_stripe_callback: The callback parameters.
+ * \retval OC_FAULT \a _dec_ctx or \a _buf is <tt>NULL</tt>.
+ * \retval OC_EINVAL \a _buf_sz is not
+ * <tt>sizeof(theora_stripe_callback)</tt>.*/
#define OC_DECCTL_SET_STRIPE_CB (7)
+/*@}*/
-/*A single color plane in an image.*/
+
+
+/**A buffer for a single color plane in an uncompressed image.
+ * This contains the image data in a left-to-righ, top-down format.
+ * Each row of pixels is stored contiguously in memory, but successive rows
+ * need not be.
+ * Use \a ystride to compute the offset of the next row.
+ * The encoder accepts both positive \a ystride values (top-down) and negative
+ * (bottom-up).
+ * The decoder currently always generates images with positive strides.
+ */
typedef struct{
+ /**The width of this plane.*/
int width;
+ /**The height of this plane.*/
int height;
+ /**The offset in bytes between successive rows.*/
int ystride;
+ /**A pointer to the first row.*/
unsigned char *data;
}theora_img_plane;
-/*A complete image buffer.
- Note: The term YUV often used to describe a colorspace is ambiguous.
- The exact parameters of the RGB<->YUV conversion process aside, in many
- contexts the U and V channels actually have opposite meanings.
- To avoid this confusion, we are explicit: the name of the color channels is
- Y'CbCr, and they appear in that order, always.
- The prime symbol denotes that the Y channel is non-linear.
- Cb and Cr stand for "Chroma blue" and "Chroma red" respectively.*/
+/**A complete image buffer for an uncompressed frame.
+ * The chroma planes may be decimated by a factor of two in either direction,
+ * as indicated by theora_info#pixel_fmt.
+ * The width and height of the Y' plane must be multiples of 16.
+ * They may need to be cropped for display, using the rectangle specified by
+ * theora_info#pic_x, theora_info#pic_y, theora_info#pic_width, and
+ * theora_info#pic_height.
+ * All samples are 8 bits.
+ * \note The term YUV often used to describe a colorspace is ambiguous.
+ * The exact parameters of the RGB to YUV conversion process aside, in many
+ * contexts the U and V channels actually have opposite meanings.
+ * To avoid this confusion, we are explicit: the name of the color channels is
+ * Y'CbCr, and they appear in that order, always.
+ * The prime symbol denotes that the Y channel is non-linear.
+ * Cb and Cr stand for "Chroma blue" and "Chroma red" respectively.*/
typedef theora_img_plane theora_ycbcr_buffer[3];
-/*A callback function for striped decoded.
- This is a function pointer to an application-provided function that gets
- called each time a section of the image is fully decoded.
- This allows the application to process the section immediately, while it is
- still in cache.
- Note that the frame is decoded bottom to top, so _yfrag0 will steadily
- decrease with each call until it reaches 0, at which point the full frame is
- decoded.
- The number of fragment rows made available in each call depends on the pixel
- format and the number of post-processing filters enabled, and may not even
- be constant for the entire frame.
- If a non-NULL _granpos pointer is passed to theora_decode_packetin(), the
- granule position for the frame will be stored in it before the first
- callback is made.
- If an entire frame is dropped (a 0-byte packet), then no callbacks will be
- made at all for that frame.
- _ctx: An application-provided context pointer.
- _buf: The image buffer for the decoded frame.
- _yfrag0: The Y coordinate of the first row of 8x8 fragments decoded.
- Multiply this by 8 to obtain the pixel row number in the luma
- plane.
- If the chroma planes are subsampled in the Y direction, this will
- always be divisible by two.
- _yfrag_end: The Y coordinate of the first row of 8x8 fragments past the
- newly decoded section.
- If the chroma planes are subsampled in the Y direction, this will
- always be divisible by two.
- I.e., this section contains fragment rows
- _yfrag0..._yfrag_end-1.*/
+/**A callback function for striped decode.
+ * This is a function pointer to an application-provided function that will be
+ * called each time a section of the image is fully decoded.
+ * This allows the application to process the section immediately, while it is
+ * still in cache.
+ * Note that the frame is decoded bottom to top, so \a _yfrag0 will steadily
+ * decrease with each call until it reaches 0, at which point the full frame
+ * is decoded.
+ * The number of fragment rows made available in each call depends on the pixel
+ * format and the number of post-processing filters enabled, and may not even
+ * be constant for the entire frame.
+ * If a non-<tt>NULL</tt> \a _granpos pointer is passed to
+ * theora_decode_packetin(), the granule position for the frame will be stored
+ * in it before the first callback is made.
+ * If an entire frame is dropped (a 0-byte packet), then no callbacks will be
+ * made at all for that frame.
+ * \param _ctx An application-provided context pointer.
+ * \param _buf The image buffer for the decoded frame.
+ * \param _yfrag0 The Y coordinate of the first row of 8x8 fragments
+ * decoded.
+ * Multiply this by 8 to obtain the pixel row number in the
+ * luma plane.
+ * If the chroma planes are subsampled in the Y direction,
+ * this will always be divisible by two.
+ * \param _yfrag_end The Y coordinate of the first row of 8x8 fragments past
+ * the newly decoded section.
+ * If the chroma planes are subsampled in the Y direction,
+ * this will always be divisible by two.
+ * I.e., this section contains fragment rows
+ * <tt>\a _yfrag0 ...\a _yfrag_end -1</tt>.*/
typedef void (*theora_stripe_decoded_func)(void *_ctx,theora_ycbcr_buffer _buf,
int _yfrag0,int _yfrag_end);
+/**The striped decode callback data to pass to #OC_DECCTL_SET_STRIPE_CB.*/
typedef struct{
+ /**An application-provided context pointer.
+ * This will be passed back verbatim to the application.*/
void *ctx;
+ /**The callback function pointer.*/
theora_stripe_decoded_func stripe_decoded;
}theora_stripe_callback;
+/**Theora bitstream information.
+ * This contains the basic playback parameters for a stream, and corresponds to
+ * the initial 'info' header packet.
+ * To initialize an encoder, the application fills in this structure and
+ * passes it to theora_encode_alloc().
+ * On decode, it is filled in by theora_decode_headerin(), and then passed to
+ * theora_decode_alloc().
+ *
+ * Encoded Theora frames must be a multiple of 16 in size;
+ * this is what the #frame_width and #frame_height members represent.
+ * To handle arbitrary picture sizes, a crop rectangle is specified in the
+ * #pic_x, #pic_y, #pic_width and #pic_height members.
+ *
+ * All frame buffers contain pointers to the full, padded frame.
+ * However, the current encoder <em>will not</em> reference pixels outside of
+ * the cropped picture region, and the application does not need to fill them
+ * in.
+ * The decoder <em>will</em> allocate storage for a full frame, but the
+ * application <em>should not</em> rely on the padding containing sensible
+ * data.
+ *
+ * It is also generally recommended that the offsets and sizes should still be
+ * multiples of 2 to avoid chroma sampling shifts.
+ * See <a href="http://www.theora.org/doc/Theora_I_spec.pdf">the Theora
+ * specification</a>, Section 4.4, for more details.
+ *
+ * Frame rate, in frames per second, is stored as a rational fraction, as is
+ * the pixel aspect ratio.
+ * Note that this refers to the aspect ratio of the individual pixels, not of
+ * the overall frame itself.
+ * The frame aspect ratio can be computed from pixel aspect ratio using the
+ * image dimensions.
+ */
typedef struct{
- /*Bitstream version information.*/
+ /**\name Theora version
+ * Bitstream version information.*/
+ /*@{*/
unsigned char version_major;
unsigned char version_minor;
unsigned char version_subminor;
- /*The encoded frame width: must be a multiple of 16, and less than 1048576.*/
+ /*@}*/
+ /**The encoded frame width.
+ * This must be a multiple of 16, and less than 1048576.*/
ogg_uint32_t frame_width;
- /*The encoded frame height: must be a multiple of 16, and less than
- 1048576.*/
+ /**The encoded frame height.
+ * This must be a multiple of 16, and less than 1048576.*/
ogg_uint32_t frame_height;
- /*The displayed picture width: must be no larger than width.*/
+ /**The displayed picture width.
+ * This must be no larger than width.*/
ogg_uint32_t pic_width;
- /*The displayed picture height: must be no larger than height.*/
+ /**The displayed picture height.
+ * This must be no larger than height.*/
ogg_uint32_t pic_height;
- /*The x offset of the displayed picture: must be no larger than
- frame_width-pic_width or 255, whichever is smaller.*/
+ /**The X offset of the displayed picture.
+ * This must be no larger than #frame_width-#pic_width or 255, whichever is
+ * smaller.*/
ogg_uint32_t pic_x;
- /*The y offset of the displayed picture: must be no larger than
- frame_height-pic_height, and frame_height-pic_height-pic_y must be no
- larger than 255.
- This offset is specified from the top of the image, as this API uses the
- standard graphics left-handed coordinate system.*/
+ /**The Y offset of the displayed picture.
+ * This must be no larger than #frame_height-#pic_height, and
+ * #frame_height-#pic_height-#pic_y must be no larger than 255.
+ * This offset is specified from the top of the image, as this API uses the
+ * standard graphics left-handed coordinate system.*/
ogg_uint32_t pic_y;
- /*The frame rate, as a fraction.
- If either is 0, the frame rate is undefined.*/
+ /**\name Frame rate
+ * The frame rate, as a fraction.
+ * If either is 0, the frame rate is undefined.*/
+ /*@{*/
ogg_uint32_t fps_numerator;
ogg_uint32_t fps_denominator;
- /*The aspect ratio of the pixels.
- If either value is zero, the aspect ratio is undefined.
- If not specified by any external means, 1:1 should be assumed.*/
+ /*@}*/
+ /**\name Aspect ratio
+ * The aspect ratio of the pixels.
+ * If either value is zero, the aspect ratio is undefined.
+ * If not specified by any external means, 1:1 should be assumed.*/
+ /*@{*/
ogg_uint32_t aspect_numerator;
ogg_uint32_t aspect_denominator;
- /*The color space.*/
+ /*@}*/
+ /**The color space.*/
theora_colorspace colorspace;
- /*The pixel format.*/
+ /**The pixel format.*/
theora_pixel_fmt pixel_fmt;
- /*The target bit-rate in bps.
- TODO: Current encoder does not support CBR mode, or anything like it.
+ /**The target bit-rate in bits per second. */
+ /*TODO: Current encoder does not support CBR mode, or anything like it.
We also don't really know what nominal rate each quality level
corresponds to yet.*/
int target_bitrate;
+ /**The target quality level.*/
/*Currently this is set so that a qi of 0 corresponds to distortions of 24
times the JND, and each increase by 16 halves that value.
This gives us fine discrimination at low qualities, yet effective rate
@@ -270,71 +376,98 @@
We'd have to redesign the token syntax to store these large coefficients,
which would make transcoding complex.*/
int quality;
- /*The amount to shift to extract the last keyframe number from the granule
- position.
- This can be at most 31.
- The maximum distance between keyframes is 1<<keyframe_granule_shift.
- If you leave this at zero and do not set the keyframe frequency with
- OC_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE, every frame will be encoded as a
- keyframe.*/
+ /**The amount to shift to extract the last keyframe number from the granule
+ * position.
+ * This can be at most 31.
+ * The maximum distance between keyframes is
+ * <tt>1<<#keyframe_granule_shift</tt>.
+ * If you leave this at zero and do not set the keyframe frequency with
+ * #OC_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE, every frame will be encoded as a
+ * keyframe.*/
int keyframe_granule_shift;
}theora_info;
+/**The number of Huffman tables used by Theora.*/
#define OC_NHUFFMAN_TABLES (80)
+/**The number of DCT token values in each table.*/
#define OC_NDCT_TOKENS (32)
-/*A Huffman code for a Theora DCT token.
- Each set of Huffman codes in a given table must form a complete, prefix-free
- code.
- There is no requirement that all the tokens in a table have a valid code,
- but the current encoder is not optimized to take advantage of this.
- If there is not at least one table with a code for every token in each of
- the five groups of 16 tables, then the encoder may fail to encode certain
- frames.
- The complete table in the first group of 16 does not have to be in the same
- place as the complete table in the other groups, but the complete tables in
- the remaining four groups must all be in the same place.*/
+/**A Huffman code for a Theora DCT token.
+ * Each set of Huffman codes in a given table must form a complete, prefix-free
+ * code.
+ * There is no requirement that all the tokens in a table have a valid code,
+ * but the current encoder is not optimized to take advantage of this.
+ * If there is not at least one table with a code for every token in each of
+ * the five groups of 16 tables, then the encoder may fail to encode certain
+ * frames.
+ * The complete table in the first group of 16 does not have to be in the same
+ * place as the complete table in the other groups, but the complete tables in
+ * the remaining four groups must all be in the same place.*/
typedef struct{
- /*The bit pattern for the code, with the LSbit of the pattern aligned in
- the LSbit of the word.*/
+ /**The bit pattern for the code, with the LSbit of the pattern aligned in
+ * the LSbit of the word.*/
ogg_uint32_t pattern;
- /*The number of bits in the code.
- This must be between 0 and 32, inclusive.*/
+ /**The number of bits in the code.
+ * This must be between 0 and 32, inclusive.*/
int nbits;
}theora_huff_code;
-/*The Huffman tables used by VP3.*/
-extern const theora_huff_code
+/**The Huffman tables used by VP3.*/
+extern const theora_huff_code
OC_VP31_HUFF_CODES[OC_NHUFFMAN_TABLES][OC_NDCT_TOKENS];
-/*The quantization parameters.
- The quantizer for each coefficient is calculated as:
+/**A single base matrix.*/
+typedef unsigned char theora_quant_base[64];
+
+/**A set of \a qi ranges.*/
+typedef struct{
+ /**The number of ranges in the set.*/
+ int nranges;
+ /**The size of each of the #nranges ranges.
+ These must sum to 63.*/
+ const int *sizes;
+ /**#nranges <tt>+1</tt> base matrices.
+ Matrices \a i and <tt>\a i +1</tt> form the endpoints of range \a i.*/
+ const theora_quant_base *base_matrices;
+}theora_quant_ranges;
+
+/**A complete set of quantization parameters.
+ The quantizer for each coefficient is calculated as:
+ \code
Q=MAX(MIN(qmin[qti][ci!=0],scale[ci!=0][qi]*base[qti][pli][qi][ci]/100),
1024).
- qti is the quantization type index: 0 for intra, 1 for inter.
- ci!=0 is 0 for the DC coefficient and 1 for the AC coefficient.
- qi is the quality index, ranging between 0 (low quality) and 63 (high
- quality).
- pli is the color plane index: 0 for Y', 1 for Cb, 2 for Cr.
- ci is the DCT coefficient index.
- Coefficient indices correspond to the normal 2D DCT block ordering--
- row-major with low frequencies first--NOT zig-zag order.
+ \endcode
- Minimum quantizers are constant, and are given by:
- qmin[2][2]={{4,2},{8,4}};
+ \a qti is the quantization type index: 0 for intra, 1 for inter.
+ <tt>\a ci !=0</tt> is 0 for the DC coefficient and 1 for the AC coefficient.
+ \a qi is the quality index, ranging between 0 (low quality) and 63 (high
+ quality).
+ \a pli is the color plane index: 0 for Y', 1 for Cb, 2 for Cr.
+ \a ci is the DCT coefficient index.
+ Coefficient indices correspond to the normal 2D DCT block
+ ordering--row-major with low frequencies first--\em not zig-zag order.
- Parameters that can be stored in the bitstream are as follows:
- The two scale matrices ac_scale and dc_scale.
+ Minimum quantizers are constant, and are given by:
+ \code
+ qmin[2][2]={{4,2},{8,4}}.
+ \endcode
+
+ Parameters that can be stored in the bitstream are as follows:
+ - The two scale matrices ac_scale and dc_scale.
+ \code
scale={dc_scale,ac_scale}.
- The base matrices for each qi, qti and pli (up to 384 in all).
+ \endcode
+ - The base matrices for each \a qi, \a qti and \a pli (up to 384 in all).
In order to avoid storing a full 384 base matrices, only a sparse set of
matrices is stored, and the rest are linearly interpolated.
This is done as follows.
- For each qti and pli, a series of n qi ranges is defined.
- The size of each qi range can vary arbitrarily, but they must sum to 63.
- Then, n+1 matrices are specified, one for each endpoint of the ranges.
- For interpolation purposes, each range's endpoints are the first qi
- value it contains and one past the last qi value it contains.
+ For each \a qti and \a pli, a series of \a n \a qi ranges is defined.
+ The size of each \a qi range can vary arbitrarily, but they must sum to
+ 63.
+ Then, <tt>\a n +1</tt> matrices are specified, one for each endpoint of
+ the ranges.
+ For interpolation purposes, each range's endpoints are the first \a qi
+ value it contains and one past the last \a qi value it contains.
Fractional values are rounded to the nearest integer, with ties rounded
away from zero.
@@ -345,90 +478,316 @@
set (indexed in row-major order) or if the inter set is the same as the
inter set.
- For the current encoder, scale[ci!=0][qi] must be <= scale[ci!=0][qi-1] and
- base[qti][pli][qi][ci] must be <= base[qti][pli][qi-1][ci].
- These two conditions ensure that the actual quantizer for a given qti, pli
- and ci does not increase as qi increases.
- This is not required by the decoder.*/
+ - Loop filter limit values.
+ The same limits are used for the loop filter in all color planes, despite
+ potentially differing levels of quantization in each.
-/*A single base matrix.*/
-typedef unsigned char theora_quant_base[64];
-
-/*A set of qi ranges.*/
+ For the current encoder, <tt>scale[ci!=0][qi]</tt> must be no greater
+ than <tt>scale[ci!=0][qi-1]</tt> and <tt>base[qti][pli][qi][ci]</tt> must
+ be no greater than <tt>base[qti][pli][qi-1][ci]</tt>.
+ These two conditions ensure that the actual quantizer for a given \a qti,
+ \a pli, and \a ci does not increase as \a qi increases.
+ This is not required by the decoder.*/
typedef struct{
- int nranges;
- const int *sizes;
- const theora_quant_base *base_matrices;
-}theora_quant_ranges;
-
-/*The complete set of quantization parameters.*/
-typedef struct{
+ /**The DC scaling factors.*/
ogg_uint16_t dc_scale[64];
+ /**The AC scaling factors.*/
ogg_uint16_t ac_scale[64];
+ /**The loop filter limit values.*/
unsigned char loop_filter_limits[64];
+ /**The \a qi ranges for each \a ci and \a pli.*/
theora_quant_ranges qi_ranges[2][3];
}theora_quant_info;
-/*The quantization parameters used by VP3.*/
+/**The quantization parameters used by VP3.*/
extern const theora_quant_info OC_VP31_QUANT_INFO;
-/*The comment information.*/
+/**The comment information.
+ *
+ * This structure holds the in-stream metadata corresponding to
+ * the 'comment' header packet.
+ * The comment header is meant to be used much like someone jotting a quick
+ * note on the label of a video.
+ * It shold be a short, to the point text note that can be more than a couple
+ * words, but not more than a short paragraph.
+ *
+ * The metadata is stored as a series of (tag, value) pairs, in
+ * length-encoded string vectors.
+ * The first occurence of the '=' character delimits the tag and value.
+ * A particular tag may occur more than once, and order is significant.
+ * The character set encoding for the strings is always UTF-8, but the tag
+ * names are limited to ASCII, and treated as case-insensitive.
+ * See <a href="http://www.theora.org/doc/Theora_I_spec.pdf">the Theora
+ * specification</a>, Section 6.3.3 for details.
+ *
+ * In filling in this structure, theora_decode_header() will null-terminate
+ * the user_comment strings for safety.
+ * However, the bitstream format itself treats them as 8-bit clean vectors,
+ * possibly containing nul characters, and so the length array should be
+ * treated as their authoritative length.
+ */
typedef struct theora_comment{
+ /**The array of comment string vectors.*/
char **user_comments;
+ /**An array of the corresponding length of each vector, in bytes.*/
int *comment_lengths;
+ /**The total number of comment strings.*/
int comments;
+ /**The null-terminated vendor string.
+ This identifies the software used to encode the stream.*/
char *vendor;
}theora_comment;
-/*These contents of the following structures are not publicly defined by this
- API.
- Referring to their internals directly is unsupported, and may break without
- warning.*/
+/**\name Encoder and decoder state
+ The following data structures are opaque, and their contents are not
+ publicly defined by this API.
+ Referring to their internals directly is unsupported, and may break without
+ warning.*/
+/*@{*/
+/**The encoder context.*/
typedef struct theora_enc_ctx theora_enc_ctx;
+/**The decoder state.*/
typedef struct theora_dec_ctx theora_dec_ctx;
+/**Setup information.
+ This contains auxilliary information (Huffman tables and quantization
+ parameters) decoded from the setup header by theora_decode_headerin() to be
+ passed to theora_decode_alloc().*/
typedef struct theora_setup_info theora_setup_info;
+/*@}*/
-extern const char *theora_version_string(void);
-extern ogg_uint32_t theora_version_number(void);
+
+/**\name Functions for manipulating header data*/
+/*@{*/
+/**Initializes a theora_info structure.
+ * This should be called on a freshly allocated #theora_info structure before
+ * attempting to use it.
+ * \param _info The #theora_info struct to initialize.*/
extern void theora_info_init(theora_info *_info);
+/**Clears a #theora_info structure.
+ * This should be called on a #theora_info structure after it is no longer
+ * needed.
+ * \param _info The #theora_info struct to clear.*/
extern void theora_info_clear(theora_info *_info);
-extern void theora_setup_free(theora_setup_info *_setup);
-
+/**Initialize a #theora_comment structure.
+ * This should be called on a freshly allocated #theora_comment structure
+ * before attempting to use it.
+ * \param _tc The #theora_comment struct to initialize.*/
extern void theora_comment_init(theora_comment *_tc);
+/**Add a comment to an initialized #theora_comment structure.
+ * \note Neither theora_comment_add() nor theora_comment_add_tag() support
+ * comments containing null values, although the bitstream format does
+ * support them.
+ * To add such comments you will need to manipulate the #theora_comment
+ * structure directly.
+ * \param _tc The #theora_comment struct to add the comment to.
+ * \param _comment Must be a null-terminated UTF-8 string containing the
+ * comment in "TAG=the value" form.*/
extern void theora_comment_add(theora_comment *_tc, char *_comment);
+/**Add a comment to an initialized #theora_comment structure.
+ * \note Neither theora_comment_add() nor theora_comment_add_tag() support
+ * comments containing null values, although the bitstream format does
+ * support them.
+ * To add such comments you will need to manipulate the #theora_comment
+ * structure directly.
+ * \param _tc The #theora_comment struct to add the comment to.
+ * \param _tag A null-terminated string containing the tag associated with
+ * the comment.
+ * \param _val The corresponding value as a null-terminated string.*/
extern void theora_comment_add_tag(theora_comment *_tc,char *_tag,char *_val);
+/**Look up a comment value by its tag.
+ * \param _tc An initialized #theora_comment structure.
+ * \param _tag The tag to look up.
+ * \param _count The instance of the tag.
+ * The same tag can appear multiple times, each with a distinct
+ * value, so an index is required to retrieve them all.
+ * The order these values appear in is significant and should be
+ * preserved.
+ * Use theora_comment_query_count() to get the legal range for
+ * the \a _count parameter.
+ * \return A pointer to the queried tag's value.
+ * \retval NULL If no matching tag is found.*/
extern char *theora_comment_query(theora_comment *_tc,char *_tag,int _count);
+/**Look up the number of instances of a tag.
+ * Call this first when querying for a specific tag and then iterate over the
+ * number of instances with separate calls to theora_comment_query() to
+ * retrieve all instances in order.
+ * \param _tc An initialized #theora_comment structure.
+ * \param _tag The tag to look up.
+ * \return The number on instances of this particular tag.*/
extern int theora_comment_query_count(theora_comment *_tc,char *_tag);
+/**Clears a #theora_comment structure.
+ * This should be called on a #theora_comment structure after it is no longer
+ * needed.
+ * It will free all memory used by the structure members.
+ * \param _tc The #theora_comment struct to clear.*/
extern void theora_comment_clear(theora_comment *_tc);
+/**Releases all storage used for the decoder setup information.
+ * This should be called after you no longer want to create any decoders for
+ * a stream after parsing its headers with theora_decode_headerin().
+ * \param _setup The setup information to free.
+ * This can safely be <tt>NULL</tt>.*/
+extern void theora_setup_free(theora_setup_info *_setup);
+/*@}*/
+
+
+/**\name Functions for encoding*/
+/*@{*/
+/**Allocates an encoder instance.
+ * \param _info A #theora_info struct filled with the desired encoding
+ * parameters.
+ * \return The initialized #theora_enc_ctx handle.
+ * \retval NULL If the encoding parameters were invalid.*/
extern theora_enc_ctx *theora_encode_alloc(const theora_info *_info);
+/**Encoder control function.
+ * This is used to provide advanced control the encoding process.
+ * \param _enc A #theora_enc_ctx handle.
+ * \param _req The control code to process.
+ * \param _buf The parameters for this control code.
+ * \param _buf_sz The size of the parameter buffer.*/
extern int theora_encode_ctl(theora_enc_ctx *_enc,int _req,void *_buf,
size_t _buf_sz);
+/**Outputs the next header packet.
+ * This should be called repeatedly after encoder initialization until it
+ * returns 0 to get all of the header packets, in order, before encoding
+ * actual video data.
+ * \param _enc A #theora_enc_ctx handle.
+ * \param _comments The metadata to place in the comment header, when it is
+ * encoded.
+ * \param _op An ogg_packet structure to fill.
+ * All of the elements of this structure will be set,
+ * including a pointer to the header data.
+ * The memory for the header data is owned by libtheora.
+ * \return A positive value indicates that a header packet was successfully
+ * produced.
+ * \retval 0 No packet was produced, and no more header packets remain.
+ * \retval OC_FAULT \a _enc, \a _comments, or \a _op was <tt>NULL</tt>.*/
extern int theora_encode_flushheader(theora_enc_ctx *_enc,
theora_comment *_comments,ogg_packet *_op);
+/**Submits an uncompressed frame to the encoder.
+ * \param _enc A #theora_enc_ctx handle.
+ * \param _ycbcr A buffer of Y'CbCr data to encode.
+ * \retval 0 Success.
+ * \retval OC_EFAULT \a _enc or \a _ycbcr is <tt>NULL</tt>.
+ * \retval OC_EINVAL The buffer size does not match the frame size the encoder
+ * was initialized with, or encoding has already completed.
+ */
extern int theora_encode_ycbcr_in(theora_enc_ctx *_enc,
theora_ycbcr_buffer _ycbcr);
+/**Retrieves encoded video data packets.
+ * This should be called repeatedly after each frame is submitted to flush any
+ * encoded packets, until it returns 0.
+ * The encoder will not buffer these packets as subsequent frames are
+ * compressed, so a failure to do so function will result in lost video data.
+ * \note Currently the encoder operates in a one-frame-in, one-packet-out
+ * manner.
+ * However, this may be changed in the future.
+ * \param _enc A #theora_enc_ctx handle.
+ * \param _last Set this flag to a non-zero value if no more uncompressed
+ * frames will be submitted.
+ * This ensures that a proper EOS flag is set on the last packet.
+ * \param _op An ogg_packet structure to fill.
+ * All of the elements of this structure will be set, including a
+ * pointer to the video data.
+ * The memory for the video data is owned by libtheora.
+ * \return A positive value indicates that a video data packet was successfully
+ * produced.
+ * \retval 0 No packet was produced, and no more encoded video data
+ * remains.
+ * \retval OC_FAULT \a _enc or \a _op was <tt>NULL</tt>.*/
extern int theora_encode_packetout(theora_enc_ctx *_enc,int _last,
ogg_packet *_op);
+/**Frees an allocated encoder instance.
+ * \param _enc A #theora_enc_ctx handle.*/
extern void theora_encode_free(theora_enc_ctx *_enc);
+/*@}*/
+
+/**\name Functions for decoding*/
+/*@{*/
extern int theora_decode_headerin(theora_info *_info,theora_comment *_tc,
theora_setup_info **_setup,ogg_packet *_op);
+/**Allocates a decoder instance.
+ * \param _info A #theora_info struct filled via theora_decode_headerin().
+ * \param _setup A #theora_setup_info handle returned via
+ * theora_decode_headerin().
+ * \return The initialized #theora_dec_ctx handle.
+ * \retval NULL If the decoding parameters were invalid.*/
extern theora_dec_ctx *theora_decode_alloc(const theora_info *_info,
const theora_setup_info *_setup);
+/**Submits a packet containing encoded video data to the decoder.
+ * \param _dec A #theora_dec_ctx handle.
+ * \param _op An ogg_packet containing encoded video data.
+ * \param _granpos Returns the granule position of the decoded packet.
+ * If non-<tt>NULL</tt>, the granule position for this specific
+ * packet is stored in this location.
+ * This is computed incrementally from previously decoded
+ * packets.
+ * After a seek, the correct granule position must be set via
+ * #OC_DECCTL_SET_GRANPOS for this to work properly.
+ * \retval 0 Success.
+ * \retval OC_FAULT \a _dec or _op was <tt>NULL</tt>.
+ * \retval OC_BADPACKET \a _op does not contain encoded video data.
+ * \retval OC_IMPL The video data uses bitstream features which this
+ * library does not support.*/
extern int theora_decode_packetin(theora_dec_ctx *_dec,const ogg_packet *_op,
ogg_int64_t *_granpos);
+/**Outputs the next available frame of decoded Y'CbCr data.
+ * \param _dec A #theora_dec_ctx handle.
+ * \param _ycbcr A video buffer structure to fill in.
+ * libtheora will fill in all the members of this structure,
+ * including the pointers to unccompressed video data.
+ * The memory for this video data is owned by libtheora.
+ * \retval 0 Success
+ */
extern int theora_decode_ycbcr_out(theora_dec_ctx *_dec,
theora_ycbcr_buffer _ycbcr);
+/**Encoder control function.
+ * This is used to provide advanced control the decoding process.
+ * \param _dec A #theora_dec_ctx handle.
+ * \param _req The control code to process.
+ * \param _buf The parameters for this control code.
+ * \param _buf_sz The size of the parameter buffer.*/
extern int theora_decode_ctl(theora_dec_ctx *_dec,int _req,void *_buf,
size_t _buf_sz);
+/**Frees an allocated decoder instance.
+ * \param _dec A #theora_dec_ctx handle.*/
extern void theora_decode_free(theora_dec_ctx *_dec);
+/*@}*/
+
+/**\name Shared encoding and decoding functions*/
+/*@{*/
+/**Retrieves a human-readable string to identify the library vendor and
+ * version.
+ * \return the version string.*/
+extern const char *theora_version_string(void);
+/**Retrieves the library version number.
+ * This is the highest bitstream version that the encoder library will produce,
+ * or that the decoder library can decode.
+ * This number is composed of a 16-bit major version, 8-bit minor version
+ * and 8 bit sub-version, composed as follows:
+ * \code
+ * (VERSION_MAJOR<<16)+(VERSION_MINOR<<8)+(VERSION_SUB)
+ * \endcode
+ * \return the version number.*/
+extern ogg_uint32_t theora_version_number(void);
+
+/**Converts a granule position to an absolute time in seconds.
+ * The granule position is interpreted in the context of a given
+ * #theora_enc_ctx or #theora_dec_ctx handle (either will suffice).
+ * \param _encdec A previously allocated #theora_enc_ctx or #theora_dec_ctx
+ * handle.
+ * \param _granpos The granule position to convert.
+ * \return The absolute time in seconds corresponding to \a _granpos.
+ * \retval -1 The given granulepos is invalid (ie. negative).*/
extern double theora_granule_time(void *_encdec,ogg_int64_t _granpos);
+/*@}*/
+
#if defined(__cplusplus)
}
#endif
More information about the commits
mailing list