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

-----------------------------
Kachel-Effekt (Kaleidoskop-Look)
-----------------------------
Zwei weitere "nackte" Kanaele, direkt nach Laserstrahl-Sichtbarkeit im
selben, letzten Block - als Schalter (rawstep mit festen Wertebereichen,
kein linearer Regler) ausgefuehrt, damit DMXControl die Optionen als
Klartext-Auswahl statt als 0-255-Slider zeigt:

  Kachel-Anzahl (config.txt: TILE_COUNT_CHANNEL)
    0-63    = Aus (normales 1:1-Bild)
    64-127  = 4 Kacheln (2x2)
    128-191 = 16 Kacheln (4x4)
    192-255 = 64 Kacheln (8x8)

  Kachel-Spiegelung (config.txt: TILE_MIRROR_CHANNEL)
    0-84    = 1:1 (keine Spiegelung, jede Kachel identisch)
    85-169  = Vertikal gespiegelt (obere Rasterhaelfte normal, untere
              Haelfte auf dem Kopf - Symmetrie an der waagerechten Mitte)
    170-255 = Horizontal gespiegelt (linke Rasterhaelfte normal, rechte
              Haelfte seitenverkehrt - Symmetrie an der senkrechten Mitte)

Beide relativ zu DMX_START konfiguriert, muessen zur jeweiligen DDF passen.

  Layer   Media Scene   Nebel   Laserstrahl   Kachel-Anz.   Kachel-Sp.   dmxaddresscount (ohne Farbverlauf)
  1       CH20          CH21    CH22          CH23          CH24         25
  2       CH40          CH41    CH42          CH43          CH44         45
  3       CH60          CH61    CH62          CH63          CH64         65
  4       CH80          CH81    CH82          CH83          CH84         85
  5       CH100         CH101   CH102         CH103         CH104        105

-----------------------------
Farbverlauf-Raster-Effekt (Kaleidoskop-Hintergrund)
-----------------------------
Neun weitere Kanaele direkt nach Kachel-Spiegelung im selben, letzten
Block - diagonaler Farbverlauf, der langsam durchlaeuft, hinter einem
Kachel-Raster mit leicht "atmenden" Luecken (siehe Hauptprojekt-README).
Start- und Endfarbe sind einzelne R/G/B-Kanaele (kein gruppierter
Farbpicker - mehrere benannte <rgb>-Bloecke in einer DDF fuehrten bei
DMXControl zu "RGB has already been defined").

  Farbverlauf-Sichtbarkeit (config.txt: GRADIENT_INTENSITY_CHANNEL)
    0-255 linear -> 0-100%; 0 = Effekt unsichtbar

  Farbverlauf-Anfang / Farbverlauf-Ende (config.txt: GRADIENT_START_R/G/B_CHANNEL,
  GRADIENT_END_R/G/B_CHANNEL, je 3 einzelne Kanaele)
    0-255 direkt je Kanal (R/G/B einzeln). Im Regenbogen-Modus ungenutzt.

  Farbverlauf-Geschwindigkeit (config.txt: GRADIENT_SPEED_CHANNEL)
    0-255 linear -> langsam bis schnell

  Farbverlauf-Modus (config.txt: GRADIENT_MODE_CHANNEL)
    0-127   = Zwei Farben (Start/Ende, Dreieckswelle hin und her)
    128-255 = Regenbogen (volles Farbspektrum, Start-/Endfarbe ungenutzt)

  Layer   Kachel-Sp.   Sichtbarkeit   Anfang(RGB)     Ende(RGB)       Geschw.   Modus   dmxaddresscount
  1       CH24         CH25           CH26-CH28       CH29-CH31       CH32      CH33    34
  2       CH44         CH45           CH46-CH48       CH49-CH51       CH52      CH53    54
  3       CH64         CH65           CH66-CH68       CH69-CH71       CH72      CH73    74
  4       CH84         CH85           CH86-CH88       CH89-CH91       CH92      CH93    94
  5       CH104        CH105          CH106-CH108     CH109-CH111     CH112     CH113   114

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