[xiph-commits] r8410 - in branches/theora-mmx: . doc doc/python
doc/spec examples include/theora
j at motherfish-iii.xiph.org
j at motherfish-iii.xiph.org
Wed Dec 15 02:44:56 PST 2004
Author: j
Date: 2004-12-15 02:44:55 -0800 (Wed, 15 Dec 2004)
New Revision: 8410
Added:
branches/theora-mmx/doc/spec/xifish.fig
Removed:
branches/theora-mmx/doc/spec/xifish.pdf
Modified:
branches/theora-mmx/
branches/theora-mmx/CHANGES
branches/theora-mmx/Makefile.am
branches/theora-mmx/README
branches/theora-mmx/configure.ac
branches/theora-mmx/doc/Makefile.am
branches/theora-mmx/doc/python/Makefile.am
branches/theora-mmx/doc/spec/Makefile
branches/theora-mmx/doc/spec/spec.tex
branches/theora-mmx/examples/encoder_example.c
branches/theora-mmx/examples/player_example.c
branches/theora-mmx/include/theora/theora.h
branches/theora-mmx/libtheora.spec.in
Log:
merge changes from trunk
Property changes on: branches/theora-mmx
___________________________________________________________________
Name: branch-point
- 7893
+ 8409
Modified: branches/theora-mmx/CHANGES
===================================================================
--- branches/theora-mmx/CHANGES 2004-12-15 10:38:21 UTC (rev 8409)
+++ branches/theora-mmx/CHANGES 2004-12-15 10:44:55 UTC (rev 8410)
@@ -1,4 +1,4 @@
-libtheora 1.0alpha4 (unreleased)
+libtheora 1.0alpha4 (2004 December 15)
* first draft of the Theora I Format Specification
* API documentation generated from theora.h with Doxygen
Modified: branches/theora-mmx/Makefile.am
===================================================================
--- branches/theora-mmx/Makefile.am 2004-12-15 10:38:21 UTC (rev 8409)
+++ branches/theora-mmx/Makefile.am 2004-12-15 10:44:55 UTC (rev 8410)
@@ -1,6 +1,6 @@
## Process this file with automake to produce Makefile.in
-AUTOMAKE_OPTIONS = foreign 1.6 dist-zip
+AUTOMAKE_OPTIONS = foreign 1.6 dist-zip dist-bzip2
SUBDIRS = lib include doc examples debian
@@ -13,6 +13,9 @@
dist-hook:
rm -rf `find $(distdir)/macos -name CVS`
rm -rf `find $(distdir)/win32 -name CVS`
+ rm -rf `find $(distdir)/macos -name .svn`
+ rm -rf `find $(distdir)/win32 -name .svn`
+ rm -rf `find $(distdir)/doc -name .svn`
debug:
$(MAKE) all CFLAGS="@DEBUG@"
Modified: branches/theora-mmx/README
===================================================================
--- branches/theora-mmx/README 2004-12-15 10:38:21 UTC (rev 8409)
+++ branches/theora-mmx/README 2004-12-15 10:44:55 UTC (rev 8410)
@@ -1,12 +1,11 @@
-------------------------------------------------------------------------
-This README file is up to date with and covers Xiph.Org's first alpha
-release of the Theora video codec on 25 09 2002.
+ The Xiph.org Foundation's libtheora 1.0alpha4 release
-------------------------------------------------------------------------
*** What is Theora?
Theora is Xiph.Org's first publicly released video codec, intended
-for use within the Ogg's project's Ogg multimedia streaming system.
+for use within the Foundation's Ogg multimedia streaming system.
Theora is derived directly from On2's VP3 codec; Currently the two are
nearly identical, varying only in encapsulating decoder tables in the
bitstream headers, but Theora will make use of this extra freedom
@@ -16,34 +15,26 @@
Theora's main site is www.theora.org. Theora and related libraries
can be gotten from www.theora.org or the main Xiph.Org site at
-www.xiph.org. In order to access CVS at xiph.org (the best way to get
-to the source), see http://www.xiph.org/cvs.html
+www.xiph.org. Development source is kept in an open subversion
+repository, see http://theora.org/svn.html for instructions.
*** What is the goal of this alpha release?
-This alpha is a proof of concept, not a production-ready release. Do
-not expect the Theora packet or stream format from this release to
-remain compatible with future releases. When the format for Theora is
-officially frozen, we'll let you know.
+The Theora bitstream format was frozen after the alpha3 release. This
+means that files produced by the alpha3 encoder will always be playable
+according to the Theora I specification.
+Traditionally alpha mean proof of concept, not a production-ready
+release. However the code is very robust, ready for and indeed
+in general use. But WE DO INTEND TO MAKE INCOMPATIBLE API changes
+before stable beta release however, particularly on the encoding side.
+
The purpose of this release is to provide an updated testing base for
-those interested in theora and to dissiminate more widely the bitstream
-changes we've made since the last alpha release.
+those interested in theora and to dissiminate more widely the changes
+we've made since the last alpha release. These include some helper
+utility functions, a draft format specification and rough api
+documentation located in the doc directory.
-In particular, the alpha 3 release includes a more complete set of
-decoder data tables in the third header packet. Also, the encoded image
-has been flipped vertically from the sense used in the alpha 1 and 2
-releases. The origin is now in the lower left to match the original VP3.
-Except for this change, lossless transcoding from alpha 1 and alpha 2 is
-possible. Without this change, lossless transcoding from VP3 is not
-possible.
-
-Once more for the record: THIS RELEASE IS NOT PRODUCTION CODE. It is
-not for ripping DVDs, or otherwise use for content you won't want to
-re-encode on demand. The Theora stream format MAY WELL CHANGE in future
-releases. The API WILL CHANGE. We will not yet support any Theora
-files produced by this alpha. Not yet. Soon, Grasshopper, Soon.
-
-------------------------------------------------------------------------
Getting started with the code
-------------------------------------------------------------------------
@@ -102,6 +93,13 @@
The sample player takes an Ogg file on standard in; the file may be
audio alone, video alone or video with audio.
+*** What other tools are available?
+
+If you're wanting to just use theora, consider the programs linked
+from http://www.theora.org/. There is playback support in a number
+of common free players, and Jan Gerber's ffmpeg2theora is an excellent
+encoding front end.
+
-------------------------------------------------------------------------
Troubleshooting the build process
-------------------------------------------------------------------------
Modified: branches/theora-mmx/configure.ac
===================================================================
--- branches/theora-mmx/configure.ac 2004-12-15 10:38:21 UTC (rev 8409)
+++ branches/theora-mmx/configure.ac 2004-12-15 10:44:55 UTC (rev 8410)
@@ -4,7 +4,7 @@
dnl Initialization and Versioning
dnl ------------------------------------------------
-AC_INIT(libtheora,[unreleased])
+AC_INIT(libtheora,[1.0alpha4])
AC_CANONICAL_HOST
AC_CANONICAL_TARGET
@@ -43,6 +43,10 @@
AC_MSG_WARN([*** doxygen not found, API documentation will not be built])
fi
+dnl Check for python
+AC_CHECK_PROG(HAVE_PYTHON, python, true, false)
+AM_CONDITIONAL(HAVE_PYTHON,$HAVE_PYTHON)
+
dnl --------------------------------------------------
dnl Set build flags based on environment
dnl --------------------------------------------------
Modified: branches/theora-mmx/doc/Makefile.am
===================================================================
--- branches/theora-mmx/doc/Makefile.am 2004-12-15 10:38:21 UTC (rev 8409)
+++ branches/theora-mmx/doc/Makefile.am 2004-12-15 10:44:55 UTC (rev 8410)
@@ -1,6 +1,6 @@
## Process this file with automake to produce Makefile.in
-SUBDIRS = python
+SUBDIRS = #python
docdir = $(datadir)/doc/$(PACKAGE)-$(VERSION)
Modified: branches/theora-mmx/doc/python/Makefile.am
===================================================================
--- branches/theora-mmx/doc/python/Makefile.am 2004-12-15 10:38:21 UTC (rev 8409)
+++ branches/theora-mmx/doc/python/Makefile.am 2004-12-15 10:44:55 UTC (rev 8410)
@@ -1,8 +1,9 @@
## Process this file with automake to produce Makefile.in
-
docdir = $(datadir)/doc/$(PACKAGE)-$(VERSION)
+if HAVE_PYTHON
built_docs = spec.py spec.html
+endif
static_docs =
# testspec.ogg testspec.raw \
@@ -20,4 +21,3 @@
spec.html : spec.txt txt2html.py
python $(srcdir)/txt2html.py $(srcdir)/spec.txt spec.html
-
Modified: branches/theora-mmx/doc/spec/Makefile
===================================================================
--- branches/theora-mmx/doc/spec/Makefile 2004-12-15 10:38:21 UTC (rev 8409)
+++ branches/theora-mmx/doc/spec/Makefile 2004-12-15 10:44:55 UTC (rev 8410)
@@ -15,11 +15,10 @@
FIG_TEXS = $(FIG_SRCS:.fig=.tex)
FIG_AUXS = $(FIG_SRCS:.fig=.aux)
+FIG_PDFS = $(FIG_SRCS:.fig=.pdf)
-FIG_OBJS = pic-frame.tex hilbert-mb.tex hilbert-block.tex xifish.pdf \
- superblock.tex macroblock.tex raster-block.tex reference-frames.tex \
- pixel444.tex pixel422.tex pixel420.tex idct.pdf fdct.pdf \
- pic_even.tex pic_even_odd.tex pic_odd.tex pic_odd_even.tex
+# add any native-pdf figures here
+FIG_OJBS = $(FIG_PDFS)
Theora_I_spec.pdf : spec.pdf
$(MV) $< $@
@@ -32,7 +31,7 @@
spec.aux : spec.tex
#Long tables require the .aux file to start from scratch
- -rm spec.aux
+ -$(RM) spec.aux
pdflatex --interaction nonstopmode $<
spec.bbl : spec.aux spec.bib
@@ -43,12 +42,12 @@
figures : $(FIG_OBJS)
-# rule to generate latex versions of the xfig figures
+# rules to generate latex and pdf versions of the xfig figures
%.tex : %.fig
fig2dev -L latex $< $@
%.pdf : %.fig
- fig2dev -L pdf $< $@
+ fig2dev -L pdf -p 0 $< $@
.PHONY: clean distclean maintainer-clean
@@ -56,6 +55,7 @@
clean:
-$(RM) $(FIG_TEXS)
-$(RM) $(FIG_AUXS)
+ -$(RM) $(FIG_PDFS)
-$(RM) vp3huff
-$(RM) vp3huff.tex
-$(RM) vp3huff.aux
Modified: branches/theora-mmx/doc/spec/spec.tex
===================================================================
--- branches/theora-mmx/doc/spec/spec.tex 2004-12-15 10:38:21 UTC (rev 8409)
+++ branches/theora-mmx/doc/spec/spec.tex 2004-12-15 10:44:55 UTC (rev 8410)
@@ -491,7 +491,7 @@
\begin{figure}[htbp]
\begin{center}
-\include{pic-frame}
+\includegraphics{pic-frame}
\end{center}
\caption{Location of frame and picture regions}
\label{fig:pic-frame}
@@ -512,7 +512,7 @@
\begin{figure}[htbp]
\begin{center}
-\include{superblock}
+\includegraphics{superblock}
\end{center}
\caption{Subdivision of a frame into blocks and super blocks}
\label{fig:superblock}
@@ -526,7 +526,7 @@
\begin{figure}[htbp]
\begin{center}
-\include{raster-block}
+\includegraphics{raster-block}
\end{center}
\caption{Raster ordering of $n\times m$ blocks}
\label{fig:raster-block}
@@ -544,7 +544,7 @@
\begin{figure}[htbp]
\begin{center}
-\include{hilbert-block}
+\includegraphics{hilbert-block}
\end{center}
\caption{Hilbert curve ordering of blocks within a super block}
\label{fig:hilbert-block}
@@ -624,7 +624,7 @@
\begin{figure}[htbp]
\begin{center}
- \include{macroblock}
+ \includegraphics{macroblock}
\end{center}
\caption{Subdivision of a frame into macro blocks}
\label{fig:macroblock}
@@ -644,7 +644,7 @@
\begin{figure}[htbp]
\begin{center}
-\include{hilbert-mb}
+\includegraphics{hilbert-mb}
\end{center}
\caption{Hilbert curve ordering of macro blocks within a super block}
\label{fig:hilbert-mb}
@@ -683,7 +683,7 @@
\begin{figure}[htbp]
\begin{center}
-\include{reference-frames}
+\includegraphics{reference-frames}
\end{center}
\caption{Example of reference frames for an inter frame}
\label{fig:reference-frames}
@@ -1463,7 +1463,7 @@
\begin{figure}[htbp]
\begin{center}
-\include{pixel444}
+\includegraphics{pixel444}
\end{center}
\caption{Pixels encoded 4:4:4}
\label{fig:pixel444}
@@ -1499,7 +1499,7 @@
\begin{figure}[htbp]
\begin{center}
-\include{pixel422}
+\includegraphics{pixel422}
\end{center}
\caption{Pixels encoded 4:2:2}
\label{fig:pixel422}
@@ -1540,7 +1540,7 @@
\begin{figure}[htbp]
\begin{center}
-\include{pixel420}
+\includegraphics{pixel420}
\end{center}
\caption{Pixels encoded 4:2:0}
\label{fig:pixel420}
@@ -1613,34 +1613,37 @@
\begin{figure}[htbp]
\begin{center}
-\include{pic_even}
+\includegraphics[width=\textwidth]{pic_even}
\end{center}
-\caption{Pixel correspondance between color planes with even picture offset and
- even picture size}
+\caption{Pixel correspondence between color planes with even picture
+ offset and even picture size}
\label{fig:pic_even}
\end{figure}
\begin{figure}[htbp]
\begin{center}
-\include{pic_even_odd}
+\includegraphics[width=\textwidth]{pic_even_odd}
\end{center}
-\caption{Pixel correspondance with even picture offset and odd picture size}
+\caption{Pixel correspondence with even picture offset and
+ odd picture size}
\label{fig:pic_even_odd}
\end{figure}
\begin{figure}[htbp]
\begin{center}
-\include{pic_odd}
+\includegraphics[width=\textwidth]{pic_odd}
\end{center}
-\caption{Pixel correspondance with odd picture offset and odd picture size}
+\caption{Pixel correspondence with odd picture offset and
+ odd picture size}
\label{fig:pic_odd}
\end{figure}
\begin{figure}[htbp]
\begin{center}
-\include{pic_odd_even}
+\includegraphics[width=\textwidth]{pic_odd_even}
\end{center}
-\caption{Pixel correspondance with odd picture offset and even picture size}
+\caption{Pixel correspondence with odd picture offset and
+ even picture size}
\label{fig:pic_odd_even}
\end{figure}
@@ -2727,7 +2730,7 @@
\paragraph{VP3 Compatibility}
The quantization parameters are hardcoded in VP3.
-The values used are given in Appendix~REF.
+The values used are given in Appendix~\ref{app:vp3-quant-params}.
\subsection{Computing a Quantization Matrix}
\label{sub:quant-mat}
@@ -3930,7 +3933,14 @@
own motion vector, and motion vectors for blocks in the chroma planes are
computed from these, using averaging appropriate to the pixel format.
-Only of a few of the macro block coding modes require decoding motion vectors
+For INTER\_MV and INTER\_GOLDEN\_MV modes, a single motion vector is decoded
+ and applied to each block.
+For INTER\_MV\_FOUR macro blocks, a motion vector is decoded for each coded
+ luma block.
+Uncoded luma blocks receive the default $(0,0)$ vector for the purposes of
+ computing the chroma motion vectors.
+
+None of the remaining macro block coding modes require decoding motion vectors
from the stream.
INTRA mode does not use a motion-compensated predictor, and so requires no
motion vector, and INTER\_NOMV and INTER\_GOLDEN\_NOMV modes use the default
@@ -3941,19 +3951,14 @@
The modes INTER\_MV\_LAST and INTER\_MV\_LAST2 use the motion vector from the
last macro block (in coded order) and the second to last macro block,
respectively, that contained a motion vector pointing to the previous frame.
+Thus no explicit motion vector needs to be decoded for these modes.
Macro blocks coded in INTRA mode or one of the GOLDEN modes are not considered
in this process.
+If an insufficient number of macro blocks have been coded in one of the INTER
+ modes, then the $(0,0)$ vector is used instead.
For macro blocks coded in INTER\_MV\_FOUR mode, the vector from the upper-right
luma block is used, even if the upper-right block is not coded.
-Thus no explicit motion vector needs to be decoded for these modes.
-For INTER\_MV and INTER\_GOLDEN\_MV modes, a single motion vector is decoded
- and applied to each block.
-For INTER\_MV\_FOUR macro blocks, a motion vector is decoded for each coded
- luma block.
-Uncoded luma blocks receive the default $(0,0)$ vector for the purposes of
- computing the chroma motion vectors.
-
The motion vectors are decoded from the stream as follows:
\begin{enumerate}
@@ -4537,8 +4542,9 @@
buffer overflows from invalidly formed packets.
\begin{verse}
{\bf Note:} One way to achieve this efficiently is to combine the inverse
- zig-zag mapping (described later in Section~REF) with coefficient decode, and
- use a table look-up to map zig-zag indices greater than 63 to a safe location.
+ zig-zag mapping (described later in Section~\ref{sub:dequant}) with
+ coefficient decode, and use a table look-up to map zig-zag indices greater
+ than 63 to a safe location.
\end{verse}
\begin{enumerate}
@@ -5422,13 +5428,13 @@
\begin{center}
\begin{tabular}{ccccrrrrr}\toprule
\multicolumn{1}{p{25pt}}{\centering$\locvar{P}[0]$ (L)} &
-\multicolumn{1}{p{25pt}}{\centering$\locvar{P}[1]$ (UL)} &
-\multicolumn{1}{p{25pt}}{\centering$\locvar{P}[2]$ (U)} &
-\multicolumn{1}{p{25pt}}{\centering$\locvar{P}[3]$ (R)} &
+\multicolumn{1}{p{25pt}}{\centering$\locvar{P}[1]$ (DL)} &
+\multicolumn{1}{p{25pt}}{\centering$\locvar{P}[2]$ (D)} &
+\multicolumn{1}{p{25pt}}{\centering$\locvar{P}[3]$ (DR)} &
\multicolumn{1}{p{25pt}}{\centering$\locvar{W}[3]$ (L)} &
-\multicolumn{1}{p{25pt}}{\centering$\locvar{W}[1]$ (UL)} &
-\multicolumn{1}{p{25pt}}{\centering$\locvar{W}[2]$ (U)} &
-\multicolumn{1}{p{25pt}}{\centering$\locvar{W}[3]$ (R)} &
+\multicolumn{1}{p{25pt}}{\centering$\locvar{W}[1]$ (DL)} &
+\multicolumn{1}{p{25pt}}{\centering$\locvar{W}[2]$ (D)} &
+\multicolumn{1}{p{25pt}}{\centering$\locvar{W}[3]$ (DR)} &
\locvar{PDIV} \\\midrule
$1$ & $0$ & $0$ & $0$ & $1$ & $0$ & $0$ & $0$ & $1$ \\
$0$ & $1$ & $0$ & $0$ & $0$ & $1$ & $0$ & $0$ & $1$ \\
@@ -6104,7 +6110,7 @@
\begin{figure}[htbp]
\begin{center}
-\includegraphics[height=\textwidth,angle=270]{idct}
+\includegraphics[width=\textwidth]{idct}
\end{center}
\caption{Signal Flow Graph for the 1D Inverse DCT}
\label{fig:idct}
@@ -6430,7 +6436,7 @@
\begin{figure}[htbp]
\begin{center}
-\includegraphics[height=\textwidth,angle=270]{fdct}
+\includegraphics[width=\textwidth]{fdct}
\end{center}
\caption{Signal Flow Graph for the 1D Forward DCT}
\label{fig:fdct}
@@ -7225,13 +7231,13 @@
Assign \locvar{\pli} the index of the color plane block \locvar{\bi} belongs
to.
\item
-Assign \locvar{REC}, \locvar{RPW}, and \locvar{RPH} the values given in
+Assign \locvar{RECP}, \locvar{RPW}, and \locvar{RPH} the values given in
Table~\ref{tab:recp} corresponding to the value of \locvar{\pli}.
\begin{table}[htbp]
\begin{center}
\begin{tabular}{clll}\toprule
-\locvar{\pli} & \locvar{REFP} & \locvar{RPW} & \locvar{RPH} \\\midrule
+\locvar{\pli} & \locvar{RECP} & \locvar{RPW} & \locvar{RPH} \\\midrule
$0$ & \bitvar{RECY} & \bitvar{RPYW} & \bitvar{RPYH} \\
$1$ & \bitvar{RECCB} & \bitvar{RPCW} & \bitvar{RPCH} \\
$2$ & \bitvar{RECCR} & \bitvar{RPCW} & \bitvar{RPCH} \\
@@ -7933,7 +7939,7 @@
implementations of Theora software under other licenses.
\begin{wrapfigure}{l}{0pt}
-\includegraphics{xifish}
+\includegraphics[width=2.5cm]{xifish}
\end{wrapfigure}
These pages are copyright \textcopyright{} 2004 Xiph.org Foundation.
Copied: branches/theora-mmx/doc/spec/xifish.fig (from rev 8409, trunk/theora/doc/spec/xifish.fig)
Deleted: branches/theora-mmx/doc/spec/xifish.pdf
===================================================================
(Binary files differ)
Modified: branches/theora-mmx/examples/encoder_example.c
===================================================================
--- branches/theora-mmx/examples/encoder_example.c 2004-12-15 10:38:21 UTC (rev 8409)
+++ branches/theora-mmx/examples/encoder_example.c 2004-12-15 10:44:55 UTC (rev 8410)
@@ -133,6 +133,7 @@
unsigned char buffer[80];
int ret;
int tmp_video_hzn, tmp_video_hzd, tmp_video_an, tmp_video_ad;
+ int extra_hdr_bytes;
/* open it, look for magic */
@@ -179,6 +180,9 @@
ret=fread(buffer,1,20,test);
if(ret<20)goto riff_err;
+ extra_hdr_bytes = (buffer[0] + (buffer[1] << 8) +
+ (buffer[2] << 16) + (buffer[3] << 24)) - 16;
+
if(memcmp(buffer+4,"\001\000",2)){
fprintf(stderr,"The WAV file %s is in a compressed format; "
"can't read it.\n",f);
@@ -195,6 +199,18 @@
exit(1);
}
+ /* read past extra header bytes */
+ while(extra_hdr_bytes){
+ int read_size = (extra_hdr_bytes > sizeof(buffer)) ?
+ sizeof(buffer) : extra_hdr_bytes;
+ ret = fread(buffer, 1, read_size, test);
+
+ if (ret < read_size)
+ goto riff_err;
+ else
+ extra_hdr_bytes -= read_size;
+ }
+
/* Now, align things to the beginning of the data */
/* Look for 'dataxxxx' */
while(!feof(test)){
Modified: branches/theora-mmx/examples/player_example.c
===================================================================
--- branches/theora-mmx/examples/player_example.c 2004-12-15 10:38:21 UTC (rev 8409)
+++ branches/theora-mmx/examples/player_example.c 2004-12-15 10:44:55 UTC (rev 8410)
@@ -553,7 +553,7 @@
if(theora_p){
theora_decode_init(&td,&ti);
printf("Ogg logical stream %x is Theora %dx%d %.02f fps video\n",
- to.serialno,ti.width,ti.height,
+ (unsigned int)to.serialno,ti.width,ti.height,
(double)ti.fps_numerator/ti.fps_denominator);
if(ti.width!=ti.frame_width || ti.height!=ti.frame_height)
printf(" Frame content is %dx%d with offset (%d,%d).\n",
@@ -569,7 +569,7 @@
vorbis_synthesis_init(&vd,&vi);
vorbis_block_init(&vd,&vb);
fprintf(stderr,"Ogg logical stream %x is Vorbis %d channel %d Hz audio.\n",
- vo.serialno,vi.channels,vi.rate);
+ (unsigned int)vo.serialno,vi.channels,(int)vi.rate);
}else{
/* tear down the partial vorbis setup */
vorbis_info_clear(&vi);
@@ -657,7 +657,7 @@
if(!videobuf_ready || !audiobuf_ready){
/* no data yet for somebody. Grab another page */
- int ret=buffer_data(infile,&oy);
+ int bytes=buffer_data(infile,&oy);
while(ogg_sync_pageout(&oy,&og)>0){
queue_page(&og);
}
Modified: branches/theora-mmx/include/theora/theora.h
===================================================================
--- branches/theora-mmx/include/theora/theora.h 2004-12-15 10:38:21 UTC (rev 8409)
+++ branches/theora-mmx/include/theora/theora.h 2004-12-15 10:44:55 UTC (rev 8410)
@@ -58,16 +58,16 @@
* All samples are 8 bits.
*/
typedef struct {
- int y_width; /* width of the Y' luminance plane */
- int y_height; /* height of the luminance plane */
- int y_stride; /* offset in bytes between successive rows */
+ int y_width; /**< width of the Y' luminance plane */
+ int y_height; /**< height of the luminance plane */
+ int y_stride; /**< offset in bytes between successive rows */
- int uv_width; /* height of the Cb and Cr chroma planes */
- int uv_height; /* width of the chroma planes */
- int uv_stride; /* offset between successive chroma rows */
- unsigned char *y; /* pointer to start of luminance data */
- unsigned char *u; /* pointer to start of Cb data */
- unsigned char *v; /* pointer to start of Cr data */
+ int uv_width; /**< height of the Cb and Cr chroma planes */
+ int uv_height; /**< width of the chroma planes */
+ int uv_stride; /**< offset between successive chroma rows */
+ unsigned char *y; /**< pointer to start of luminance data */
+ unsigned char *u; /**< pointer to start of Cb data */
+ unsigned char *v; /**< pointer to start of Cr data */
} yuv_buffer;
@@ -84,6 +84,21 @@
* Theora bitstream info.
* Contains the basic playback parameters for a stream,
* corresponds to the initial 'info' header packet.
+ *
+ * Encoded theora frames must be a multiple of 16 is size;
+ * this is what the width and height members represent. To
+ * handle other sizes, a crop rectangle is specified in
+ * frame_height and frame_width, offset_x and offset_y. The
+ * offset and size should still be a power of 2 to avoid
+ * chroma sampling shifts.
+ *
+ * Frame rate, in frames per second is stored as a rational
+ * fraction. So is the aspect ratio. Note that this refers
+ * to the aspect ratio of the frame pixels, not of the
+ * overall frame itself.
+ *
+ * see the example code for use of the other parameters and
+ * good default settings for the encoder parameters.
*/
typedef struct {
ogg_uint32_t width;
@@ -98,7 +113,7 @@
ogg_uint32_t aspect_denominator;
theora_colorspace colorspace;
int target_bitrate;
- int quality;
+ int quality; /**< nominal quality setting, 0-63 */
int quick_p; /**< quick encode/decode */
/* decode only */
@@ -160,15 +175,15 @@
} theora_comment;
-#define OC_FAULT -1
-#define OC_EINVAL -10
-#define OC_DISABLED -11
-#define OC_BADHEADER -20
-#define OC_NOTFORMAT -21
-#define OC_VERSION -22
-#define OC_IMPL -23
-#define OC_BADPACKET -24
-#define OC_NEWPACKET -25
+#define OC_FAULT -1 /**< general failure */
+#define OC_EINVAL -10 /**< library encountered invalid internal data */
+#define OC_DISABLED -11 /**< requested action is disabled */
+#define OC_BADHEADER -20 /**< header packet was corrupt/invalid */
+#define OC_NOTFORMAT -21 /**< packet is not a theora packet */
+#define OC_VERSION -22 /**< bitstream version is not handled */
+#define OC_IMPL -23 /**< feature or action not implemented */
+#define OC_BADPACKET -24 /**< packet is corrupt */
+#define OC_NEWPACKET -25 /**< packet is an (ignorable) unhandled extension */
/**
* Retrieve a human-readable string to identify the encoder vendor and version.
@@ -388,12 +403,42 @@
*/
extern void theora_clear(theora_state *t);
+/** Initialize an allocated theora_comment structure */
extern void theora_comment_init(theora_comment *tc);
+/** Add a comment to an initialized theora_comment structure
+ \param comment must be a null-terminated string encoding
+ 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
+ \param tag a null-terminated string containing the tag
+ associated with the comment.
+ \param value the corresponding value as a null-terminated string
+ Neither theora_comment_add() nor theora_comment_add_tag() support
+ comments containing null values, although the bitstream format
+ supports this. To add such comments you will need to manipulate
+ the theora_comment structure directly */
extern void theora_comment_add_tag(theora_comment *tc,
char *tag, char *value);
+/** look up a comment value by 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 and ordered value, so
+ an index is required to retrieve them all.
+ Use theora_comment_query_count() to get the legal range for the
+ count parameter
+ \returns 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
+ \param tc an initialized theora_comment structure
+ \param tag the tag to look up
+ \returns the number on instances of a particular tag.
+ Call this first when querying for a specific tag and then interate
+ over the number of instances with separate calls to
+ theora_comment_query() to retrieve all instances in order. */
extern int theora_comment_query_count(theora_comment *tc, char *tag);
+/** clears an allocated theora_comment struct so that it can be freed. */
extern void theora_comment_clear(theora_comment *tc);
#ifdef __cplusplus
Modified: branches/theora-mmx/libtheora.spec.in
===================================================================
--- branches/theora-mmx/libtheora.spec.in 2004-12-15 10:38:21 UTC (rev 8409)
+++ branches/theora-mmx/libtheora.spec.in 2004-12-15 10:44:55 UTC (rev 8410)
@@ -1,6 +1,6 @@
Name: libtheora
Version: @VERSION@
-Release: 0.xiph.0.3.alpha3
+Release: 0.xiph.0.4.alpha4
Summary: The Theora Video Compression Codec.
Group: System Environment/Libraries
More information about the commits
mailing list