# Structure of XML file for mod_collage

Authors: Marc Alba and Jaume Singla

Our XML file always starts with a definition of itself (see the code at the end of this document). Then we need two tags to define an activity which are `<activity>` and `</activity>`. The first one is the begining of an activity and the second is the end, so we must define the activity between this two tags.

Each activity is composed by a list of modules from 1 to more.

A module is also defined by two tags: the begining tag `<module>` and the ending tag `</module>`. At the begining tag you can define attributes from a module in this way

`<module attribute1="property1" attribute2="property2">`

Attributes for `module` tag:

- `moduleType`: Is a required attribute and defines wich kernel to use. Only properties `COLLAGE` and `CYCLE` are valid. The collage makes transitions from every picture creating and destroying them according to motion. The cycle makes transitions with pictures without creating and destroying them, in a loop, also according to motion.

- `delayType`: Is an optional attribute and defines the behaviour of a module. Only properties `NODELAY`, `RAND` and `MOTION` are valid. Nodelay means that transitions are applied normally, rand is applied randomly and motion is applied according to motion. If no `delaytype` defined then the default is the `RAND` one.

- `listSrcBackground`: Is an optional attribute. It can contain a list of images, with their relatives paths, separated with commas to make an animation in the background. Also you can insert carriage return between sources to make XML clearer.

- `lapseAnimation`: Is an optional attribute, but if `listSrcBackground` is defined then that one is required, because to do an animation we need the time between pictures, that's it. The attribute must to be a float. If you only define one picture in the list and the lapse animation is zero, then we obtain a static background image, well same effect if there are more pictures but lapse is zero.

A module is composed by one element called `default` and a list of pictures from one to more. As before the elements are defined with a begining and ending tag.

default ⇒ `<default>` and `</default>` picture ⇒ `<picture>` and `</picture>`

The `default` element allows to define the input and output transition to use with pictures after defined, if the picture doesn't define a transition. In this element you can define one or two transitions. The default doesn't have attributes.

You can define attributes for a picture at begining tag as the module but in `<picture att1="prop1">`.

Attributes for `picture` tag:

- `src`: Is a required attribute, if not defined then, the picture is ignored. It can contain a list of pictures with their relatives paths, separated with commas. Also you can insert carriage return between sources to make XML clearer.

- `quantity`: Is an optional attribute, if is not defined then quantity equals one (is an integer). It can specify how many times appears the pictures divided by the number of pictures defined, this means that if you specify two pictures at the attribute `src` and eight at this attribute, each picture appears four times alternatively in the same order specified.

- `scale`: Is an optional attribute, a float one, and if is not defined then scale equals 0.25. It serves to zoom the picture.

- `rotated`: Is an optional attribute, if is not defined then rotated equals zero. It is used for rotate the picture the degrees (not radians) specified by this attribute. It must be an integer.

- `position`: Is the relative position where the picture will be painted. Its format is `(x,y)` with the parenthesis and the comma, then x and y are the coordinates in float number. I.e. `<picture … position="(0.3,0.5)" >`.

Each picture is composed by transitions from zero to more. In case of collage makes sense to specify two transitions, one for the input transition and the second for the output transition, but in the cycle module if two transitions are specified…well you can try, may be the result is unexpected and interesant at the same time. Specify more than two transitions has no sense but probably the last two will be taken, so be carefull. If a picture has no transitions defined then the default ones are taken, if there is no default element it will be an error. By definition it will become the activity into invalid one, but without DTD it only ignores the picture.

Each transition is composed, as before, with a begining and endig tag: `<transition>` and `</transition>`. Its attribute are defined as before in the begining tag `<transition att1="prop1">`

Attributes for transition tag:

- `transitionType`: is an optional attribute, if is not defined then `IDENTITY` is taken. Its only valid values are:

  - `IDENTITY`: transition has no effect.

  - `ALPHA`: picture appears or desappears through the alpha channel.

  - `SCALE`: picture is zommed in and out.

  - `ROTATE`: picture is rotated.

  - `CHANGE`: picture is changed for another (extra attribute is needed).

  - `VIBRATE`: picture vibrates.

  - `TRANSLATE`: picture is translated (extra attribute is needed).

  - `RANDOM`: takes a random transition from before mentioned.

- `inout`: is an optional attribute, if is not defined then `MIX` is taken. Its values are `IN`, `OUT` and `MIX`. They specify if is an input transition (in)m an output transition (out) or only one transition is needed (mix). As mentioned before the input and output transitions only takes sense with the collage module, so in the cycle you can define only one transition per picture without this attribute, because the default is the `mix` one.

- `degreesRotation`: is an optional parameter to specify the degrees of rotate transition, if is not defined it takes 90 degrees, and is an integer.

- `destinationSrc`: Is an optional attribute. It can contain a list of pictures with their relatives paths, separated with commas. Also you can insert carriage return between sources to make XML clearer. This attribute only makes sense if the transition type is `CHANGE`, and if the transition is the `CHANGE` one, then you need to specify the pictures to change for.

- `destinationPos`: is an optional attribute which only makes sense if the transition is `TRANSLATE`, so if is a `TRANSLATE` transition you need to define this attribute. Is the relative position where the picture will be tranlated. Its format is `(x,y)` with the parenthesis and the comma, then x and y are the coordinates in float number. I.e. `<transition transitionType="TRANSLATE" destinationPos="(0.5,0.8)" >`.

Note that the transition has no elemnts inside so it can be defined without the mentioned ending tag from above, but in the same way needs and end, and it's a slash at the end of the begining tag. i. e. `<transition transitionType="ALPHA" />`.

The same applies if a picture has no transitions defined because we want to pick the default ones. So it will be: `<picture src="…" position="(0.2,0.4)" />`

See the samples at `graphics/mod_collage_xml` directory.

The next code is a template for defining any kind of activity:

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE activity [<!ELEMENT activity (module+)>
    <!ELEMENT module (default, picture+)>
    <!ATTLIST module
            delayType (NODELAY|RAND|MOTION) "RAND"
            moduleType (COLLAGE|CYCLE) #REQUIRED
            listSrcBackground CDATA #IMPLIED
            lapseAnimation CDATA "-1"
    >

    <!ELEMENT default (transition, transition?)>

    <!ELEMENT picture (transition*)>
    <!ATTLIST picture
            src CDATA #REQUIRED
            quantity CDATA "1"
            scale CDATA "0.25"
            position CDATA #IMPLIED
            rotated CDATA #IMPLIED
    >

    <!ELEMENT transition EMPTY>
    <!ATTLIST transition
            transitionType (IDENTITY|ALPHA|SCALE|ROTATE|CHANGE|VIBRATE|TRANSLATE|RANDOM) "IDENTITY"
            inout (IN|OUT|MIX) "MIX"
            destinationSrc CDATA #IMPLIED
            degreesRotation CDATA #IMPLIED
            destinationPos CDATA #IMPLIED
    >
    ]>
    <activity>
            <!--HERE YOU CAN DEFINE VARIOUS MODULES-->
    </activity>