[xiph-commits] r13960 - trunk/theora/doc/spec
giles at svn.xiph.org
giles at svn.xiph.org
Thu Oct 11 18:15:37 PDT 2007
Author: giles
Date: 2007-10-11 18:15:36 -0700 (Thu, 11 Oct 2007)
New Revision: 13960
Modified:
trunk/theora/doc/spec/spec.tex
Log:
Add figures describing the header packet structure at various levels of
detail. Need to anchor the figures a little better.
Also add a more complete list of suggested comment fields.
Modified: trunk/theora/doc/spec/spec.tex
===================================================================
--- trunk/theora/doc/spec/spec.tex 2007-10-12 00:06:07 UTC (rev 13959)
+++ trunk/theora/doc/spec/spec.tex 2007-10-12 01:15:36 UTC (rev 13960)
@@ -1949,6 +1949,26 @@
\section{Common Header Decode}
\label{sub:common-header}
+\begin{figure}[Htbp]
+\begin{center}
+\begin{verbatim}
+ 0 1 2 3
+ 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | header type | 't' | 'h' | 'e' |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | 'o' | 'r' | 'a' | data... |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | ... header-specific data ... |
+ | ... |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+\end{verbatim}
+\end{center}
+\caption{Common Header Packet Layout}
+\label{fig:commonheader}
+\end{figure}
+
+
\paragraph{Input parameters:} None.
\paragraph{Output parameters:}\hfill\\*
@@ -2004,6 +2024,40 @@
\section{Identification Header Decode}
\label{sec:idheader}
+\begin{figure}[Htbp]
+\begin{center}
+\begin{verbatim}
+ 0 1 2 3
+ 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | 0x80 | 't' | 'h' | 'e' |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | 'o' | 'r' | 'a' | VMAJ |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | VMIN | VREV | FMBW |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | FMBH | PICW... |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | ...PICW | PICH |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | PICX | PICY | FRN... |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | ...FRN | FRD... |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | ...FRD | PARN... |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | ...PARN | PARD |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | CS | NOMBR |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | QUAL | KFGSHIFT| PF| Res |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+\end{verbatim}
+\end{center}
+\caption{Identification Header Packet}
+\label{fig:idheader}
+\end{figure}
+
\paragraph{Input parameters:} None.
\paragraph{Output parameters:}\hfill\\*
@@ -2267,7 +2321,8 @@
belongs in a separate logical stream that provides greater structure and
machine parseability.
-%r: I tried to morph this a little more in the direction of our application space
+%r: I tried to morph this a little more in the direction of our
+% application space
The comment field is meant to be used much like someone jotting a quick note on
the label of a video.
It should be a little information to remember the disc or tape by and explain it to
@@ -2289,6 +2344,19 @@
\subsection{Comment Length Decode}
\label{sub:comment-len}
+\begin{figure}
+\begin{center}
+\begin{tabular}{ | c | c | }
+ \hline
+ 4 byte length &
+ UTF-8 encoded string ...\\
+ \hline
+\end{tabular}
+\end{center}
+\caption{Length encoded string layout}
+\label{fig:comment-len}
+\end{figure}
+
\paragraph{Input parameters:} None.
\paragraph{Output parameters:}\hfill\\*
@@ -2338,6 +2406,22 @@
\subsection{Comment Header Decode}
+\begin{figure}
+\begin{center}
+\begin{tabular}{ | c | }
+ \hline
+ vendor string \\ \hline
+ number of comments \\ \hline
+ comment string \\ \hline
+ comment string \\ \hline
+ ... \\
+ \hline
+\end{tabular}
+\end{center}
+\caption{Comment Header Layout}
+\label{fig:commentheader}
+\end{figure}
+
\paragraph{Input parameters:} None.
\paragraph{Output parameters:}\hfill\\*
@@ -2464,6 +2548,8 @@
\paragraph{Field Names}
+%r should this be an appendix?
+
Below is a proposed, minimal list of standard field names with a description of
their intended use.
No field names are mandatory; a comment header may contain one or more, all, or
@@ -2471,7 +2557,30 @@
\begin{description}
\item{TITLE:} Video name.
-%TODO: Complete list
+\item{ARTIST:} Filmmaker or other creator name.
+\item{VERSION:} Subtitle, remix info, or other text distinguishing
+ versions of a video.
+\item{DATE:} Date associated with the video. Implementations SHOULD attempt
+ to parse this field as an ISO 8601 date for machine interpretation and
+ conversion.
+\item{LOCATION:} Location associated with the video. This is usually the
+ filming location for non-fiction works.
+\item{COPYRIGHT:} Copyright statement.
+\item{LICENSE:} Copyright and other licensing information.
+ Implementations wishing to do automatic parsing of e.g
+ of distribution terms SHOULD look here for a URL uniquely defining
+ the license. If no instance of this field is present, or if no
+ instance contains a parseable URL, and implementation MAY look
+ in the COPYRIGHT field for such a URL.
+\item{ORGANIZATION:} Studio name, Publisher, or other organization
+ involved in the creation of the video.
+
+\item{DIRECTOR:} Director or Filmmaker credit, similar to ARTIST.
+\item{PRODUCER:} Producer credit for the video.
+\item{COMPOSER:} Music credit for the video.
+\item{ACTOR:} Acting credit for the video.
+
+\item{DESCRIPTION:} General description, summary, or blurb.
\end{description}
\section{Setup Header}
@@ -2483,6 +2592,28 @@
Because the contents of this header are specific to Theora, no concessions have
been made to keep the fields octet-aligned for easy parsing.
+\begin{figure}
+\begin{center}
+\begin{tabular}{ | c | }
+ \hline
+ common header block \\ \hline
+ loop filter table resolution \\ \hline
+ loop filter table \\ \hline
+ scale table resolution \\ \hline
+ AC scale table \\ \hline
+ DC scale table \\ \hline
+ number of base matricies \\ \hline
+ base quatization matricies \\ \hline
+ ... \\ \hline
+ quant range interpolation table \\ \hline
+ DCT token Huffman tables \\
+ \hline
+\end{tabular}
+\end{center}
+\caption{Setup Header structure}
+\label{fig:setupheader}
+\end{figure}
+
\subsection{Loop Filter Limit Table Decode}
\label{sub:loop-filter-limits}
More information about the commits
mailing list