*******************************************
* DMXControl 3 DDFs fuer rpi-beamertool   *
*******************************************

In diesem Verzeichnis liegen die an rpi-beamertool angepassten DMXControl-3
Geraetedefinitionen (DDFs), abgeleitet vom Original-Beamertool von Zoidberg,
sowie Werkzeuge, um die Media-Player-Dateiliste darin zu pflegen.

-----------------------------
Varianten je Layer-Anzahl
-----------------------------
Es gibt eine DDF pro Anzahl simulierter Laser (1-5 Layer). Innerhalb jeder
Layer-Variante gibt es zwei bzw. drei Auspraegungen (die 1-4 Layer haben
zusaetzlich .orig, die 5-Layer-Variante wurde direkt nach demselben Muster
aus der 4-Layer-DDF abgeleitet, ohne separate .orig-Variante):

  Beamertool-Zoidberg Beamer(Nlayer).xml           aktuelle Version
                                                    (identisch zu .list)
  Beamertool-Zoidberg Beamer(Nlayer).xml.list       Version mit ausgeschriebener
                                                    Auswahlliste fuer die
                                                    Media-Player-Dateien
                                                    (Dateiname erscheint direkt
                                                    im DMXControl-Kanal-Editor)
  Beamertool-Zoidberg Beamer(Nlayer).xml.numeric    Media-Auswahl in reinen
                                                    Einerschritten (0-255),
                                                    ohne erkennbaren Dateinamen
  Beamertool-Zoidberg Beamer(Nlayer).xml.orig       unveraenderte Original-DDF
                                                    von Zoidberg (ohne
                                                    Media-Player-Kanal)

-----------------------------
Media-Player-Kanal
-----------------------------
Gegenueber dem Original kommt ein zusaetzlicher, "nackter" Kanal hinzu, der
zwischen Laser-Simulation und Media Player umschaltet - siehe
Hauptprojekt-README, Abschnitt "Media Player". Er ist jeweils der ERSTE
Kanal im letzten Channel-Block der DDF (direkt gefolgt von Nebeldichte und
Laserstrahl-Sichtbarkeit, siehe naechster Abschnitt). Die zugehoerige
RELATIVE Adresse (zu DMX_START) wird auf dem Pi in
/opt/rpi-beamertool/config.txt unter MEDIA_PLAYER_CHANNEL eingetragen -
muss zur DDF passen.

Beispiel (.list-Variante, 1-Layer-DDF), steht am Ende der DDF:

    <!-- Kanal 20: Media-Modus - Szenen-/Dateiauswahl -->
    <rawstep dmxchannel="20" name="Media Scene">
       <step mindmx="0" maxdmx="0" caption="Laser Simulation"/>
       <step mindmx="1" maxdmx="1" name="001_Foo.png" caption="001_Foo.png"/>
       <step mindmx="2" maxdmx="2" name="002_Bar.jpg" caption="002_Bar.jpg"/>
       ...
    </rawstep>
    <raw dmxchannel="21" name="Nebel-Dichte" >
        <range type="linear" mindmx="0" maxdmx="255" minval="0" maxval="100" />
    </raw>
    <raw dmxchannel="22" name="Laserstrahl-Sichtbarkeit" >
        <range type="linear" mindmx="0" maxdmx="255" minval="0" maxval="100" />
    </raw>

-----------------------------
Nebel-Dichte & Laserstrahl-Sichtbarkeit (Festival-Look)
-----------------------------
Zwei weitere "nackte" Kanaele, direkt nach dem Media-Scene-Kanal im selben,
letzten Block. Ergeben zusammen den Eindruck einer echten Festival-
Lasershow mit Nebelmaschine (siehe Hauptprojekt-README). Beide sind
einfache lineare 0-100%-Regler (0-255 DMX -> 0-100%), relativ zu DMX_START
konfiguriert ueber config.txt: FOG_DENSITY_CHANNEL und
BEAM_VISIBILITY_CHANNEL - muessen zur jeweiligen DDF passen (siehe Tabelle
unten fuer die Kanalnummern je Layer-Anzahl).

  Layer   Media Scene   Nebel-Dichte   Laserstrahl-Sichtbarkeit   dmxaddresscount
  1       CH20          CH21           CH22                       23
  2       CH40          CH41           CH42                       43
  3       CH60          CH61           CH62                       63
  4       CH80          CH81           CH82                       83
  5       CH100         CH101          CH102                      103

-----------------------------
Media-Dateiliste pflegen (tools/genprefix.sh, tools/genddflist.sh)
-----------------------------
Damit die .list-Variante im DMXControl-Kanal-Editor den tatsaechlichen
Dateinamen statt nur einer Zahl zeigt, braucht die DDF eine feste Liste
aller Dateien in ./media/. Zwei Helferskripte (im Hauptprojekt unter
tools/) erleichtern die Pflege dieser Liste:

  tools/genprefix.sh
    Im media/-Verzeichnis ausfuehren: nummeriert alle Dateien fortlaufend
    mit einem dreistelligen Prefix (001_, 002_, ...). Neue, spaeter
    hinzugefuegte Dateien bekommen automatisch die naechste freie Nummer,
    ohne bereits vergebene Nummern/Praefixe zu aendern - so muss die DDF-
    Liste nicht bei jeder neuen Datei komplett neu erzeugt werden.

        cd /opt/rpi-beamertool/media
        /opt/rpi-beamertool/tools/genprefix.sh

  tools/genddflist.sh
    Erzeugt aus dem aktuellen Inhalt von ./media/ den passenden
    <rawstep>-Block (DMX-Werte 1..N in Dateireihenfolge, "0" fest als
    "Laser Simulation"). Ausgabe geht auf stdout und muss manuell in die
    DDF (den bestehenden <rawstep dmxchannel="..." name="Media Scene">-
    Block) eingefuegt/ersetzt werden.

        cd /opt/rpi-beamertool/media
        /opt/rpi-beamertool/tools/genddflist.sh > /tmp/media_scene_block.xml

Alternative ohne Liste: die .numeric-DDF-Variante nutzen. Dort waehlt man
Medien nur ueber den reinen DMX-Zahlenwert - erfordert keine Pflege der
Liste, zeigt aber nicht an, welches Medium sich hinter welcher Nummer
verbirgt.
