<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>