1 <chapter> <title> VLC Overview </title>
3 <sect1> <title> LibVLC </title>
5 <para> LibVLC is the core part of VLC. It is a library providing an
6 interface for programs such as VLC to a lot of functionalities such as
7 stream access, audio and video output, plugin handling, a thread system.
8 All the LibVLC source files are located in the <filename>src/</filename>
9 directory and its subdirectories: </para>
13 <listitem> <para> <filename>interface/</filename>: contains code for
14 user interaction such as key presses and device ejection. </para>
17 <listitem> <para> <filename>playlist/</filename>: manages playlist
18 interaction such as stop, play, next, or random playback. </para>
21 <listitem> <para> <filename>input/</filename>: opens an input module,
22 reads packets, parses them and passes reconstituted elementary streams
23 to the decoder(s). </para> </listitem>
25 <listitem> <para> <filename>video_output/</filename>: initializes the
26 video display, gets all pictures and subpictures (ie. subtitles) from
27 the decoder(s), optionally converts them to another format (such as YUV
28 to RGB), and displays them. </para></listitem>
30 <listitem> <para> <filename>audio_output/</filename>: initializes the
31 audio mixer, ie. finds the right playing frequency, and then resamples
32 audio frames received from the decoder(s). </para> </listitem>
34 <listitem> <para> <filename>stream_output/</filename>: TODO </para>
37 <listitem> <para> <filename>misc/</filename>: miscellaneous utilities
38 used in other parts of libvlc, such as the thread system, the message
39 queue, CPU detection, the object lookup system, or platform-specific
40 code. </para> </listitem>
46 <imagedata fileref="modules.png" format="PNG" scalefit="1" scale="80"/>
49 <imagedata fileref="modules.gif" format="GIF" />
52 <phrase> Data flow between modules </phrase>
58 <sect1> <title> VLC </title>
60 <para> VLC is a simple program written around LibVLC. It is very small,
61 but is a fully featured multimedia player thanks to LibVLC's support for
62 dynamic modules. </para>
66 <sect1> <title> Modules </title>
68 <para> Modules are located in the <filename>modules/</filename>
69 subdirectory and are loaded at runtime. Every module may offer different
70 features that will best suit a particular file or a particular
71 environment. Besides, most portability works result in the writing of an
72 audio_output/video_output/interface module to support a new platform (eg.
73 BeOS or MacOS X). </para>
75 <para> Plugin modules are loaded and unloaded dynamically
76 by functions in <filename>src/misc/modules.c</filename> and
77 <filename>include/modules*.h</filename>. The API for writing modules will
78 be discussed in a following chapter. </para>
80 <para> Modules can also be built directly into the application which uses
81 LibVLC, for instance on an operating system that does not have support for
82 dynamically loadable code. Modules statically built into the application
83 are called builtins. </para>
87 <sect1> <title> Threads </title>
89 <sect2> <title> Thread management </title>
91 <para> VLC is heavily multi-threaded. We chose against a single-thread
92 approach because decoder preemptibility and scheduling would be a
93 mastermind (for instance decoders and outputs have to be separated,
94 otherwise it cannot be warrantied that a frame will be played at the
95 exact presentation time), and we currently have no plan to support a
96 single-threaded client. Multi-process decoders usually imply more overhead
97 (problems of shared memory) and communication between processes is harder.
100 <para> Our threading structure is modeled on pthreads.
101 However, for portability reasons, we don't call
102 <function>pthread_*</function> functions directly, but use a
103 similar wrapper, made of <function>vlc_thread_create</function>,
104 <function>vlc_thread_exit</function>,
105 <function>vlc_thread_join</function>,
106 <function>vlc_mutex_init</function>, <function>vlc_mutex_lock</function>,
107 <function>vlc_mutex_unlock</function>,
108 <function>vlc_mutex_destroy</function>,
109 <function>vlc_cond_init</function>, <function>vlc_cond_signal</function>,
110 <function>vlc_cond_broadcast</function>,
111 <function>vlc_cond_wait</function>, <function>vlc_cond_destroy</function>,
112 and structures <type>vlc_thread_t</type>, <type>vlc_mutex_t</type>, and
113 <type>vlc_cond_t</type>. </para>
117 <sect2> <title> Synchronization </title>
119 <para> Another key feature of VLC is that decoding and playing are
120 asynchronous: decoding is done by a decoder thread, playing is done by
121 audio_output or video_output thread. The design goal is to ensure that
122 an audio or video frame is played exactly at the right time, without
123 blocking any of the decoder threads. This leads to a complex communication
124 structure between the interface, the input, the decoders and the outputs.
127 <para> Having several input and video_output threads reading multiple
128 files at the same time is permitted, despite the fact that the current
129 interface doesn't allow any way to do it [this is subject to change in the
130 near future]. Anyway the client has been written from the ground up with
131 this in mind. This also implies that a non-reentrant library (including in
132 particular liba52) cannot be used without using a global lock. </para>
134 <para> Presentation Time Stamps located in the system layer of the
135 stream are passed to the decoders, and all resulting samples are dated
136 accordingly. The output layers are supposed to play them at the right
137 time. Dates are converted to microseconds ; an absolute date is the number
138 of microseconds since Epoch (Jan 1st, 1970). The <type>mtime_t</type> type
139 is a signed 64-bit integer. </para>
141 <para> The current date can be retrieved with
142 <function>mdate()</function>. The execution of a thread can be suspended
143 until a certain <parameter>date</parameter> via <function>mwait</function>
144 <parameter>( mtime_t date )</parameter>. You can sleep for a fixed number
145 of microseconds with <function>msleep</function> <parameter>( mtime_t
146 delay )</parameter>. </para>
148 <warning> <para> Please remember to wake up slightly
149 <emphasis>before</emphasis> the presentation date, if some particular
150 treatment needs to be done (e.g. a chroma transformation). For instance
151 in <filename>modules/codec/mpeg_video/synchro.c</filename>, track of the
152 average decoding times is kept to ensure pictures are not decoded too
153 late. </para> </warning>
159 <sect1> <title> Code conventions </title>
161 <sect2> <title> Function naming </title>
164 All functions are named accordingly : module name (in lower case) + _ +
165 function name (in mixed case, <emphasis> without underscores</emphasis>).
166 For instance : <function>intf_FooFunction</function>. Static functions
167 don't need usage of the module name.
172 <sect2> <title> Variable naming </title>
175 Hungarian notations are used, that means we have the following prefixes :
179 <listitem> <para> i_ for integers (sometimes l_ for long integers) ;
181 <listitem> <para> b_ for booleans ; </para> </listitem>
182 <listitem> <para> d_ for doubles (sometimes f_ for floats) ;
184 <listitem> <para> pf_ for function pointers ; </para> </listitem>
185 <listitem> <para> psz_ for a Pointer to a String terminated by a
188 <listitem> <para> More generally, we add a p when the variable is
189 a pointer to a type. </para> </listitem>
193 If one variable has no basic type (for instance a complex structure), don't
194 put any prefix (except p_* if it's a pointer). After one prefix, put
195 an <emphasis> explicit </emphasis> variable name <emphasis> in lower
196 case</emphasis>. If several words are required, join them with an
197 underscore (no mixed case). Examples :
202 <type> data_packet_t * </type> <varname> p_buffer; </varname>
203 </para> </listitem> <listitem> <para>
204 <type> char </type> <varname> psz_msg_date[42]; </varname>
205 </para> </listitem> <listitem> <para>
206 <type> int </type> <varname> pi_es_refcount[MAX_ES]; </varname>
207 </para> </listitem> <listitem> <para>
208 <type> void </type> <varname> (* pf_next_data_packet)( int * ); </varname>
214 <sect2> <title> A few words about white spaces </title>
217 First, never use tabs in the source (you're entitled to use them in the
218 Makefile :-). Use <command> set expandtab </command> under <application>
219 vim </application> or the equivalent under <application>
220 emacs</application>. Indents are 4 spaces long.
224 Second, put spaces <emphasis> before and after </emphasis> operators, and
225 inside brackets. For instance :
226 <programlisting> for( i = 0; i < 12; i++, j += 42 ); </programlisting>
230 Third, leave braces alone on their lines (GNU style). For instance :
240 We write C, so use C-style comments /* ... */.