videolan
/
vlc
mirror of https://code.videolan.org/videolan/vlc
1
Fork 0
Code Releases Activity

* Added IDEALX developer documentation into main CVS - PLEASE UPDATE 

REGULARLY ;
* Cleaned up doc/ directory.
This commit is contained in:
Christophe Massiot 2001-07-16 15:54:59 +00:00
parent a707befb58
commit 1a03af9a54
30 changed files with 4593 additions and 657 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
doc/common.tex
View File

@ -1,15 +0,0 @@
%
% common.tex: common definitions for LaTeX files.
% (c)1999 VideoLAN
%
% Included packages
\usepackage{alltt}
% C-related commands
\newcommand{\csymbol}[1]{\texttt{#1}}
% C-related environments
\newenvironment{csource}
{\begin{alltt}}
{\end{alltt}}

15
doc/conventions
View File

@ -1,15 +0,0 @@
- Pas de tabulations dans les sources
- Pas de include dans les headers sauf all.h
- Utiliser systématiquement NULL pour les pointeurs nuls, et non pas 0
- Eviter le if( (a=toto()) != b ), preferer l'ecriture sur 2 lignes, en
particulier pour les malloc(s):
a = toto();
if( a != b )
- A propos des mallocs, plus une remarque qu'une convention: il n'est
spécifié nul part que errno est mis à jour si malloc renvoie NULL.
Préférez donc strerror(ENOMEM) à strerror(errno) !

47
doc/developer/Makefile Normal file
View File

@ -0,0 +1,47 @@
# Extract from the Debian SGML/XML HOWTO by Stéphane Bortzmeyer
MAX_TEX_RECURSION=4
# For Debian :
XML_DECL=/usr/lib/sgml/declaration/xml.decl
HTML_SS=/usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh/html/docbook.dsl
PRINT_SS=/usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh/print/docbook.dsl
# For RedHat :
#XML_DECL=/usr/lib/sgml/stylesheets/nwalsh-modular/dtds/decls/xml.dcl
#HTML_SS=/usr/lib/sgml/stylesheets/nwalsh-modular/html/docbook.dsl
#PRINT_SS=/usr/lib/sgml/stylesheets/nwalsh-modular/print/docbook.dsl
all: manual
JADE=jade
manual: manual.txt manual.ps manual.html
%.tex: %.xml
$(JADE) -t tex -V %section-autolabel% -d $(PRINT_SS) $(XML_DECL) $<
perl -i.bak -pe 's/\000//g' $@ && rm $*.tex.bak
# No it's not a joke
%.html: %.xml
$(JADE) -t sgml -V %section-autolabel% -V nochunks \
-d $(HTML_SS) $(XML_DECL) $< > $@
%.dvi: %.tex
jadetex $<
jadetex $<
jadetex $<
%.ps: %.dvi
dvips -f $< > $@
%.txt: %.xml
$(JADE) -t sgml -V nochunks -d $(HTML_SS) $(XML_DECL) $< > dump.html
lynx -force_html -dump dump.html > $@
-rm -f dump.html
clean:
rm -f manual.txt
rm -f *.html *.aux *.log *.dvi *.ps *.tex
rm -f *.bck *~ .\#* \#*

68
doc/developer/audio_output.xml Normal file
View File

@ -0,0 +1,68 @@
<chapter> <title> The audio output layer </title>
<sect1> <title> Data exchanges between a decoder and the audio output
</title>
<para>
The audio output basically takes audio samples from one or several
FIFOs, mixes and resamples them, and plays them through the audio
chip. Data exchanges are simple and described in <filename>
src/audio_output/audio_output.c.</filename> A decoder needs to open
a channel FIFO with <function> aout_CreateFifo </function>, and
then write the data to the buffer. The buffer is in <parameter>
p_aout_fifo-&gt;buffer + p_aout_fifo-&gt;l_end_frame </parameter>
* <constant> ADEC_FRAME_SIZE</constant>.
</para>
</sect1>
<sect1> <title> How to write an audio output plugin </title>
<para>
[This API is subject to change in the very near future.] Have a look at
<filename> plugins/dsp/aout_dsp.c</filename>. You need to write six
functions :
</para>
<itemizedlist>
<listitem> <para> <type> int </type> <function> aout_Probe </function>
<parameter> ( probedata_t *p_data ) </parameter> :
Returns a score between 0 and 999 to tell whether the plugin
can be used. <parameter> p_data </parameter> is currently
unused.
</para> </listitem>
<listitem> <para> <type> int </type> <function> aout_Open </function>
<parameter> ( aout_thread_t *p_aout ) </parameter> :
Opens the audio device.
</para> </listitem>
<listitem> <para> <type> int </type> <function> aout_SetFormat
</function> <parameter> ( aout_thread_t *p_aout ) </parameter> :
Sets the output format, the number of channels, and the output
rate.
</para> </listitem>
<listitem> <para> <type> long </type> <function> aout_GetBufInfo
</function> <parameter> ( aout_thread_t *p_aout,
long l_buffer_limit ) </parameter> :
Gets the status of the audio buffer.
</para> </listitem>
<listitem> <para> <function> aout_Play </function> <parameter>
( aout_thread_t *p_aout, byte_t *buffer, int i_size )
</parameter> :
Writes the audio output buffer to the audio device.
</para> </listitem>
<listitem> <para> <function> aout_Close </function> <parameter>
( aout_thread_t *p_aout ) </parameter> :
Closes the audio device.
</para> </listitem>
</itemizedlist>
</sect1>
</chapter>

55
doc/developer/debugging.xml Normal file
View File

@ -0,0 +1,55 @@
<appendix> <title> Advanced debugging </title>
<para>
We never debug our code, because we don't put bugs in. Okay, you want
some real stuff. Sam still uses <function> printf() </function> to
find out where it crashes. For real programmers, here is a summary
of what you can do if you have problems.
</para>
<sect1> <title> Where does it crash ? </title>
<para>
The best way to know that is to use gdb. You can start using it with
good chances by configuring with <parameter> --enable-debug </parameter>.
It will add <parameter> -g </parameter> to the compiler <parameter>
CFLAGS</parameter>, and activate some additional safety checks. Just
run <command> gdb vlc</command>, type <command> run myfile.vob</command>,
and wait until it crashes. You can view where it stopped with
<command>bt</command>, and print variables with <command>print
&lt;C-style&gt;</command>.
</para>
<para>
If you run into troubles, you may want to turn the optimizations off.
Optimizations (especially inline functions) may confuse the debugger.
Use <parameter> --disable-optimizations </parameter> in that case.
</para>
</sect1>
<sect1> <title> Other problems </title>
<para>
It may be more complicated than that, for instance unpredictable
behaviour, random bug or performance issue. You have several options
to deal with this. If you experience unpredictable behaviour, I hope
you don't have a heap or stack corruption (eg. writing in an unallocated
space), because they are hard to find. If you are really desperate, have
a look at something like ElectricFence or dmalloc. Under GNU/Linux, an
easy check is to type <command> export MALLOC_CHECK_=2 </command> before
launching vlc (see <command> malloc(3) </command> for more information).
</para>
<para>
VLC offers a "trace-mode". It can create a log file with very accurate dates
and messages of what it does, so it is useful to detect performance
issues or lock-ups. Compile with <parameter> --enable-trace </parameter>
and tune the <parameter> TRACE_* </parameter> flags in <filename>
include/config.h </filename> to enable certain types of messages (log
file writing can take up a lot of time, and will have side effects).
</para>
</sect1>
</appendix>

430
doc/developer/decoders.xml Normal file
View File

@ -0,0 +1,430 @@
<chapter> <title> How to write a decoder </title>
<sect1> <title> What is precisely a decoder in the VLC scheme ? </title>
<para>
The decoder does the mathematical part of the process of playing a
stream. It is separated from the demultiplexers (in the input module),
which manage packets to rebuild a continuous elementary stream, and from
the output thread, which takes samples reconstituted by the decoder
and plays them. Basically, a decoder has no interaction with devices,
it is purely algorithmic.
</para>
<para>
In the next section we will describe how the decoder retrieves the
stream from the input. The output API (how to say "this sample is
decoded and can be played at xx") will be talked about in the next
chapters.
</para>
</sect1>
<sect1> <title> Decoder configuration </title>
<para>
The input thread spawns the appropriate decoders [the relation is
currently hard-wired in <filename>src/input/input_programs.c</filename>].
It then launches <function> *_CreateThread()</function>, with either
an <type>adec_config_t</type> (audio) or an <type> vdec_config_t</type>
(video) structure, described in <filename> include/input_ext-dec.h</filename>.
</para>
<para>
It contains some parameters relative to the output thread, which will
be described in the following chapters, and a generic <type>
decoder_config_t</type>, which gives the decoder the ES ID and type, and
pointers to a <type> stream_control_t </type> structure (gives
information on the play status), a <type> decoder_fifo_t </type>
and <parameter> pf_init_bit_stream</parameter>, which will be
described in the next two sections.
</para>
</sect1>
<sect1> <title> Packet structures </title>
<para>
The input module provides an advanced API for delivering stream data
to the decoders. First let's have a look at the packet structures.
They are defined in <filename> include/input_ext-dec.h</filename>.
</para>
<para>
<type>data_packet_t</type> contains a pointer to the physical location
of data. Decoders should only start to read them at <parameter>
p_payload_start </parameter> until <parameter> p_payload_end</parameter>.
Thereafter, it will switch to the next packet, <parameter> p_next
</parameter> if it is not <constant>NULL</constant>. If the
<parameter> b_discard_payload
</parameter> flag is up, the content of the packet is messed up and it
should be discarded.
</para>
<para>
<type>data_packet_t</type> are contained into <type>pes_packet_t</type>.
<type>pes_packet_t</type> features a chained list
(<parameter>p_first</parameter>) of <type>data_packet_t
</type> representing (in the MPEG paradigm) a complete PES packet. For
PS streams, a <type> pes_packet_t </type> usually only contains one
<type>data_packet_t</type>. In TS streams though, one PES can be split
among dozens of TS packets. A PES packet has PTS dates (see your
MPEG specification for more information) and the current pace of reading
that should be applied for interpolating dates (<parameter>i_rate</parameter>).
<parameter> b_data_alignment </parameter> (if available in the system
layer) indicates if the packet is a random access point, and <parameter>
b_discontinuity </parameter> tells whether previous packets have been
dropped.
</para>
<mediaobject>
<imageobject>
<imagedata fileref="ps.eps" format="EPS" scalefit="1" scale="95" />
</imageobject>
<imageobject>
<imagedata fileref="ps.gif" format="GIF" />
</imageobject>
<textobject>
<phrase> A PES packet in a Program Stream </phrase>
</textobject>
<caption>
<para> In a Program Stream, a PES packet features only one
data packet, whose buffer contains the PS header, the PES
header, and the data payload.
</para>
</caption>
</mediaobject>
<mediaobject>
<imageobject>
<imagedata fileref="ts.eps" format="EPS" scalefit="1" scale="95" />
</imageobject>
<imageobject>
<imagedata fileref="ts.gif" format="GIF" />
</imageobject>
<textobject>
<phrase> A PES packet in a Transport Stream </phrase>
</textobject>
<caption>
<para> In a Transport Stream, a PES packet can feature an
unlimited number of data packets (three on the figure)
whose buffers contains the PS header, the PES
header, and the data payload.
</para>
</caption>
</mediaobject>
<para>
The structure shared by both the input and the decoder is <type>
decoder_fifo_t</type>. It features a rotative FIFO of PES packets to
be decoded. The input provides macros to manipulate it : <function>
DECODER_FIFO_ISEMPTY, DECODER_FIFO_ISFULL, DECODER_FIFO_START,
DECODER_FIFO_INCSTART, DECODER_FIFO_END, DECODER_FIFO_INCEND</function>.
Please remember to take <parameter>p_decoder_fifo-&gt;data_lock
</parameter> before any operation on the FIFO.
</para>
<para>
The next packet to be decoded is DECODER_FIFO_START( *p_decoder_fifo ).
When it is finished, you need to call <function>
p_decoder_fifo-&gt;pf_delete_pes( p_decoder_fifo-&gt;p_packets_mgt,
DECODER_FIFO_START( *p_decoder_fifo ) ) </function> and then
<function> DECODER_FIFO_INCSTART( *p_decoder_fifo )</function> to
return the PES to the <link linkend="input_buff">buffer manager</link>.
</para>
<para>
If the FIFO is empty (<function>DECODER_FIFO_ISEMPTY</function>), you
can block until a new packet is received with a cond signal :
<function> vlc_cond_wait( &amp;p_fifo-&gt;data_wait,
&amp;p_fifo-&gt;data_lock )</function>. You have to hold the lock before
entering this function. If the file is over or the user quits,
<parameter>p_fifo-&gt;b_die</parameter> will be set to 1. It indicates
that you must free all your data structures and call <function>
vlc_thread_exit() </function> as soon as possible.
</para>
</sect1>
<sect1> <title> The bit stream (input module) </title>
<para>
This classical way of reading packets is not convenient, though, since
the elementary stream can be split up arbitrarily. The input module
provides primitives which make reading a bit stream much easier.
Whether you use it or not is at your option, though if you use it you
shouldn't access the packet buffer any longer.
</para>
<para>
The bit stream allows you to just call <function> GetBits()</function>,
and this functions will transparently read the packet buffers, change
data packets and pes packets when necessary, without any intervention
from you. So it is much more convenient for you to read a continuous
Elementary Stream, you don't have to deal with packet boundaries
and the FIFO, the bit stream will do it for you.
</para>
<para>
The central idea is to introduce a buffer of 32 bits [normally
<type> WORD_TYPE</type>, but 64-bit version doesn't work yet], <type>
bit_fifo_t</type>. It contains the word buffer and the number of
significant bits (higher part). The input module provides five
inline functions to manage it :
</para>
<itemizedlist>
<listitem> <para> <type> u32 </type> <function> GetBits </function>
<parameter>( bit_stream_t * p_bit_stream, unsigned int i_bits )
</parameter> :
Returns the next <parameter> i_bits </parameter> bits from the
bit buffer. If there are not enough bits, it fetches the following
word from the <type>decoder_fifo_t</type>. This function is only
guaranteed to work with up to 24 bits. For the moment it works until
31 bits, but it is a side effect. We were obliged to write a different
function, <function>GetBits32</function>, for 32-bit reading,
because of the &lt;&lt; operator.
</para> </listitem>
<listitem> <para> <function> RemoveBits </function> <parameter>
( bit_stream_t * p_bit_stream, unsigned int i_bits ) </parameter> :
The same as <function> GetBits()</function>, except that the bits
aren't returned (we spare a few CPU cycles). It has the same
limitations, and we also wrote <function> RemoveBits32</function>.
</para> </listitem>
<listitem> <para> <type> u32 </type> <function> ShowBits </function>
<parameter>( bit_stream_t * p_bit_stream, unsigned int i_bits )
</parameter> :
The same as <function> GetBits()</function>, except that the bits
don't get flushed after reading, so that you need to call
<function> RemoveBits() </function> by hand afterwards. Beware,
this function won't work above 24 bits, except if you're aligned
on a byte boundary (see next function).
</para> </listitem>
<listitem> <para> <function> RealignBits </function> <parameter>
( bit_stream_t * p_bit_stream ) </parameter> :
Drops the n higher bits (n &lt; 8), so that the first bit of
the buffer be aligned an a byte boundary. It is useful when
looking for an aligned startcode (MPEG for instance).
</para> </listitem>
<listitem> <para> <function> GetChunk </function> <parameter>
( bit_stream_t * p_bit_stream, byte_t * p_buffer, size_t i_buf_len )
</parameter> :
It is an analog of <function> memcpy()</function>, but taking
a bit stream as first argument. <parameter> p_buffer </parameter>
must be allocated and at least <parameter> i_buf_len </parameter>
long. It is useful to copy data you want to keep track of.
</para> </listitem>
</itemizedlist>
<para>
All these functions recreate a continuous elementary stream paradigm.
When the bit buffer is empty, they take the following word in the
current packet. When the packet is empty, it switches to the next
<type>data_packet_t</type>, or if unapplicable to the next <type>
pes_packet_t</type> (see <function>
p_bit_stream-&gt;pf_next_data_packet</function>). All this is
completely transparent.
</para>
<note> <title> Packet changes and alignment issues </title>
<para>
We have to study the conjunction of two problems. First, a
<type> data_packet_t </type> can have an even number of bytes,
for instance 177, so the last word will be truncated. Second,
many CPU (sparc, alpha...) can only read words aligned on a
word boundary (that is, 32 bits for a 32-bit word). So packet
changes are a lot more complicated than you can imagine, because
we have to read truncated words and get aligned.
</para>
<para>
For instance <function> GetBits() </function> will call
<function> UnalignedGetBits() </function> from <filename>
src/input/input_ext-dec.c</filename>. Basically it will
read byte after byte until the stream gets realigned. <function>
UnalignedShowBits() </function> is a bit more complicated
and may require a temporary packet
(<parameter>p_bit_stream-&gt;showbits_data</parameter>).
</para> </note>
<para>
To use the bit stream, you have to call <parameter>
p_decoder_config-&gt;pf_init_bit_stream( bit_stream_t * p_bit_stream,
decoder_fifo_t * p_fifo )</parameter> to set up all variables. You will
probably need to regularly fetch specific information from the packet,
for instance the PTS. If <parameter> p_bit_stream-&gt;pf_bit_stream_callback
</parameter> is not <constant> NULL</constant>, it will be called
on a packet change. See <filename> src/video_parser/video_parser.c
</filename> for an example. The second argument
indicates whether it is just a new <type>data_packet_t</type> or
also a new <type>pes_packet_t</type>. You can store your own structure in
<parameter> p_bit_stream-&gt;p_callback_arg</parameter>.
</para>
<warning> <para>
When you call <function>pf_init_bit_stream</function>, the
<function>pf_bitstream_callback</function> is not defined yet,
but it jumps to the first packet, though. You will probably
want to call your bitstream callback by hand just after
<function> pf_init_bit_stream</function>.
</para> </warning>
</sect1>
<sect1> <title> Built-in decoders </title>
<para>
VLC already features an MPEG layer 1 and 2 audio decoder, an MPEG MP@ML
video decoder, an AC3 decoder (borrowed from LiViD), a DVD SPU decoder,
and an LPCM decoder [not functional yet]. You can write your own
decoder, just mimic the video parser.
</para>
<note> <title> Limitations in the current design </title>
<para>
Currently, decoders are not "plug-ins", that is they are not dynamically
loadable. The way the input chooses a decoder is also not final - it
is hard-wired in <filename> src/input/input_programs.c</filename>.
</para> </note>
<para>
The MPEG audio decoder is native, but doesn't support layer 3 decoding
[too much trouble], the AC3 decoder is a port from Aaron
Holtzman's libac3 (the original libac3 isn't reentrant), and the
SPU decoder is native. You may want to have a look at <function>
BitstreamCallback </function> in the AC3 decoder. In that case we have
to jump the first 3 bytes of a PES packet, which are not part of the
elementary stream. The video decoder is a bit special and will
be described in the following section.
</para>
</sect1>
<sect1> <title> The MPEG video decoder </title>
<para>
VideoLAN Client provides an MPEG-1, and an MPEG-2 Main Profile @
Main Level decoder. It has been natively written for VLC, and is quite
mature. Its status is a bit special, since it is splitted between two
modules : video parser and video decoder [this is subject to change].
The initial goal is to separate bit stream parsing functions from
highly parallelizable mathematical algorithms. In theory, there can be
one video parser thread (and only one, otherwise we would have race
conditions reading the bit stream), along with several video decoder
threads, which do IDCT and motion compensation on several blocks
at once [practically,
multi-threaded mode hasn't been tested for a while, still needs some
work, and was actually slower than mono-threaded mode ; the
multi-threaded mode won't be documented for the moment].
</para>
<para>
It doesn't (and won't) support MPEG-4 or DivX decoding. It is not an
encoder. It should support the whole MPEG-2 MP@ML specification, though
some features are still left untested, like Differential Motion Vectors.
Please bear in mind before complaining that the input elementary stream
must be valid (for instance this is not the case when you directly read
a DVD multi-angle .vob file).
</para>
<para>
The most interesting file is <filename> vpar_synchro.c</filename>, it is
really worth the shot. It explains the whole frame dropping algorithm.
In a nutshell, if the machine is powerful enough, we decoder all IPBs,
otherwise we decode all IPs and Bs if we have enough time (this is
based on on-the-fly decoding time statistics). Another interesting file
is <filename>vpar_blocks.c</filename>, which describes all block
(including coefficients and motion vectors) parsing algorithms. Look
at the bottom of the file, we indeed generate one optimized function
for every common picture type, and one slow generic function. There
are also several levels of optimization (which makes compilation slower
but certain types of files faster decoded) called <constant>
VPAR_OPTIM_LEVEL</constant>, level 0 means no optimization, level 1
means optimizations for MPEG-1 and MPEG-2 frame pictures, level 2
means optimizations for MPEG-1 and MPEG-2 field and frame pictures.
</para>
<sect2> <title> Motion compensation plug-ins </title>
<para>
Motion compensation (i.e. copy of regions from a reference picture) is
very platform-dependant (for instance with MMX or AltiVec versions), so
we moved it to the <filename> plugins/motion </filename> directory. It
is more convenient for the video decoder, and resulting plug-ins may
be used by other video decoders (MPEG-4 ?). A motion plugin must
define 6 functions, coming straight from the specification :
<function> vdec_MotionFieldField420, vdec_MotionField16x8420,
vdec_MotionFieldDMV420, vdec_MotionFrameFrame420, vdec_MotionFrameField420,
vdec_MotionFrameDMV420</function>. The equivalent 4:2:2 and 4:4:4
functions are unused, since these formats are forbidden in MP@ML (it
would only take longer compilation time).
</para>
<para>
Look at the C version of the algorithms if you want more information.
Note also that the DMV algorithm is untested and is probably buggy.
</para>
</sect2>
<sect2> <title> IDCT plug-ins </title>
<para>
Just like motion compensation, IDCT is platform-specific. So we moved it
to <filename> plugins/idct</filename>. You need to define four methods :
</para>
<itemizedlist>
<listitem> <para> <function> vdec_IDCT </function> <parameter>
( vdec_thread_t * p_vdec, dctelem_t * p_block, int ) </parameter> :
Does the complete 2-D IDCT. 64 coefficients are in <parameter>
p_block</parameter>.
</para> </listitem>
<listitem> <para> <function> vdec_SparseIDCT </function>
<parameter> ( vdec_thread_t * p_vdec, dctelem_t * p_block,
int i_sparse_pos ) </parameter> :
Does an IDCT on a block with only one non-NULL coefficient
(designated by <parameter> i_sparse_pos</parameter>). You can
use the function defined in <filename> plugins/idct/idct_common.c
</filename> which precalculates these 64 matrices at
initialization time.
</para> </listitem>
<listitem> <para> <function> vdec_InitIDCT </function>
<parameter> ( vdec_thread_t * p_vdec ) </parameter> :
Does the initialization stuff needed by <function>
vdec_SparseIDCT</function>.
</para> </listitem>
<listitem> <para> <function> vdec_NormScan </function>
<parameter> ( u8 ppi_scan[2][64] ) </parameter> :
Normally, this function does nothing. For minor optimizations,
some IDCT (MMX) need to invert certain coefficients in the
MPEG scan matrices (see ISO/IEC 13818-2).
</para> </listitem>
</itemizedlist>
<para>
Currently we have implemented optimized versions for : MMX, MMXEXT, and
AltiVec [doesn't work]. We have two plain C versions, the normal
(supposedly optimized) Berkeley version (<filename>idct.c</filename>),
and the simple 1-D separation IDCT from the ISO reference decoder
(<filename>idctclassic.c</filename>).
</para>
<para>
[In the future, the IDCT plug-in will include <function> vdec_AddBlock
</function> and <function> vdec_CopyBlock </function>, which are
often architecture-specific.]
</para>
</sect2>
</sect1>
</chapter>

436
doc/developer/gfdl.xml Normal file
View File

@ -0,0 +1,436 @@
<appendix id="gfdl">
<title>GNU Free Documentation License</title>
<!-- - GNU Project - Free Software Foundation (FSF) -->
<!-- LINK REV="made" HREF="mailto:webmasters@gnu.org" -->
<!-- sect1>
<title>GNU Free Documentation License</title -->
<para>Version 1.1, March 2000</para>
<blockquote>
<para>Copyright (C) 2000 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.</para>
</blockquote>
<sect1 label="0">
<title>PREAMBLE</title>
<para>The purpose of this License is to make a manual, textbook,
or other written document "free" in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or
noncommercially. Secondarily, this License preserves for the
author and publisher a way to get credit for their work, while not
being considered responsible for modifications made by
others.</para>
<para>This License is a kind of "copyleft", which means that
derivative works of the document must themselves be free in the
same sense. It complements the GNU General Public License, which
is a copyleft license designed for free software.</para>
<para>We have designed this License in order to use it for manuals
for free software, because free software needs free documentation:
a free program should come with manuals providing the same
freedoms that the software does. But this License is not limited
to software manuals; it can be used for any textual work,
regardless of subject matter or whether it is published as a
printed book. We recommend this License principally for works
whose purpose is instruction or reference.</para>
</sect1>
<sect1 label="1">
<title>APPLICABILITY AND DEFINITIONS</title>
<para>This License applies to any manual or other work that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License. The "Document",
below, refers to any such manual or work. Any member of the
public is a licensee, and is addressed as "you".</para>
<para>A "Modified Version" of the Document means any work
containing the Document or a portion of it, either copied
verbatim, or with modifications and/or translated into another
language.</para>
<para>A "Secondary Section" is a named appendix or a front-matter
section of the Document that deals exclusively with the
relationship of the publishers or authors of the Document to the
Document's overall subject (or to related matters) and contains
nothing that could fall directly within that overall subject.
(For example, if the Document is in part a textbook of
mathematics, a Secondary Section may not explain any mathematics.)
The relationship could be a matter of historical connection with
the subject or with related matters, or of legal, commercial,
philosophical, ethical or political position regarding
them.</para>
<para>The "Invariant Sections" are certain Secondary Sections
whose titles are designated, as being those of Invariant Sections,
in the notice that says that the Document is released under this
License.</para>
<para>The "Cover Texts" are certain short passages of text that
are listed, as Front-Cover Texts or Back-Cover Texts, in the
notice that says that the Document is released under this
License.</para>
<para>A "Transparent" copy of the Document means a
machine-readable copy, represented in a format whose specification
is available to the general public, whose contents can be viewed
and edited directly and straightforwardly with generic text
editors or (for images composed of pixels) generic paint programs
or (for drawings) some widely available drawing editor, and that
is suitable for input to text formatters or for automatic
translation to a variety of formats suitable for input to text
formatters. A copy made in an otherwise Transparent file format
whose markup has been designed to thwart or discourage subsequent
modification by readers is not Transparent. A copy that is not
"Transparent" is called "Opaque".</para>
<para>Examples of suitable formats for Transparent copies include
plain ASCII without markup, Texinfo input format, LaTeX input
format, SGML or XML using a publicly available DTD, and
standard-conforming simple HTML designed for human modification.
Opaque formats include PostScript, PDF, proprietary formats that
can be read and edited only by proprietary word processors, SGML
or XML for which the DTD and/or processing tools are not generally
available, and the machine-generated HTML produced by some word
processors for output purposes only.</para>
<para>The "Title Page" means, for a printed book, the title page
itself, plus such following pages as are needed to hold, legibly,
the material this License requires to appear in the title page.
For works in formats which do not have any title page as such,
"Title Page" means the text near the most prominent appearance of
the work's title, preceding the beginning of the body of the
text.</para>
</sect1>
<sect1 label="2">
<title>VERBATIM COPYING</title>
<para>You may copy and distribute the Document in any medium,
either commercially or noncommercially, provided that this
License, the copyright notices, and the license notice saying this
License applies to the Document are reproduced in all copies, and
that you add no other conditions whatsoever to those of this
License. You may not use technical measures to obstruct or
control the reading or further copying of the copies you make or
distribute. However, you may accept compensation in exchange for
copies. If you distribute a large enough number of copies you
must also follow the conditions in section 3.</para>
<para>You may also lend copies, under the same conditions stated
above, and you may publicly display copies.</para>
</sect1>
<sect1 label="3">
<title>COPYING IN QUANTITY</title>
<para>If you publish printed copies of the Document numbering more
than 100, and the Document's license notice requires Cover Texts,
you must enclose the copies in covers that carry, clearly and
legibly, all these Cover Texts: Front-Cover Texts on the front
cover, and Back-Cover Texts on the back cover. Both covers must
also clearly and legibly identify you as the publisher of these
copies. The front cover must present the full title with all
words of the title equally prominent and visible. You may add
other material on the covers in addition. Copying with changes
limited to the covers, as long as they preserve the title of the
Document and satisfy these conditions, can be treated as verbatim
copying in other respects.</para>
<para>If the required texts for either cover are too voluminous to
fit legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto
adjacent pages.</para>
<para>If you publish or distribute Opaque copies of the Document
numbering more than 100, you must either include a
machine-readable Transparent copy along with each Opaque copy, or
state in or with each Opaque copy a publicly-accessible
computer-network location containing a complete Transparent copy
of the Document, free of added material, which the general
network-using public has access to download anonymously at no
charge using public-standard network protocols. If you use the
latter option, you must take reasonably prudent steps, when you
begin distribution of Opaque copies in quantity, to ensure that
this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you
distribute an Opaque copy (directly or through your agents or
retailers) of that edition to the public.</para>
<para>It is requested, but not required, that you contact the
authors of the Document well before redistributing any large
number of copies, to give them a chance to provide you with an
updated version of the Document.</para>
</sect1>
<sect1 label="4">
<title>MODIFICATIONS</title>
<para>You may copy and distribute a Modified Version of the
Document under the conditions of sections 2 and 3 above, provided
that you release the Modified Version under precisely this
License, with the Modified Version filling the role of the
Document, thus licensing distribution and modification of the
Modified Version to whoever possesses a copy of it. In addition,
you must do these things in the Modified Version:</para>
<orderedlist numeration="upperalpha">
<listitem><para>Use in the Title Page
(and on the covers, if any) a title distinct from that of the
Document, and from those of previous versions (which should, if
there were any, be listed in the History section of the
Document). You may use the same title as a previous version if
the original publisher of that version gives permission.</para>
</listitem>
<listitem><para>List on the Title Page,
as authors, one or more persons or entities responsible for
authorship of the modifications in the Modified Version,
together with at least five of the principal authors of the
Document (all of its principal authors, if it has less than
five).</para>
</listitem>
<listitem><para>State on the Title page
the name of the publisher of the Modified Version, as the
publisher.</para>
</listitem>
<listitem><para>Preserve all the
copyright notices of the Document.</para>
</listitem>
<listitem><para>Add an appropriate
copyright notice for your modifications adjacent to the other
copyright notices.</para>
</listitem>
<listitem><para>Include, immediately
after the copyright notices, a license notice giving the public
permission to use the Modified Version under the terms of this
License, in the form shown in the Addendum below.</para>
</listitem>
<listitem><para>Preserve in that license
notice the full lists of Invariant Sections and required Cover
Texts given in the Document's license notice.</para>
</listitem>
<listitem><para>Include an unaltered
copy of this License.</para>
</listitem>
<listitem><para>Preserve the section
entitled "History", and its title, and add to it an item stating
at least the title, year, new authors, and publisher of the
Modified Version as given on the Title Page. If there is no
section entitled "History" in the Document, create one stating
the title, year, authors, and publisher of the Document as given
on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.</para>
</listitem>
<listitem><para>Preserve the network
location, if any, given in the Document for public access to a
Transparent copy of the Document, and likewise the network
locations given in the Document for previous versions it was
based on. These may be placed in the "History" section. You
may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.</para>
</listitem>
<listitem><para>In any section entitled
"Acknowledgements" or "Dedications", preserve the section's
title, and preserve in the section all the substance and tone of
each of the contributor acknowledgements and/or dedications
given therein.</para>
</listitem>
<listitem><para>Preserve all the
Invariant Sections of the Document, unaltered in their text and
in their titles. Section numbers or the equivalent are not
considered part of the section titles.</para>
</listitem>
<listitem><para>Delete any section
entitled "Endorsements". Such a section may not be included in
the Modified Version.</para>
</listitem>
<listitem><para>Do not retitle any
existing section as "Endorsements" or to conflict in title with
any Invariant Section.</para>
</listitem>
</orderedlist>
<para>If the Modified Version includes new front-matter sections
or appendices that qualify as Secondary Sections and contain no
material copied from the Document, you may at your option
designate some or all of these sections as invariant. To do this,
add their titles to the list of Invariant Sections in the Modified
Version's license notice. These titles must be distinct from any
other section titles.</para>
<para>You may add a section entitled "Endorsements", provided it
contains nothing but endorsements of your Modified Version by
various parties--for example, statements of peer review or that
the text has been approved by an organization as the authoritative
definition of a standard.</para>
<para>You may add a passage of up to five words as a Front-Cover
Text, and a passage of up to 25 words as a Back-Cover Text, to the
end of the list of Cover Texts in the Modified Version. Only one
passage of Front-Cover Text and one of Back-Cover Text may be
added by (or through arrangements made by) any one entity. If the
Document already includes a cover text for the same cover,
previously added by you or by arrangement made by the same entity
you are acting on behalf of, you may not add another; but you may
replace the old one, on explicit permission from the previous
publisher that added the old one.</para>
<para>The author(s) and publisher(s) of the Document do not by
this License give permission to use their names for publicity for
or to assert or imply endorsement of any Modified Version.</para>
</sect1>
<sect1 label="5">
<title>COMBINING DOCUMENTS</title>
<para>You may combine the Document with other documents released
under this License, under the terms defined in section 4 above for
modified versions, provided that you include in the combination
all of the Invariant Sections of all of the original documents,
unmodified, and list them all as Invariant Sections of your
combined work in its license notice.</para>
<para>The combined work need only contain one copy of this
License, and multiple identical Invariant Sections may be replaced
with a single copy. If there are multiple Invariant Sections with
the same name but different contents, make the title of each such
section unique by adding at the end of it, in parentheses, the
name of the original author or publisher of that section if known,
or else a unique number. Make the same adjustment to the section
titles in the list of Invariant Sections in the license notice of
the combined work.</para>
<para>In the combination, you must combine any sections entitled
"History" in the various original documents, forming one section
entitled "History"; likewise combine any sections entitled
"Acknowledgements", and any sections entitled "Dedications". You
must delete all sections entitled "Endorsements."</para>
</sect1>
<sect1 label="6">
<title>COLLECTIONS OF DOCUMENTS</title>
<para>You may make a collection consisting of the Document and
other documents released under this License, and replace the
individual copies of this License in the various documents with a
single copy that is included in the collection, provided that you
follow the rules of this License for verbatim copying of each of
the documents in all other respects.</para>
<para>You may extract a single document from such a collection,
and distribute it individually under this License, provided you
insert a copy of this License into the extracted document, and
follow this License in all other respects regarding verbatim
copying of that document.</para>
</sect1>
<sect1 label="7">
<title>AGGREGATION WITH INDEPENDENT WORKS</title>
<para>A compilation of the Document or its derivatives with other
separate and independent documents or works, in or on a volume of
a storage or distribution medium, does not as a whole count as a
Modified Version of the Document, provided no compilation
copyright is claimed for the compilation. Such a compilation is
called an "aggregate", and this License does not apply to the
other self-contained works thus compiled with the Document, on
account of their being thus compiled, if they are not themselves
derivative works of the Document.</para>
<para>If the Cover Text requirement of section 3 is applicable to
these copies of the Document, then if the Document is less than
one quarter of the entire aggregate, the Document's Cover Texts
may be placed on covers that surround only the Document within the
aggregate. Otherwise they must appear on covers around the whole
aggregate.</para>
</sect1>
<sect1 label="8">
<title>TRANSLATION</title>
<para>Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section
4. Replacing Invariant Sections with translations requires
special permission from their copyright holders, but you may
include translations of some or all Invariant Sections in addition
to the original versions of these Invariant Sections. You may
include a translation of this License provided that you also
include the original English version of this License. In case of
a disagreement between the translation and the original English
version of this License, the original English version will
prevail.</para>
</sect1>
<sect1 label="9">
<title>TERMINATION</title>
<para>You may not copy, modify, sublicense, or distribute the
Document except as expressly provided for under this License. Any
other attempt to copy, modify, sublicense or distribute the
Document is void, and will automatically terminate your rights
under this License. However, parties who have received copies, or
rights, from you under this License will not have their licenses
terminated so long as such parties remain in full
compliance.</para>
</sect1>
<sect1 label="10">
<title>FUTURE REVISIONS OF THIS LICENSE</title>
<para>The Free Software Foundation may publish new, revised
versions of the GNU Free Documentation License from time to time.
Such new versions will be similar in spirit to the present
version, but may differ in detail to address new problems or
concerns. See <ulink
url="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</ulink>.</para>
<para>Each version of the License is given a distinguishing
version number. If the Document specifies that a particular
numbered version of this License "or any later version" applies to
it, you have the option of following the terms and conditions
either of that specified version or of any later version that has
been published (not as a draft) by the Free Software Foundation.
If the Document does not specify a version number of this License,
you may choose any version ever published (not as a draft) by the
Free Software Foundation.</para>
</sect1>
</appendix>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-parent-document: ("referenz.sgml" "appendix")
sgml-exposed-tags:nil
sgml-local-ecat-files:nil
sgml-local-catalogs: CATALOG
sgml-validate-command: "nsgmls -s referenz.sgml"
ispell-skip-sgml: t
End:
-->

205
doc/developer/glossary.xml Normal file
View File

@ -0,0 +1,205 @@
<glossary>
<warning> <para>
Please note that this book is in no way a reference documentation
on how DVDs work. Its only purpose is to describe the API
available for programmers in VideoLAN Client. It is assumed that
you have basic knowledge of what MPEG is. The following paragraph
is just here as a reminder :
</para> </warning>
<glossentry>
<glossterm> <acronym> AC3 </acronym> :
Digital Audio Compression Standard </glossterm>
<glossdef> <para> Specification for coding audio data, used in DVD.
The documentation is
<ulink url="http://www.linuxvideo.org/devel/library/ac3-standard_a_52.pdf">
freely available </ulink>.
</para> </glossdef>
</glossentry>
<glossentry>
<glossterm> <acronym> B </acronym> (bi-directional) picture </glossterm>
<glossdef> <para> Picture decoded from its own data, <emphasis>
and </emphasis> from the data of the previous and next (that
means <emphasis>in the future</emphasis>) reference
pictures (I or P pictures). It is the most compressed picture
format, but it is less fault-tolerant.
</para> </glossdef>
</glossentry>
<glossentry>
<glossterm> <acronym> DVD </acronym> :
Digital Versatile Disc </glossterm>
<glossdef> <para> Disc hardware format, using the UDF file system,
an extension of the ISO 9660 file system format and a video format
which is an extension of the MPEG-2 specification.
It basically uses MPEG-2 PS files, with subtitles and sound
tracks encoded as private data and fed into non-MPEG decoders,
along with .ifo files describing the contents of the DVD. DVD
specifications are very hard to get, and it takes some
time to reverse-engineer it. Sometimes DVD are zoned and
scrambled, so we use a brute-force algorithm to find the key.
</para> </glossdef>
</glossentry>
<glossentry>
<glossterm> <acronym> ES </acronym> : Elementary Stream </glossterm>
<glossdef> <para> Continuous stream of data fed into a decoder,
without any multiplexing layer. ES streams can be MPEG video
MPEG audio, AC3 audio, LPCM audio, SPU subpictures...
</para> </glossdef>
</glossentry>
<glossentry>
<glossterm> Field picture </glossterm>
<glossdef> <para> Picture split in two fields, even and odd, like
television does. DVDs coming from TV shows typically use field
pictures.
</para> </glossdef>
</glossentry>
<glossentry>
<glossterm> Frame picture </glossterm>
<glossdef> <para> Picture without even/odd discontinuities, unlike
field pictures. DVDs coming from movies typically use frame
pictures.
</para> </glossdef>
</glossentry>
<glossentry>
<glossterm> <acronym>I</acronym> (intra) picture </glossterm>
<glossdef> <para> Picture independantly coded. It can be
decoded without any other reference frame. It is regularly
sent (like twice a second) for resynchronization purposes.
</para> </glossdef>
</glossentry>
<glossentry>
<glossterm> <acronym> IDCT </acronym> : Inverse Discrete
Cosinus Transform </glossterm>
<glossdef> <para> IDCT is a classical mathematical algorithm
to convert from a space domain to a frequency domain. In a
nutshell, it codes differences instead of coding all absolute
pixels. MPEG uses an 2-D IDCT in the video decoder, and a 1-D
IDCT in the audio decoder.
</para> </glossdef>
</glossentry>
<glossentry>
<glossterm> <acronym> LPCM </acronym> :
Linear Pulse Code Modulation </glossterm>
<glossdef> <para> LPCM is a non-compressed audio encoding,
available in DVDs.
</para> </glossdef>
</glossentry>
<glossentry>
<glossterm> <acronym> MPEG </acronym> :
Motion Picture Expert Group </glossterm>
<glossdef> <para> Specification describing a standard syntax of files
and streams for carrying motion pictures and sound. MPEG-1 is
ISO/IEC 11172 (three books), MPEG-2 is ISO/IEC 13818. MPEG-4
version 1 is out, but this player doesn't support it. It is
relatively easy to get an MPEG specification from ISO or
equivalent, drafts are even freely available on the Internet.
</para> </glossdef>
</glossentry>
<glossentry>
<glossterm> <acronym> P </acronym> (predictive) picture </glossterm>
<glossdef> <para> Picture decoded from its own data <emphasis>
and </emphasis> data from a reference picture, which is the
last I or P picture received.
</para> </glossdef>
</glossentry>
<glossentry>
<glossterm> <acronym> PES </acronym> :
Packetized Elementary Stream </glossterm>
<glossdef> <para> A chunk of elementary stream. It often corresponds
to a logical boundary of the stream (for instance a picture
change), but it is not mandatory. PES carry the synchronization
information.
</para> </glossdef>
</glossentry>
<glossentry>
<glossterm> <acronym> PTS </acronym> :
Presentation Time Stamp </glossterm>
<glossdef> <para> Time at which the content of a PES packet is supposed
to be played. It is used for A/V synchronization.
</para> </glossdef>
</glossentry>
<glossentry>
<glossterm> <acronym> PS </acronym> : Program Stream </glossterm>
<glossdef> <para> File format obtained by concatenating PES packets
and inserting Pack headers and System headers (for timing
information). It is the only format described in MPEG-1, and
the most used format in MPEG-2.
</para></glossdef>
</glossentry>
<glossentry>
<glossterm> <acronym> RGB </acronym> : Red Green Blue </glossterm>
<glossdef> <para> Picture format where every pixel is calculated in a
vector space whose coordinates are red, green, and blue. This
is natively used by monitors and TV sets.
</para> </glossdef>
</glossentry>
<glossentry>
<glossterm> <acronym> SPU </acronym> : Sub Picture Unit </glossterm>
<glossdef> <para> Picture format allowing to do overlays, such
as subtitles or DVD menus.
</para> </glossdef>
</glossentry>
<glossentry>
<glossterm> <acronym> SCR </acronym> :
System Clock Reference </glossterm>
<glossdef> <para> Time at which the first byte of a particular pack
is supposed to be fed to the decoder. VLC uses it to read the
stream at the right pace.
</para> </glossdef>
</glossentry>
<glossentry>
<glossterm> <acronym> SDL </acronym> :
Simple DirectMedia Layer </glossterm>
<glossdef> <para> <ulink url="http://www.libsdl.org/"> SDL </ulink>
is a cross-platform multimedia library
designed to provide fast access to the video framebuffer and
the audio device. Since version 1.1, it features YUV overlay
support, which reduces decoding times by a third.
</para> </glossdef>
</glossentry>
<glossentry>
<glossterm> <acronym> TS </acronym> : Transport Stream </glossterm>
<glossdef> <para> Stream format constituted of fixed size packets
(188 bytes), defined by ISO/IEC 13818-1. PES packets are
split among several TS packets.
A TS stream can contain several programs. It is used in
streaming applications, in particular for satellite or cable
broadcasting.
</para> </glossdef>
</glossentry>
<glossentry>
<glossterm> <acronym> YUV </acronym> :
Luminance/Chrominance </glossterm>
<glossdef> <para> Picture format with 1 coordinate of luminance (black
and white) and 2 coordinates of chrominance (red and blue).
This is natively used by PAL video system, for backward
compatibility with older black and white TV sets. Your eyes
distinguish luminance variations much better than chrominance
variations, so you can compress them more. It is therefore
well suited for image compression, and is used by the MPEG
specification. The RGB picture can be obtained from the YUV one
via a costly matrix multiply operation, which can be done in
hardware by most modern video cards ("YUV acceleration").
</para> </glossdef>
</glossentry>
</glossary>

131
doc/developer/history.xml Normal file
View File

@ -0,0 +1,131 @@
<appendix> <title> Project history </title>
<sect1> <title> VIA and the Network2000 project </title>
<para>
The whole project started back in 1995. At that time, students of the
<ulink url="http://www.ecp.fr/"> &Eacute;cole Centrale de Paris </ulink>
enjoyed a TokenRing network, managed by the <ulink
url="http://www.via.ecp.fr/"> VIA Centrale R&eacute;seaux
association</ulink>, and were looking
for a solution to upgrade to a modern network. So the idea behind
Network2000 was to find a project students would realize that would
be interesting, would require a high-quality network, and could
provide enough fame so that sponsors would be interested.
</para>
<para>
Someone came up with the idea of doing television broadcast on the
network, so that students could watch TV in their room. This was
interesting, mixed a lot of cool technologies, and provided fame
because no one had written a free MPEG-2 decoder so far.
</para>
</sect1>
<sect1> <title> Foundation of the VideoLAN project </title>
<para>
<ulink url="http://www.3com.com/"> 3Com</ulink>,
<ulink url="http://www.bouygues.com/"> Bouygues </ulink> and
la Soci&eacute;t&eacute; des Amis were
interested and financed the project, which was then known after
the name of VideoLAN.
</para>
<para>
The VideoLAN team, in particular <ulink url="mailto:walken@via.ecp.fr">
Michel Lespinasse </ulink> (current maintainer of <ulink
url="http://www.linuxvideo.org/">LiViD</ulink>'s mpeg2dec)
and <ulink url="mailto:hpreg@via.ecp.fr"> R&eacute;gis
Duchesne</ulink>, started writing code in 1996. By the end of 1997 they had
a working client-server solution, but it would crash a lot and was
hard to extend.
</para>
<para>
At that time it was still closed-source and only-for-demo code.
</para>
</sect1>
<sect1> <title> VideoLAN Client design </title>
<para>
In 1998, <ulink url="mailto:seguin@via.ecp.fr"> Vincent Seguin</ulink>
(structure, interface and video output),
<ulink url="mailto:massiot@via.ecp.fr"> Christophe Massiot</ulink>
(input and video decoder),
<ulink url="mailto:maxx@via.ecp.fr"> Michel Kaempf</ulink>
(audio decoder and audio output) and
<ulink url="mailto:polux@via.ecp.fr"> Jean-Marc Dressler</ulink>
(synchronization) decided to write a brand new player from scratch,
called VideoLAN Client (VLC), so that it could be easily open sourced.
Of course we based it on code written by our predecessors, but in
an advanced structure, described in the first chapter (it hasn't been
necessary to change it a lot).
</para>
<para>
At the same time, <ulink url="mailto:benny@via.ecp.fr"> Beno&icirc;t
Steiner </ulink> started the writing of an advanced stream server, called
VideoLAN Server (VLS).
</para>
<para>
Functional test seeds have been released internally in June 1999
(vlc-DR1) and November 1999 (vlc-DR2), and we started large scale tests
and presentations. The French audience discovered us at Linux Expo
in June 1999, presenting our 20 minutes of Golden Eye (which is now
a legend among developers :-). At that time only a network input was
possible, file input was added later, but it remained kludgy for a while.
</para>
<para>
In early 2000, we (especially <ulink url="mailto:sam@via.ecp.fr"> Samuel
Hocevar</ulink>, who is still a major contributor) started working
on DVDs (PS files, AC3, SPU). In the summer 2000, pre-release builds
have been seeded (0.2.0 versions), but they still lacked essential
features.
</para>
<para>
In late 2000, <ulink url="mailto:massiot@via.ecp.fr"> Christophe Massiot
</ulink> with the support of his company,
<ulink url="http://www.idealx.com/"> IDEALX</ulink>, rewrote major
parts of the input to allow modularization and advanced navigation, and <ulink
url="mailto:stef@via.ecp.fr"> Stéphane Borel </ulink> worked on a
fully-featured DVD plug-in for VLC.
</para>
</sect1>
<sect1> <title> The Opening </title>
<para>
For Linux Expo in February 2001, the <ulink url="http://www.gnu.org/">
Free Software Foundation </ulink> and <ulink url="http://www.idealx.com/">
IDEALX </ulink> wanted to make live streaming of the 2001 FSF awards
from Paris to New York. VideoLAN was the chosen solution. Finally
it couldn't be done live because of bandwidth considerations, but a
<ulink url="http://www.via.ecp.fr/~massiot/encoding.html"> chain of
fully open-source solutions </ulink> made it possible to record it.
</para>
<para>
At the same time, the president of the <ulink url="http://www.ecp.fr/">
&Eacute;cole Centrale Paris</ulink> officially decided to place the software
under GNU General Public Licence, thanks to <ulink
url="mailto:henri@via.ecp.fr"> Henri Fallon</ulink>, <ulink
url="mailto:jprey@ads.ecp.fr"> Jean-Philippe Rey</ulink>, and the IDEALX team.
</para>
<para>
VideoLAN software is now one of the most popular open source DVD
players available, and has contributors all around the world. The
last chapter of this appendix is not written yet :-).
</para>
</sect1>
</appendix>

454
doc/developer/input.xml Normal file
View File

@ -0,0 +1,454 @@
<chapter> <title> The complex multi-layer input </title>
<para>
The idea behind the input module is to treat packets, without knowing
at all what is in it. It only takes a packet,
reads its ID, and delivers it to the decoder at the right time
indicated in the packet header (SCR and PCR fields in MPEG).
All the basic browsing operations are implemented without peeking at the
content of the elementary stream.
</para>
<para>
Thus it remains very generic. This also means you can't do stuff like
"play 3 frames now" or "move forward 10 frames" or "play as fast as you
can but play all frames". It doesn't even know what a "frame" is. There
is no privileged elementary stream, like the video one could be (for
the simple reason that, according to MPEG, a stream may contain
several video ES).
</para>
<sect1> <title> What happens to a file </title>
<para>
An input thread is spawned for every file read. Indeed, input structures
and decoders need to be reinitialized because the specificities of
the stream may be different. <function> input_CreateThread </function>
is called by the interface thread (playlist module).
</para>
<para>
At first, an input plug-in capable of reading the plugin item is looked
for [this is inappropriate : we should first open the socket,
and then probe the beginning of the stream to see which plug-in can read
it]. The socket is opened by either <function> input_FileOpen</function>,
<function> input_NetworkOpen</function>, or <function>
input_DvdOpen</function>. This function sets two very important parameters :
<parameter> b_pace_control </parameter> and <parameter> b_seekable
</parameter> (see next section).
</para>
<note> <para>
We could use so-called "access" plugins for this whole mechanism
of opening the input socket. This is not the case because we
thought only those three methods were to be used at present,
and if we need others we can still build them in.
</para> </note>
<para>
Now we can launch the input plugin's <function> pf_init </function>
function, and an endless loop doing <function> pf_read </function>
and <function> pf_demux</function>. The plugin is responsible
for initializing the stream structures
(<parameter>p_input-&gt;stream</parameter>), managing packet buffers,
reading packets and demultiplex them. But in most tasks it will
be assisted by functions from the advanced input API (c). That is
what we will study in the coming sections !
</para>
</sect1>
<sect1> <title> Stream Management </title>
<para>
The function which has opened the input socket must specify two
properties about it :
</para>
<orderedlist>
<listitem> <para> <emphasis> p_input-&gt;stream.b_pace_control
</emphasis> : Whether or not the stream can be read at our own
pace (determined by the stream's frequency and
the host computer's system clock). For instance a file or a pipe
(including TCP/IP connections) can be read at our pace, if we don't
read fast enough, the other end of the pipe will just block on a
<function> write() </function> operation. On the contrary, UDP
streaming (such as the one used by VideoLAN Server) is done at
the server's pace, and if we don't read fast enough, packets will
simply be lost when the kernel's buffer is full. So the drift
introduced by the server's clock must be regularly compensated.
This property controls the clock management, and whether
or not fast forward and slow motion can be done.</para>
<note> <title> Subtilities in the clock management </title> <para>
With a UDP socket and a distant server, the drift is not
negligible because on a whole movie it can account for
seconds if one of the clocks is slightly fucked up. That means
that presentation dates given by the input thread may be
out of sync, to some extent, with the frequencies given in
every Elementary Stream. Output threads (and, anecdotically,
decoder threads) must deal with it. </para>
<para> The same kind of problems may happen when reading from
a device (like video4linux's <filename> /dev/video </filename>)
connected for instance to a video encoding board.
There is no way we could differentiate
it from a simple <command> cat foo.mpg | vlc - </command>, which
doesn't imply any clock problem. So the Right Thing (c) would be
to ask the user about the value of <parameter> b_pace_control
</parameter>, but nobody would understand what it means (you are
not the dumbest person on Earth, and obviously you have read this
paragraph several times to understand it :-). Anyway,
the drift should be negligible since the board would share the
same clock as the CPU, so we chose to neglect it. </para> </note>
</listitem>
<listitem> <para> <emphasis> p_input-&gt;stream.b_seekable
</emphasis> : Whether we can do <function> lseek() </function>
calls on the file descriptor or not. Basically whether we can
jump anywhere in the stream (and thus display a scrollbar) or
if we can only read one byte after the other. This has less impact
on the stream management than the previous item, but it
is not redundant, because for instance
<command> cat foo.mpg | vlc - </command> is b_pace_control = 1
but b_seekable = 0. On the contrary, you cannot have
b_pace_control = 0 along with b_seekable = 1. If a stream is seekable,
<parameter> p_input-&gt;stream.p_selected_area-&gt;i_size </parameter>
must be set (in an arbitrary unit, for instance bytes, but it
must be the same as p_input-&gt;i_tell which indicates the byte
we are currently reading from the stream).</para>
<note> <title> Offset to time conversions </title> <para>
Functions managing clocks are located in <filename>
src/input/input_clock.c</filename>. All we know about a file
is its start offset and its end offset
(<parameter>p_input-&gt;stream.p_selected_area-&gt;i_size</parameter>),
currently in bytes, but it could be plugin-dependant. So
how the hell can we display in the interface a time in seconds ?
Well, we cheat. PS streams have a <parameter> mux_rate </parameter>
property which indicates how many bytes we should read in
a second. This is subject to change at any time, but practically
it is a constant for all streams we know. So we use it to
determine time offsets. </para> </note> </listitem>
</orderedlist>
</sect1>
<sect1> <title> Structures exported to the interface </title>
<para>
Let's focus on the communication API between the input module and the
interface. The most important file is <filename> include/input_ext-intf.h,
</filename> which you should know almost by heart. This file defines
the input_thread_t structure, the stream_descriptor_t and all programs
and ES descriptors included (you can view it as a tree).
</para>
<para>
First, note that the input_thread_t structure features two <type> void *
</type> pointers, <parameter> p_method_data </parameter> and <parameter>
p_plugin_data</parameter>, which you can respectivly use for buffer
management data and plugin data.
</para>
<para>
Second, a stream description is stored in a tree featuring program
descriptors, which themselves contain several elementary stream
descriptors. For those of you who don't know all MPEG concepts, an
elementary stream, aka ES, is a continuous stream of video or
(exclusive) audio data, directly readable by a decoder, without
decapsulation.
</para>
<para>
This tree structure is illustrated by the following
figure, where one stream holds two programs.
In most cases there will only be one program (to my
knowledge only TS streams can carry several programs, for instance
a movie and a football game at the same time - this is adequate
for satellite and cable broadcasting).
</para>
<mediaobject>
<imageobject>
<imagedata fileref="stream.eps" format="EPS" scalefit="1" scale="80"/>
</imageobject>
<imageobject>
<imagedata fileref="stream.gif" format="GIF" />
</imageobject>
<textobject>
<phrase> The program tree </phrase>
</textobject>
<caption>
<para> <emphasis> p_input-&gt;stream </emphasis> :
The stream, programs and elementary streams can be viewed as a tree.
</para>
</caption>
</mediaobject>
<warning> <para>
For all modifications and accesses to the <parameter>p_input-&gt;stream
</parameter> structure, you <emphasis>must</emphasis> hold
the p_input-&gt;stream.stream_lock.
</para> </warning>
<para>
ES are described by an ID (the ID the appropriate demultiplexer will
look for), a <parameter> stream_id </parameter> (the real MPEG stream
ID), a type (defined
in ISO/IEC 13818-1 table 2-29) and a litteral description. It also
contains context information for the demultiplexer, and decoder
information <parameter> p_decoder_fifo </parameter> we will talk
about in the next chapter. If the stream you want to read is not an
MPEG system layer (for instance AVI or RTP), a specific demultiplexer
will have to be written. In that case, if you need to carry additional
information, you can use <type> void * </type> <parameter> p_demux_data
</parameter> at your convenience. It will be automatically freed on
shutdown.
</para>
<note> <title> Why ID and not use the plain MPEG <parameter>
stream_id </parameter> ? </title> <para>
When a packet (be it a TS packet, PS packet, or whatever) is read,
the appropriate demultiplexer will look for an ID in the packet, find the
relevant elementary stream, and demultiplex it if the user selected it.
In case of TS packets, the only information we have is the
ES PID, so the reference ID we keep is the PID. PID don't exist
in PS streams, so we have to invent one. It is of course based on
the <parameter> stream_id </parameter> found in all PS packets,
but it is not enough, since private streams (ie. AC3, SPU and
LPCM) all share the same <parameter> stream_id </parameter>
(<constant>0xBD</constant>). In that case the first byte of the
PES payload is a stream private ID, so we combine this with
the stream_id to get our ID (if you did not understand everything,
it isn't very important - just remember we used our brains
before writing the code :-).
</para> </note>
<para>
The stream, program and ES structures are filled in by the plugin's
<function> pf_init()
</function> using functions in <filename> src/input/input_programs.c,
</filename> but are subject to change at any time. The DVD plugin
parses .ifo files to know which ES are in the stream; the TS plugin
reads the PAT and PMT structures in the stream; the PS plugin can
either parse the PSM structure (but it is rarely present), or build
the tree "on the fly" by pre-parsing the first megabyte of data.
</para>
<warning> <para>
In most cases we need to pre-parse (that is, read the first MB of data,
and go back to the beginning) a PS stream, because the PSM (Program
Stream Map) structure is almost never present. This is not appropriate,
though, but we don't have the choice. A few problems will arise. First,
non-seekable streams cannot be pre-parsed, so the ES tree will be
built on the fly. Second, if a new elementary stream starts after the
first MB of data (for instance a subtitle track won't show up
during the credits), it won't appear in the menu before we encounter
the first packet. We cannot pre-parse the entire stream because it
would take hours (even without decoding it).
</para> </warning>
<para>
It is currently the responsibility of the input plugin to spawn the necessary
decoder threads. It must call <function> input_SelectES </function>
<parameter>( input_thread_t * p_input, es_descriptor_t * p_es )
</parameter> on the selected ES.
</para>
<para>
The stream descriptor also contains a list of areas. Areas are logical
discontinuities in the stream, for instance chapters and titles in a
DVD. There is only one area in TS and PS streams, though we could
use them when the PSM (or PAT/PMT) version changes. The goal is that
when you seek to another area, the input plugin loads the new stream
descriptor tree (otherwise the selected ID may be wrong).
</para>
</sect1>
<sect1> <title> Methods used by the interface </title>
<para>
Besides, <filename> input_ext-intf.c </filename>provides a few functions
to control the reading of the stream :
</para>
<itemizedlist>
<listitem> <para> <function> input_SetStatus </function>
<parameter> ( input_thread_t * p_input, int i_mode ) </parameter> :
Changes the pace of reading. <parameter> i_mode </parameter> can
be one of <constant> INPUT_STATUS_END, INPUT_STATUS_PLAY,
INPUT_STATUS_PAUSE, INPUT_STATUS_FASTER, INPUT_STATUS_SLOWER.
</constant> </para>
<note> <para> Internally, the pace of reading is determined
by the variable <parameter>
p_input-&gt;stream.control.i_rate</parameter>. The default
value is <constant> DEFAULT_RATE</constant>. The lower the
value, the faster the pace is. Rate changes are taken into account
in <function> input_ClockManageRef</function>. Pause is
accomplished by simply stopping the input thread (it is
then awaken by a pthread signal). In that case, decoders
will be stopped too. Please remember this if you do statistics
on decoding times (like <filename> src/video_parser/vpar_synchro.c
</filename> does). Don't call this function if <parameter>
p_input-&gt;b_pace_control </parameter> == 0.</para> </note>
</listitem>
<listitem> <para> <function> input_Seek </function> <parameter>
( input_thread_t * p_input, off_t i_position ) </parameter> :
Changes the offset of reading. Used to jump to another place in a
file. You <emphasis>mustn't</emphasis> call this function if
<parameter> p_input-&gt;stream.b_seekable </parameter> == 0.
The position is a number (usually long long, depends on your
libc) between <parameter>p_input-&gt;p_selected_area-&gt;i_start
</parameter> and <parameter>p_input-&gt;p_selected_area-&gt;i_size
</parameter> (current value is in <parameter>
p_input-&gt;p_selected_area-&gt;i_tell</parameter>). </para>
<note> <para> Multimedia files can be very large, especially
when we read a device like <filename> /dev/dvd</filename>, so
offsets must be 64 bits large. Under a lot of systems, like
FreeBSD, off_t are 64 bits by default, but it is not the
case under GNU libc 2.x. That is why we need to compile VLC
with -D_FILE_OFFSET_BITS=64 -D__USE_UNIX98. </para> </note>
<note> <title> Escaping stream discontinuities </title>
<para>
Changing the reading position at random can result in a
messed up stream, and the decoder which reads it may
segfault. To avoid this, we send several NULL packets
(ie. packets containing nothing but zeros) before changing
the reading position. Indeed, under most video and audio
formats, a long enough stream of zeros is an escape sequence
and the decoder can exit cleanly.
</para> </note>
</listitem>
<listitem> <para> <function> input_OffsetToTime </function>
<parameter> ( input_thread_t * p_input, char * psz_buffer,
off_t i_offset ) </parameter> : Converts an offset value to
a time coordinate (used for interface display).
[currently it is broken with MPEG-2 files]
</para> </listitem>
<listitem> <para> <function> input_ChangeES </function>
<parameter> ( input_thread_t * p_input, es_descriptor_t * p_es,
u8 i_cat ) </parameter> : Unselects all elementary streams of
type <parameter> i_cat </parameter> and selects <parameter>
p_es</parameter>. Used for instance to change language or
subtitle track.
</para> </listitem>
<listitem> <para> <function> input_ToggleES </function>
<parameter> ( input_thread_t * p_input, es_descriptor_t * p_es,
boolean_t b_select ) </parameter> : This is the clean way to
select or unselect a particular elementary stream from the
interface.
</para> </listitem>
</itemizedlist>
</sect1>
<sect1 id="input_buff"> <title> Buffers management </title>
<para>
Input plugins must implement a way to allocate and deallocate packets
(whose structures will be described in the next chapter). We
basically need four functions :
</para>
<itemizedlist>
<listitem> <para> <function> pf_new_packet </function>
<parameter> ( void * p_private_data, size_t i_buffer_size )
</parameter> :
Allocates a new <type> data_packet_t </type> and an associated
buffer of i_buffer_size bytes.
</para> </listitem>
<listitem> <para> <function> pf_new_pes </function>
<parameter> ( void * p_private_data ) </parameter> :
Allocates a new <type> pes_packet_t</type>.
</para> </listitem>
<listitem> <para> <function> pf_delete_packet </function>
<parameter> ( void * p_private_data, data_packet_t * p_data )
</parameter>&nbsp;:
Deallocates <parameter> p_data</parameter>.
</para> </listitem>
<listitem> <para> <function> pf_delete_pes </function>
<parameter> ( void * p_private_data, pes_packet_t * p_pes )
</parameter> :
Deallocates <parameter> p_pes</parameter>.
</para> </listitem>
</itemizedlist>
<para>
All functions are given <parameter> p_input-&gt;p_method_data </parameter>
as first parameter, so that you can keep records of allocated and freed
packets.
</para>
<note> <title> Buffers management strategies </title>
<para> Buffers management can be done in three ways : </para>
<orderedlist>
<listitem> <para> <emphasis> Traditional libc allocation </emphasis> :
For a long time we have used in the PS plugin
<function> malloc()
</function> and <function> free() </function> every time
we needed to allocate or deallocate a packet. Contrary
to a popular belief, it is not <emphasis>that</emphasis>
slow.
</para> </listitem>
<listitem> <para> <emphasis> Netlist </emphasis> :
In this method we allocate a very big buffer at the
beginning of the problem, and then manage a list of pointers
to free packets (the "netlist"). This only works well if
all packets have the same size. It is used for long for
the TS input. The DVD plugin also uses it, but adds a
<emphasis> refcount </emphasis> flag because buffers (2048
bytes) can be shared among several packets. It is now
deprecated and won't be documented.
</para> </listitem>
<listitem> <para> <emphasis> Buffer cache </emphasis> :
We are currently developing a new method. It is
already in use in the PS plugin. The idea is to call
<function> malloc() </function> and <function> free()
</function> to absorb stream irregularities, but re-use
all allocated buffers via a cache system. We are
extending it so that it can be used in any plugin without
performance hit, but it is currently left undocumented.
</para> </listitem>
</orderedlist>
</note>
</sect1>
<sect1> <title> Demultiplexing the stream </title>
<para>
After being read by <function> pf_read </function>, your plugin must
give a function pointer to the demultiplexer function. The demultiplexer
is responsible for parsing the packet, gathering PES, and feeding decoders.
</para>
<para>
Demultiplexers for standard MPEG structures (PS and TS) have already
been written. You just need to indicate <function> input_DemuxPS
</function> and <function> input_DemuxTS </function> for <function>
pf_demux</function>. You can also write your own demultiplexer.
</para>
<para>
It is not the purpose of this document to describe the different levels
of encapsulation in an MPEG stream. Please refer to your MPEG specification
for that.
</para>
</sect1>
</chapter>

268
doc/developer/interface.xml Normal file
View File

@ -0,0 +1,268 @@
<chapter> <title> VLC interface </title>
<sect1> <title> A typical VLC run course </title>
<para>
This section describes what happens when you launch the <application>
vlc</application>
program. After the ELF dynamic loader blah blah blah, the main thread
becomes the interface thread and starts up in <filename>
src/interface/main.c </filename>. It passes through the following steps :
</para>
<orderedlist>
<listitem> <para> CPU detection : which CPU are we running on, what are
its capabilities (MMX, MMXEXT, 3DNow, AltiVec...) ? </para> </listitem>
<listitem> <para> Message interface initialization ; </para> </listitem>
<listitem> <para> Command line options parsing ; </para> </listitem>
<listitem> <para> Playlist creation ; </para> </listitem>
<listitem> <para> Module bank initialization ; </para> </listitem>
<listitem> <para> Interface opening ; </para> </listitem>
<listitem> <para> Signal handler installation : SIGHUP, SIGINT
and SIGQUIT are caught to manage a clean quit (please note that the SDL
library also catches SIGSEGV) ; </para> </listitem>
<listitem> <para> Audio output thread spawning ; </para> </listitem>
<listitem> <para> Video output thread spawning ; </para> </listitem>
<listitem> <para> Main loop : events management ; </para> </listitem>
</orderedlist>
<para>
Following sections describe each of these steps in particular, and many more.
</para>
</sect1>
<sect1> <title> The message interface </title>
<para>
It is a know fact that <function> printf() </function> functions are
not necessarily thread-safe. As a result,
one thread interrupted in a <function> printf() </function> call, followed
by another calls to it, will leave the program in an undetermined state. So
an API must be set up to print messages without crashing.
</para>
<para>
This API is implemented in two ways. If <constant> INTF_MSG_QUEUE </constant>
is defined in <filename> config.h </filename>, every <function>
printf</function>-like (see below) call will queue the message into a chained list.
This list will be printed and flushed by the interface thread once upon
an event loop. If <constant> INTF_MSG_QUEUE </constant> is undefined,
the calling thread will acquire the print lock (which prevents two
print operations to occur at the same time) and print the message
directly (default behaviour).
</para>
<para>
Functions available to print messages are :
</para>
<itemizedlist>
<listitem> <para> <function> intf_Msg </function> ( <parameter>
char * psz_format, ... </parameter> ) :
Print a message to <constant> stdout </constant>, plain and
stupid (for instance "vlc 0.2.72 (Apr 16 2001)"). </para> </listitem>
<listitem> <para> <function> intf_ErrMsg </function> ( <parameter>
char * psz_format, ... </parameter> ) :
Print an error message to <constant> stderr </constant>. </para>
</listitem>
<listitem> <para> <function> intf_WarnMsg </function> ( <parameter>
int i_level, char * psz_format, ... </parameter> ) :
Print a message to <constant> stderr </constant> if the warning
level (determined by -v, -vv and -vvv) is low enough. </para>
<note> <para> Please note
that the lower the level, the less important the message is (dayou
spik ingliche ?). </para> </note> </listitem>
<listitem> <para> <function> intf_DbgMsg </function> ( <parameter>
char * psz_format, ... </parameter> ) :
This function is designed for optional checkpoint messages, such
as "we are now entering function dvd_foo_thingy". It does nothing
in non-trace mode. If the VLC is compiled with --enable-trace, the
message is either written to the file <filename> vlc-trace.log </filename>
(if TRACE_LOG is defined in config.h), or printed to <constant> stderr
</constant> (otherwise). </para> </listitem>
<listitem> <para> <function> intf_MsgImm, intf_ErrMsgImm, intf_WarnMsgImm,
intf_DbgMsgImm </function> :
Same as above, except that the message queue, in case <parameter>
INTF_MSG_QUEUE </parameter> is defined,
will be flushed before the function returns.
</para> </listitem>
<listitem> <para> <function> intf_WarnHexDump </function> ( <parameter>
int i_level, void * p_data, int i_size </parameter> ) :
Dumps <parameter> i_size </parameter> bytes from <parameter>
p_data </parameter> in hexadecimal. <parameter> i_level </parameter>
works like <function> intf_WarnMsg </function>. This is useful for
debugging purposes. </para> </listitem>
<listitem> <para> <function> intf_FlushMsg </function> () :
Flush the message queue, if it is in use. </para> </listitem>
</itemizedlist>
</sect1>
<sect1> <title> Command line options </title>
<para>
VLC uses GNU getopt to parse command line options. getopt structures are
defined in <filename> src/interface/main.c </filename> in the "Command
line options constants" section. To add a new option This section needs
to be changed, along with
<function> GetConfiguration </function> and <function> Usage</function>.
</para>
<para>
Most configuration directives are exchanged via the environment array,
using <function> main_Put*Variable </function> and <function>
main_Get*Variable</function>. As a result, <command>
./vlc --height 240 </command> is strictly equivalent to : <command>
vlc_height=240 ./vlc</command>. That way configuration variables are
available everywhere, including plugins.
</para>
<warning> <para>
Please note that for thread-safety issues, you should not use
<function> main_Put*Variable </function> once the second thread has
been spawned.
</para> </warning>
</sect1>
<sect1> <title> Playlist management </title>
<para>
The playlist is created on startup from files given in the command line.
An appropriate interface plugin can then add or remove files from it.
Functions to be used are described in <filename>
src/interface/intf_playlist.c</filename>.
<function> intf_PlaylistAdd </function> and <function>
intf_PlaylistDelete</function> are typically the most common used.
</para>
<para>
The main interface loop <function> intf_Manage </function> is then
supposed to <emphasis> start and kill input threads </emphasis> when necessary.
</para>
</sect1>
<sect1> <title> Module bank </title>
<para>
On startup, VLC creates a bank of all available .so files (plugins) in
<filename>., ./lib, /usr/local/lib/videolan/vlc</filename> <constant>
(PLUGIN_PATH)</constant>, and built-in plugins. Every plugin is checked
with its capabilities, which are :
</para>
<itemizedlist>
<listitem> <para> MODULE_CAPABILITY_INTF : An interface plugin ;
</para> </listitem>
<listitem> <para> MODULE_CAPABILITY_ACCESS : A sam-ism, unused at
present ;</para> </listitem>
<listitem> <para> MODULE_CAPABILITY_INPUT : An input plugin, for
instance PS or DVD ;</para> </listitem>
<listitem> <para> MODULE_CAPABILITY_DECAPS : A sam-ism, unused at
present ;</para> </listitem>
<listitem> <para> MODULE_CAPABILITY_ADEC : An audio decoder ;
</para> </listitem>
<listitem> <para> MODULE_CAPABILITY_VDEC : A video decoder ;
</para> </listitem>
<listitem> <para> MODULE_CAPABILITY_MOTION : A motion compensation
module (for the video decoder) ;</para> </listitem>
<listitem> <para> MODULE_CAPABILITY_IDCT : An IDCT module (for
the video decoder) ;</para> </listitem>
<listitem> <para> MODULE_CAPABILITY_AOUT : An audio output module ;
</para> </listitem>
<listitem> <para> MODULE_CAPABILITY_VOUT : A video output module ;
</para> </listitem>
<listitem> <para> MODULE_CAPABILITY_YUV : A YUV module (for the
video output) ;</para> </listitem>
<listitem> <para> MODULE_CAPABILITY_AFX : An audio effects plugin
(for the audio output ; unimplemented) ;</para> </listitem>
<listitem> <para> MODULE_CAPABILITY_VFX : A video effects plugin
(for the video output ; unimplemented) ;</para> </listitem>
</itemizedlist>
<para>
How to write a plugin is described in the latter sections. Other threads
can request a plugin descriptor with <function> module_Need </function>
<parameter> ( module_bank_t * p_bank, int i_capabilities, void * p_data ).
p_data </parameter> is an optional parameter (reserved for future use) for the
<function> pf_probe() </function> function. The returned module_t
structure contains pointers to the functions of the plug-in. See
<filename>include/modules.h</filename> for more information.
</para>
</sect1>
<sect1> <title> The interface main loop </title>
<para>
The interface thread will first look for a suitable interface plugin.
Then it enters the main interface loop, with the plugin's <function>
pf_run </function> function. This function will do what's appropriate,
and every 100 ms will call (typically via a GUI timer callback)
<function>intf_Manage</function>.
</para>
<para>
<function>intf_Manage</function> cleans up the module bank by unloading
unnecessary modules, manages the playlist, and flushes waiting
messages (if the message queue is in use).
</para>
</sect1>
<sect1> <title> How to write an interface plugin </title>
<para>
Have a look at <filename>plugins/dummy/intf_dummy.c</filename> and
<filename>plugins/gtk/intf_gtk.c</filename>. Basically, you have to
write 5 functions :
</para>
<itemizedlist>
<listitem> <para> <function> intf_Probe </function> ( <parameter>
probedata_t * p_data </parameter> ) :
This is supposed to tell whether your plugin can work in this
environment or not. If it can, it returns a score between 1
and 999 indicating whether this plugin should be preferred
against others or not. <parameter> p_data </parameter> is
currently unused. </para> </listitem>
<listitem> <para> <function> intf_Open </function> ( <parameter>
intf_thread_t * p_intf </parameter> ) :
Initializes the interface (ie. opens a new window, etc.).
You can store your information in p_intf-&gt;p_sys.
</para> </listitem>
<listitem> <para> <function> intf_Close </function> ( <parameter>
intf_thread_t * p_intf </parameter> ) :
Closes the interface and frees all allocated structures
(including p_intf-&gt;p_sys).
</para> </listitem>
<listitem> <para> <function> intf_Run </function> ( <parameter>
intf_thread_t * p_intf </parameter> ) :
Launches the main loop, which shouldn't return
until p_intf-&gt;b_die is set to 1. Pay attention not to take all
CPU time with an infinite loop (add <function> msleep</function>).
</para> </listitem>
</itemizedlist>
<para>
Don't forget to define intf_sys_t to contain any variable you need
(don't use static variables, they suck in a multi-threaded
application :-). If additionnal
capabilities (such as Open button, playlist, menus, etc.) are needed,
look at the GTK+ plug-in in <filename> plugins/gtk</filename>.
</para>
</sect1>
</chapter>

124
doc/developer/manual.xml Normal file
View File

@ -0,0 +1,124 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.3//EN" "docbookx.dtd"
[
<!ENTITY glossary SYSTEM "glossary.xml">
<!ENTITY overview SYSTEM "overview.xml">
<!ENTITY interface SYSTEM "interface.xml">
<!ENTITY input SYSTEM "input.xml">
<!ENTITY decoders SYSTEM "decoders.xml">
<!ENTITY video_output SYSTEM "video_output.xml">
<!ENTITY audio_output SYSTEM "audio_output.xml">
<!ENTITY ports SYSTEM "ports.xml">
<!ENTITY debugging SYSTEM "debugging.xml">
<!ENTITY history SYSTEM "history.xml">
<!ENTITY gfdl SYSTEM "gfdl.xml">
]>
<book>
<title> VideoLAN Client API Documentation </title>
<bookinfo>
<author>
<firstname> Christophe </firstname>
<surname> Massiot </surname>
<affiliation>
<jobtitle> <ulink url="mailto:christophe.massiot@idealx.com">
Developer </ulink> </jobtitle>
<orgname> <ulink url="http://www.idealx.com"> IDEALX
S.A.S. </ulink> </orgname>
<orgdiv> Industrial Computing </orgdiv>
</affiliation>
</author>
<collab>
<collabname> <ulink url="mailto:sam@zoy.org"> Samuel Hocevar
</ulink> </collabname>
<affiliation>
<jobtitle> Developer </jobtitle>
<orgname> VideoLAN project </orgname>
</affiliation>
</collab>
<collab>
<collabname> Jean-Fran&ccedil;ois Lecomte </collabname>
<affiliation>
<jobtitle> <ulink url="mailto:jean-francois.lecomte@idealx.com">
Developer </ulink> </jobtitle>
<orgname> <ulink url="http://www.idealx.com"> IDEALX
S.A.S. </ulink> </orgname>
</affiliation>
</collab>
<pubdate> $Id: manual.xml,v 1.1 2001/07/16 15:54:59 massiot Exp $ </pubdate>
<copyright> <year> 2001 </year>
<holder> Christophe Massiot, for IDEALX S.A.S. </holder>
</copyright>
<legalnotice> <para>
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
A copy of the license is included in the section entitled "GNU
Free Documentation License".
</para> </legalnotice>
</bookinfo>
<toc />
<!-- ============================ GLOSSARY ============================
-->
&glossary;
<!-- ============================ OVERVIEW ============================
-->
&overview;
<!-- =========================== INTERFACE ============================
-->
&interface;
<!-- ============================= INPUT ==============================
-->
&input;
<!-- ============================ DECODERS ============================
-->
&decoders;
<!-- ========================== VIDEO OUTPUT ==========================
-->
&video_output;
<!-- ========================== AUDIO OUTPUT ==========================
-->
&audio_output;
<!-- ============================= PORTS ==============================
-->
&ports;
<!-- ======================= ADVANCED DEBUGGING =======================
-->
&debugging;
<!-- ======================== PROJECT HISTORY =========================
-->
&history;
<!-- ============================= GFDL ===============================
-->
&gfdl;
</book>

680
doc/developer/modules.eps Normal file
View File

@ -0,0 +1,680 @@
%!PS-Adobe-2.0 EPSF-2.0
%%Title: modules.eps
%%Creator: fig2dev Version 3.2 Patchlevel 3a
%%CreationDate: Fri May 4 17:42:40 2001
%%For: cmassiot@salomon (Christophe Massiot,,,)
%%BoundingBox: 0 0 514 459
%%Magnification: 1.0000
%%EndComments
/$F2psDict 200 dict def
$F2psDict begin
$F2psDict /mtrx matrix put
/col-1 {0 setgray} bind def
/col0 {0.000 0.000 0.000 srgb} bind def
/col1 {0.000 0.000 1.000 srgb} bind def
/col2 {0.000 1.000 0.000 srgb} bind def
/col3 {0.000 1.000 1.000 srgb} bind def
/col4 {1.000 0.000 0.000 srgb} bind def
/col5 {1.000 0.000 1.000 srgb} bind def
/col6 {1.000 1.000 0.000 srgb} bind def
/col7 {1.000 1.000 1.000 srgb} bind def
/col8 {0.000 0.000 0.560 srgb} bind def
/col9 {0.000 0.000 0.690 srgb} bind def
/col10 {0.000 0.000 0.820 srgb} bind def
/col11 {0.530 0.810 1.000 srgb} bind def
/col12 {0.000 0.560 0.000 srgb} bind def
/col13 {0.000 0.690 0.000 srgb} bind def
/col14 {0.000 0.820 0.000 srgb} bind def
/col15 {0.000 0.560 0.560 srgb} bind def
/col16 {0.000 0.690 0.690 srgb} bind def
/col17 {0.000 0.820 0.820 srgb} bind def
/col18 {0.560 0.000 0.000 srgb} bind def
/col19 {0.690 0.000 0.000 srgb} bind def
/col20 {0.820 0.000 0.000 srgb} bind def
/col21 {0.560 0.000 0.560 srgb} bind def
/col22 {0.690 0.000 0.690 srgb} bind def
/col23 {0.820 0.000 0.820 srgb} bind def
/col24 {0.500 0.190 0.000 srgb} bind def
/col25 {0.630 0.250 0.000 srgb} bind def
/col26 {0.750 0.380 0.000 srgb} bind def
/col27 {1.000 0.500 0.500 srgb} bind def
/col28 {1.000 0.630 0.630 srgb} bind def
/col29 {1.000 0.750 0.750 srgb} bind def
/col30 {1.000 0.880 0.880 srgb} bind def
/col31 {1.000 0.840 0.000 srgb} bind def
end
save
newpath 0 459 moveto 0 0 lineto 514 0 lineto 514 459 lineto closepath clip newpath
-36.0 472.0 translate
1 -1 scale
/cp {closepath} bind def
/ef {eofill} bind def
/gr {grestore} bind def
/gs {gsave} bind def
/sa {save} bind def
/rs {restore} bind def
/l {lineto} bind def
/m {moveto} bind def
/rm {rmoveto} bind def
/n {newpath} bind def
/s {stroke} bind def
/sh {show} bind def
/slc {setlinecap} bind def
/slj {setlinejoin} bind def
/slw {setlinewidth} bind def
/srgb {setrgbcolor} bind def
/rot {rotate} bind def
/sc {scale} bind def
/sd {setdash} bind def
/ff {findfont} bind def
/sf {setfont} bind def
/scf {scalefont} bind def
/sw {stringwidth} bind def
/tr {translate} bind def
/tnt {dup dup currentrgbcolor
4 -2 roll dup 1 exch sub 3 -1 roll mul add
4 -2 roll dup 1 exch sub 3 -1 roll mul add
4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb}
bind def
/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
4 -2 roll mul srgb} bind def
/reencdict 12 dict def /ReEncode { reencdict begin
/newcodesandnames exch def /newfontname exch def /basefontname exch def
/basefontdict basefontname findfont def /newfont basefontdict maxlength dict def
basefontdict { exch dup /FID ne { dup /Encoding eq
{ exch dup length array copy newfont 3 1 roll put }
{ exch newfont 3 1 roll put } ifelse } { pop pop } ifelse } forall
newfont /FontName newfontname put newcodesandnames aload pop
128 1 255 { newfont /Encoding get exch /.notdef put } for
newcodesandnames length 2 idiv { newfont /Encoding get 3 1 roll put } repeat
newfontname newfont definefont pop end } def
/isovec [
8#055 /minus 8#200 /grave 8#201 /acute 8#202 /circumflex 8#203 /tilde
8#204 /macron 8#205 /breve 8#206 /dotaccent 8#207 /dieresis
8#210 /ring 8#211 /cedilla 8#212 /hungarumlaut 8#213 /ogonek 8#214 /caron
8#220 /dotlessi 8#230 /oe 8#231 /OE
8#240 /space 8#241 /exclamdown 8#242 /cent 8#243 /sterling
8#244 /currency 8#245 /yen 8#246 /brokenbar 8#247 /section 8#250 /dieresis
8#251 /copyright 8#252 /ordfeminine 8#253 /guillemotleft 8#254 /logicalnot
8#255 /hyphen 8#256 /registered 8#257 /macron 8#260 /degree 8#261 /plusminus
8#262 /twosuperior 8#263 /threesuperior 8#264 /acute 8#265 /mu 8#266 /paragraph
8#267 /periodcentered 8#270 /cedilla 8#271 /onesuperior 8#272 /ordmasculine
8#273 /guillemotright 8#274 /onequarter 8#275 /onehalf
8#276 /threequarters 8#277 /questiondown 8#300 /Agrave 8#301 /Aacute
8#302 /Acircumflex 8#303 /Atilde 8#304 /Adieresis 8#305 /Aring
8#306 /AE 8#307 /Ccedilla 8#310 /Egrave 8#311 /Eacute
8#312 /Ecircumflex 8#313 /Edieresis 8#314 /Igrave 8#315 /Iacute
8#316 /Icircumflex 8#317 /Idieresis 8#320 /Eth 8#321 /Ntilde 8#322 /Ograve
8#323 /Oacute 8#324 /Ocircumflex 8#325 /Otilde 8#326 /Odieresis 8#327 /multiply
8#330 /Oslash 8#331 /Ugrave 8#332 /Uacute 8#333 /Ucircumflex
8#334 /Udieresis 8#335 /Yacute 8#336 /Thorn 8#337 /germandbls 8#340 /agrave
8#341 /aacute 8#342 /acircumflex 8#343 /atilde 8#344 /adieresis 8#345 /aring
8#346 /ae 8#347 /ccedilla 8#350 /egrave 8#351 /eacute
8#352 /ecircumflex 8#353 /edieresis 8#354 /igrave 8#355 /iacute
8#356 /icircumflex 8#357 /idieresis 8#360 /eth 8#361 /ntilde 8#362 /ograve
8#363 /oacute 8#364 /ocircumflex 8#365 /otilde 8#366 /odieresis 8#367 /divide
8#370 /oslash 8#371 /ugrave 8#372 /uacute 8#373 /ucircumflex
8#374 /udieresis 8#375 /yacute 8#376 /thorn 8#377 /ydieresis] def
/Times-Bold /Times-Bold-iso isovec ReEncode
/Times-Roman /Times-Roman-iso isovec ReEncode
/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
/$F2psEnd {$F2psEnteredState restore end} def
$F2psBegin
%%Page: 1 1
10 setmiterlimit
0.06299 0.06299 sc
% Polyline
7.500 slw
n 1080 2070 m 2880 2070 l 2880 1620 l 1080 1620 l
cp gs col0 s gr
/Times-Bold-iso ff 180.00 scf sf
1170 1800 m
gs 1 -1 sc (interface) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
1170 1980 m
gs 1 -1 sc (management and loop) col0 sh gr
% Polyline
n 1080 2970 m 2520 2970 l 2520 2520 l 1080 2520 l
cp gs col0 s gr
/Times-Bold-iso ff 180.00 scf sf
1170 2700 m
gs 1 -1 sc (intf_msg) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
1170 2880 m
gs 1 -1 sc (messages output) col0 sh gr
% Polyline
gs clippath
1500 2535 m 1560 2535 l 1560 2384 l 1530 2504 l 1500 2384 l cp
eoclip
n 1530 2070 m
1530 2520 l gs col4 s gr gr
% arrowhead
n 1500 2384 m 1530 2504 l 1560 2384 l 1500 2384 l cp gs col4 1.00 shd ef gr col4 s
% Polyline
gs clippath
1590 2535 m 1650 2535 l 1650 2384 l 1620 2504 l 1590 2384 l cp
eoclip
n 1620 2070 m
1620 2520 l gs col0 s gr gr
% arrowhead
n 1590 2384 m 1620 2504 l 1650 2384 l 1590 2384 l cp gs 0.00 setgray ef gr col0 s
% Polyline
n 1080 3645 m 2835 3645 l 2835 3195 l 1080 3195 l
cp gs col0 s gr
% Polyline
gs clippath
2625 3210 m 2685 3210 l 2685 3059 l 2655 3179 l 2625 3059 l cp
eoclip
n 2655 2070 m
2655 3195 l gs col4 s gr gr
% arrowhead
n 2625 3059 m 2655 3179 l 2685 3059 l 2625 3059 l cp gs col4 1.00 shd ef gr col4 s
% Polyline
gs clippath
2715 3210 m 2775 3210 l 2775 3059 l 2745 3179 l 2715 3059 l cp
eoclip
n 2745 2070 m
2745 3195 l gs col0 s gr gr
% arrowhead
n 2715 3059 m 2745 3179 l 2775 3059 l 2715 3059 l cp gs 0.00 setgray ef gr col0 s
% Polyline
n 1005 900 m 900 900 900 3765 105 arcto 4 {pop} repeat
900 3870 3045 3870 105 arcto 4 {pop} repeat
3150 3870 3150 1005 105 arcto 4 {pop} repeat
3150 900 1005 900 105 arcto 4 {pop} repeat
cp gs col0 s gr
/Times-Roman-iso ff 180.00 scf sf
1080 1350 m
gs 1 -1 sc (Manage threads and user) col0 sh gr
/Times-Bold-iso ff 180.00 scf sf
1170 3375 m
gs 1 -1 sc (playlist) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
1170 3555 m
gs 1 -1 sc (playlist management) col0 sh gr
% Polyline
n 4500 675 m 5850 675 l 5850 225 l 4500 225 l
cp gs col0 s gr
/Times-Bold-iso ff 180.00 scf sf
4590 405 m
gs 1 -1 sc (main) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
4590 585 m
gs 1 -1 sc (program control) col0 sh gr
% Polyline
n 4275 2250 m 5805 2250 l 5805 1620 l 4275 1620 l
cp gs col0 s gr
/Times-Bold-iso ff 180.00 scf sf
4365 1800 m
gs 1 -1 sc (video_output) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
4365 1980 m
gs 1 -1 sc (pictures rendering) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
4365 2160 m
gs 1 -1 sc (and displaying) col0 sh gr
% Polyline
gs clippath
4695 2625 m 4755 2625 l 4755 2474 l 4725 2594 l 4695 2474 l cp
eoclip
n 4725 2250 m
4725 2610 l gs col4 s gr gr
% arrowhead
n 4695 2474 m 4725 2594 l 4755 2474 l 4695 2474 l cp gs col4 1.00 shd ef gr col4 s
% Polyline
gs clippath
4785 2625 m 4845 2625 l 4845 2474 l 4815 2594 l 4785 2474 l cp
eoclip
n 4815 2250 m
4815 2610 l gs col0 s gr gr
% arrowhead
n 4785 2474 m 4815 2594 l 4845 2474 l 4785 2474 l cp gs 0.00 setgray ef gr col0 s
% Polyline
gs clippath
4875 2625 m 4935 2625 l 4935 2474 l 4905 2594 l 4875 2474 l cp
eoclip
n 4905 2250 m
4905 2610 l gs col2 s gr gr
% arrowhead
n 4875 2474 m 4905 2594 l 4935 2474 l 4875 2474 l cp gs col2 1.00 shd ef gr col2 s
% Polyline
n 4200 900 m 4095 900 4095 3135 105 arcto 4 {pop} repeat
4095 3240 5880 3240 105 arcto 4 {pop} repeat
5985 3240 5985 1005 105 arcto 4 {pop} repeat
5985 900 4200 900 105 arcto 4 {pop} repeat
cp gs col0 s gr
% Polyline
n 4275 3060 m 5805 3060 l 5805 2610 l 4275 2610 l
cp gs col0 s gr
/Times-Bold-iso ff 240.00 scf sf
4275 1170 m
gs 1 -1 sc (video_output) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
4275 1350 m
gs 1 -1 sc (pictures displaying) col0 sh gr
/Times-Bold-iso ff 180.00 scf sf
4365 2790 m
gs 1 -1 sc (vout plug-in) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
4365 2970 m
gs 1 -1 sc (Output driver) col0 sh gr
% Polyline
n 1080 6570 m 2700 6570 l 2700 6120 l 1080 6120 l
cp gs col0 s gr
/Times-Bold-iso ff 180.00 scf sf
1170 6300 m
gs 1 -1 sc (input) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
1170 6480 m
gs 1 -1 sc (file/network socket) col0 sh gr
% Polyline
n 2970 6570 m 4590 6570 l 4590 6120 l 2970 6120 l
cp gs col0 s gr
/Times-Bold-iso ff 180.00 scf sf
3060 6300 m
gs 1 -1 sc (input plug-in) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
3060 6480 m
gs 1 -1 sc (init, read and demux) col0 sh gr
% Polyline
n 4860 6570 m 6480 6570 l 6480 6120 l 4860 6120 l
cp gs col0 s gr
/Times-Bold-iso ff 180.00 scf sf
4950 6300 m
gs 1 -1 sc (programs) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
4950 6480 m
gs 1 -1 sc (stream management) col0 sh gr
% Polyline
n 1080 7290 m 2700 7290 l 2700 6840 l 1080 6840 l
cp gs col0 s gr
/Times-Bold-iso ff 180.00 scf sf
1170 7020 m
gs 1 -1 sc (input_ext-intf) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
1170 7200 m
gs 1 -1 sc (stream navigation) col0 sh gr
% Polyline
n 2970 7290 m 4590 7290 l 4590 6840 l 2970 6840 l
cp gs col0 s gr
/Times-Bold-iso ff 180.00 scf sf
3060 7020 m
gs 1 -1 sc (mpeg_system) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
3060 7200 m
gs 1 -1 sc (demultiplexer) col0 sh gr
% Polyline
n 4860 7290 m 6480 7290 l 6480 6840 l 4860 6840 l
cp gs col0 s gr
/Times-Bold-iso ff 180.00 scf sf
4950 7020 m
gs 1 -1 sc (clock) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
4950 7200 m
gs 1 -1 sc (time management) col0 sh gr
% Polyline
gs clippath
2985 6285 m 2985 6225 l 2834 6225 l 2954 6255 l 2834 6285 l cp
eoclip
n 2700 6255 m
2970 6255 l gs col4 s gr gr
% arrowhead
n 2834 6285 m 2954 6255 l 2834 6225 l 2834 6285 l cp gs col4 1.00 shd ef gr col4 s
% Polyline
gs clippath
4875 6285 m 4875 6225 l 4724 6225 l 4844 6255 l 4724 6285 l cp
eoclip
n 4590 6255 m
4860 6255 l gs col4 s gr gr
% arrowhead
n 4724 6285 m 4844 6255 l 4724 6225 l 4724 6285 l cp gs col4 1.00 shd ef gr col4 s
% Polyline
gs clippath
2985 6375 m 2985 6315 l 2834 6315 l 2954 6345 l 2834 6375 l cp
eoclip
n 2700 6345 m
2970 6345 l gs col0 s gr gr
% arrowhead
n 2834 6375 m 2954 6345 l 2834 6315 l 2834 6375 l cp gs 0.00 setgray ef gr col0 s
% Polyline
gs clippath
4875 6375 m 4875 6315 l 4724 6315 l 4844 6345 l 4724 6375 l cp
eoclip
n 4590 6345 m
4860 6345 l gs col0 s gr gr
% arrowhead
n 4724 6375 m 4844 6345 l 4724 6315 l 4724 6375 l cp gs 0.00 setgray ef gr col0 s
% Polyline
n 1005 5490 m 900 5490 900 7365 105 arcto 4 {pop} repeat
900 7470 6600 7470 105 arcto 4 {pop} repeat
6705 7470 6705 5595 105 arcto 4 {pop} repeat
6705 5490 1005 5490 105 arcto 4 {pop} repeat
cp gs col0 s gr
% Polyline
gs clippath
3615 6855 m 3675 6855 l 3675 6704 l 3645 6824 l 3615 6704 l cp
eoclip
n 3645 6570 m
3645 6840 l gs col1 s gr gr
% arrowhead
n 3615 6704 m 3645 6824 l 3675 6704 l 3615 6704 l cp gs col1 1.00 shd ef gr col1 s
% Polyline
gs clippath
4875 7095 m 4875 7035 l 4724 7035 l 4844 7065 l 4724 7095 l cp
eoclip
n 4590 7065 m
4860 7065 l gs col1 s gr gr
% arrowhead
n 4724 7095 m 4844 7065 l 4724 7035 l 4724 7095 l cp gs col1 1.00 shd ef gr col1 s
/Times-Bold-iso ff 240.00 scf sf
1080 5760 m
gs 1 -1 sc (input) col0 sh gr
% Polyline
n 4275 4635 m 5805 4635 l 5805 4185 l 4275 4185 l
cp gs col0 s gr
/Times-Roman-iso ff 180.00 scf sf
4365 4545 m
gs 1 -1 sc (ES decoder) col0 sh gr
/Times-Bold-iso ff 180.00 scf sf
4365 4365 m
gs 1 -1 sc (video_decoder) col0 sh gr
% Polyline
n 6885 2250 m 8505 2250 l 8505 1620 l 6885 1620 l
cp gs col0 s gr
/Times-Bold-iso ff 180.00 scf sf
6975 1800 m
gs 1 -1 sc (audio_output) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
6975 1980 m
gs 1 -1 sc (audio frames mixer) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
6975 2160 m
gs 1 -1 sc (and player) col0 sh gr
% Polyline
gs clippath
7305 2625 m 7365 2625 l 7365 2474 l 7335 2594 l 7305 2474 l cp
eoclip
n 7335 2250 m
7335 2610 l gs col4 s gr gr
% arrowhead
n 7305 2474 m 7335 2594 l 7365 2474 l 7305 2474 l cp gs col4 1.00 shd ef gr col4 s
% Polyline
gs clippath
7395 2625 m 7455 2625 l 7455 2474 l 7425 2594 l 7395 2474 l cp
eoclip
n 7425 2250 m
7425 2610 l gs col0 s gr gr
% arrowhead
n 7395 2474 m 7425 2594 l 7455 2474 l 7395 2474 l cp gs 0.00 setgray ef gr col0 s
% Polyline
n 6810 900 m 6705 900 6705 3135 105 arcto 4 {pop} repeat
6705 3240 8580 3240 105 arcto 4 {pop} repeat
8685 3240 8685 1005 105 arcto 4 {pop} repeat
8685 900 6810 900 105 arcto 4 {pop} repeat
cp gs col0 s gr
% Polyline
n 6885 3060 m 8325 3060 l 8325 2610 l 6885 2610 l
cp gs col0 s gr
/Times-Bold-iso ff 240.00 scf sf
6885 1170 m
gs 1 -1 sc (audio_output) col0 sh gr
/Times-Bold-iso ff 180.00 scf sf
6975 2790 m
gs 1 -1 sc (aout plug-in) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
6975 2970 m
gs 1 -1 sc (output driver) col0 sh gr
% Polyline
n 6885 4635 m 8505 4635 l 8505 4185 l 6885 4185 l
cp gs col0 s gr
/Times-Bold-iso ff 180.00 scf sf
6975 4365 m
gs 1 -1 sc (audio_decoder) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
6975 4545 m
gs 1 -1 sc (ES decoder) col0 sh gr
% Polyline
gs clippath
6900 2100 m 6900 2040 l 6749 2040 l 6869 2070 l 6749 2100 l cp
eoclip
n 6885 4275 m 6345 4275 l 6345 2070 l
6885 2070 l gs col1 s gr gr
% arrowhead
n 6749 2100 m 6869 2070 l 6749 2040 l 6749 2100 l cp gs col1 1.00 shd ef gr col1 s
% Polyline
gs clippath
6900 2010 m 6900 1950 l 6749 1950 l 6869 1980 l 6749 2010 l cp
eoclip
n 6885 4365 m 6255 4365 l 6255 1980 l
6885 1980 l gs col2 s gr gr
% arrowhead
n 6749 2010 m 6869 1980 l 6749 1950 l 6749 2010 l cp gs col2 1.00 shd ef gr col2 s
% Polyline
n 6810 3465 m 6705 3465 6705 4710 105 arcto 4 {pop} repeat
6705 4815 8580 4815 105 arcto 4 {pop} repeat
8685 4815 8685 3570 105 arcto 4 {pop} repeat
8685 3465 6810 3465 105 arcto 4 {pop} repeat
cp gs col0 s gr
% Polyline
gs clippath
1095 6285 m 1095 6225 l 944 6225 l 1064 6255 l 944 6285 l cp
eoclip
n 1080 1800 m 675 1800 l 675 6255 l
1080 6255 l gs col2 s gr gr
% arrowhead
n 944 6285 m 1064 6255 l 944 6225 l 944 6285 l cp gs col2 1.00 shd ef gr col2 s
% Polyline
gs clippath
2220 1635 m 2280 1635 l 2280 1484 l 2250 1604 l 2220 1484 l cp
eoclip
n 4500 360 m 2250 360 l
2250 1620 l gs col2 s gr gr
% arrowhead
n 2220 1484 m 2250 1604 l 2280 1484 l 2220 1484 l cp gs col2 1.00 shd ef gr col2 s
% Polyline
gs clippath
1500 6135 m 1560 6135 l 1560 5984 l 1530 6104 l 1500 5984 l cp
eoclip
n 1530 3645 m
1530 6120 l gs col4 s gr gr
% arrowhead
n 1500 5984 m 1530 6104 l 1560 5984 l 1500 5984 l cp gs col4 1.00 shd ef gr col4 s
% Polyline
gs clippath
4290 1920 m 4290 1860 l 4139 1860 l 4259 1890 l 4139 1920 l cp
eoclip
n 4275 4410 m 3645 4410 l 3645 1890 l
4275 1890 l gs col2 s gr gr
% arrowhead
n 4139 1920 m 4259 1890 l 4139 1860 l 4139 1920 l cp gs col2 1.00 shd ef gr col2 s
% Polyline
gs clippath
4290 2010 m 4290 1950 l 4139 1950 l 4259 1980 l 4139 2010 l cp
eoclip
n 4275 4320 m 3735 4320 l 3735 1980 l
4275 1980 l gs col1 s gr gr
% arrowhead
n 4139 2010 m 4259 1980 l 4139 1950 l 4139 2010 l cp gs col1 1.00 shd ef gr col1 s
% Polyline
gs clippath
4290 1830 m 4290 1770 l 4139 1770 l 4259 1800 l 4139 1830 l cp
eoclip
n 4275 4500 m 3555 4500 l 3555 1800 l
4275 1800 l gs col4 s gr gr
% arrowhead
n 4139 1830 m 4259 1800 l 4139 1770 l 4139 1830 l cp gs col4 1.00 shd ef gr col4 s
% Polyline
gs clippath
7710 1635 m 7770 1635 l 7770 1484 l 7740 1604 l 7710 1484 l cp
eoclip
n 5850 450 m 7740 450 l
7740 1620 l gs col4 s gr gr
% arrowhead
n 7710 1484 m 7740 1604 l 7770 1484 l 7710 1484 l cp gs col4 1.00 shd ef gr col4 s
% Polyline
gs clippath
7800 1635 m 7860 1635 l 7860 1484 l 7830 1604 l 7800 1484 l cp
eoclip
n 5850 360 m 7830 360 l
7830 1620 l gs col2 s gr gr
% arrowhead
n 7800 1484 m 7830 1604 l 7860 1484 l 7800 1484 l cp gs col2 1.00 shd ef gr col2 s
% Polyline
gs clippath
1095 7050 m 1095 6990 l 944 6990 l 1064 7020 l 944 7050 l cp
eoclip
n 1080 1710 m 585 1710 l 585 7020 l
1080 7020 l gs col0 s gr gr
% arrowhead
n 944 7050 m 1064 7020 l 944 6990 l 944 7050 l cp gs 0.00 setgray ef gr col0 s
% Polyline
gs clippath
5160 4620 m 5100 4620 l 5100 4771 l 5130 4651 l 5160 4771 l cp
eoclip
n 5130 6120 m
5130 4635 l gs col2 s gr gr
% arrowhead
n 5160 4771 m 5130 4651 l 5100 4771 l 5160 4771 l cp gs col2 1.00 shd ef gr col2 s
% Polyline
gs clippath
5250 4620 m 5190 4620 l 5190 4771 l 5220 4651 l 5250 4771 l cp
eoclip
n 5220 6120 m
5220 4635 l gs col4 s gr gr
% arrowhead
n 5250 4771 m 5220 4651 l 5190 4771 l 5250 4771 l cp gs col4 1.00 shd ef gr col4 s
% Polyline
gs clippath
5340 4620 m 5280 4620 l 5280 4771 l 5310 4651 l 5340 4771 l cp
eoclip
n 5310 6120 m
5310 4635 l gs col1 s gr gr
% arrowhead
n 5340 4771 m 5310 4651 l 5280 4771 l 5340 4771 l cp gs col1 1.00 shd ef gr col1 s
% Polyline
n 4200 3465 m 4095 3465 4095 4710 105 arcto 4 {pop} repeat
4095 4815 5880 4815 105 arcto 4 {pop} repeat
5985 4815 5985 3570 105 arcto 4 {pop} repeat
5985 3465 4200 3465 105 arcto 4 {pop} repeat
cp gs col0 s gr
% Polyline
gs clippath
7455 4620 m 7395 4620 l 7395 4771 l 7425 4651 l 7455 4771 l cp
eoclip
n 5670 6120 m 5670 5175 l 7425 5175 l
7425 4635 l gs col2 s gr gr
% arrowhead
n 7455 4771 m 7425 4651 l 7395 4771 l 7455 4771 l cp gs col2 1.00 shd ef gr col2 s
% Polyline
gs clippath
7545 4620 m 7485 4620 l 7485 4771 l 7515 4651 l 7545 4771 l cp
eoclip
n 5760 6120 m 5760 5265 l 7515 5265 l
7515 4635 l gs col4 s gr gr
% arrowhead
n 7545 4771 m 7515 4651 l 7485 4771 l 7545 4771 l cp gs col4 1.00 shd ef gr col4 s
% Polyline
gs clippath
7635 4620 m 7575 4620 l 7575 4771 l 7605 4651 l 7635 4771 l cp
eoclip
n 5850 6120 m 5850 5355 l 7605 5355 l
7605 4635 l gs col1 s gr gr
% arrowhead
n 7635 4771 m 7605 4651 l 7575 4771 l 7635 4771 l cp gs col1 1.00 shd ef gr col1 s
% Polyline
gs clippath
7350 6195 m 7350 6135 l 7199 6135 l 7319 6165 l 7199 6195 l cp
eoclip
n 6840 6165 m
7335 6165 l gs col2 s gr gr
% arrowhead
n 7199 6195 m 7319 6165 l 7199 6135 l 7199 6195 l cp gs col2 1.00 shd ef gr col2 s
% Polyline
gs clippath
7350 6465 m 7350 6405 l 7199 6405 l 7319 6435 l 7199 6465 l cp
eoclip
n 6840 6435 m
7335 6435 l gs col0 s gr gr
% arrowhead
n 7199 6465 m 7319 6435 l 7199 6405 l 7199 6465 l cp gs 0.00 setgray ef gr col0 s
% Polyline
gs clippath
7350 6735 m 7350 6675 l 7199 6675 l 7319 6705 l 7199 6735 l cp
eoclip
n 6840 6705 m
7335 6705 l gs col4 s gr gr
% arrowhead
n 7199 6735 m 7319 6705 l 7199 6675 l 7199 6735 l cp gs col4 1.00 shd ef gr col4 s
% Polyline
gs clippath
7350 7185 m 7350 7125 l 7199 7125 l 7319 7155 l 7199 7185 l cp
eoclip
n 6840 7155 m
7335 7155 l gs col1 s gr gr
% arrowhead
n 7199 7185 m 7319 7155 l 7199 7125 l 7199 7185 l cp gs col1 1.00 shd ef gr col1 s
/Times-Bold-iso ff 240.00 scf sf
1080 1170 m
gs 1 -1 sc (interface) col0 sh gr
/Times-Bold-iso ff 240.00 scf sf
4275 3735 m
gs 1 -1 sc (video_decoder) col0 sh gr
/Times-Bold-iso ff 240.00 scf sf
6930 3735 m
gs 1 -1 sc (audio_decoder) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
7470 6480 m
gs 1 -1 sc (manage) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
7470 6210 m
gs 1 -1 sc (store reference) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
7470 6750 m
gs 1 -1 sc (create/initialize/) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
7470 7200 m
gs 1 -1 sc (feed) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
7470 6975 m
gs 1 -1 sc (destroy) col0 sh gr
$F2psEnd
rs

244
doc/developer/modules.fig Normal file
View File

@ -0,0 +1,244 @@
#FIG 3.2
Landscape
Center
Metric
A4
100.00
Single
-2
1200 2
6 900 900 3150 3870
6 1080 1620 2880 2070
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
1080 2070 2880 2070 2880 1620 1080 1620 1080 2070
4 0 0 100 0 2 12 0.0000 4 135 735 1170 1800 interface\001
4 0 0 100 0 0 12 0.0000 4 180 1635 1170 1980 management and loop\001
-6
6 1080 2520 2520 2970
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
1080 2970 2520 2970 2520 2520 1080 2520 1080 2970
4 0 0 100 0 2 12 0.0000 4 180 660 1170 2700 intf_msg\001
4 0 0 100 0 0 12 0.0000 4 150 1290 1170 2880 messages output\001
-6
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
1530 2070 1530 2520
2 1 0 1 0 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
1620 2070 1620 2520
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
1080 3645 2835 3645 2835 3195 1080 3195 1080 3645
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
2655 2070 2655 3195
2 1 0 1 0 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
2745 2070 2745 3195
2 4 0 1 0 7 100 0 -1 0.000 0 0 7 0 0 5
3150 900 3150 3870 900 3870 900 900 3150 900
4 0 0 100 0 0 12 0.0000 4 180 1920 1080 1350 Manage threads and user\001
4 0 0 100 0 2 12 0.0000 4 180 570 1170 3375 playlist\001
4 0 0 100 0 0 12 0.0000 4 180 1560 1170 3555 playlist management\001
-6
6 4500 225 5850 675
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
4500 675 5850 675 5850 225 4500 225 4500 675
4 0 0 100 0 2 12 0.0000 4 135 375 4590 405 main\001
4 0 0 100 0 0 12 0.0000 4 180 1185 4590 585 program control\001
-6
6 4095 900 5985 3240
6 4275 1620 5805 2250
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
4275 2250 5805 2250 5805 1620 4275 1620 4275 2250
4 0 0 100 0 2 12 0.0000 4 180 1020 4365 1800 video_output\001
4 0 0 100 0 0 12 0.0000 4 180 1365 4365 1980 pictures rendering\001
4 0 0 100 0 0 12 0.0000 4 180 1080 4365 2160 and displaying\001
-6
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
4725 2250 4725 2610
2 1 0 1 0 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
4815 2250 4815 2610
2 1 0 1 2 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
4905 2250 4905 2610
2 4 0 1 0 7 100 0 -1 0.000 0 0 7 0 0 5
5985 900 5985 3240 4095 3240 4095 900 5985 900
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
4275 3060 5805 3060 5805 2610 4275 2610 4275 3060
4 0 0 100 0 2 16 0.0000 4 225 1380 4275 1170 video_output\001
4 0 0 100 0 0 12 0.0000 4 180 1425 4275 1350 pictures displaying\001
4 0 0 100 0 2 12 0.0000 4 180 945 4365 2790 vout plug-in\001
4 0 0 100 0 0 12 0.0000 4 180 1005 4365 2970 Output driver\001
-6
6 900 5490 6705 7470
6 1080 6120 2700 6570
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
1080 6570 2700 6570 2700 6120 1080 6120 1080 6570
4 0 0 100 0 2 12 0.0000 4 180 375 1170 6300 input\001
4 0 0 100 0 0 12 0.0000 4 135 1455 1170 6480 file/network socket\001
-6
6 2970 6120 4590 6570
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
2970 6570 4590 6570 4590 6120 2970 6120 2970 6570
4 0 0 100 0 2 12 0.0000 4 180 975 3060 6300 input plug-in\001
4 0 0 100 0 0 12 0.0000 4 165 1515 3060 6480 init, read and demux\001
-6
6 4860 6120 6480 6570
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
4860 6570 6480 6570 6480 6120 4860 6120 4860 6570
4 0 0 100 0 2 12 0.0000 4 135 765 4950 6300 programs\001
4 0 0 100 0 0 12 0.0000 4 150 1530 4950 6480 stream management\001
-6
6 1080 6840 2700 7290
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
1080 7290 2700 7290 2700 6840 1080 6840 1080 7290
4 0 0 100 0 2 12 0.0000 4 180 1080 1170 7020 input_ext-intf\001
4 0 0 100 0 0 12 0.0000 4 180 1350 1170 7200 stream navigation\001
-6
6 2970 6840 4590 7290
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
2970 7290 4590 7290 4590 6840 2970 6840 2970 7290
4 0 0 100 0 2 12 0.0000 4 165 1080 3060 7020 mpeg_system\001
4 0 0 100 0 0 12 0.0000 4 180 1020 3060 7200 demultiplexer\001
-6
6 4860 6840 6480 7290
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
4860 7290 6480 7290 6480 6840 4860 6840 4860 7290
4 0 0 100 0 2 12 0.0000 4 135 435 4950 7020 clock\001
4 0 0 100 0 0 12 0.0000 4 180 1335 4950 7200 time management\001
-6
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
2700 6255 2970 6255
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
4590 6255 4860 6255
2 1 0 1 0 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
2700 6345 2970 6345
2 1 0 1 0 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
4590 6345 4860 6345
2 4 0 1 0 7 100 0 -1 0.000 0 0 7 0 0 5
6705 5490 6705 7470 900 7470 900 5490 6705 5490
2 1 0 1 1 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
3645 6570 3645 6840
2 1 0 1 1 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
4590 7065 4860 7065
4 0 0 100 0 2 16 0.0000 4 225 570 1080 5760 input\001
-6
6 4275 4185 5805 4635
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
4275 4635 5805 4635 5805 4185 4275 4185 4275 4635
4 0 0 100 0 0 12 0.0000 4 135 870 4365 4545 ES decoder\001
4 0 0 100 0 2 12 0.0000 4 180 1185 4365 4365 video_decoder\001
-6
6 6255 900 8685 4815
6 6705 900 8685 3240
6 6885 1620 8505 2250
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
6885 2250 8505 2250 8505 1620 6885 1620 6885 2250
4 0 0 100 0 2 12 0.0000 4 180 1020 6975 1800 audio_output\001
4 0 0 100 0 0 12 0.0000 4 135 1440 6975 1980 audio frames mixer\001
4 0 0 100 0 0 12 0.0000 4 180 780 6975 2160 and player\001
-6
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
7335 2250 7335 2610
2 1 0 1 0 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
7425 2250 7425 2610
2 4 0 1 0 7 100 0 -1 0.000 0 0 7 0 0 5
8685 900 8685 3240 6705 3240 6705 900 8685 900
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
6885 3060 8325 3060 8325 2610 6885 2610 6885 3060
4 0 0 100 0 2 16 0.0000 4 225 1410 6885 1170 audio_output\001
4 0 0 100 0 2 12 0.0000 4 180 960 6975 2790 aout plug-in\001
4 0 0 100 0 0 12 0.0000 4 180 960 6975 2970 output driver\001
-6
6 6885 4185 8505 4635
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
6885 4635 8505 4635 8505 4185 6885 4185 6885 4635
4 0 0 100 0 2 12 0.0000 4 180 1185 6975 4365 audio_decoder\001
4 0 0 100 0 0 12 0.0000 4 135 870 6975 4545 ES decoder\001
-6
2 1 0 1 1 7 100 0 -1 0.000 0 0 -1 1 0 4
1 1 1.00 60.00 120.00
6885 4275 6345 4275 6345 2070 6885 2070
2 1 0 1 2 7 100 0 -1 0.000 0 0 -1 1 0 4
1 1 1.00 60.00 120.00
6885 4365 6255 4365 6255 1980 6885 1980
2 4 0 1 0 7 100 0 -1 0.000 0 0 7 0 0 5
8685 3465 8685 4815 6705 4815 6705 3465 8685 3465
-6
2 1 0 1 2 7 100 0 -1 0.000 0 0 -1 1 0 4
1 1 1.00 60.00 120.00
1080 1800 675 1800 675 6255 1080 6255
2 1 0 1 2 7 100 0 -1 0.000 0 0 -1 1 0 3
1 1 1.00 60.00 120.00
4500 360 2250 360 2250 1620
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
1530 3645 1530 6120
2 1 0 1 2 7 100 0 -1 0.000 0 0 -1 1 0 4
1 1 1.00 60.00 120.00
4275 4410 3645 4410 3645 1890 4275 1890
2 1 0 1 1 7 100 0 -1 0.000 0 0 -1 1 0 4
1 1 1.00 60.00 120.00
4275 4320 3735 4320 3735 1980 4275 1980
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 4
1 1 1.00 60.00 120.00
4275 4500 3555 4500 3555 1800 4275 1800
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 3
1 1 1.00 60.00 120.00
5850 450 7740 450 7740 1620
2 1 0 1 2 7 100 0 -1 0.000 0 0 -1 1 0 3
1 1 1.00 60.00 120.00
5850 360 7830 360 7830 1620
2 1 0 1 0 7 100 0 -1 0.000 0 0 -1 1 0 4
1 1 1.00 60.00 120.00
1080 1710 585 1710 585 7020 1080 7020
2 1 0 1 2 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
5130 6120 5130 4635
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
5220 6120 5220 4635
2 1 0 1 1 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
5310 6120 5310 4635
2 4 0 1 0 7 100 0 -1 0.000 0 0 7 0 0 5
5985 3465 5985 4815 4095 4815 4095 3465 5985 3465
2 1 0 1 2 7 100 0 -1 0.000 0 0 -1 1 0 4
1 1 1.00 60.00 120.00
5670 6120 5670 5175 7425 5175 7425 4635
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 4
1 1 1.00 60.00 120.00
5760 6120 5760 5265 7515 5265 7515 4635
2 1 0 1 1 7 100 0 -1 0.000 0 0 -1 1 0 4
1 1 1.00 60.00 120.00
5850 6120 5850 5355 7605 5355 7605 4635
2 1 0 1 2 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
6840 6165 7335 6165
2 1 0 1 0 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
6840 6435 7335 6435
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
6840 6705 7335 6705
2 1 0 1 1 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
6840 7155 7335 7155
4 0 0 100 0 2 16 0.0000 4 165 930 1080 1170 interface\001
4 0 0 100 0 2 16 0.0000 4 225 1485 4275 3735 video_decoder\001
4 0 0 100 0 2 16 0.0000 4 225 1515 6930 3735 audio_decoder\001
4 0 0 100 0 0 12 0.0000 4 135 585 7470 6480 manage\001
4 0 0 100 0 0 12 0.0000 4 135 1155 7470 6210 store reference\001
4 0 0 100 0 0 12 0.0000 4 135 1215 7470 6750 create/initialize/\001
4 0 0 100 0 0 12 0.0000 4 135 330 7470 7200 feed\001
4 0 0 50 0 0 12 0.0000 4 180 570 7470 6975 destroy\001

BIN
doc/developer/modules.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 262 KiB

240
doc/developer/overview.xml Normal file
View File

@ -0,0 +1,240 @@
<chapter> <title> VLC Overview </title>
<sect1> <title> Code modules </title>
<para>
The VLC code uses modules and plugins. A module is a group of compiled-in
C source files. They are linked against the main application at build time.
At present, these modules are :
</para>
<itemizedlist>
<listitem> <para> Interface : this is the entry point of the program. It manages
all user interactions and thread spawning. </para> </listitem>
<listitem> <para> Input : it opens the input socket, reads packets, parses
them and passes reconstituted elementary streams to the decoder(s).
</para> </listitem>
<listitem> <para> Video output : it initializes the video display. Then it
gets all pictures and subpictures (ie. subtitles) from the decoder(s),
optionally converts them to RGB format (from YUV), and displays them.
</para> </listitem>
<listitem> <para> Audio output : it initializes the audio mixer, ie.
finds the right playing frequency, and then resamples audio frames
received from the decoder(s). </para> </listitem>
<listitem> <para> Misc : miscellaneous utilities used in other modules.
This is the only module that will never launch a thread.
</para> </listitem>
<listitem> <para> ac3_decoder, audio_decoder, generic_decoder, lpcm_decoder,
spu_decoder, video_decoder, video_parser : decoders used by VLC to
decode different kinds of elementary stream data. [these are subject
to move to <filename> plugins/ </filename> in a forthcoming
version]</para> </listitem>
</itemizedlist>
<mediaobject>
<imageobject>
<imagedata fileref="modules.eps" format="EPS" scalefit="1" scale="80"/>
</imageobject>
<imageobject>
<imagedata fileref="modules.gif" format="GIF" />
</imageobject>
<textobject>
<phrase> Data flow between modules </phrase>
</textobject>
</mediaobject>
</sect1>
<sect1> <title> Plug-ins </title>
<para>
Plugins are located in the <filename> plugins/ </filename> subdirectory
and are loaded at runtime. Every plug-in
may offer different features that will best suit a particular file or
a particular environment. Besides, most portability works result in the writing
of an audio_output/video_output/interface plug-in to support a new
platform (eg. BeOS or MacOS X).
</para>
<para>
Plug-ins are loaded and unloaded dynamically by functions in
<filename> src/misc/modules.c </filename> and <filename> include/modules*.h
</filename>. The API for writing plugins will be discussed in a
following chapter.
</para>
<para>
Plugins can also be built into the VLC main application by changing the
<parameter> BUILTINS </parameter> line in <filename>
Makefile.opts</filename>.
</para>
</sect1>
<sect1> <title> Threads </title>
<sect2> <title> Thread management </title>
<para>
VLC is heavily multi-threaded. We chose against a single-thread approach
because decoder preemptibility and scheduling would be a mastermind (for
instance decoders and outputs have to be separated, otherwise it cannot
be warrantied that a frame will be played at the exact presentation
time), and
we currently have no plan to support a single-threaded client.
Multi-process decoders usually imply more overhead (problems of shared
memory) and communication between processes is harder.
</para>
<para>
Our threading structure is modeled on pthreads. However, for portability
reasons, we don't call <function>pthread_*</function> functions
directly, but use a similar wrapper, made of <function> vlc_thread_create,
vlc_thread_exit, vlc_thread_join, vlc_mutex_init, vlc_mutex_lock,
vlc_mutex_unlock, vlc_mutex_destroy, vlc_cond_init, vlc_cond_signal,
vlc_cond_wait, vlc_cond_destroy</function>, and structures <type>
vlc_thread_t, vlc_mutex_t, and vlc_cond_t</type>.
</para>
</sect2>
<sect2> <title> Synchronization </title>
<para>
Another key feature of VLC is that decoding and playing are asynchronous :
decoding is done by a *_decoder thread, playing is done by audio_output
or video_output thread. The design goal is to ensure that an audio or
video frame is played exactly at the right time, without blocking any
of the decoder threads. This leads to a complex communication structure
between the interface, the input, the decoders and the outputs.
</para>
<para>
Having several input and video_output threads reading multiple files at
the same time is permitted, despite the fact that the current interface
doesn't allow any way to do it [this is subject to change in the near
future]. Anyway the client has been written from the ground up
with this in mind. This also implies that a non-reentrant
library (including in particular LiViD's libac3) cannot be used.
</para>
<para>
Presentation Time Stamps located in the system layer of the stream are
passed to the decoders, and all resulting samples are dated accordingly.
The output layers are supposed to play them at the right time. Dates are
converted to microseconds ; an absolute date is the number of microseconds
since Epoch (Jan 1st 1970). The <type> mtime_t </type> type is a signed
64-bit integer.
</para>
<para>
The current date can be retrieved with <function> mdate()</function>.
Te execution of a thread can be suspended until a certain <parameter>
date </parameter> via <function> mwait </function> <parameter>
( mtime_t date )</parameter>. You can sleep for a fixed number of
microseconds with <function> msleep </function> <parameter>
( mtime_t delay )</parameter>.
</para>
<warning> <para>
Please remember to wake up a little while <emphasis> before
</emphasis> the presentation date, if some particular treatment
needs to be done (e.g. a YUV transform). For instance in <filename>
src/video_parser/vpar_synchro.c</filename>, track of the average
decoding times is kept to ensure pictures are not decoded too
late.
</para> </warning>
</sect2>
</sect1>
<sect1> <title> Code conventions </title>
<sect2> <title> Function naming </title>
<para>
All functions are named accordingly : module name (in lower case) + _ +
function name (in mixed case, <emphasis> without underscores</emphasis>).
For instance : <function>intf_FooFunction</function>. Static functions
don't need usage of the module name.
</para>
</sect2>
<sect2> <title> Variable naming </title>
<para>
Hungarian notations used, that means we have the following prefixes :
</para>
<itemizedlist>
<listitem> <para> i_ for integers (sometimes l_ for long integers) ;
</para> </listitem>
<listitem> <para> b_ for booleans ; </para> </listitem>
<listitem> <para> d_ for doubles (sometimes f_ for floats) ;
</para> </listitem>
<listitem> <para> pf_ for function pointers ; </para> </listitem>
<listitem> <para> psz_ for a Pointer to a String terminated by a
Zero (C-string) ;
</para> </listitem>
<listitem> <para> More generally, we add a p when the variable is
a pointer to a type. </para> </listitem>
</itemizedlist>
<para>
If one variable has no basic type (for instance a complex structure), don't
put any prefix (except p_* if it's a pointer). After one prefix, put
an <emphasis> explicit </emphasis> variable name <emphasis> in lower
case</emphasis>. If several words are required, join them with an
underscore (no mixed case). Examples :
</para>
<itemizedlist>
<listitem> <para>
<type> data_packet_t * </type> <varname> p_buffer; </varname>
</para> </listitem> <listitem> <para>
<type> char </type> <varname> psz_msg_date[42]; </varname>
</para> </listitem> <listitem> <para>
<type> int </type> <varname> pi_es_refcount[MAX_ES]; </varname>
</para> </listitem> <listitem> <para>
<type> void </type> <varname> (* pf_next_data_packet)( int * ); </varname>
</para> </listitem>
</itemizedlist>
</sect2>
<sect2> <title> A few words about white spaces </title>
<para>
First, never use tabs in the source (you're entitled to use them in the
Makefile :-). Use <command> set expandtab </command> under <application>
vim </application> or the equivalent under <application>
emacs</application>. Indents are 4 spaces long.
</para>
<para>
Second, put spaces <emphasis> before and after </emphasis> operators, and
inside brackets. For instance :
<programlisting> for( i = 0; i &lt; 12; i++, j += 42 ); </programlisting>
</para>
<para>
Third, leave braces alone on their lines (GNU style). For instance :
<programlisting>
if( i_es == 42 )
{
p_buffer[0] = 0x12;
}
</programlisting>
</para>
<para>
We write C, so use C-style comments /* ... */.
</para>
</sect2>
</sect1>
</chapter>

159
doc/developer/ports.xml Normal file
View File

@ -0,0 +1,159 @@
<appendix> <title> Ports </title>
<sect1> <title> Port steps </title>
<para>
Basically, porting to a new architecture boils down to follow the
following steps :
</para>
<orderedlist>
<listitem> <para> <emphasis> Building the VLC : </emphasis>
That may be the most difficult part, depending on how POSIX
the architecture is. You have to produce valid C.
</para> </listitem>
<listitem> <para> <emphasis> Having video : </emphasis>
If your architecture features an X server, it should be
straightforward, though you might have problems with xvideo
or xshm. Otherwise you can try to use SDL if it is supported,
or end up writing your own video output plugin.
</para> </listitem>
<listitem> <para> <emphasis> Having audio : </emphasis>
If your architecture features an OSS compatible DSP or ALSA, you
can reuse an existing plugin. Otherwise you will have to write
your own audio output plugin.
</para> </listitem>
<listitem> <para> <emphasis> Accessing DVDs : </emphasis>
You are going to need a write access to the DVD device.
Every system has specific ioctl() for key negociation with
the DVD drive, so we have set up an abstration layer in
<filename> plugins/dvd/dvd_ioctl.c</filename>. You might
need to add stuff here. Some operating systems won't give
you access to the key negociation (MacOS X), so you will
have to write a kernel extension or you will only be able to read
unencrypted DVDs. Other operating systems might only give
you read access to the DVD device if you are root. Your mileage
may vary.
</para> </listitem>
<listitem> <para> <emphasis> Writing a native interface : </emphasis>
If your system doesn't support GTK or Qt, you will have to
write a native interface plugin (for instance Aqua or Win32).
You may also need to rewrite the video output plugin if
you're currently using a slow compatibility layer.
</para> </listitem>
<listitem> <para> <emphasis> Optimizing : </emphasis>
If your architecture features a special set of multimedia
instructions (such as MMX) that is not supported by VLC, you
may want to write specific optimizations. Heavy calculation
parts are : IDCT (see idct plugin), motion compensation
(see motion plugin), and YUV (see video output) if you don't
use the YUV overlay support of your video board (SDL or
XVideo extension).
</para> </listitem>
</orderedlist>
</sect1>
<sect1> <title> Building </title>
<para>
This is probably the most complicated part. If your platform is fully
POSIX-compliant (such as GNU/Linux), it should be quick, otherwise
expect troubles. Known issues are :
</para>
<itemizedlist>
<listitem> <para> Finding a compiler : We use <application> gcc
</application> on all platforms, and <application> mingw32
</application> to cross-compile the win32 port. If you don't you're
probably in <emphasis> very big </emphasis> trouble. Good luck.
</para> </listitem>
<listitem> <para> Finding <application> GNU make </application> : Our
<filename>Makefile</filename> is heavily <application>GNU make
</application> specific, so I suggest you install it.
</para> </listitem>
<listitem> <para> Running the <filename> configure </filename>
script : This is basically a shell script, so if you have a UNIX
shell on your platform it shouldn't be a problem. It will probe
your system for headers and libraries needed. It needs
adequate <filename> config.sub </filename> and <filename>
config.guess</filename>, so if your platform is young your
provider may have supplied customized versions. Check with it.
</para> </listitem>
<listitem> <para> Compiling the VLC binary : This is the most
difficult. Type <command> make </command> or <command> gmake
</command> and watch the results. It will probably break soon
on a parse error. Add the headers missing, fix mistakes. If
you cannot make it to also compiles on other platforms, use
#ifdef directives. Add tests for functions or libraries in
<filename> configure.in </filename> and run <command> autoheader
</command> and <command> autoconf</command>. Always prefer
tests on <property> #ifdef HAVE_MY_HEADER_T</property>,
instead of <property> #ifdef SYS_MYOPERATINGSYSTEM</property>.
You may especially experience problems with the network code
in <filename> src/input/input.c</filename>.
</para> </listitem>
<listitem> <para> Threads : If your system has an exotic thread
implementation, you will probably need to fill the wrappers in
<filename> include/threads.h </filename> for your system.
Currently supported implementations include the POSIX pthreads,
the BeOS threads, and the Mach cthreads.
</para> </listitem>
<listitem> <para> Linking : You will need special flags to the
compiler, to allow symbol exports (otherwise plug-ins won't
work). For instance under GNU/Linux you need <parameter>
-rdynamic</parameter>.
</para> </listitem>
<listitem> <para> Compiling plug-ins : You do not need external
plug-ins at first, you can build all you need in (see <filename>
Makefile.opts</filename>). In the long run though, it is a
good idea to change <parameter> PCFLAGS</parameter> and <parameter>
PLCFLAGS</parameter> to allow run-time loading of libraries.
You are going to need <application> libdl</application>, or a
similar dynamic loader. To add support for an exotic dynamic
loader, have a look at <filename> include/modules_core.h
</filename>. Currently supported implementations include the
UNIX dynamic loader and the BeOS image loader.
</para> </listitem>
<listitem> <para> Assembling : If you use specific optimizations
(such as MMX), you may have problem assembling files, because
the assembler syntax may be different on your platform. Try
without it at first. Pay attention to the optimization flags
too, you may see a <emphasis>huge</emphasis> difference.
</para> </listitem>
</itemizedlist>
<para>
VLC should work both on little endian and big endian systems. All
load operations should be aligned on the native size of the type, so
that it works on exotic processors like Sparc or Alpha. It should
work on 64-bit platforms, though it has not been optimized for it.
A big boost for them would be to have a WORD_TYPE = u64 in <filename>
include/input_ext-dec.h</filename>, but it is currently broken for
unknown reasons.
</para>
<para>
If you experience run-time problems, see the following appendix and
pray for you to have <command> gdb</command>...
</para>
</sect1>
</appendix>

173
doc/developer/ps.eps Normal file
View File

@ -0,0 +1,173 @@
%!PS-Adobe-2.0 EPSF-2.0
%%Title: ps.eps
%%Creator: fig2dev Version 3.2 Patchlevel 3a
%%CreationDate: Fri May 4 16:12:26 2001
%%For: cmassiot@salomon (Christophe Massiot,,,)
%%BoundingBox: 0 0 399 164
%%Magnification: 1.0000
%%EndComments
/$F2psDict 200 dict def
$F2psDict begin
$F2psDict /mtrx matrix put
/col-1 {0 setgray} bind def
/col0 {0.000 0.000 0.000 srgb} bind def
/col1 {0.000 0.000 1.000 srgb} bind def
/col2 {0.000 1.000 0.000 srgb} bind def
/col3 {0.000 1.000 1.000 srgb} bind def
/col4 {1.000 0.000 0.000 srgb} bind def
/col5 {1.000 0.000 1.000 srgb} bind def
/col6 {1.000 1.000 0.000 srgb} bind def
/col7 {1.000 1.000 1.000 srgb} bind def
/col8 {0.000 0.000 0.560 srgb} bind def
/col9 {0.000 0.000 0.690 srgb} bind def
/col10 {0.000 0.000 0.820 srgb} bind def
/col11 {0.530 0.810 1.000 srgb} bind def
/col12 {0.000 0.560 0.000 srgb} bind def
/col13 {0.000 0.690 0.000 srgb} bind def
/col14 {0.000 0.820 0.000 srgb} bind def
/col15 {0.000 0.560 0.560 srgb} bind def
/col16 {0.000 0.690 0.690 srgb} bind def
/col17 {0.000 0.820 0.820 srgb} bind def
/col18 {0.560 0.000 0.000 srgb} bind def
/col19 {0.690 0.000 0.000 srgb} bind def
/col20 {0.820 0.000 0.000 srgb} bind def
/col21 {0.560 0.000 0.560 srgb} bind def
/col22 {0.690 0.000 0.690 srgb} bind def
/col23 {0.820 0.000 0.820 srgb} bind def
/col24 {0.500 0.190 0.000 srgb} bind def
/col25 {0.630 0.250 0.000 srgb} bind def
/col26 {0.750 0.380 0.000 srgb} bind def
/col27 {1.000 0.500 0.500 srgb} bind def
/col28 {1.000 0.630 0.630 srgb} bind def
/col29 {1.000 0.750 0.750 srgb} bind def
/col30 {1.000 0.880 0.880 srgb} bind def
/col31 {1.000 0.840 0.000 srgb} bind def
end
save
newpath 0 164 moveto 0 0 lineto 399 0 lineto 399 164 lineto closepath clip newpath
-27.0 171.0 translate
1 -1 scale
/cp {closepath} bind def
/ef {eofill} bind def
/gr {grestore} bind def
/gs {gsave} bind def
/sa {save} bind def
/rs {restore} bind def
/l {lineto} bind def
/m {moveto} bind def
/rm {rmoveto} bind def
/n {newpath} bind def
/s {stroke} bind def
/sh {show} bind def
/slc {setlinecap} bind def
/slj {setlinejoin} bind def
/slw {setlinewidth} bind def
/srgb {setrgbcolor} bind def
/rot {rotate} bind def
/sc {scale} bind def
/sd {setdash} bind def
/ff {findfont} bind def
/sf {setfont} bind def
/scf {scalefont} bind def
/sw {stringwidth} bind def
/tr {translate} bind def
/tnt {dup dup currentrgbcolor
4 -2 roll dup 1 exch sub 3 -1 roll mul add
4 -2 roll dup 1 exch sub 3 -1 roll mul add
4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb}
bind def
/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
4 -2 roll mul srgb} bind def
/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
/$F2psEnd {$F2psEnteredState restore end} def
$F2psBegin
%%Page: 1 1
10 setmiterlimit
0.06299 0.06299 sc
% Polyline
7.500 slw
n 450 135 m 6750 135 l 6750 2295 l 450 2295 l
cp gs col0 s gr
% Polyline
n 900 405 m 1800 405 l 1800 900 l 900 900 l
cp gs col7 0.95 shd ef gr gs col0 s gr
% Polyline
n 1800 405 m 2790 405 l 2790 900 l 1800 900 l
cp gs col7 0.90 shd ef gr gs col0 s gr
% Polyline
n 2790 405 m 6300 405 l 6300 900 l 2790 900 l
cp gs col0 s gr
% Polyline
n 900 405 m 630 405 l 630 900 l 900 900 l
cp gs col7 0.35 shd ef gr gs col0 s gr
% Polyline
n 6300 405 m 6570 405 l 6570 900 l 6300 900 l
cp gs col7 0.35 shd ef gr gs col0 s gr
% Polyline
gs clippath
660 930 m 600 930 l 600 1081 l 630 961 l 660 1081 l cp
eoclip
n 630 1350 m
630 945 l gs col0 s gr gr
% arrowhead
n 660 1081 m 630 961 l 600 1081 l 660 1081 l cp gs 0.00 setgray ef gr col0 s
% Polyline
gs clippath
2820 930 m 2760 930 l 2760 1081 l 2790 961 l 2820 1081 l cp
eoclip
n 2790 1395 m
2790 945 l gs col0 s gr gr
% arrowhead
n 2820 1081 m 2790 961 l 2760 1081 l 2820 1081 l cp gs 0.00 setgray ef gr col0 s
% Polyline
gs clippath
6330 930 m 6270 930 l 6270 1081 l 6300 961 l 6330 1081 l cp
eoclip
n 6300 1395 m
6300 945 l gs col0 s gr gr
% arrowhead
n 6330 1081 m 6300 961 l 6270 1081 l 6330 1081 l cp gs 0.00 setgray ef gr col0 s
% Polyline
gs clippath
6600 930 m 6540 930 l 6540 1081 l 6570 961 l 6600 1081 l cp
eoclip
n 6570 1710 m
6570 945 l gs col0 s gr gr
% arrowhead
n 6600 1081 m 6570 961 l 6540 1081 l 6600 1081 l cp gs 0.00 setgray ef gr col0 s
/Times-Roman ff 180.00 scf sf
990 720 m
gs 1 -1 sc (PS header) col0 sh gr
/Times-Roman ff 180.00 scf sf
1845 720 m
gs 1 -1 sc (PES header) col0 sh gr
/Times-Roman ff 180.00 scf sf
2970 720 m
gs 1 -1 sc (PES payload \(ES data\)) col0 sh gr
/Times-Roman ff 180.00 scf sf
585 1575 m
gs 1 -1 sc (p_buffer) col0 sh gr
/Times-Roman ff 180.00 scf sf
2745 1620 m
gs 1 -1 sc (p_payload_start) col0 sh gr
/Times-Roman ff 180.00 scf sf
5220 1575 m
gs 1 -1 sc (p_payload_end) col0 sh gr
/Times-Roman ff 180.00 scf sf
6615 1890 m
gs 1 -1 sc (p_buffer + i_size) dup sw pop neg 0 rm col0 sh gr
/Times-Roman ff 210.00 scf sf
2205 2025 m
gs 1 -1 sc (First \(and last\) data packet) col0 sh gr
/Times-Roman ff 210.00 scf sf
2835 2655 m
gs 1 -1 sc (PES packet) col0 sh gr
$F2psEnd
rs

42
doc/developer/ps.fig Normal file
View File

@ -0,0 +1,42 @@
#FIG 3.2
Landscape
Center
Metric
A4
100.00
Single
-2
1200 2
2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
450 135 6750 135 6750 2295 450 2295 450 135
2 2 0 1 0 7 50 0 19 0.000 0 0 -1 0 0 5
900 405 1800 405 1800 900 900 900 900 405
2 2 0 1 0 7 50 0 18 0.000 0 0 -1 0 0 5
1800 405 2790 405 2790 900 1800 900 1800 405
2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
2790 405 6300 405 6300 900 2790 900 2790 405
2 2 0 1 0 7 50 0 7 0.000 0 0 -1 0 0 5
900 405 630 405 630 900 900 900 900 405
2 2 0 1 0 7 50 0 7 0.000 0 0 -1 0 0 5
6300 405 6570 405 6570 900 6300 900 6300 405
2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
630 1350 630 945
2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
2790 1395 2790 945
2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
6300 1395 6300 945
2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
6570 1710 6570 945
4 0 0 50 0 0 12 0.0000 4 135 765 990 720 PS header\001
4 0 0 50 0 0 12 0.0000 4 135 885 1845 720 PES header\001
4 0 0 50 0 0 12 0.0000 4 180 1755 2970 720 PES payload (ES data)\001
4 0 0 50 0 0 12 0.0000 4 180 630 585 1575 p_buffer\001
4 0 0 50 0 0 12 0.0000 4 180 1215 2745 1620 p_payload_start\001
4 0 0 50 0 0 12 0.0000 4 180 1125 5220 1575 p_payload_end\001
4 2 0 50 0 0 12 0.0000 4 180 1275 6615 1890 p_buffer + i_size\001
4 0 0 50 0 0 14 0.0000 4 195 2295 2205 2025 First (and last) data packet\001
4 0 0 50 0 0 14 0.0000 4 195 1005 2835 2655 PES packet\001

BIN
doc/developer/ps.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 73 KiB

268
doc/developer/stream.eps Normal file
View File

@ -0,0 +1,268 @@
%!PS-Adobe-2.0 EPSF-2.0
%%Title: stream.eps
%%Creator: fig2dev Version 3.2 Patchlevel 3a
%%CreationDate: Wed May 2 18:55:53 2001
%%For: cmassiot@salomon (Christophe Massiot,,,)
%%BoundingBox: 0 0 323 476
%%Magnification: 1.0000
%%EndComments
/$F2psDict 200 dict def
$F2psDict begin
$F2psDict /mtrx matrix put
/col-1 {0 setgray} bind def
/col0 {0.000 0.000 0.000 srgb} bind def
/col1 {0.000 0.000 1.000 srgb} bind def
/col2 {0.000 1.000 0.000 srgb} bind def
/col3 {0.000 1.000 1.000 srgb} bind def
/col4 {1.000 0.000 0.000 srgb} bind def
/col5 {1.000 0.000 1.000 srgb} bind def
/col6 {1.000 1.000 0.000 srgb} bind def
/col7 {1.000 1.000 1.000 srgb} bind def
/col8 {0.000 0.000 0.560 srgb} bind def
/col9 {0.000 0.000 0.690 srgb} bind def
/col10 {0.000 0.000 0.820 srgb} bind def
/col11 {0.530 0.810 1.000 srgb} bind def
/col12 {0.000 0.560 0.000 srgb} bind def
/col13 {0.000 0.690 0.000 srgb} bind def
/col14 {0.000 0.820 0.000 srgb} bind def
/col15 {0.000 0.560 0.560 srgb} bind def
/col16 {0.000 0.690 0.690 srgb} bind def
/col17 {0.000 0.820 0.820 srgb} bind def
/col18 {0.560 0.000 0.000 srgb} bind def
/col19 {0.690 0.000 0.000 srgb} bind def
/col20 {0.820 0.000 0.000 srgb} bind def
/col21 {0.560 0.000 0.560 srgb} bind def
/col22 {0.690 0.000 0.690 srgb} bind def
/col23 {0.820 0.000 0.820 srgb} bind def
/col24 {0.500 0.190 0.000 srgb} bind def
/col25 {0.630 0.250 0.000 srgb} bind def
/col26 {0.750 0.380 0.000 srgb} bind def
/col27 {1.000 0.500 0.500 srgb} bind def
/col28 {1.000 0.630 0.630 srgb} bind def
/col29 {1.000 0.750 0.750 srgb} bind def
/col30 {1.000 0.880 0.880 srgb} bind def
/col31 {1.000 0.840 0.000 srgb} bind def
end
save
newpath 0 476 moveto 0 0 lineto 323 0 lineto 323 476 lineto closepath clip newpath
1.0 480.0 translate
1 -1 scale
/cp {closepath} bind def
/ef {eofill} bind def
/gr {grestore} bind def
/gs {gsave} bind def
/sa {save} bind def
/rs {restore} bind def
/l {lineto} bind def
/m {moveto} bind def
/rm {rmoveto} bind def
/n {newpath} bind def
/s {stroke} bind def
/sh {show} bind def
/slc {setlinecap} bind def
/slj {setlinejoin} bind def
/slw {setlinewidth} bind def
/srgb {setrgbcolor} bind def
/rot {rotate} bind def
/sc {scale} bind def
/sd {setdash} bind def
/ff {findfont} bind def
/sf {setfont} bind def
/scf {scalefont} bind def
/sw {stringwidth} bind def
/tr {translate} bind def
/tnt {dup dup currentrgbcolor
4 -2 roll dup 1 exch sub 3 -1 roll mul add
4 -2 roll dup 1 exch sub 3 -1 roll mul add
4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb}
bind def
/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
4 -2 roll mul srgb} bind def
/reencdict 12 dict def /ReEncode { reencdict begin
/newcodesandnames exch def /newfontname exch def /basefontname exch def
/basefontdict basefontname findfont def /newfont basefontdict maxlength dict def
basefontdict { exch dup /FID ne { dup /Encoding eq
{ exch dup length array copy newfont 3 1 roll put }
{ exch newfont 3 1 roll put } ifelse } { pop pop } ifelse } forall
newfont /FontName newfontname put newcodesandnames aload pop
128 1 255 { newfont /Encoding get exch /.notdef put } for
newcodesandnames length 2 idiv { newfont /Encoding get 3 1 roll put } repeat
newfontname newfont definefont pop end } def
/isovec [
8#055 /minus 8#200 /grave 8#201 /acute 8#202 /circumflex 8#203 /tilde
8#204 /macron 8#205 /breve 8#206 /dotaccent 8#207 /dieresis
8#210 /ring 8#211 /cedilla 8#212 /hungarumlaut 8#213 /ogonek 8#214 /caron
8#220 /dotlessi 8#230 /oe 8#231 /OE
8#240 /space 8#241 /exclamdown 8#242 /cent 8#243 /sterling
8#244 /currency 8#245 /yen 8#246 /brokenbar 8#247 /section 8#250 /dieresis
8#251 /copyright 8#252 /ordfeminine 8#253 /guillemotleft 8#254 /logicalnot
8#255 /hyphen 8#256 /registered 8#257 /macron 8#260 /degree 8#261 /plusminus
8#262 /twosuperior 8#263 /threesuperior 8#264 /acute 8#265 /mu 8#266 /paragraph
8#267 /periodcentered 8#270 /cedilla 8#271 /onesuperior 8#272 /ordmasculine
8#273 /guillemotright 8#274 /onequarter 8#275 /onehalf
8#276 /threequarters 8#277 /questiondown 8#300 /Agrave 8#301 /Aacute
8#302 /Acircumflex 8#303 /Atilde 8#304 /Adieresis 8#305 /Aring
8#306 /AE 8#307 /Ccedilla 8#310 /Egrave 8#311 /Eacute
8#312 /Ecircumflex 8#313 /Edieresis 8#314 /Igrave 8#315 /Iacute
8#316 /Icircumflex 8#317 /Idieresis 8#320 /Eth 8#321 /Ntilde 8#322 /Ograve
8#323 /Oacute 8#324 /Ocircumflex 8#325 /Otilde 8#326 /Odieresis 8#327 /multiply
8#330 /Oslash 8#331 /Ugrave 8#332 /Uacute 8#333 /Ucircumflex
8#334 /Udieresis 8#335 /Yacute 8#336 /Thorn 8#337 /germandbls 8#340 /agrave
8#341 /aacute 8#342 /acircumflex 8#343 /atilde 8#344 /adieresis 8#345 /aring
8#346 /ae 8#347 /ccedilla 8#350 /egrave 8#351 /eacute
8#352 /ecircumflex 8#353 /edieresis 8#354 /igrave 8#355 /iacute
8#356 /icircumflex 8#357 /idieresis 8#360 /eth 8#361 /ntilde 8#362 /ograve
8#363 /oacute 8#364 /ocircumflex 8#365 /otilde 8#366 /odieresis 8#367 /divide
8#370 /oslash 8#371 /ugrave 8#372 /uacute 8#373 /ucircumflex
8#374 /udieresis 8#375 /yacute 8#376 /thorn 8#377 /ydieresis] def
/Times-Roman /Times-Roman-iso isovec ReEncode
/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
/$F2psEnd {$F2psEnteredState restore end} def
$F2psBegin
%%Page: 1 1
10 setmiterlimit
0.06299 0.06299 sc
% Polyline
7.500 slw
n 1305 90 m 3915 90 l 3915 1170 l 1305 1170 l
cp gs col0 s gr
% Polyline
gs clippath
1001 3421 m 1056 3445 l 1116 3306 l 1042 3405 l 1061 3282 l cp
eoclip
n 1980 1215 m
1035 3420 l gs col0 s gr gr
% arrowhead
n 1061 3282 m 1042 3405 l 1116 3306 l col0 s
% Polyline
n 225 3465 m 1800 3465 l 1800 4275 l 225 4275 l
cp gs col0 s gr
% Polyline
gs clippath
373 6221 m 433 6228 l 450 6078 l 407 6194 l 391 6071 l cp
eoclip
n 630 4275 m
405 6210 l gs col0 s gr gr
% arrowhead
n 391 6071 m 407 6194 l 450 6078 l col0 s
% Polyline
n 0 6300 m 1845 6300 l 1845 7605 l 0 7605 l
cp gs col0 s gr
% Polyline
gs clippath
960 5640 m 1020 5640 l 1020 5488 l 990 5608 l 960 5488 l cp
eoclip
n 990 4275 m
990 5625 l gs col0 s gr gr
% arrowhead
n 960 5488 m 990 5608 l 1020 5488 l col0 s
% Polyline
n 720 5670 m 1260 5670 l 1260 5985 l 720 5985 l
cp gs col0 s gr
% Polyline
gs clippath
1638 5600 m 1697 5588 l 1667 5440 l 1662 5564 l 1608 5452 l cp
eoclip
n 1395 4275 m
1665 5580 l gs col0 s gr gr
% arrowhead
n 1608 5452 m 1662 5564 l 1667 5440 l col0 s
% Polyline
n 1440 5670 m 2025 5670 l 2025 5985 l 1440 5985 l
cp gs col0 s gr
% Polyline
gs clippath
4073 3400 m 4128 3377 l 4070 3237 l 4089 3360 l 4015 3260 l cp
eoclip
n 3195 1215 m
4095 3375 l gs col0 s gr gr
% arrowhead
n 4015 3260 m 4089 3360 l 4070 3237 l col0 s
% Polyline
n 3645 3375 m 4590 3375 l 4590 3780 l 3645 3780 l
cp gs col0 s gr
% Polyline
gs clippath
3387 5676 m 3445 5692 l 3483 5545 l 3424 5654 l 3425 5530 l cp
eoclip
n 3915 3780 m
3420 5670 l gs col0 s gr gr
% arrowhead
n 3425 5530 m 3424 5654 l 3483 5545 l col0 s
% Polyline
n 3060 5760 m 3690 5760 l 3690 6120 l 3060 6120 l
cp gs col0 s gr
% Polyline
gs clippath
4790 5692 m 4847 5676 l 4805 5530 l 4810 5654 l 4748 5546 l cp
eoclip
n 4275 3780 m
4815 5670 l gs col0 s gr gr
% arrowhead
n 4748 5546 m 4810 5654 l 4805 5530 l col0 s
% Polyline
n 4545 5760 m 5085 5760 l 5085 6120 l 4545 6120 l
cp gs col0 s gr
/Times-Roman-iso ff 180.00 scf sf
1485 360 m
gs 1 -1 sc (Stream :) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
1485 585 m
gs 1 -1 sc (- b_pace_control, b_seekable) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
1485 810 m
gs 1 -1 sc (- i_size, i_tell) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
1485 1035 m
gs 1 -1 sc (- control) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
360 3690 m
gs 1 -1 sc (Program 1 :) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
360 3915 m
gs 1 -1 sc (- synchro info) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
360 4140 m
gs 1 -1 sc (- p_vout, p_aout) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
90 6525 m
gs 1 -1 sc (ES 1 :) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
90 6750 m
gs 1 -1 sc (- audio, video or SPU) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
90 6975 m
gs 1 -1 sc (- ID) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
90 7200 m
gs 1 -1 sc (- i_type) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
90 7425 m
gs 1 -1 sc (- p_decoder_fifo) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
810 5895 m
gs 1 -1 sc (ES 2) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
1575 5895 m
gs 1 -1 sc (ES 3) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
3735 3645 m
gs 1 -1 sc (Program 2) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
3195 6030 m
gs 1 -1 sc (ES 4) col0 sh gr
/Times-Roman-iso ff 180.00 scf sf
4635 6030 m
gs 1 -1 sc (ES 5) col0 sh gr
$F2psEnd
rs

63
doc/developer/stream.fig Normal file
View File

@ -0,0 +1,63 @@
#FIG 3.2
Landscape
Center
Metric
A4
100.00
Single
-2
1200 2
2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
1305 90 3915 90 3915 1170 1305 1170 1305 90
2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
0 0 1.00 60.00 120.00
1980 1215 1035 3420
2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
225 3465 1800 3465 1800 4275 225 4275 225 3465
2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
0 0 1.00 60.00 120.00
630 4275 405 6210
2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
0 6300 1845 6300 1845 7605 0 7605 0 6300
2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
0 0 1.00 60.00 120.00
990 4275 990 5625
2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
720 5670 1260 5670 1260 5985 720 5985 720 5670
2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
0 0 1.00 60.00 120.00
1395 4275 1665 5580
2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
1440 5670 2025 5670 2025 5985 1440 5985 1440 5670
2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
0 0 1.00 60.00 120.00
3195 1215 4095 3375
2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
3645 3375 4590 3375 4590 3780 3645 3780 3645 3375
2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
0 0 1.00 60.00 120.00
3915 3780 3420 5670
2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
3060 5760 3690 5760 3690 6120 3060 6120 3060 5760
2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
0 0 1.00 60.00 120.00
4275 3780 4815 5670
2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
4545 5760 5085 5760 5085 6120 4545 6120 4545 5760
4 0 0 50 0 0 12 0.0000 4 135 630 1485 360 Stream :\001
4 0 0 50 0 0 12 0.0000 4 180 2250 1485 585 - b_pace_control, b_seekable\001
4 0 0 50 0 0 12 0.0000 4 180 1065 1485 810 - i_size, i_tell\001
4 0 0 50 0 0 12 0.0000 4 135 675 1485 1035 - control\001
4 0 0 50 0 0 12 0.0000 4 180 855 360 3690 Program 1 :\001
4 0 0 50 0 0 12 0.0000 4 180 1080 360 3915 - synchro info\001
4 0 0 50 0 0 12 0.0000 4 150 1260 360 4140 - p_vout, p_aout\001
4 0 0 50 0 0 12 0.0000 4 135 450 90 6525 ES 1 :\001
4 0 0 50 0 0 12 0.0000 4 165 1635 90 6750 - audio, video or SPU\001
4 0 0 50 0 0 12 0.0000 4 135 345 90 6975 - ID\001
4 0 0 50 0 0 12 0.0000 4 180 615 90 7200 - i_type\001
4 0 0 50 0 0 12 0.0000 4 180 1275 90 7425 - p_decoder_fifo\001
4 0 0 50 0 0 12 0.0000 4 135 360 810 5895 ES 2\001
4 0 0 50 0 0 12 0.0000 4 135 360 1575 5895 ES 3\001
4 0 0 50 0 0 12 0.0000 4 180 765 3735 3645 Program 2\001
4 0 0 50 0 0 12 0.0000 4 135 360 3195 6030 ES 4\001
4 0 0 50 0 0 12 0.0000 4 135 360 4635 6030 ES 5\001

BIN
doc/developer/stream.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 171 KiB

215
doc/developer/ts.eps Normal file
View File

@ -0,0 +1,215 @@
%!PS-Adobe-2.0 EPSF-2.0
%%Title: ts.eps
%%Creator: fig2dev Version 3.2 Patchlevel 3a
%%CreationDate: Fri May 4 16:43:24 2001
%%For: cmassiot@salomon (Christophe Massiot,,,)
%%BoundingBox: 0 0 422 181
%%Magnification: 1.0000
%%EndComments
/$F2psDict 200 dict def
$F2psDict begin
$F2psDict /mtrx matrix put
/col-1 {0 setgray} bind def
/col0 {0.000 0.000 0.000 srgb} bind def
/col1 {0.000 0.000 1.000 srgb} bind def
/col2 {0.000 1.000 0.000 srgb} bind def
/col3 {0.000 1.000 1.000 srgb} bind def
/col4 {1.000 0.000 0.000 srgb} bind def
/col5 {1.000 0.000 1.000 srgb} bind def
/col6 {1.000 1.000 0.000 srgb} bind def
/col7 {1.000 1.000 1.000 srgb} bind def
/col8 {0.000 0.000 0.560 srgb} bind def
/col9 {0.000 0.000 0.690 srgb} bind def
/col10 {0.000 0.000 0.820 srgb} bind def
/col11 {0.530 0.810 1.000 srgb} bind def
/col12 {0.000 0.560 0.000 srgb} bind def
/col13 {0.000 0.690 0.000 srgb} bind def
/col14 {0.000 0.820 0.000 srgb} bind def
/col15 {0.000 0.560 0.560 srgb} bind def
/col16 {0.000 0.690 0.690 srgb} bind def
/col17 {0.000 0.820 0.820 srgb} bind def
/col18 {0.560 0.000 0.000 srgb} bind def
/col19 {0.690 0.000 0.000 srgb} bind def
/col20 {0.820 0.000 0.000 srgb} bind def
/col21 {0.560 0.000 0.560 srgb} bind def
/col22 {0.690 0.000 0.690 srgb} bind def
/col23 {0.820 0.000 0.820 srgb} bind def
/col24 {0.500 0.190 0.000 srgb} bind def
/col25 {0.630 0.250 0.000 srgb} bind def
/col26 {0.750 0.380 0.000 srgb} bind def
/col27 {1.000 0.500 0.500 srgb} bind def
/col28 {1.000 0.630 0.630 srgb} bind def
/col29 {1.000 0.750 0.750 srgb} bind def
/col30 {1.000 0.880 0.880 srgb} bind def
/col31 {1.000 0.840 0.000 srgb} bind def
end
save
newpath 0 181 moveto 0 0 lineto 422 0 lineto 422 181 lineto closepath clip newpath
-27.0 188.0 translate
1 -1 scale
/cp {closepath} bind def
/ef {eofill} bind def
/gr {grestore} bind def
/gs {gsave} bind def
/sa {save} bind def
/rs {restore} bind def
/l {lineto} bind def
/m {moveto} bind def
/rm {rmoveto} bind def
/n {newpath} bind def
/s {stroke} bind def
/sh {show} bind def
/slc {setlinecap} bind def
/slj {setlinejoin} bind def
/slw {setlinewidth} bind def
/srgb {setrgbcolor} bind def
/rot {rotate} bind def
/sc {scale} bind def
/sd {setdash} bind def
/ff {findfont} bind def
/sf {setfont} bind def
/scf {scalefont} bind def
/sw {stringwidth} bind def
/tr {translate} bind def
/tnt {dup dup currentrgbcolor
4 -2 roll dup 1 exch sub 3 -1 roll mul add
4 -2 roll dup 1 exch sub 3 -1 roll mul add
4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb}
bind def
/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
4 -2 roll mul srgb} bind def
/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
/$F2psEnd {$F2psEnteredState restore end} def
$F2psBegin
%%Page: 1 1
10 setmiterlimit
0.06299 0.06299 sc
% Polyline
7.500 slw
n 765 405 m 1665 405 l 1665 900 l 765 900 l
cp gs col7 0.95 shd ef gr gs col0 s gr
% Polyline
n 1665 405 m 2655 405 l 2655 900 l 1665 900 l
cp gs col7 0.90 shd ef gr gs col0 s gr
% Polyline
gs clippath
2685 930 m 2625 930 l 2625 1081 l 2655 961 l 2685 1081 l cp
eoclip
n 2655 1395 m
2655 945 l gs col0 s gr gr
% arrowhead
n 2685 1081 m 2655 961 l 2625 1081 l 2685 1081 l cp gs 0.00 setgray ef gr col0 s
% Polyline
n 2655 405 m 4500 405 l 4500 900 l 2655 900 l
cp gs col0 s gr
% Polyline
n 4500 405 m 4680 405 l 4680 900 l 4500 900 l
cp gs col7 0.35 shd ef gr gs col0 s gr
% Polyline
gs clippath
660 930 m 600 930 l 600 1081 l 630 961 l 660 1081 l cp
eoclip
n 630 1350 m
630 945 l gs col0 s gr gr
% arrowhead
n 660 1081 m 630 961 l 600 1081 l 660 1081 l cp gs 0.00 setgray ef gr col0 s
% Polyline
gs clippath
4530 930 m 4470 930 l 4470 1081 l 4500 961 l 4530 1081 l cp
eoclip
n 4500 1395 m
4500 945 l gs col0 s gr gr
% arrowhead
n 4530 1081 m 4500 961 l 4470 1081 l 4530 1081 l cp gs 0.00 setgray ef gr col0 s
% Polyline
gs clippath
4710 930 m 4650 930 l 4650 1081 l 4680 961 l 4710 1081 l cp
eoclip
n 4680 1710 m
4680 945 l gs col0 s gr gr
% arrowhead
n 4710 1081 m 4680 961 l 4650 1081 l 4710 1081 l cp gs 0.00 setgray ef gr col0 s
/Times-Roman ff 180.00 scf sf
855 720 m
gs 1 -1 sc (TS header) col0 sh gr
/Times-Roman ff 180.00 scf sf
1710 720 m
gs 1 -1 sc (PES header) col0 sh gr
/Times-Roman ff 180.00 scf sf
2070 1575 m
gs 1 -1 sc (p_payload_start) col0 sh gr
/Times-Roman ff 180.00 scf sf
2700 720 m
gs 1 -1 sc (PES payload \(ES data\)) col0 sh gr
/Times-Roman ff 180.00 scf sf
585 1575 m
gs 1 -1 sc (p_buffer) col0 sh gr
/Times-Roman ff 180.00 scf sf
3420 1575 m
gs 1 -1 sc (p_payload_end) col0 sh gr
/Times-Roman ff 180.00 scf sf
4725 1890 m
gs 1 -1 sc (p_buffer + i_size) dup sw pop neg 0 rm col0 sh gr
% Polyline
n 765 405 m 630 405 l 630 900 l 765 900 l
cp gs col7 0.35 shd ef gr gs col0 s gr
% Polyline
n 5265 405 m 6930 405 l 6930 900 l 5265 900 l
cp gs col0 s gr
/Times-Roman ff 180.00 scf sf
5310 720 m
gs 1 -1 sc (PES payload \(cont'd\)) col0 sh gr
% Polyline
gs clippath
5055 660 m 5055 600 l 4904 600 l 5024 630 l 4904 660 l cp
eoclip
n 4680 630 m
5040 630 l gs col0 s gr gr
% arrowhead
n 4904 660 m 5024 630 l 4904 600 l 4904 660 l cp gs 0.00 setgray ef gr col0 s
% Polyline
n 5265 405 m 5085 405 l 5085 900 l 5265 900 l
cp gs col7 0.95 shd ef gr gs col0 s gr
% Polyline
n 5265 1575 m 5085 1575 l 5085 2070 l 5265 2070 l
cp gs col7 0.95 shd ef gr gs col0 s gr
% Polyline
n 5265 1575 m 6930 1575 l 6930 2070 l 5265 2070 l
cp gs col0 s gr
% Polyline
gs clippath
6810 1545 m 6870 1545 l 6870 1394 l 6840 1514 l 6810 1394 l cp
eoclip
n 6840 900 m
6840 1530 l gs col0 s gr gr
% arrowhead
n 6810 1394 m 6840 1514 l 6870 1394 l 6810 1394 l cp gs 0.00 setgray ef gr col0 s
% Polyline
n 450 135 m 7110 135 l 7110 2565 l 450 2565 l
cp gs col0 s gr
/Times-Roman ff 210.00 scf sf
1845 2340 m
gs 1 -1 sc (First data packet) col0 sh gr
/Times-Roman ff 210.00 scf sf
5040 1170 m
gs 1 -1 sc (Second data packet) col0 sh gr
/Times-Roman ff 180.00 scf sf
5400 1890 m
gs 1 -1 sc (PES payload \(end\)) col0 sh gr
/Times-Roman ff 210.00 scf sf
4590 2340 m
gs 1 -1 sc (Third \(and last\) data packet) col0 sh gr
/Times-Roman ff 210.00 scf sf
3330 2925 m
gs 1 -1 sc (PES packet) col0 sh gr
$F2psEnd
rs

66
doc/developer/ts.fig Normal file
View File

@ -0,0 +1,66 @@
#FIG 3.2
Landscape
Center
Metric
A4
100.00
Single
-2
1200 2
6 585 405 4725 1935
6 585 405 4725 1935
2 2 0 1 0 7 50 0 19 0.000 0 0 -1 0 0 5
765 405 1665 405 1665 900 765 900 765 405
2 2 0 1 0 7 50 0 18 0.000 0 0 -1 0 0 5
1665 405 2655 405 2655 900 1665 900 1665 405
2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
2655 1395 2655 945
2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
2655 405 4500 405 4500 900 2655 900 2655 405
2 2 0 1 0 7 50 0 7 0.000 0 0 -1 0 0 5
4500 405 4680 405 4680 900 4500 900 4500 405
2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
630 1350 630 945
2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
4500 1395 4500 945
2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
4680 1710 4680 945
4 0 0 50 0 0 12 0.0000 4 135 765 855 720 TS header\001
4 0 0 50 0 0 12 0.0000 4 135 885 1710 720 PES header\001
4 0 0 50 0 0 12 0.0000 4 180 1215 2070 1575 p_payload_start\001
4 0 0 50 0 0 12 0.0000 4 180 1755 2700 720 PES payload (ES data)\001
4 0 0 50 0 0 12 0.0000 4 180 630 585 1575 p_buffer\001
4 0 0 50 0 0 12 0.0000 4 180 1125 3420 1575 p_payload_end\001
4 2 0 50 0 0 12 0.0000 4 180 1275 4725 1890 p_buffer + i_size\001
-6
2 2 0 1 0 7 50 0 7 0.000 0 0 -1 0 0 5
765 405 630 405 630 900 765 900 765 405
-6
6 5265 405 6975 900
2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
5265 405 6930 405 6930 900 5265 900 5265 405
4 0 0 50 0 0 12 0.0000 4 180 1635 5310 720 PES payload (cont'd)\001
-6
2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
4680 630 5040 630
2 2 0 1 0 7 50 0 19 0.000 0 0 -1 0 0 5
5265 405 5085 405 5085 900 5265 900 5265 405
2 2 0 1 0 7 50 0 19 0.000 0 0 -1 0 0 5
5265 1575 5085 1575 5085 2070 5265 2070 5265 1575
2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
5265 1575 6930 1575 6930 2070 5265 2070 5265 1575
2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
6840 900 6840 1530
2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
450 135 7110 135 7110 2565 450 2565 450 135
4 0 0 50 0 0 14 0.0000 4 195 1440 1845 2340 First data packet\001
4 0 0 50 0 0 14 0.0000 4 195 1695 5040 1170 Second data packet\001
4 0 0 50 0 0 12 0.0000 4 180 1425 5400 1890 PES payload (end)\001
4 0 0 50 0 0 14 0.0000 4 195 2370 4590 2340 Third (and last) data packet\001
4 0 0 50 0 0 14 0.0000 4 195 1005 3330 2925 PES packet\001

BIN
doc/developer/ts.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 85 KiB

225
doc/developer/video_output.xml Normal file
View File

@ -0,0 +1,225 @@
<chapter> <title> The video output layer </title>
<sect1> <title> Data structures and main loop </title>
<para>
Important data structures are defined in <filename> include/video.h
</filename> and <filename> include/video_output.h</filename>. The main
data structure is <type> picture_t</type>, which describes everything a
video decoder thread needs. Please refer to this file for more
information. Typically, <parameter> p_data </parameter> will be a
pointer to YUV planar picture.
</para>
<para>
Note also the <type> subpicture_t </type> structure. In fact the VLC SPU
decoder only parses the SPU header, and converts the SPU graphical data
to an internal format which can be rendered much faster. So a part of
the "real" SPU decoder lies in
<filename> src/video_output/video_spu.c</filename>.
</para>
<para>
The <type> vout_thread_t </type> structure is much more complex, but
you needn't understand everything. Basically the video output thread
manages a heap of pictures and subpictures (5 by default). Every
picture has a status (displayed, destroyed, empty...) and eventually
a presentation time. The main job of the video output is an infinite
loop to : [this is subject to change in the near future]
</para>
<orderedlist>
<listitem> <para> Find the next picture to display in the heap.
</para> </listitem>
<listitem> <para> Find the current subpicture to display.
</para> </listitem>
<listitem> <para> Render the picture (if the video output plug-in
doesn't support YUV overlay). Rendering will call an optimized
YUV plug-in, which will also do the scaling, add subtitles and
an optional picture information field.
</para> </listitem>
<listitem> <para> Sleep until the specified date.
</para> </listitem>
<listitem> <para> Display the picture (plug-in function). For
outputs which display RGB data, it is often accomplished with
a buffer switching. <parameter> p_vout-&gt;p_buffer </parameter>
is an array of two buffers where the YUV transform takes place,
and p_vout-&gt;i_buffer_index indicates the currently displayed
buffer.
</para> </listitem>
<listitem> <para> Manage events.
</para> </listitem>
</orderedlist>
</sect1>
<sect1> <title> Methods used by video decoders </title>
<para>
The video output exports a bunch of functions so that decoders can send
their decoded data. The most important function is
<function>vout_CreatePicture</function> which allocates the picture
buffer to the size indicated by the video decoder. It then just needs
to feed <type> (void *) </type><parameter> p_picture-&gt;p_data </parameter>
with the decoded data, and call <function> vout_DisplayPicture </function>
and <function> vout_DatePicture </function> upon necessary.
</para>
<itemizedlist>
<listitem> <para> <type> picture_t * </type> <function>
vout_CreatePicture </function>
<parameter> ( vout_thread_t *p_vout, int i_type, int i_width,
int i_height ) </parameter> :
Returns an allocated picture buffer. <parameter> i_type </parameter>
will be for instance <constant> YUV_420_PICTURE</constant>, and
i_width and i_height are in pixels.
</para>
<warning> <para> If no picture is available in the heap,
<function> vout_CreatePicture </function> will return NULL.
</para> </warning>
</listitem>
<listitem> <para> <function> vout_LinkPicture </function>
<parameter> ( vout_thread_t *p_vout, picture_t *p_pic ) </parameter> :
Increases the refcount of the picture, so that it doesn't get
accidently freed while the decoder still needs it. For instance,
an I or P picture can still be needed after displaying to decode
interleaved B pictures.
</para> </listitem>
<listitem> <para> <function> vout_UnlinkPicture </function>
<parameter> ( vout_thread_t *p_vout, picture_t *p_pic ) </parameter> :
Decreases the refcount of the picture. An unlink must be done
for every link previously made.
</para> </listitem>
<listitem> <para> <function> vout_DatePicture </function>
<parameter> ( vout_thread_t *p_vout, picture_t *p_pic ) </parameter> :
Gives the picture a presentation date. You can start working on
a picture before knowing precisely at what time it will be
displayed. For instance to date an I or P picture, you must wait
until you have decoded all previous B pictures (which are
indeed placed after - decoding order != presentation order).
</para> </listitem>
<listitem> <para> <function> vout_DisplayPicture </function>
<parameter> ( vout_thread_t *p_vout, picture_t *p_pic ) </parameter> :
Tells the video output that a picture has been completely decoded
and is ready to be rendered. It can be called before or after
<function> vout_DatePicture</function>.
</para> </listitem>
<listitem> <para> <function> vout_DestroyPicture </function>
<parameter> ( vout_thread_t *p_vout, picture_t *p_pic ) </parameter> :
Marks the picture as empty (useful in case of a stream parsing
error).
</para> </listitem>
<listitem> <para> <type> subpicture_t * </type> <function>
vout_CreateSubPicture </function> <parameter> ( vout_thread_t *p_vout,
int i_type, int i_size ) </parameter> :
Returns an allocated subpicture buffer. <parameter> i_type
</parameter> is <constant> DVD_SUBPICTURE </constant> or
<constant> TEXT_SUBPICTURE</constant>, <parameter> i_size
</parameter> is the length in bytes of the packet.
</para> </listitem>
<listitem> <para> <function> vout_DisplaySubPicture </function>
<parameter> ( vout_thread_t *p_vout, subpicture_t *p_subpic )
</parameter> :
Tells the video output that a subpicture has been completely
decoded. It obsoletes the previous subpicture.
</para> </listitem>
<listitem> <para> <function> vout_DestroySubPicture </function>
<parameter> ( vout_thread_t *p_vout, subpicture_t *p_subpic )
</parameter> :
Marks the subpicture as empty.
</para> </listitem>
</itemizedlist>
</sect1>
<sect1> <title> How to write a video output plug-in </title>
<para>
A video output takes care of the system calls to display the pictures and
manage the output window. Have a look at <filename>
plugins/x11/vout_x11.c</filename>. You must write the following
functions :
</para>
<orderedlist>
<listitem> <para> <type> int </type> <function> vout_Probe </function>
<parameter> ( probedata_t *p_data ) </parameter> :
Returns a score between 0 and 999 to indicate whether it can
run on the architecture. 999 is the best. <parameter> p_data
</parameter> is currently unused.
</para> </listitem>
<listitem> <para> <type> int </type> <function> vout_Create </function>
<parameter> ( vout_thread_t *p_vout ) </parameter> :
Basically, initializes and opens a new window. Returns TRUE if
it failed.
</para> </listitem>
<listitem> <para> <type> int </type> <function> vout_Init </function>
<parameter> ( vout_thread_t *p_vout ) </parameter> :
Creates optional picture buffers (for instance ximages or
xvimages). Returns TRUE if it failed.
</para> </listitem>
<listitem> <para> <function> vout_End </function> <parameter>
( vout_thread_t *p_vout ) </parameter> :
Frees optional picture buffers.
</para> </listitem>
<listitem> <para> <function> vout_Destroy </function> <parameter>
( vout_thread_t *p_vout ) </parameter> :
Unmaps the window and frees all allocated resources.
</para> </listitem>
<listitem> <para> <type> int </type> <function> vout_Manage
</function> <parameter> ( vout_thread_t *p_vout ) </parameter> :
Manages events (including for instance resize events).
</para> </listitem>
<listitem> <para> <function> vout_Display </function> <parameter>
( vout_thread_t *p_vout ) </parameter> :
Displays a previously rendered buffer.
</para> </listitem>
<listitem> <para> <function> vout_SetPalette </function>
<parameter> ( vout_thread_t *p_vout, u16 *red, u16 *green,
u16 *blue, u16 *transp ) </parameter> :
Sets the 8 bpp palette. <parameter> red, green </parameter>
and <parameter> blue </parameter> are arrays of 256 <type>
unsigned shorts</type>.
</para> </listitem>
</orderedlist>
</sect1>
<sect1> <title> How to write a YUV plug-in </title>
<para>
Look at the C source <filename> plugins/yuv/transforms_yuv.c</filename>.
You need to redefine just the same transformations. Basically, it is a
matrix multiply operation. Good luck.
</para>
</sect1>
</chapter>

60
doc/main.tex
View File

@ -1,60 +0,0 @@
%
% main.tex: structure of the vlc LaTeX documentation
% (c)1999 VideoLAN
%
\documentclass[a4paper]{report}
%
% Packages and definitions
%
\usepackage{graphicx}
\include{common}
\newcommand{\VideoLAN}{\textit{Video}\textsc{lan}}
%
% Document
%
\begin{document}
% Title page and table of contents
\begin{titlepage}
\VideoLAN project
\begin{center}
\resizebox{\textwidth}{!}{vlc: the \VideoLAN\ client}
\bigskip
a real-time MPEG-2 software decoder and player
\end{center}
\end{titlepage}
\tableofcontents
% General description of the project
\part{General description}
\chapter{The goal}
\chapter{??}
\chapter{vlc: the \VideoLAN\ client}
\chapter{Continuation of the project}
% Project organization
\part{Project organization}
\chapter{Team and communication}
\chapter{Source control}
\chapter{Coding conventions}
\include{threads}
% Code description
\part{Code description}
\end{document}

312
doc/organization.fig
View File

@ -1,312 +0,0 @@
#FIG 3.2
Landscape
Center
Metric
A4
100.00
Single
-2
1200 2
6 8820 9180 11970 10260
2 1 0 1 2 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
8820 9360 9720 9360
2 1 0 1 0 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
8820 9630 9720 9630
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
8820 9900 9720 9900
2 1 0 1 1 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
8820 10170 9720 10170
4 0 0 100 0 0 12 0.0000 4 135 1155 10170 9360 store reference\001
4 0 0 100 0 0 12 0.0000 4 135 585 10170 9630 manage\001
4 0 0 100 0 0 12 0.0000 4 135 330 10170 10170 feed\001
4 0 0 100 0 0 12 0.0000 4 180 1785 10170 9900 create/initialize/destroy\001
-6
6 900 900 4950 6030
6 900 900 4950 6030
6 1080 1620 2880 2070
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
1080 2070 2880 2070 2880 1620 1080 1620 1080 2070
4 0 0 100 0 2 12 0.0000 4 135 735 1170 1800 interface\001
4 0 0 100 0 0 12 0.0000 4 180 1635 1170 1980 management and loop\001
-6
6 1080 2520 2970 3150
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
1080 3150 2970 3150 2970 2520 1080 2520 1080 3150
4 0 0 100 0 2 12 0.0000 4 180 975 1170 2700 intf_console\001
4 0 0 100 0 0 12 0.0000 4 135 1755 1170 2880 command-line oriented\001
4 0 0 100 0 0 12 0.0000 4 135 1050 1170 3060 user interface\001
-6
6 1080 3600 2520 4050
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
1080 4050 2520 4050 2520 3600 1080 3600 1080 4050
4 0 0 100 0 2 12 0.0000 4 180 660 1170 3780 intf_cmd\001
4 0 0 100 0 0 12 0.0000 4 180 1245 1170 3960 command parser\001
-6
6 1080 4500 3060 4950
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
1080 4950 3060 4950 3060 4500 1080 4500 1080 4950
4 0 0 100 0 2 12 0.0000 4 180 615 1170 4680 intf_ctrl\001
4 0 0 100 0 0 12 0.0000 4 135 1785 1170 4860 command line functions\001
-6
6 1080 5400 3150 5850
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
1080 5850 3150 5850 3150 5400 1080 5400 1080 5850
4 0 0 100 0 2 12 0.0000 4 135 570 1170 5580 control\001
4 0 0 100 0 0 12 0.0000 4 180 1935 1170 5760 program control functions\001
-6
6 3330 2520 4770 2970
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
3330 2970 4770 2970 4770 2520 3330 2520 3330 2970
4 0 0 100 0 2 12 0.0000 4 180 660 3420 2700 intf_msg\001
4 0 0 100 0 0 12 0.0000 4 150 1290 3420 2880 messages output\001
-6
2 4 0 1 0 7 100 0 -1 0.000 0 0 7 0 0 5
4950 900 4950 6030 900 6030 900 900 4950 900
4 0 0 100 0 2 16 0.0000 4 165 930 1080 1170 interface\001
4 0 0 100 0 0 12 0.0000 4 180 1920 1080 1350 Manage threads and user\001
-6
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
1530 2070 1530 2520
2 1 0 1 1 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
1530 3150 1530 3600
2 1 0 1 1 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
1530 4050 1530 4500
2 1 0 1 1 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
1530 4950 1530 5400
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 3
1 1 1.00 60.00 120.00
2880 1890 3780 1890 3780 2520
2 1 0 1 0 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
1620 2070 1620 2520
2 1 0 1 0 7 100 0 -1 0.000 0 0 -1 1 0 3
1 1 1.00 60.00 120.00
2880 1800 3870 1800 3870 2520
2 1 0 1 2 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
1710 2070 1710 2520
-6
6 900 7200 7380 10350
6 3240 8910 4860 9360
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
3240 9360 4860 9360 4860 8910 3240 8910 3240 9360
4 0 0 100 0 0 12 0.0000 4 180 1440 3330 9270 files input methods\001
4 0 0 100 0 2 12 0.0000 4 180 720 3330 9090 input_file\001
-6
6 5220 8910 7200 9360
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
5220 9360 7200 9360 7200 8910 5220 8910 5220 9360
4 0 0 100 0 2 12 0.0000 4 180 1140 5310 9090 input_network\001
4 0 0 100 0 0 12 0.0000 4 180 1815 5310 9270 networks input methods\001
-6
6 5670 9720 7200 10170
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
5670 10170 7200 10170 7200 9720 5670 9720 5670 10170
4 0 0 100 0 2 12 0.0000 4 180 795 5760 9900 input_vlan\001
4 0 0 100 0 0 12 0.0000 4 180 1410 5760 10080 vlans management\001
-6
6 1080 8910 2880 9360
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
1080 9360 2880 9360 2880 8910 1080 8910 1080 9360
4 0 0 100 0 2 12 0.0000 4 135 495 1170 9090 netlist\001
4 0 0 100 0 0 12 0.0000 4 180 1605 1170 9270 packets management\001
-6
6 1080 9720 2070 10170
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
1080 10170 2070 10170 2070 9720 1080 9720 1080 10170
4 0 0 100 0 2 12 0.0000 4 180 690 1170 9900 input_psi\001
4 0 0 100 0 0 12 0.0000 4 180 795 1170 10080 PSI parser\001
-6
6 2430 9720 3510 10170
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
2430 10170 3510 10170 3510 9720 2430 9720 2430 10170
4 0 0 100 0 2 12 0.0000 4 180 720 2520 9900 input_pcr\001
4 0 0 100 0 0 12 0.0000 4 180 870 2520 10080 PCR parser\001
-6
6 1080 7830 2610 8460
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
1080 8460 2610 8460 2610 7830 1080 7830 1080 8460
4 0 0 100 0 2 12 0.0000 4 180 375 1170 8010 input\001
4 0 0 100 0 0 12 0.0000 4 180 1365 1170 8190 stream parser and\001
4 0 0 100 0 0 12 0.0000 4 180 1020 1170 8370 demultiplexer\001
-6
2 4 0 1 0 7 100 0 -1 0.000 0 0 7 0 0 5
7380 7200 7380 10350 900 10350 900 7200 7380 7200
4 0 0 100 0 2 16 0.0000 4 225 570 1080 7470 input\001
-6
6 6750 180 8100 630
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
6750 630 8100 630 8100 180 6750 180 6750 630
4 0 0 100 0 2 12 0.0000 4 135 375 6840 360 main\001
4 0 0 100 0 0 12 0.0000 4 180 1185 6840 540 program control\001
-6
6 6300 900 8190 3240
6 6300 900 8190 3240
6 6480 1620 8010 2250
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
6480 2250 8010 2250 8010 1620 6480 1620 6480 2250
4 0 0 100 0 2 12 0.0000 4 180 1020 6570 1800 video_output\001
4 0 0 100 0 0 12 0.0000 4 180 1365 6570 1980 pictures rendering\001
4 0 0 100 0 0 12 0.0000 4 180 1080 6570 2160 and displaying\001
-6
6 6480 2610 8010 3060
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
6480 3060 8010 3060 8010 2610 6480 2610 6480 3060
4 0 0 100 0 2 12 0.0000 4 180 795 6570 2790 video_x11\001
4 0 0 100 0 0 12 0.0000 4 180 1320 6570 2970 X11 output driver\001
-6
2 4 0 1 0 7 100 0 -1 0.000 0 0 7 0 0 5
8190 900 8190 3240 6300 3240 6300 900 8190 900
4 0 0 100 0 2 16 0.0000 4 225 1380 6480 1170 video_output\001
4 0 0 100 0 0 12 0.0000 4 180 1425 6480 1350 pictures displaying\001
-6
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
6930 2250 6930 2610
2 1 0 1 0 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
7020 2250 7020 2610
2 1 0 1 2 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
7110 2250 7110 2610
-6
6 9450 900 11430 3240
6 9450 900 11430 3240
6 9630 1620 11250 2250
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
9630 2250 11250 2250 11250 1620 9630 1620 9630 2250
4 0 0 100 0 2 12 0.0000 4 180 1020 9720 1800 audio_output\001
4 0 0 100 0 0 12 0.0000 4 135 1440 9720 1980 audio frames mixer\001
4 0 0 100 0 0 12 0.0000 4 180 780 9720 2160 and player\001
-6
6 9630 2610 11070 3060
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
9630 3060 11070 3060 11070 2610 9630 2610 9630 3060
4 0 0 100 0 2 12 0.0000 4 180 795 9720 2790 audio_dsp\001
4 0 0 100 0 0 12 0.0000 4 180 1275 9720 2970 dsp output driver\001
-6
2 4 0 1 0 7 100 0 -1 0.000 0 0 7 0 0 5
11430 900 11430 3240 9450 3240 9450 900 11430 900
4 0 0 100 0 2 16 0.0000 4 225 1410 9630 1170 audio_output\001
-6
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
10080 2250 10080 2610
2 1 0 1 0 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
10170 2250 10170 2610
-6
6 6300 4050 8640 5400
6 6480 4770 8460 5220
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
6480 5220 8460 5220 8460 4770 6480 4770 6480 5220
4 0 0 100 0 2 12 0.0000 4 180 1185 6570 4950 video_decoder\001
4 0 0 100 0 0 12 0.0000 4 180 1815 6570 5130 PES parser and decoder\001
-6
2 4 0 1 0 7 100 0 -1 0.000 0 0 7 0 0 5
8640 4050 8640 5400 6300 5400 6300 4050 8640 4050
4 0 0 100 0 2 16 0.0000 4 225 1485 6480 4320 video_decoder\001
-6
6 9450 4050 11790 5400
6 9630 4770 11610 5220
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
9630 5220 11610 5220 11610 4770 9630 4770 9630 5220
4 0 0 100 0 2 12 0.0000 4 180 1185 9720 4950 audio_decoder\001
4 0 0 100 0 0 12 0.0000 4 180 1815 9720 5130 PES parser and decoder\001
-6
2 4 0 1 0 7 100 0 -1 0.000 0 0 7 0 0 5
11790 4050 11790 5400 9450 5400 9450 4050 11790 4050
4 0 0 100 0 2 16 0.0000 4 225 1515 9630 4320 audio_decoder\001
-6
2 1 0 1 2 7 100 0 -1 0.000 0 0 -1 1 0 4
1 1 1.00 60.00 120.00
1080 1800 450 1800 450 8100 1080 8100
2 1 0 1 2 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
2880 1710 6480 1710
2 1 0 1 2 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
1350 8460 1350 8910
2 1 0 1 0 7 100 0 -1 0.000 0 0 -1 1 0 3
1 1 1.00 60.00 120.00
2610 8100 3690 8100 3690 8910
2 1 0 1 1 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
3240 9180 2880 9180
2 1 0 1 1 7 100 0 -1 0.000 0 0 -1 1 0 4
1 1 1.00 60.00 120.00
5400 9360 5400 9540 2700 9540 2700 9360
2 1 0 1 0 7 100 0 -1 0.000 0 0 -1 1 0 3
1 1 1.00 60.00 120.00
2610 8010 5400 8010 5400 8910
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 3
1 1 1.00 60.00 120.00
2610 8190 3510 8190 3510 8910
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 3
1 1 1.00 60.00 120.00
2610 7920 5670 7920 5670 8910
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 3
1 1 1.00 60.00 120.00
8100 450 9990 450 9990 1620
2 1 0 1 2 7 100 0 -1 0.000 0 0 -1 1 0 3
1 1 1.00 60.00 120.00
6750 360 2250 360 2250 1620
2 1 0 1 2 7 100 0 -1 0.000 0 0 -1 1 0 3
1 1 1.00 60.00 120.00
8100 360 10080 360 10080 1620
2 1 0 1 2 7 100 0 -1 0.000 0 0 -1 1 0 4
1 1 1.00 60.00 120.00
6480 4950 5850 4950 5850 1890 6480 1890
2 1 0 1 1 7 100 0 -1 0.000 0 0 -1 1 0 4
1 1 1.00 60.00 120.00
6480 4860 5940 4860 5940 1980 6480 1980
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
1530 5850 1530 7830
2 1 0 1 1 7 100 0 -1 0.000 0 0 -1 1 0 4
1 1 1.00 60.00 120.00
9630 4950 9090 4950 9090 2070 9630 2070
2 1 0 1 2 7 100 0 -1 0.000 0 0 -1 1 0 4
1 1 1.00 60.00 120.00
9630 5040 9000 5040 9000 1980 9630 1980
2 1 0 1 2 7 100 0 -1 0.000 0 0 -1 1 0 4
1 1 1.00 60.00 120.00
2250 7830 2250 6750 10350 6750 10350 5220
2 1 0 1 2 7 100 0 -1 0.000 0 0 -1 1 0 4
1 1 1.00 60.00 120.00
1800 7830 1800 6300 6750 6300 6750 5220
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 4
1 1 1.00 60.00 120.00
1890 7830 1890 6390 6840 6390 6840 5220
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 4
1 1 1.00 60.00 120.00
2340 7830 2340 6840 10440 6840 10440 5220
2 1 0 1 1 7 100 0 -1 0.000 0 0 -1 1 0 4
1 1 1.00 60.00 120.00
1980 7830 1980 6480 6930 6480 6930 5220
2 1 0 1 1 7 100 0 -1 0.000 0 0 -1 1 0 4
1 1 1.00 60.00 120.00
2430 7830 2430 6930 10530 6930 10530 5220
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 4
1 1 1.00 60.00 120.00
3150 5490 5400 5490 5400 1800 6480 1800
2 1 0 1 2 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
11700 7650 12600 7650
2 1 0 1 0 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
11700 7830 12600 7830
2 1 0 1 4 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
11700 8010 12600 8010
2 1 0 1 1 7 100 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 60.00 120.00
11700 8190 12600 8190

255
doc/threads.tex
View File

@ -1,255 +0,0 @@
%
% threads.tex: description of threads interface for VideoLAN client
% (c)1999 VideoLAN
%
\section{A common thread interface}
This document describes how the different threads in the VideoLAN client are
organized, their API and functionnment.
%
% Thread properties
%
\subsection{Thread properties}
A thread is described by a \csymbol{X\_thread\_t} structure (i.e.
\csymbol{vout\_thread\_t}), which is used to reference the thread in calls to
its API. This structure includes beside following thread-specific data the
following fields:
\begin{csource}
typedef struct X_thread_s \{
pthread_t thread_id; /* thread id for pthreads */
boolean_t b_die; /* `die' flag */
boolean_t b_run; /* `run' flag */
boolean_t b_error; /* `error' flag */
boolean_t b_active; /* `active' flag */
... other fields ...
\} X_thread_t;
\end{csource}
%
% Meaning of common flags
%
\subsection{Meaning of common flags}
\begin{description}
\item[\csymbol{die}]:
The \csymbol{die} flag means that the thread received a destruction request
from another thread. It must terminate as soon as possible. This field is
written (set to 1) by other threads and read by the thread itself. It cannot
be reset to 0 once it has been set.
Note that when the \csymbol{die} flag is set, no other thread should feed the
dying one, and all shared structures should have been freed (i.e. the images
and video streams for the video output thread).
\item[\csymbol{run}]:
The \csymbol{run} flag tells the other threads that the concerned thread is
ready to receive data. It is set to 1 by the thread itself when the second
phase of the initialization has succeeded, and set to 0 again by the thread
once it exited.
\item[\csymbol{error}]:
The \csymbol{error} flag tells the other threads that a fatal error occured in
the concerned thread. It can be set by all threads, and is read by the thread
itself and the controlling thread.
When a thread is in \csymbol{error} state, it runs in a special loop,
accepting feed from other threads, but trashing eveything, waiting for a
\csymbol{die} signal.
Therefore, the controlling thread should check periodically if a thread has an
\csymbol{error} set and, if yes, set its \csymbol{die} flag after having
destroyed all depending threads.
This flag is optionnal, but recommanded if an error can be envisaged in a later
extension.
\item[\csymbol{active}]:
This flag's purpose is to avoid using useless resources. An in-\csymbol{active}
thread must accept input as if it was inactive, but can treat its input
differently.
In example: the video output thread will set itself as in-\csymbol{active}
when it is unmapped, and continue to sort and trash images, but will not
render or display them to avoid consumming useless CPU. When a video decoder
thread will detect that its related output thread is inactive, it will set
itself inactive and trash everything except I images.
The \csymbol{active} flag can be set and read by anyone. Precautions should be
taken to avoid too long wake-up times.
This flag is optionnal, but recommanded if its use can be envisaged in a later
extension.
\end{description}
%
% API
%
\subsection{API}
This API is only a recommandation.
% Creation
\subsubsection{Creation}
\begin{csource}
X_thread_t * X_CreateThread( X_cfg_t *p_cfg )
\end{csource}
This function will allocate thread descriptor, perform basic (and fast)
initialization steps, and create the thread itself using
\csymbol{pthread\_create}.
Once it has been called, all flags are set to 0. It will return the thread
descriptor or \csymbol{NULL} on failure.
% Termination
\subsubsection{Termination}
\begin{csource}
void X_TerminateThread( X_thread_t * p_X );
\end{csource}
This function will set the \csymbol{die} flag of the thread and and return
immediately.
% Destruction
\subsubsection{Destruction}
\begin{csource}
int X_DestroyThread( X_thread_t *p_X );
\end{csource}
This function will try to destroy the thread descriptor, if it is possible
(if the \csymbol{run} flag is not set). It will return 0 if it succeeded,
and non 0 if the thread was still active.
%
% Local functions names
%
\subsection{Local functions names}
The following functions names are recommanded to implement the different
parts of the thread creation and destruction:
\begin{csource}
int InitThread(); /* second phase of initialization */
int RunThread(); /* main loop */
int RunError(); /* error loop */
int DestroyThread(); /* thread destruction */
\end{csource}
\csymbol{X\_CreateThread()} will spawn a thread using \csymbol{RunThread()}
function, which will call \csymbol{InitThread()}, enter its main loop,
eventually call \csymbol{RunError()} and finally calls \csymbol{DestroyThread}
when \csymbol{die} is received.
%
% Order of operations
%
\subsection{Order of operations}
% Creation
\subsubsection{Creation}
\begin{tabular}{l|l}
Controlling thread & Thread \\
\hline
\csymbol{p\_X = X\_CreateThread( p\_cfg )}: & \\
descriptor allocation and initialization & \\
all flags are set to 0 & \\
base structures initialization & \\
If \csymbol{p\_X == NULL}: error & \\
\csymbol{X\_DestroyThread( p\_X )}: & \\
destruction of the descriptor & \\
end...
Else, continuation.... & \csymbol{pthread\_create()} \\
& Second step of initialization \\
& On error: \\
& \csymbol{b\_error = 1} \\
& destruction of structures \\
& Else: \\
& \csymbol{b\_run = 1} \\
& beginning of main loop \\
\hline
Wait for \csymbol{b\_run} or \csymbol{b\_error}...& main loop... \\
If \csymbol{b\_error}: & \\
\csymbol{X\_DestroyThread( p\_X )} & \\
end... & \\
Else (\csymbol{b\_run == 1}): & \\
the thread is ready and can be feeded... & \\
\hline
\end{tabular}
Notes:
\begin{enumerate}
\item The configuration structure can have been destroyed just after
\csymbol{X\_CreateThread()}. Therefore, it should not be used during second
initialization step.
\item When an error occurs during second initialization step, the allocated structures
are automatically destroyed (except the thread descriptor). Therefore, a call to
\csymbol{X\_TerminateThread} is not required.
\end{enumerate}
% Main loop
\subsubsection{Main loop}
\begin{tabular}{l|l}
Controlling thread & Thread \\
\hline
Periodically check for \csymbol{b\_error} & Periodically check for \\
If set, then: & \csymbol{b\_error} and \csymbol{b\_die}\\
terminate all dependant threads & \\
destroy all dependant threads & \\
terminate and destroy thread & \\
\hline
\end{tabular}
% Destruction
\subsubsection{Destruction}
\begin{tabular}{l|l}
Controlling thread & Thread \\
\hline
\csymbol{X\_TerminateThread( p\_X )}: & \\
set \csymbol{b\_die} & \\
all flags are set to 0 & If \csymbol{DEBUG}, check if \\
& all shared structures are ok. \\
& Destroy and close everything, but \\
& keep descriptor. \\
& Set \csymbol{b\_run} to 0. \\
& Exit thread. \\
\hline
Loop until \csymbol{X\_DestroyThread} is 0: & \\
check if \csymbol{b\_run == 0} & \\
if yes: & \\
destroy descriptor & \\
return 0 & \\
else: & \\
return 1 & \\
\hline
\end{tabular}