modified ext. links (e.g. VRPN that has changed to github recenty).

added details on plugin install and on plugin configuration in .xml file.

manual/architecture/configuration-file.rst

@@ -20,6 +20,7 @@ Document Sections
   * `Users Section`_
   * `Computers Section`_
   * `Screens Section`_
+  * `Plugin Section`_
   * `Sample Configuration File`_
 
 Redundant Sections
@@ -201,19 +202,18 @@ Library Path Sub-Section
 Plugins often relies on external libraries. If the library is not bundled in the ``blenderplayer`` python folder, the library folder can be specified with the ``library`` element.
 If any library is defined in a system section, they all must be defined.
 
-In the example below both OSC and VRPN library folders are specified for the OSX system, while the Linux stations shared the same system as defined in the top of the ``computers`` section.
+In the example below, the VRPN library folder is specified for the OSX system, while the Linux stations share the same system as defined in the top of the ``computers`` section.
 
 .. code:: xml
 
   <computers>
     <system>
       <library path="/usr/local/lib/vrpn/" />
-      <library path="/usr/local/lib/osc/" />
     </system>
     <computer name='OSX station' hostname='mac'>
       <system>
+        <!-- define path towards VRPN python shared object-->
         <library path="/User/dev/vrpn/build/python/" />
-        <library path="/User/dev/osc/lib/" />
       </system>
     </computer>
     <computer name='Linux station A' hostname='linux_a' />
@@ -329,10 +329,66 @@ Both require a screen definition: three corners (top right, top left and bottom
 
 For Wall, the screens are defined in `vehicle <../architecture/vehicle.html>`_ reference frame. For HMD, the screens are defined in the reference frame of head tracker.
 
+Plugin Section
+--------------
+
+So far, the plugin section can hold up to three sub-sections:
+
+* ``<vrpn>``: this section defines how to handle VRPN data sent by your VRPN server.
+* ``<osc>``: this section defines how to handle OSC data sent via OSC (e.g. with the `Sound Rendering Engine addon <https://blendervr.limsi.fr/doku.php?id=addons>`_ for BlenderVR) to an OSC client.
+* ``<oculus_dk2>``: this section defines how to handle data sent by the oculus rift dk2.
+
+The following lines of code defines/assumes:
+
+* ``<vrpn>``: A VRPN server at ``192.168.48.201`` with a device named ``DTrack``, saying that the callback ``user_position_dtrack`` (that has to be defined in the processor file) should be used to handle VRPN data comming from sensor ``22`` of ``DTrack`` device for ``user A``. A VRPN server at ``localhost`` with a device named ``device0``, saying that the callbacks ``space_navigator_analog`` and ``space_navigator_button`` should be used to handle VRPN data comming from ``device0`` device.
+
+* ``<osc>``: An OSC client at ``localhost`` listening to port ``3819``. The remaining flag will send init messages to the OSC client as defined in the `BlenderVR OSC API <http://blender-vr.readthedocs.org/processor-file/osc_api.html>`_.
+
+* ``<oculus_dk2>``: An oculus rift dk2 plugged on computer ``localhost`` (named ``myComputer`` in computers section) saying that the callback ``user_position`` should be used to handle DK2 data (e.g. head orientation) for ``user A``.
+
+.. code:: xml
+
+    <plugins>
+
+      <vrpn>
+        <floor x='0.0'/>
+
+        <--! define DTrack parameters from VRPN server @ distant host -->
+        <tracker device="DTrack" host="192.168.48.201">
+          <transformation>
+            <post_translation z="0.0"/>
+            <post_rotation x="1.0" y="1.0" z="1.0" angle="`-2*math.pi/3`"/>
+            <pre_rotation x="1.0" y="1.0" z="1.0" angle="`2*math.pi/3`"/>
+          </transformation>
+          <sensor id="22" processor_method='user_position_dtrack' users='user A'/>
+        </tracker>
+
+        <--! define device0 parameters from VRPN server @ local host -->
+        <analog device="device0" host="localhost" processor_method="space_navigator_analog"/>
+        <button device="device0" host="localhost" processor_method="space_navigator_button"/>
+
+      </vrpn>
+
+      <--! define OSC parameters for OSC client @ localhost -->
+      <osc host='localhost' port='3819' configuration='Laptop SPAT'>
+        <user listener='Binaural 1' viewer='user A' />
+        <user listener='Binaural 2' viewer='user B' />
+        <user listener='Ambisonic' />
+        <user listener='Stereo' />
+      </osc>
+
+      <--! define oculus dk2 parameters -->
+      <oculus_dk2>
+        <user host="localhost" processor_method="user_position" viewer='user A' computer='myComputer'/>
+      </oculus_dk2>
+
+    </plugins>
+
+
 Sample Configuration File
 -------------------------
 
-This sample configuration file can be used for a cave with three vertical square (2m x 2m) screens (left, front and right) plus a console computer with a single windowed screen.
+This sample configuration file can be used for a CAVE with three vertical square (2m x 2m) screens (left, front and right) plus a console computer with a single windowed screen.
 
 .. code:: xml
 

manual/development/documentation.rst

@@ -1,6 +1,6 @@
-=============
-Documentation
-=============
+======================
+Building Documentation
+======================
 
 There are two parts of the project that are covered by this documents:
 Source Code API [1]_ and the User Manual [2]_.

manual/development/index.rst

@@ -2,26 +2,26 @@
 Development
 ############
 
-The BlenderVR project is open-source and open for external collaboration.
+The BlenderVR project is open-source, opened to external collaboration.
 
-Links
------
+.. toctree::
+   :maxdepth: 1
+
+   BlenderVR API <http://blender-vr.readthedocs.org/>
+   documentation.rst
+   build-win-exe.rst
+
+
+
+**Project links (Repos, API, etc.)**
 
 * `BlenderVR Home <http://blendervr.limsi.fr/>`__
+* `BlenderVR API <http://blender-vr.readthedocs.org/>`_
 * `All Repositories <https://github.com/BlenderVR>`_
 * `Source Code Repository <https://github.com/BlenderVR/source>`_
 * `Manual Repository <https://github.com/BlenderVR/manual>`_
 * `Samples Repository <https://github.com/BlenderVR/samples>`_
 * `Bug List <https://github.com/BlenderVR/source/issues>`_
 
-Development Documents
-----------------------
-
-.. toctree::
-   :maxdepth: 1
-
-   documentation.rst
-   build-win-exe.rst
-
 ..
   Talk about git, github, getting involved, ...

manual/installation/development.rst

@@ -58,8 +58,9 @@ Regarding BlenderVR samples, Git is not a good system to work on binary files, s
   $ cd $INSTALL_DIR
   $ svn checkout https://github.com/BlenderVR/samples/trunk samples
 
+where $INSTALL_DIR is the root BlenderVR folder (see the `Install BlenderVR <installation.html#folder-structure>`_ page for more details).
 
-Or for an individual sample folder:
+Alternatively, to fetch an individual sample folder, you can use:
 
 .. code-block:: bash
 

manual/installation/installation.rst

@@ -42,7 +42,7 @@ Document Sections
 Folder Structure
 ----------------
 
-After all the downloads and installations you should end up with the following folder structure. This is a recommendation, and it will be used as reference along this manual (the directory holding these files is  referred as $INSTALL_DIR in the next sections).
+After all the downloads and installations you should end up with the following folder structure. This is a recommendation, and it will be used as reference along this manual (the directory holding these files is referred as $INSTALL_DIR in the next sections).
 
 ``//source/``
 *BlenderVR Source Code*

manual/installation/plugins.rst

@@ -24,12 +24,13 @@ Add a ``plugins`` directory to your $INSTALL_DIR (see `Folder Structure <install
 VRPN
 ----
 
-This section briefly exposes the `VRPN <http://www.cs.unc.edu/Research/vrpn/index.html>`__, install.
+This section briefly exposes the `VRPN <https://github.com/vrpn/vrpn/wiki>`__, install.
 In a nutshell, you will have to build VRPN, launch a VRPN server and BlenderVR then will act as a VRPN client to fetch the data from your VRPN devices.
 once the VRPN server launched on your machine/network, any device defined in your vrpn.cfg (input of vrpn server) will be handled by the server and its related ``infos`` pulled by the BlenderVR VRPN client.
-See `Getting started with VRPN <http://www.cs.unc.edu/Research/vrpn/vrpn_getting_started.html>`_ for more information.
+See VRPN `Getting Started <https://github.com/vrpn/vrpn/wiki/Getting-Started>`_ page for more information.
+
+* Download `VRPN 07.33.zip <https://github.com/vrpn/vrpn/releases/download/v07.33/vrpn_07_33.zip>`_ and unzip it (e.g. into ``$INSTALL_DIR/plugins/vrpn``).
 
-Download `VRPN 07.33.zip <http://www.cs.unc.edu/Research/vrpn/downloads/vrpn_07_33.zip>`__ and unzip it into $INSTALL_DIR/plugins/vrpn/.
 .. Create a ``build`` directory to finally have the following tree:
 
 .. ``//plugins/vrpn/vrpn``
@@ -43,11 +44,16 @@ Download `VRPN 07.33.zip <http://www.cs.unc.edu/Research/vrpn/downloads/vrpn_07_
 ..   $ cmake -DCMAKE_OSX_ARCHITECTURES=x86_64 ../vrpn
 ..   $ make
 
-then follow compilation instructions from `VRPN Compiling <http://www.cs.unc.edu/Research/vrpn/vrpn_standard_stuff.html>`__.
+* Follow compilation instructions from `Getting Started <https://github.com/vrpn/vrpn/wiki/Getting-Started#compiling>`_ page.
+
+* Add the path of the vrpn python directory to your `configuration file <../architecture/configuration-file.html#library-path-sub-section>`_.
+
+Once done, to test your installation:
 
-Add the path of the vrpn python directory to your `configuration file <../architecture/configuration-file.html#library-path-sub-section>`_.
+* Grab a VRPN device, find it's name in the VRPN server, and define it's associated callback name in the ``<vrpn>`` sub-section of the `configuration file <../architecture/configuration-file.html#plugin-section>`_ (said name is yours to chose).
 
-Once done, launch the ``basic-vrpn.blend`` scene in ``$INSTALL_DIR/samples/plugin/vrpn/basic-vrpn/``.
+* Define the callback method in the processor.py attached to your scene (said method being named after the callback declared in the configuration file).
+Use the ``basic-vrpn.blend`` scene in ``$INSTALL_DIR/samples/plugin/vrpn/basic-vrpn/`` and its associated processor file for an example of how to use VRPN issued data, modifying the vrpn methods names ``space_navigator_analog`` and ``space_navigator_button`` to fit yours.
 
 Oculus Rift DK2
 ---------------