Plugin Tutorial 2
aus dem DMXControl-Wiki
Inhaltsverzeichnis |
Plugin Tutorial 2
4.1 Überblick
In diesem Teil des Tutorials wird auch die Rückrichtung realisiert, d.h. auch die von DMXControl gesendeten DMX Werte können empfangen werden.
Auch hier gilt, dass das Plugin in die gleichen drei Teile dekomponiert werden sollte, d.h. wir unterscheiden wieder in
- GUI
- Logik des Plugins
- Interface zu DMXControl.
Diese werden im folgenden beispielhaft beschrieben. Dazu wird unser Plugin aus dem ersten Teil um den Empfang von DMX-Signalen erweitert. Diese Signale, die z.B. vom Submaster oder Sound Analyzer für die 4 Dimmerkanäle ausgelöst werden können, werden dann im GUI-Matrixfeld in einer Art Lichtorgel visualisiert. Wie schon im ersten Teil wird hier im Sinne der Einfachheit und Übersichtlichkeit die einfachste Variante demonstriert, indem je nach Signalwert die Zellen eines Kanals in drei Stufen gefärbt werden. Natürlich können Sie dieses Beispiel erweitern, indem z.B. RGB-Werte zur Darstellung einzelner Kanäle oder der gesamten Matrix verwendet werden.
4.2 GUI Administration
In der Plugin-Oberfläche gibt es nur eine Änderung, ein zusätzlicher Kommando-Button wurde eingeführt, der als Umschaltbutton zwischen Sendemode (unveränderter erster Teil des Tutorials) und Empfangsmode (dieser Teil) fungiert. Das Tutorialbeispiel ist zur besseren Klarheit so konstruiert, dass entweder Signale gesendet oder empfangen werden können (Umschalten mit dem Send/Receive-Button). Diese Einschränkung ist nicht zwingend. Sie können also in Ihrem Plugin beide Modes kombinieren.
Den anderen Pluginteilen wird über die Variable "gblnReceiveMode" mitgeteilt, welcher Mode gerade aktiviert ist.
Abbildung 7: DMX-Receive Mode für das Plugin
4.3. Interface zu DMXControl
Die Methode "IDMXCPlugin_MessageHandle" im Modul clsDMXCPlugIn wird von DMXControl jedesmal aufgerufen, wenn ein DMX-Kanal einen neuen Wert erhält. Da dieser Modul nur das Interface zu DMXControl implementieren sollte, wird hier lediglich anhand des Wertes der Variable "gblnReceiveMode" geprüft, ob die empfangenen Signale an die Logik weitergeleitet werden sollen. Im Falle des Sendemodus werden die Signale einfach ignoriert, ansonsten wird die Routine "TutorLLGetDMXValue" im Modul DMXCTutorLL aufgerufen, weil dort die Logik implementiert ist, was mit dem empfangenen Signal zu geschehen hat. Natürlich können Sie in Ihrem Plugin die Signale feiner filtern oder auch andere Messages empfangen.
Private Function IDMXCPlugin_MessageHandle(Msg As DMXCTypeLib.MSGs, Arg1 As Long, Arg2 As Long) As Long
Select Case Msg
Case MSG_Channel_Send
If gblnReceiveMode Then
TutorLLGetDMXvalue Arg1, Arg2
End If
End Select
End Function
4.4 Logik
Im Modul DMXCTutorLL (Routine "TutorLLGetDMXValue") müssen also alle Operationen gestartet werden, die sich mit der Auswertung und Analyse der emfangenen Werte beschäftigen.
Public Sub TutorLLGetDMXvalue(ByVal Ch As Integer, ByVal Value As Long)
Dim i, Channel As Integer
If Ch >= mDimmerAddr And Ch < mDimmerAddr + 4 Then
Channel = Ch - mDimmerAddr + 1 'map to 1..4
If Value >= 128 Then
If mcurDMXValues(Channel) < 128 Then
Call frmTutorMain.enlightChannel(Channel, LED_on)
End If
mcurDMXValues(Channel) = Value
Exit Sub 'ready
Else
If Value >= 25 Then
If mcurDMXValues(Channel) > 128 Or mcurDMXValues(Channel) < 25 Then
Call frmTutorMain.enlightChannel(Channel, LED_off) 'reset cell
Call frmTutorMain.enlightChannel(Channel, LED_dimmed)
End If
mcurDMXValues(Channel) = Value
Exit Sub 'ready
Else
' Value < 25
If mcurDMXValues(Channel) >= 25 Then
Call frmTutorMain.enlightChannel(Channel, LED_off)
End If
mcurDMXValues(Channel) = Value
End If
End If
End If
End Sub
Die Logik ist in unserem Beispiel wieder extrem einfach. Das empfangene Signal wird auf 3 Zustände abgebildet:
Wert 0-25 -> entsprechender Kanal wird logisch auf "aus" gesetzt Wert 26-127 -> entsprechender Kanal wird logisch auf "dimmed" gesetzt Wert 128-255 -> entsprechender Kanal wird logisch auf "on" gesetzt
Daher prüft diese Prozedur, in welcher der drei Kategorien der aktuellen Wert liegt. In unserem Beispiel ist es erneut nicht
nötig, dem GUI Modul einen DMX-Wert zu übergeben, sondern es werden wiederum die drei bekannten Zustände verwendet. Dieser
berechnete Zustand wird dem GUI-Teil mitgeteilt, indem die Routine "enligthChannel" gerufen wird.
Es gibt einer zweiten Weg. DMX-Werte zu empfangen, nämlich durch explizite Abfrage, z.B.
dmxValue = mHelper.ChannelGetValue(currentChannel)
Ursprünglich war diese Methode dazu gedacht, bei der Initialisierung des Plugins die aktuellen Werte zu übernehmen.Es gibt aber auch Anwendungsfälle, wo das zielgerichtete Abfragen ("polling") viel effektiver und weniger Performance-fressend ist, als ständig auf alle "push"-Werte von DMXControl zu reagieren.
4.5 GUI Anzeige
Schliesslich bleibt die Aufgabe, anhand des übermittelten Zustandes eine Visualisierung in der Matrix vorzunehmen. Hierzu werden die bereits bekannten Methoden "colorizeCell" wiederverwendet.
Public Sub enlightChannel(ByVal ch As Integer, ByVal Status As LED_status)
Dim i As Integer
For i = 1 To 60
LED_matrix(i, ch) = Status
Call ColorizeCurrentCell(i, ch, True)
Next
End Sub
Auch für dieses Tutorialbeispiel gilt, dass vieles optimierter programmiert werden könnte, z.B. Änderung der Zellfarbe nur, wenn sich wirklich der Wert ändern. Aber das würde die Verständlichkeit des Beispiels verringern.
4.6 Integration in DMXControl
Da sich an der Modul-Struktur des Plugins nichts geändert hat, gilt hier alles, was im Kapitel 3.6 und 3.7 (Plugin Tutorial 1) beschrieben wurde. Vergessen Sie beim Ausprobieren nicht, die Startadresse des Dimmerpacks einzustellen und den "Receive"-Mode zu aktivieren.
Mit Hilfe des Submasters können Sie die Änderung der DMX-Werte auf den Dimmerpack-Kanälen vornehmen und dann die visuelle Anzeige in unserem Plugin bestaunen. Es ergibt sich auch tatsächlich ein Lichtorgel-Effekt bei der Benutzung des Sound Analyzers.
Wir wünschen Ihnen nun viel Spaß und Erfolg bei der Erstellung Ihres eigenen Plugins.
Sie können den Sourcecode des Demo-Plugins im File DMXC_Demo_Plugin.zip komplett ansehen.
Alle APIs finden Sie in der Plugin Interface Referenz
