git.sesse.net Git - vlc/blob - doc/developer/overview.xml

   1 <chapter> <title> VLC Overview </title>
   2
   3   <sect1> <title> LibVLC </title>
   4
   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>
  10
  11     <itemizedlist>
  12
  13       <listitem> <para> <filename>interface/</filename>: contains code for
  14       user interaction such as key presses and device ejection. </para>
  15       </listitem>
  16
  17       <listitem> <para> <filename>playlist/</filename>: manages playlist
  18       interaction such as stop, play, next, or random playback. </para>
  19       </listitem>
  20
  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>
  24
  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>
  29
  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>
  33
  34       <listitem> <para> <filename>stream_output/</filename>: TODO </para>
  35       </listitem>
  36
  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>
  41
  42     </itemizedlist>
  43
  44     <mediaobject>
  45       <imageobject>
  46         <imagedata fileref="modules.png" format="PNG" scalefit="1" scale="80"/>
  47       </imageobject>
  48       <imageobject>
  49         <imagedata fileref="modules.gif" format="GIF" />
  50       </imageobject>
  51       <textobject>
  52         <phrase> Data flow between modules </phrase>
  53       </textobject>
  54     </mediaobject>
  55
  56   </sect1>
  57
  58   <sect1> <title> VLC </title>
  59
  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>
  63
  64   </sect1>
  65
  66   <sect1> <title> Modules </title>
  67
  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>
  74
  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>
  79
  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>
  84
  85   </sect1>
  86
  87   <sect1> <title> Threads </title>
  88
  89     <sect2> <title> Thread management </title>
  90
  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.
  98     </para>
  99
 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>
 114
 115     </sect2>
 116
 117     <sect2> <title> Synchronization </title>
 118
 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.
 125     </para>
 126
 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>
 133
 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>
 140
 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>
 147
 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>
 154
 155     </sect2>
 156
 157   </sect1>
 158
 159   <sect1> <title> Code conventions </title>
 160
 161     <sect2> <title> Function naming </title>
 162
 163       <para>
 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.
 168       </para>
 169
 170     </sect2>
 171
 172     <sect2> <title> Variable naming </title>
 173
 174       <para>
 175 Hungarian notations are used, that means we have the following prefixes :
 176       </para>
 177
 178       <itemizedlist>
 179         <listitem> <para> i_ for integers (sometimes l_ for long integers) ;
 180         </para> </listitem>
 181         <listitem> <para> b_ for booleans ; </para> </listitem>
 182         <listitem> <para> d_ for doubles (sometimes f_ for floats) ;
 183         </para> </listitem>
 184         <listitem> <para> pf_ for function pointers ; </para> </listitem>
 185         <listitem> <para> psz_ for a Pointer to a String terminated by a
 186         Zero (C-string) ;
 187         </para> </listitem>
 188         <listitem> <para> More generally, we add a p when the variable is
 189         a pointer to a type. </para> </listitem>
 190       </itemizedlist>
 191
 192       <para>
 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 :
 198       </para>
 199
 200       <itemizedlist>
 201         <listitem> <para>
 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>
 209         </para> </listitem>
 210       </itemizedlist>
 211
 212     </sect2>
 213
 214     <sect2> <title> A few words about white spaces </title>
 215
 216       <para>
 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.
 221       </para>
 222
 223       <para>
 224 Second, put spaces <emphasis> before and after </emphasis> operators, and
 225 inside brackets. For instance :
 226 <programlisting> for( i = 0; i &lt; 12; i++, j += 42 ); </programlisting>
 227       </para>
 228
 229       <para>
 230 Third, leave braces alone on their lines (GNU style). For instance :
 231         <programlisting>
 232 if( i_es == 42 )
 233 {
 234     p_buffer[0] = 0x12;
 235 }
 236         </programlisting>
 237       </para>
 238
 239       <para>
 240 We write C, so use C-style comments /* ... */.
 241       </para>
 242
 243     </sect2>
 244
 245   </sect1>
 246
 247 </chapter>