Skip to content

V
vlc-2-2
Commit 80921ca7 authored by Alexis de Lattre's avatar Alexis de Lattre
Browse files
Options

Fixed a bug in the developer doc : hacking.xml and overview.xml were 

identical ! So I removed hacking.xml...
parent 2328faeb
Hide whitespace changes
Inline Side-by-side
Showing with 4 additions and 257 deletions
doc/developer/Makefile
View file @ 80921ca7
......@@ -25,12 +25,12 @@ all: manual
manual: manual.txt manual.ps manual.html
manual.tex: audio_output.xml debugging.xml decoders.xml gfdl.xml glossary.xml hacking.xml history.xml input.xml interface.xml manual.xml overview.xml ports.xml video_output.xml
manual.tex: audio_output.xml debugging.xml decoders.xml gfdl.xml glossary.xml history.xml input.xml interface.xml manual.xml overview.xml ports.xml video_output.xml
$(JADE) -t tex -V %section-autolabel% -d $(PRINT_SS) $(XML_DECL) manual.xml
perl -i.bak -pe 's/\000//g' $@ && rm $*.tex.bak
# No it's not a joke
manual.html: audio_output.xml debugging.xml decoders.xml gfdl.xml glossary.xml hacking.xml history.xml input.xml interface.xml manual.xml overview.xml ports.xml video_output.xml
manual.html: audio_output.xml debugging.xml decoders.xml gfdl.xml glossary.xml history.xml input.xml interface.xml manual.xml overview.xml ports.xml video_output.xml
$(JADE) -t sgml -V %section-autolabel% -V nochunks \
-d $(HTML_SS) $(XML_DECL) manual.xml > $@
......@@ -42,7 +42,7 @@ manual.dvi: manual.tex modules.eps ps.eps stream.eps ts.eps
manual.ps: manual.dvi
dvips -f $< > $@
manual.txt: audio_output.xml debugging.xml decoders.xml gfdl.xml glossary.xml hacking.xml history.xml input.xml interface.xml manual.xml overview.xml ports.xml video_output.xml
manual.txt: audio_output.xml debugging.xml decoders.xml gfdl.xml glossary.xml history.xml input.xml interface.xml manual.xml overview.xml ports.xml video_output.xml
$(JADE) -t sgml -V nochunks -d $(HTML_SS) $(XML_DECL) manual.xml > dump.html
lynx -force_html -dump dump.html > $@
-rm -f dump.html
......
doc/developer/hacking.xml deleted 100644 → 0
View file @ 2328faeb
<chapter> <title> VLC Overview </title>
<sect1> <title> LibVLC </title>
<para> LibVLC is the core part of VLC. It is a library providing an
interface for programs such as VLC to a lot of functionalities such as
stream access, audio and video output, plugin handling, a thread system.
All the LibVLC source files are located in the <filename>src/</filename>
directory and its subdirectories: </para>
<itemizedlist>
<listitem> <para> <filename>interface/</filename>: contains code for
user interaction such as key presses and device ejection. </para>
</listitem>
<listitem> <para> <filename>playlist/</filename>: manages playlist
interaction such as stop, play, next, or random playback. </para>
</listitem>
<listitem> <para> <filename>input/</filename>: opens an input module,
reads packets, parses them and passes reconstituted elementary streams
to the decoder(s). </para> </listitem>
<listitem> <para> <filename>video_output/</filename>: initializes the
video display, gets all pictures and subpictures (ie. subtitles) from
the decoder(s), optionally converts them to another format (such as YUV
to RGB), and displays them. </para></listitem>
<listitem> <para> <filename>audio_output/</filename>: initializes the
audio mixer, ie. finds the right playing frequency, and then resamples
audio frames received from the decoder(s). </para> </listitem>
<listitem> <para> <filename>stream_output/</filename>: TODO </para>
</listitem>
<listitem> <para> <filename>misc/</filename>: miscellaneous utilities
used in other parts of libvlc, such as the thread system, the message
queue, CPU detection, the object lookup system, or platform-specific
code. </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> VLC </title>
<para> VLC is a simple program written around LibVLC. It is very small,
but is a fully featured multimedia player thanks to LibVLC's support for
dynamic modules. </para>
</sect1>
<sect1> <title> Modules </title>
<para> Modules are located in the <filename>modules/</filename>
subdirectory and are loaded at runtime. Every module 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 module to support a new platform (eg.
BeOS or MacOS X). </para>
<para> Plugin modules are loaded and unloaded dynamically
by functions in <filename>src/misc/modules.c</filename> and
<filename>include/modules*.h</filename>. The API for writing modules will
be discussed in a following chapter. </para>
<para> Modules can also be built directly into the application which uses
LibVLC, for instance on an operating system that does not have support for
dynamically loadable code. Modules statically built into the application
are called builtins. </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</function>,
<function>vlc_thread_exit</function>,
<function>vlc_thread_join</function>,
<function>vlc_mutex_init</function>, <function>vlc_mutex_lock</function>,
<function>vlc_mutex_unlock</function>,
<function>vlc_mutex_destroy</function>,
<function>vlc_cond_init</function>, <function>vlc_cond_signal</function>,
<function>vlc_cond_broadcast</function>,
<function>vlc_cond_wait</function>, <function>vlc_cond_destroy</function>,
and structures <type>vlc_thread_t</type>, <type>vlc_mutex_t</type>, and
<type>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 liba52) cannot be used without using a global lock. </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>. The 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 slightly
<emphasis>before</emphasis> the presentation date, if some particular
treatment needs to be done (e.g. a chroma transformation). For instance
in <filename>modules/codec/mpeg_video/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 are 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>
doc/developer/manual.xml
View file @ 80921ca7
......@@ -4,7 +4,6 @@
[
<!ENTITY glossary SYSTEM "glossary.xml">
<!ENTITY overview SYSTEM "overview.xml">
<!ENTITY hacking SYSTEM "hacking.xml">
<!ENTITY interface SYSTEM "interface.xml">
<!ENTITY input SYSTEM "input.xml">
<!ENTITY decoders SYSTEM "decoders.xml">
......@@ -58,7 +57,7 @@
<orgname> VideoLAN project </orgname>
</affiliation>
</collab>
<pubdate> $Id: manual.xml,v 1.4 2002/09/30 11:05:33 sam Exp $ </pubdate>
<pubdate> $Id: manual.xml,v 1.5 2002/10/12 23:15:45 alexis Exp $ </pubdate>
<copyright> <year> 2001 </year>
<holder> Christophe Massiot, for IDEALX S.A.S. </holder>
</copyright>
......@@ -84,11 +83,6 @@
&overview;
<!-- ============================ HACKING =============================
-->
&hacking;
<!-- =========================== INTERFACE ============================
-->
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment