*******************************************
* 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 als <matrix rows="1" columns="2"> mit zwei
<rgb>-Farbpickern ausgefuehrt (unbenannt, innerhalb des Matrix-Elements
verschachtelt) - dadurch zeigt DMXControl echte Farbpicker UND kann
seine eingebauten Effekte darauf anwenden. WICHTIG: mehrere benannte
<rgb name="..."> BLOECKE DIREKT AUF OBERSTER EBENE fuehrten bei
DMXControl zu "RGB has already been defined" - innerhalb eines
gemeinsamen <matrix> ohne eigene Namen funktioniert es dagegen.

  Farbverlauf-Sichtbarkeit (config.txt: GRADIENT_INTENSITY_CHANNEL)
    0-255 linear -> 0-100%; 0 = Effekt komplett unsichtbar (unabhaengig
    von den Farbkanaelen - siehe Renderer::drawGradientGrid: bei
    Sichtbarkeit 0 wird gar nicht erst gezeichnet)

  Farbverlauf-Anfang / Farbverlauf-Ende (config.txt: GRADIENT_START_R/G/B_CHANNEL,
  GRADIENT_END_R/G/B_CHANNEL, je 3 Kanaele als <rgb>-Farbpicker)
    0-255 direkt je Kanal. 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

-----------------------------
Laserstrahl-Faecher (pro Layer, NICHT im letzten globalen Block!)
-----------------------------
Im Unterschied zu allen bisherigen Zusatz-Effekten liegen diese vier
Kanaele NICHT im letzten, gemeinsamen Block, sondern in JEDEM einzelnen
Layer-Block selbst - sie nutzen die vier Kanaele, die pro 20-Kanal-Layer
sonst frei geblieben waeren. Kanal +13 war zuvor "animation speed"
(wirkungslos) und ist jetzt umbenannt/neu belegt; +17 bis +19 waren
zuvor komplett ungenutzt.

  Layer-Offset +13: Laserstrahl-Faecher Sichtbarkeit (0-255 linear -> 0-100%)
  Layer-Offset +17: Laserstrahl-Faecher Anzahl (0-255 linear -> 2-64 Strahlen)
  Layer-Offset +18: Laserstrahl-Faecher Laenge (0-255 linear -> 0-100%)
  Layer-Offset +19: Laserstrahl-Faecher Breite (0-255 linear -> 0-100%)

Beispiel Layer 1 (DMX_START-relativ CH13/CH17/CH18/CH19): bei DMX_START=100
also absolute Kanaele 113/117/118/119. Layer 2 entsprechend +20 usw.

Ursprung der Strahlen = die eigene Position des Layers (Kanal +2/+3),
Richtung = die normale Rotation des Layers (Kanal +6/+15 - dieselbe, die
auch das Gobo dreht), Farbe = der bestehende Farbkanal (+10/+11/+12).
Kein eigener Farb- oder Richtungskanal noetig.

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