===== How to use libyuri =====
There are two basic ways, how to use **libyuri**. You can either compile your **own application** that uses libyuri API a links agains it, or the much easier way is to create an **XML configuration file** a let the binary //yuri2// to parse it and execute for you.

==== Using yuri2 ====
the basic syntax to run your application from an XML file is:

  yuri2 app.xml

Simple, right? More advanced usage is in form:

  yuri2 [options] app.xml [variable=value] ...

The options are described bellow. Interesting part are the variables. This let's you configure the application without modifying the XML file.

Supported options are:
  * **-h** or **--help**: Shows help and quit.
  * **-V** or **--version**: Shows a version string a exits.
  * **-l <arg>** or **--list <arg>**: Lists available objects. Arg can be 'classes' or 'formats'. If no argumet is specified, it defaults to 'classes'.
  * **-v** or **--verbose**: More verbose output
  * **-q** or **--quiet**:Less verbose output

=== XML file format ===
Let's look at a sample file first:

<file xml webcam.xml>
<?xml version="1.0" ?>

<!-- Simple XML application -->          
<app name="webcam">
        <!-- Specify variables for command line substitution -->
        <variable name="device" default="/dev/video0"/>
        <variable name="fps" default="30"/>

        <!-- General settings -->
        <general>
                <!-- Unlimited run time -->
                <parameter name="run_limit">-1</parameter>
                <!-- Moderate debug informations -->
                <parameter name="debug">0</parameter>
        </general>

        <!-- Video4Linux2 device source -->
        <node class="v4l2source" name="webcam">
                <parameter name="path">@device</parameter>
                <parameter name="width">800</parameter>
                <parameter name="height">600</parameter>
                <parameter name="fps">@fps</parameter>
        </node>

        <!-- And finally simple rendering window -->
        <node class="simple_renderer" name="renderer">
                <parameter name="width">800</parameter>
                <parameter name="height">600</parameter>
        </node>

        <!-- Link specifications -->
        <link name="yuyv_image" source="webcam:0" target="renderer:0">
            <parameter name="limit">1</parameter>
            <parameter name="limit_type">count</parameter>
        </link>
        
</app>

</file>

As you can see, it's an ordinary XML file. comments work the usual way, between %%<!--%% and %%-->%%.

The root element is **%%<app>%%** and has optional parameter //name//.

Then you can specify **%%<variable>%%**. These are the variables that can be specified from a command line. They should have a //name// and a //default// value.

Next, there is **%%<general>%%** element. This specified some global **%%<parameter>%%**s for the whole application, like run time limit (parameter 'run_limit') or global debug level.

The you specify **%%<node>%%**s. These are the nodes of oriented graph representing the application. Each node has a //class// (the "type" of the node) and a __unique__ //name// used to refer to this node. The name **has to be unique!** It won't format your hard drive if it isn't, but it probably won't do what you wanted it to do. Inside each node element, you can specify **%%<parameter>%%**s, just like in the **%%<global>%%** element. Each of the parameters should correspond to some parameter of the class that the node represents.(TIP: You can get list of there parameters by running //yuri2 -l//). Instead of specifying a value for the parameter, you can use syntax //@variable// to have the value be set pro a variable at execution time (either with user specified value or with the default value). The variable has to be declared using **%%<variable>%%** element.

Last but not least, there is the **%%<link>%%** element. This element defines oriented links between nodes, thus defining the structure of the application graph. it has to have a //name// specified (unique among the links) and the //source// and //target// node port specification. The syntax for these ports is simple: **node_name:port_number**. For simple nodes the port number is always 0, some more complicated one may have more than a single input or output ports.

so to run this sample application, just run:
  yuri2 webcam.xml

and you should get a window with picture from your web camera.
You can also specify to use other camera using variables. For example to use camera on /dev/video1 use:
  yuri2 webcam.xml device=/dev/video1



=== Additional XML files ===
You can find some testing config files in the source distrubution under directory //configs///