1 <chapter> <title> VLC Overview </title>
3 <sect1> <title> Code modules </title>
6 The VLC code uses modules and plugins. A module is a group of compiled-in
7 C source files. They are linked against the main application at build time.
8 At present, these modules are :
12 <listitem> <para> Interface : this is the entry point of the program. It manages
13 all user interactions and thread spawning. </para> </listitem>
14 <listitem> <para> Input : it opens the input socket, reads packets, parses
15 them and passes reconstituted elementary streams to the decoder(s).
17 <listitem> <para> Video output : it initializes the video display. Then it
18 gets all pictures and subpictures (ie. subtitles) from the decoder(s),
19 optionally converts them to RGB format (from YUV), and displays them.
21 <listitem> <para> Audio output : it initializes the audio mixer, ie.
22 finds the right playing frequency, and then resamples audio frames
23 received from the decoder(s). </para> </listitem>
24 <listitem> <para> Misc : miscellaneous utilities used in other modules.
25 This is the only module that will never launch a thread.
27 <listitem> <para> ac3_decoder, audio_decoder, generic_decoder, lpcm_decoder,
28 spu_decoder, video_decoder, video_parser : decoders used by VLC to
29 decode different kinds of elementary stream data. [these are subject
30 to move to <filename> plugins/ </filename> in a forthcoming
31 version]</para> </listitem>
36 <imagedata fileref="modules.eps" format="EPS" scalefit="1" scale="80"/>
39 <imagedata fileref="modules.gif" format="GIF" />
42 <phrase> Data flow between modules </phrase>
48 <sect1> <title> Plug-ins </title>
51 Plugins are located in the <filename> plugins/ </filename> subdirectory
52 and are loaded at runtime. Every plug-in
53 may offer different features that will best suit a particular file or
54 a particular environment. Besides, most portability works result in the writing
55 of an audio_output/video_output/interface plug-in to support a new
56 platform (eg. BeOS or MacOS X).
60 Plug-ins are loaded and unloaded dynamically by functions in
61 <filename> src/misc/modules.c </filename> and <filename> include/modules*.h
62 </filename>. The API for writing plugins will be discussed in a
67 Plugins can also be built into the VLC main application by changing the
68 <parameter> BUILTINS </parameter> line in <filename>
69 Makefile.opts</filename>.
74 <sect1> <title> Threads </title>
76 <sect2> <title> Thread management </title>
79 VLC is heavily multi-threaded. We chose against a single-thread approach
80 because decoder preemptibility and scheduling would be a mastermind (for
81 instance decoders and outputs have to be separated, otherwise it cannot
82 be warrantied that a frame will be played at the exact presentation
84 we currently have no plan to support a single-threaded client.
85 Multi-process decoders usually imply more overhead (problems of shared
86 memory) and communication between processes is harder.
90 Our threading structure is modeled on pthreads. However, for portability
91 reasons, we don't call <function>pthread_*</function> functions
92 directly, but use a similar wrapper, made of <function> vlc_thread_create,
93 vlc_thread_exit, vlc_thread_join, vlc_mutex_init, vlc_mutex_lock,
94 vlc_mutex_unlock, vlc_mutex_destroy, vlc_cond_init, vlc_cond_signal,
96 vlc_cond_wait, vlc_cond_destroy</function>, and structures <type>
97 vlc_thread_t, vlc_mutex_t, and vlc_cond_t</type>.
102 <sect2> <title> Synchronization </title>
105 Another key feature of VLC is that decoding and playing are asynchronous :
106 decoding is done by a *_decoder thread, playing is done by audio_output
107 or video_output thread. The design goal is to ensure that an audio or
108 video frame is played exactly at the right time, without blocking any
109 of the decoder threads. This leads to a complex communication structure
110 between the interface, the input, the decoders and the outputs.
114 Having several input and video_output threads reading multiple files at
115 the same time is permitted, despite the fact that the current interface
116 doesn't allow any way to do it [this is subject to change in the near
117 future]. Anyway the client has been written from the ground up
118 with this in mind. This also implies that a non-reentrant
119 library (including in particular LiViD's libac3) cannot be used.
123 Presentation Time Stamps located in the system layer of the stream are
124 passed to the decoders, and all resulting samples are dated accordingly.
125 The output layers are supposed to play them at the right time. Dates are
126 converted to microseconds ; an absolute date is the number of microseconds
127 since Epoch (Jan 1st 1970). The <type> mtime_t </type> type is a signed
132 The current date can be retrieved with <function> mdate()</function>.
133 Te execution of a thread can be suspended until a certain <parameter>
134 date </parameter> via <function> mwait </function> <parameter>
135 ( mtime_t date )</parameter>. You can sleep for a fixed number of
136 microseconds with <function> msleep </function> <parameter>
137 ( mtime_t delay )</parameter>.
141 Please remember to wake up a little while <emphasis> before
142 </emphasis> the presentation date, if some particular treatment
143 needs to be done (e.g. a YUV transform). For instance in <filename>
144 src/video_parser/vpar_synchro.c</filename>, track of the average
145 decoding times is kept to ensure pictures are not decoded too
153 <sect1> <title> Code conventions </title>
155 <sect2> <title> Function naming </title>
158 All functions are named accordingly : module name (in lower case) + _ +
159 function name (in mixed case, <emphasis> without underscores</emphasis>).
160 For instance : <function>intf_FooFunction</function>. Static functions
161 don't need usage of the module name.
166 <sect2> <title> Variable naming </title>
169 Hungarian notations are used, that means we have the following prefixes :
173 <listitem> <para> i_ for integers (sometimes l_ for long integers) ;
175 <listitem> <para> b_ for booleans ; </para> </listitem>
176 <listitem> <para> d_ for doubles (sometimes f_ for floats) ;
178 <listitem> <para> pf_ for function pointers ; </para> </listitem>
179 <listitem> <para> psz_ for a Pointer to a String terminated by a
182 <listitem> <para> More generally, we add a p when the variable is
183 a pointer to a type. </para> </listitem>
187 If one variable has no basic type (for instance a complex structure), don't
188 put any prefix (except p_* if it's a pointer). After one prefix, put
189 an <emphasis> explicit </emphasis> variable name <emphasis> in lower
190 case</emphasis>. If several words are required, join them with an
191 underscore (no mixed case). Examples :
196 <type> data_packet_t * </type> <varname> p_buffer; </varname>
197 </para> </listitem> <listitem> <para>
198 <type> char </type> <varname> psz_msg_date[42]; </varname>
199 </para> </listitem> <listitem> <para>
200 <type> int </type> <varname> pi_es_refcount[MAX_ES]; </varname>
201 </para> </listitem> <listitem> <para>
202 <type> void </type> <varname> (* pf_next_data_packet)( int * ); </varname>
208 <sect2> <title> A few words about white spaces </title>
211 First, never use tabs in the source (you're entitled to use them in the
212 Makefile :-). Use <command> set expandtab </command> under <application>
213 vim </application> or the equivalent under <application>
214 emacs</application>. Indents are 4 spaces long.
218 Second, put spaces <emphasis> before and after </emphasis> operators, and
219 inside brackets. For instance :
220 <programlisting> for( i = 0; i < 12; i++, j += 42 ); </programlisting>
224 Third, leave braces alone on their lines (GNU style). For instance :
234 We write C, so use C-style comments /* ... */.
projects / vlc / blob