DMX-Plugin:Scripted-Gerät

Das DMX-Plugin für SkyConductor besteht aus mehreren Einzel-Plugins. Eines davon ist das sogenannte "Scripted device"-DMX-Plugin. Dieses Plugin ermöglicht es, auch komplexe Geräte in der DMX-Programmierung von SkyConductor zu verwenden. Die Erstellung eines solchen Gerätes erfordert dafür jedoch auch tieferes Wissen der internen Strukturen von SkyConductor sowie etwas Programmierpraxis da die Ansteuerung der DMX-Kanäle programm- und nicht mustergesteuert erzeugt wird.

Geräte-Definitionen

Das Scripted Device-Plugin verwendet Standardmäßig alle Gerätedefinitionen die im Anwendungsdaten-Verzeichnis "SkyConductor\dmx" gefunden werden. Pro Gerät muss eine eigene Datei in diesem Verzeichnis angelegt werden, der Dateiname muss auf .scd enden. Die Liste der unterstützten DMX-Geräte wird von SkyConductor beim Start des Programms geladen. Bevor eine Show an das Zündsystem übertragen wird (z.B. Export in eine Datei, Programmieren der Module etc) werden die Informationen jeder Gerätedatei neu geladen, so dass bei Veränderungen in einer Datei im Normalfall ein erneuter Export der Daten ausreicht um die letzte Änderung testen zu können. Bei Bedarf kann der genaue Pfad im Registry-Editor ("regedit.exe") im Pfad HKEY_CURRENT_USER\Software\VB and VBA Program Settings\SC DMX Custom Script\Path\PresetPath nachgesehen bzw. für den angemeldeten Nutzer verändert werden.

Aufbau einer .dms-Gerätedatei

In den folgenden Bereichen wird der Aufbau einer .scd-Gerätedefinition erklärt. Die Datei besteht, anders als beim Custom Device-Plugin, aus nur einem einzigen Abschnitt, welcher als VB-Script interpretiert und ausgeführt wird. Insofern wird empfohlen, sich vor dem Start mit dem grundsätzlichen Aufbau und der Funktionsweise von VB-Script vertraut zu machen. Eine gute (englische) Quelle dazu ist hier zu finden, Google liefert unter dem Stichwort VBScript oder VBS jedoch auch viele deutsche Treffer.

Abruf der Script-Identität

Jedes Script hat eine eigenen Identität, so dass verschiedene Gerätedateien vom System einfacher unterschieden werden können. Der zurückgegebene Name muss zwischen allen Scriptdateien eindeutig sein, darf sich also nicht wiederholen. Am besten sollte eine Kombination aus Datum, Uhrzeit, Autoren-Name und Script-Name verwendet werden.

Function GetScriptIdentity()
 GetScriptIdentity = "01.09.2015_15:04:16_Tobias_Hagemeier_DEMO"
End Function

Abruf von Gerätedaten

Da mehrere Geräte innerhalb einer Datei definiert werden dürfen, ist eine Routine zum Abruf der Gerätedaten erforderlich. Diese sieht wie folgt aus:

Sub AddDMXDevices()
 Container.AddDMXDevice "Hersteller", "Gerätename 1", 5, "Hersteller_Gerätename1_ID1"
 Container.AddDMXDevice "Hersteller", "Gerätename 2", 3, "Hersteller_Gerätename2_ID2"
End Sub

Für jedes unterstützte Gerät muss eine Container.AddDMXDevice-Zeile hinzugefügt werden. Die Definition der aufgerufenen Funktion AddDMXDevice lautet dabei wie folgt:

Public Sub AddDMXDevice(Manufacturer As String, DeviceName As String, NumChannels As Integer, Optional ID As String, Optional flags As String)

Der Parameter Manufacturer gibt dabei den Hersteller des Gerätes an nach dem der Gerätebaum in Unterkategorien gruppiert wird. Der Parameter DeviceName sollte den Namen des Gerätes enthalten wie er auch vom Hersteller verwendet wird um eine einfache Identifizierung des Geräts durch den Nutzer zu ermöglichen. NumChannels gibt an, wie viele aufeinander folgende DMX-Kanäle das Gerät belegt. Sind die Kanäle frei konfigurierbar sollte davon ausgegangen werden, dass die Kanäle am Gerät auf fortlaufende Nummern vergeben werden. Der Parameter ID dient der Unterscheidung mehrerer Geräte im Script - wenn mehrere Geräte definiert sind wird die ID später wieder als Gerätetyp übergeben. Die ID sollte somit innerhalb eines Scripts jeweils eindeutig sein. Das DMX-Script-Plugin ruft diese Funktion auf, um heraus zu finden welche Geräte von der entsprechenden Datei überhaupt behandelt werden können.

Das DMXDevice-Objekt

Das DMXDevice-Objekt wird verschiedenen Funktionen übergeben welche sich auf ein bestimmtes, definiertes DMX-Gerät beziehen. Es besitzt Eigenschaften die es ermöglichen, Parameter eines Geräts zu erfragen die für die Erzeugung von DMX-Sequenzen benötigt werden. Das DMXDevice-Objekt besitzt die folgenden Eigenschaften auf mittels der Notation DMXDevice.Eigenschaft zugegriffen werden können:

StartAddress

Variablentyp Integer - Der erste Kanal der für das Gerät verwendet wird

AddressCount

Variablentyp Integer - Die Anzahl an Adressen die für das Gerät vorgesehen ist

Das DMXSequenceStore-Objekt

Das DMXSequenceStore-Objekt verwaltet alle angelegten Sequenzen und ermöglicht es, beliebige Sequezen abzurufen oder ihre Eigenschaften zu verändern. Es ermöglicht außerdem den Zugriff auf die DMX-Kanaleigenschaften welche in der CompileBaseSequences-Funktion für das DMX-Gerät gesetzt werden sollten. Beispiele zur Anwendung folgen weiter unten; die API-Dokumentation ist eventuell eingeklappt (siehe rechter Rand).

Folgende Parameter und Funktionen stehen zur Verfügung:

Sub ClearChannelFlag(Ch As Integer, Flag As DMX_CHANNEL_FLAG)

Markiert das angegebene Flag für den angegebenen Kanal als "nicht erwünscht". Je nach Kanaleigenschaft bekommst später die Angabe, dass eine Eigenschaft nicht erwünscht ist oder die Angabe (von einem anderen Plugin) das die Eigenschaft erwünscht sei Priorität.

Sub SetChannelFlag(Ch As Integer, Flag As DMX_CHANNEL_FLAG)

Markiert das angegebene Flag für den angegebenen Kanal als "erwünscht". Je nach Kanaleigenschaft bekommst später die Angabe, dass eine Eigenschaft nicht erwünscht ist oder die Angabe (von einem anderen Plugin) das die Eigenschaft erwünscht sei Priorität.

Function GetOrAdd(SequenceNumber As Long) As DMXSequence

Ruft die DMX-Sequenz mit der angegebenen Nummer ab. Sollte die DMX-Sequenz noch nicht existieren wird sie erstellt und in die Liste der Sequenzen eingefügt so dass jede Sequenz nur einmal existieren kann und zwischen verschiedenen DMX-Plugins und auch DMX-Geräten geteilt wird. Die Funktion gibt die entsprechende Sequenz zurück mit welcher dann weiter gearbeitet werden kann.

Function GetPrivateSequence() As DMXSequence

Ruft eine private DMX-Sequenz ab. Bei jedem Aufruf wird eine neue DMX-Sequenz erzeugt und zurück gegeben, diese Sequenzen sind also bei jedem Aufruf "privat" und nur die anfragende Funktion kann damit arbeiten. Private Sequenzen werden üblicherweise für Servicesequenzen genutzt. Intern erhalten sie die Sequenznummern 50000..60000.

DMX_CHANNEL_FLAG-Typ

Mögliche Werte für die Kanaleinstellungen:

DMX_CHANNEL_FLAG_ARMING_LOCK

Der Kanal wird so lange auf Wert 0 gehalten, wie das DMX-Modul unscharf ist. Ein höherer Wert wird erst dann ausgegeben, wenn das DMX-Modul scharf ist. Auch von einem vor dem DMX-Modul angeschlossenen Lichtpult wird der Kanal nicht weiter gegeben.

DMX_CHANNEL_FLAG_ALWAYS_INTERNAL

Der Kanal wird ausschließlich vom DMX-Modul selbst angesteuert. Werte, die von einem vor dem DMX-Modul angeschlossenen Lichtpult geliefert werden, werden ignoriert.

DMX_CHANNEL_FLAG_COPY_ARMED_VALUE

Beim Unscharf schalten wird der letzte Wert des Kanals in den Unscharf-Modus übernommen statt auf den Wert, welcher vor der Scharfschaltung aktuell war, zurück zu setzen.

Das DMXSequence-Objekt

Jedes Mal wenn vom DMXSequenceStore-Objekt eine DMX-Sequenz angefragt wird, wird ein DMXSequence-Objekt zurück gegeben. Dieses repräsentiert eine einzelne Sequenz des DMX-Moduls. Zu Beginn des Exports einer Show sind alle DMX-Sequenzen komplett leer, sie werden anschließend über die einzelnen Plugins mit entsprechenden Anweisungen gefüllt. Beispiele zur Anwendung folgen weiter unten; die API-Dokumentation ist eventuell eingeklappt (siehe rechter Rand).

Eine Sequenz kann mit den folgenden Funktionen bearbeitet werden:

Sub AddDMXEvent(ByVal AbsoluteTime As Long, ByVal DMXChannel As Integer, ByVal DMXValue As Integer, ByVal DMXMode As DMXChannelMode, ByVal UID As String)

Diese Routine fügt eine DMX-Kanaländerung zu einer DMX-Sequenz hinzu. Für jede Änderung des DMX-Kanals muss ein eigener Funktionsaufruf stattfinden. AbsoluteTime gibt den absoluten Zeitpunkt innerhalb der Sequenz in Millisekunden an. DMXChannel ist die Nummer des DMX-Kanals und darf zwischen 1-512 liegen. DMXValue gibt den gewünschten Wert für den Kanal an. Der Wert darf zwischen 0 und 255 liegen. DMXMode gibt an mit welchem DMX-Mischmodus die Kanaländerung erfolgt. Der Wert wird über eine der Konstanten MODE_LTP, MODE_HTP oder MODE_LOCK ausgewählt. UID legt eine eindeutige Kennung fest über welche ein Gerät identifiziert wird. Diese Kennung ist erforderlich, damit die DMX-Modi korrekt zusammen gemischt werden können. Kanalsperren, HTP- und LTP-Mischen werden immer über die UID ausgewertet. Wenn ein Kanal von UID 1 gesperrt wurde, kann er auch nur von UID 1 wieder freigegeben werden. Zugriffe die unter einer anderen UID erfolgen werden so lange gesperrt bis der Kanal von UID 1 wieder freigegeben wurde. Innerhalb der Basissequenzen kann ein beliebiger Text angegeben werden, wenn ein Cue in DMX-Daten gewandelt wird (Funktion CompileCueChannel) MUSS die UID des umzuwandelnden Cues benutzt werden (Zugriff über Cue.UID).

SequenceFlags

Typ DMXSequenceFlags - Eigenschaften der Sequenz. Darf nur für Service-Sequenzen verändert werden.

ManualSequenceName

Typ String - Der Name der für eine manuelle Sequenz. Die Länge sollte 20 Zeichen nicht überschreiten und am besten den Namen des Geräts beinhalten (längere Namen können vom DMX-Modul nicht angezeigt werden)

DoIncludeManual

Typ Boolean - Soll die Sequenz als manuelle Sequenz aufgenommen werden (als Servicesequenz)

ManualSequenceFlags

Typ DMXManualSequenceFlags - Gibt Eigenschaften für die Auflistung und Ausführung einer Servicesequenz an

DMXSequenceFlags

Sequenz-Eigenschaften für den Cue. Zur Zeit ist nur der Wert DMX_SEQUENCE_FLAG_MAY_RUN_DISARMED möglich, welcher angibt, dass die Sequenz auch laufen darf wenn das DMX-Modul unscharf geschaltet ist.

DMXManualSequenceFlags

Eigenschaften für den Menüeintrag der möglichen Servicesequenz. Möglich ist hier zur Zeit nur DMX_MAN_SEQFLAG_ARM_TO_RUN. Dieser Wert gibt an, dass das DMX-Modul scharf geschaltet werden soll wenn die Sequenz gestartet wird. Dies ist mit einer entsprechenden Sicherheitsabfrage verbunden.

Erzeugung von Basis-Gerätesequenzen

Für jedes Gerät müssen einige Basis-Sequenzen angelegt werden. Hierunter fallen vor allem folgende Sequenzen:

• Scharfschalte-Sequenze (Nummer 65535)

Muss sämtliche Geräte in einen Zustand bringen in dem eine Auslösung/Ansteuerung möglich ist und wo dies nicht vor jeder Auslösung erfolgen darf weil z.B. das Erreichen des betriebsbereiten Zustandes länger als eine halbe Sekunde dauert oder das wiederholte Scharf schalten und unscharf schalten Resourcen verbraucht

• Die Paused-Sequenz (Nummer 65534)

Wird aufgerufen wenn eine Show pausiert wird. Sollte jedes Gerät, welches nur eine begrenzte Zeit eingeschaltet bleiben darf, abschalten. Beispielsweise zu verwenden für Flammenprojektoren oder Nebelmaschinen

• Service-Sequenzen (spezieller Abruf)

Über Service-Sequenzen können Sonderfunktionen eines Geräts abgerufen werden um zum Beispiel einen Gerätetest durchzuführen oder das System herunter zu fahren (entlüften etc).

Um diese Basis-Sequenzen zu erzeugen, wird die CompileBaseSequences-Funktion für jedes definierte DMX-Gerät einmal aufgerufen. Die Funktion hat die folgende Definition: Function CompileBaseSequences(DeviceType, DMXDevice, DMXSequences) As Boolean

DeviceType

Typ String, die in der AddDMXDevice angegebene ID. Dient zur Unterscheidung mehrerer von der Gerätedefinition unterstützter Gerätetypen

DMXDevice

Typ DMXDevice, das interne DMX-Geräteobjekt welches das spezifische zu behandelnde Gerät abbildet. Beschreibung siehe oben.

DMXSequences

Typ DMXSequenceStore. Dieses Objekt verwaltet alle angelegten Sequenzen und ermöglicht es, beliebige Sequezen abzurufen oder ihre Eigenschaften zu verändern. Es ermöglicht außerdem den Zugriff auf die DMX-Kanaldaten welche in der CompileBaseSequences-Funktion für das DMX-Gerät gesetzt werden sollten.

Ein Beispiel für eine Implementierung welche alle möglichen Sequenztypen einfügt:

Function CompileBaseSequences(DeviceType, DMXDevice, DMXSequences)
 With DMXSequences.GetOrAdd(65535)                                                           'Arming-Sequenz einbauen
  .AddDMXEvent 0, DMXDevice.StartAddress, 255, MODE_LTP, "_ARM_this_Device_"                 'Sofort: Gerätekanal 1 auf 255
  .AddDMXEvent 500, DMXDevice.StartAddress + 1, 128, MODE_LTP, "_ARM_this_Device_"           'Nach 500ms: Gerätekanal 2 auf 128. Beides im LTP-Modus
 End With
 With DMXSequences.GetOrAdd(65534)                                                           'Paused-Sequenz einbauen
  .AddDMXEvent 0, DMXDevice.StartAddress + 2, 0, MODE_LTP, "SeqPaused"                       'Sofort: Zündungkanal auf 0 damit ein dauerhafter Effekt abgeschaltet würde
 End With
 With DMXSequences.GetPrivateSequence()                                                      'Neue "private" Sequenz anlegen
  .AddDMXEvent 0, DMXDevice.StartAddress, 255, MODE_LTP, "FlameTest"                         'Scharf schalten
  .AddDMXEvent 250, DMXDevice.StartAddress + 2, 255, MODE_HTP, "FlameTest"                   'Nach 250ms den Zündkanal einschalten
  .AddDMXEvent 750, DMXDevice.StartAddress + 2, 0, MODE_HTP, "FlameTest"                     'Nach weiteren 500ms den Zündkanal abschalten

                                                                                             'Die Scharfschaltung DARF hier nicht aufgehoben
                                                                                             'werden. Sonst kommt es eventuell zu Problemen
                                                                                             'wenn die die Servicesequenz aufrufen während
                                                                                             'sowieso scharf geschaltet ist.

  .SequenceFlags = 0                                                                         'Diese Sequenz darf nicht laufen wenn das DMX-Modul unscharf ist
  .ManualSequenceName = "Test " & DMXDevice.ID                                               'Dieser Name wird dem Benutzer später in der Liste der Servicesequenzen angezeigt
  .DoIncludeManual = True                                                                    'Diese Sequenz als manuelle Sequenz mit aufnehmen
  .ManualSequenceFlags = DMX_MAN_SEQFLAG_ARM_TO_RUN                                          'Diese Sequenz erfordert es, das DMX-Modul scharf zu schalten um die Sequenz zu starten
 End With
 DMXSequences.SetChannelFlag DMXDevice.StartAddress, DMX_CHANNEL_FLAG_ARMING_LOCK            'Scharfschalte-Kanal darf nur dann > 0 werden wenn auch das DMX-Modul scharf ist
 DMXSequences.SetChannelFlag DMXDevice.StartAddress + 1, DMX_CHANNEL_FLAG_COPY_ARMED_VALUE   'Dieser Kanal wird durch die Scharf/Unscharf-Zyklen nicht beeinflusst (behält immer seinen aktuellen Wert)
 
 'Erfolg vermelden:
 CompileBaseSequences = True
End Function

Erzeugung von Cue-Sequenzen

Die eigentlichen Effekte werden mithilfe der Funktion CompileCueChannelSequence aufgerufen, welche die folgende Definition hat:

Function CompileCueChannelSequence(BaseTime, DeviceType, SequenceNumber, DMXSequences, UID, Cue, Index, DMXDevice)

BaseTime

Typ Long - Die Basiszeit der Sequenz. Diese Zeit muss zu allen Effektzeiten addiert werden und gibt einen eventuellen Offset einer Sequenz an.

DeviceType

Typ String - Der Typ des DMX-Geräts mit dem wir arbeiten

SequenceNumber

Typ Long - Die Sequenznummer in welcher das umzusetzende Ereignis liegt. Diese Sequenznummer muss anschließend aus den DMXSequences abgerufen und für die Umsetzung benutzt werden

DMXSequences

Typ DMXSequenceStore - Sequenzdaten müssen von diesem Objekt abgerufen werden. Dies erfolgt (siehe Beispiel) hier über den Aufruf von DMXSequences.GetOrAdd(SequenceNumber)

UID

Typ String - Die eindeutige ID des Cues. Diese sollte verwendet werden um alle DMX-Ereignisse anzulegen damit gewährleistet ist dass die Mischmodi LTP, HTP und Lock korrekt umgesetzt werden.

Cue

Typ Cue - Der Cue welcher in DMX-Steuerinformationen umgesetzt werden muss. Wichtige Eigenschaften und Funktionen sind unten aufgelistet.

Index

Typ Integer - Der Index der Zündung innerhalb des Cues. Wichtig um unterschiedliche Geräteeinstellungen pro Position auszulesen und abspeichern zu können.

DMXDevice

Typ DMXDevice - Das DMX-Gerät welches mit dem aktuellen Cue-Index verbunden ist. Notwendig um die DMX-Kanalinformationen zu erhalten.

Typ Cue

Der Cue ist das zentrale Verwaltungsobjekt für Zündpunkte und Effektinformationen in SkyConductor. Änderungen an einem Cue sollten immer sehr gut erprobt werden, da sie sich IMMER ZWANGSWEISE direkt auf die Funktionalität der restlichen Software auswirken. Die folgende Liste enthält einige wichtige Zugriffsfunktionen und Eigenschaften des Cue-Objektes, ist aber bei weitem nicht als vollständig anzusehen. Für Fragen zu weiteren Eigenschaften bzw. direkter Hilfe zu Problemstellungen wenden Sie sich bitte an den Hersteller der SkyConductor-Software.

PermanentIgnition

Typ Boolean - Soll der Cue eine dauerhafte Effektauslösung darstellen? Eventuell für eigene Geräte sinnvoll zu benutzen um unterschiedliche Modi abzubilden. Wird mit dem Symbol einer brennenden Lampe gekennzeichnet

Manufacturer

Typ String - Der im Showscript angezeigte Effekthersteller

IgnitionChannelCount

Typ Byte - Die Anzahl der Zündpositionen dieses Cues. Im Normalfall nicht interessant, da die Erzeugung der DMX-Daten für jede einzelne Position separat angefragt wird

IgnitionAngle(Index As Byte)

Typ Long - Der Abschusswinkel des Effekts an der angegebenen Position. Das MSB gibt an ob der Winkel ganz links gesetzt ist (Achtung: Bit 31 ist das Bit für das Vorzeichen, welches nicht benutzt wird!), das LSB ob der Winkel ganz rechts gesetzt ist. Die Richtung "gerade nach oben" wird entweder durch IgnitionAngle=0 oder ein gesetztes Bit 15 (dezimal 32768, hex 0x8000) angezeigt. Winkel können einfacher über die Hilfsfunktion Container.IsCueAngleSet getestet werden. Falls Winkel "rückwärts" gesetzt werden müssen, ist dise Eigenschaft aber zwingend zu benutzen.

IgnitorCount

Typ String - Entweder leer (""), dann wird die Anzahl der Zünder aus der Anzahl der Effekte abgeleitet. Für Strings welche eine Ganzzahl darstellen wird der hier eingetragene Wert als Zünderanzahl benutzt.

Comment

Typ String - Kommentar des Cues

Count

Typ Long - Anzahl der Effekte

Text

Typ String - Beschreibungstext des Effektes

StartOfRange

Typ Long (nur lesbar) - Absolute Zündzeit des Effekts innerhalb der Sequenz in Millisekunden

DelayTimeMs

Typ Long - Aufstiegszeit des Effekts (diese Zeit wird zur "Vorbereitung" des Effekts benötigt z.B. zum Anfahren des korrekten Startwinkels etc)

Achtung: Diese Eigenschaft muss effektabhängig in der AdjustCueData-Funktion korrekt gesetzt werden!

ExplodeTimeMs

Typ Long - Effektzeit des Effekts (hier soll der Effekt für den Zuschauer sichtbar werden)

EffectDurationMs

Typ Long - Effektdauer des Effekts (während dieser Zeit ist der Effekt für den Zuschauer sichtbar)

EndOfRange

Typ Long (nur lesbar) - Ende der Effektzeit (zu diesem Zeitpunkt wird der Effekt für den Zuschauer unsichtbar)

Beispiel für die Verwendung innerhalb einer CompileCueChannelSequence-Funktion:

Function CompileCueChannelSequence(BaseTime, DeviceType, SequenceNumber, DMXSequences, UID, Cue, Index, DMXDevice)
 With DMXSequences.GetOrAdd(SequenceNumber)                                                              'Korrekte DMX-Sequenz holen
  Select Case LCase(DeviceType)                                                                          'Je nachdem für welches Gerät wir laufen
   Case "id"                                                                                             'Wir haben nur das Gerät "id" in dieser Datei eingebaut
    If BaseTime + Cue.StartOfRange >= 0 Then                                                             'Prüfen ob so eine Auslösung überhaupt zeitlich funktioniert
     .AddDMXEvent BaseTime + Cue.StartOfRange, DMXDevice.StartAddress + 3, 255, MODE_HTP, UID            'Sicherheitskanal 50ms vorher ansteuern
     .AddDMXEvent BaseTime + Cue.ExplodeTimeMs, DMXDevice.StartAddress + 1, 255, MODE_HTP, UID           'Zündkanal genau zur Zündzeit ansteuern
     .AddDMXEvent BaseTime + Cue.EndOfRange, DMXDevice.StartAddress + 1, 0, MODE_LTP, UID                'Zündkanal genau zum Ende der Effektzeit wieder auf 0 fahren
     .AddDMXEvent BaseTime + Cue.EndOfRange, DMXDevice.StartAddress + 3, 0, MODE_LTP, UID                'Sicherheitskanal zur gleichen Zeit schließen
     CompileCueChannelSequence = True                                                                    'Erfolg vermelden
    Else
     CompileCueChannelSequence = False                                                                   'So ist leider keine Zündung möglich..
     Exit Function
    End If
  End Select
 End With
End Function

Datenübertragung in Cues

Um die Benutzungsfreundlichkeit zu steigern, sollten einige Basisdaten bereits auf einen Cue übertragen werden wenn das entsprechende DMX-Gerät ausgewählt wird. Hierfür sollten Standarddaten verwendet werden, die ohne eine weitere Bearbeitung des Cues zur Anwendung kommen würden. Im nachfolgenden Beispiel wird zumindest die Länge der Vorbereitungsphase angegeben (entsprechend der Aufstiegzeit bei einem pyrotechnischen Effekt) welche in jedem Fall und grundsätzlich vor einem Export von DMX-Daten korrekt angegeben sein muss.

Definition der Routine: Sub AdjustCueData(DeviceType, Cue, DMXDevice)

DeviceType

Typ String, die in der AddDMXDevice angegebene ID. Dient zur Unterscheidung mehrerer von der Gerätedefinition unterstützter Gerätetypen

Cue

Typ Cue - Der anzupassende Cue

DMXDevice

Typ DMXDevice - Die Gerätedefinition des DMX-Geräts

Sub AdjustCueData(Cue, DMXDevice)
 Cue.DelayTimeMs = 300
End Sub

Verwaltung von Cue-Einstellungen

Je nach DMX-Gerät können pro Auslösung unterschiedlichste Einstellungen möglich sein. Diese Einstellungen können in den seltensten Fällen über das Showscript direkt gemacht werden weil die entsprechenden Eingabeelemente dort nicht grundsätzlich vorhanden sind. Es besteht deshalb die Möglichkeit der GUI-Programmierung für die Eingabe dieser gerätespezifischen Daten. Um diese Eingabe zu ermöglichen wird bei einem Doppelklick auf den Cue die EditCue-Funktion aufgerufen. Innerhalb dieser Funktion können die Daten des Cue bearbeitet werden, so dass individuell programmierbare Effekte möglich sind. Die Funktion besitzt die folgende Signatur:

Function EditCue(DeviceType, Cue, ClickedLine, DMXDevice) Die Parameter haben die folgende Bedeutung:

DeviceType

Typ String - Typ des angesprochenen Geräts

Cue

Typ Cue - Der entsprechende Cue für welchen der Effekt bearbeitet werden soll

ClickedLine

Typ Integer - Der Index der Zeile bzw. der Position des Cues welche bearbeitet werden soll

DMXDevice

Typ DMXDevice - Das DMX-Gerät für welches die Einstellung vorgenommen werden soll

Hier fehlen Informationen zur GUI-Programmierung

Das Container-Objekt

Das Container-Objekt steht dem Gerätescript global zur Verfügung um diverse Funktionen direkt anzusprechen. Hierzu gehören Funktionen zum Speichern von Cue-Daten und auch Funktionen um Eingabeformulare etc anzeigen zu können. Folgende Funktionen sind hier definiert:

Sub SetGlobalSetting(ItemName As String, Value As String)

Über diese Funktion können globale Einstellungen für das Gerätescript abgelegt werden. Der Speicher fungiert als Key-Value-Speicher für Strings. Über den Parameter ItemName wird der Schlüssel festgelegt unter welchem der als Value bezeichnete Parameter abgelegt wird.

Function GetGlobalSetting(ItemName As String, Optional DefaultValue As String)

Diese Funktion ruft einen vorher per SetGlobalSetting gespeicherten Wert ab. Optional kann ein zweiter Parameter angegeben werden welcher zurückgegeben wird wenn die Einstellung vorher nie gespeichert wurde. In einem solchen Fall wird, sofern der DefaultValue-Parameter nicht angegeben wurde, ein leerer String zurück gegeben.

Sub SetCueSetting(ItemName As String, Value As String, Optional Index As Integer = 0)

Speichert eine Eigenschaft für den aktuellen Cue sofern sie aus einer Funktion mit "Cue"-Parameter aufgerufen wurde. Der Speicher fungiert als Key-Value-Speicher für Strings. Über den Parameter ItemName wird der Schlüssel festgelegt unter welchem der als Value bezeichnete Parameter abgelegt wird. Der Parameter Index kann optional verwendet werden wenn pro Zeile/Position (Funktionsparameter Index) unterschiedliche Informationen abgelegt werden sollen.

Function GetCueSetting(ItemName As String, Optional DefaultValue As String, Optional Index As Integer = 0)

Diese Funktion ruft einen vorher per SetCueSetting gespeicherten Wert ab. Sie kann aus einer Funktion aufgerufen werden welche einen Cue-Parameter besitzt. Optional kann ein zweiter Parameter angegeben werden welcher zurückgegeben wird wenn die Einstellung vorher nie gespeichert wurde. In einem solchen Fall wird, sofern der DefaultValue-Parameter nicht angegeben wurde, ein leerer String zurück gegeben. Der dritte, optionale Parameter Index kann verwendet werden wenn unterschiedliche Einstellungen für jede Position des Cues abgelegt werden sollen.

Function IsCueAngleSet(LeftAngle As Integer, RightAngle As Integer, Optional Index As Integer = 0) As Boolean

Diese Funktion prüft ob ein Cue an einer bestimmten Position für einen bestimmten Winkel eingetragen ist. Sie kann aus einer Funktion aufgerufen werden welche einen Cue-Parameter besitzt. Die Angaben LeftAngle und RightAngle geben als Abweichung von der Senkrechten den Suchbereich an (nach links: negativ, nach recht: positiv). Die Funktion gibt True zurück, wenn im angegebenen Bereich ein Winkel gesetzt ist. Der optionale Parameter Index gibt an welche Position des Cues durchsucht werden soll.

Function GetNewForm(Optional Caption As String = "Window") As Form

Diese Funktion gibt ein neues GUI-Fenster mit dem angegeben Titel zurück. Das zurückgegebene Fenster-Objekt kann benutzt werden, um dem Benutzer eine grafische Konfigurationsmöglichkeit für den Effekt anzubieten (siehe unten).

Sub CloseAllWindows()

Schließt alle noch offenen vom Script geöffneten Fenster

Das Form-Objekt

Das Form-Objekt ermöglicht es, innerhalb einer EditCue-Funktion eine grafische Eingabemöglichkeit zur Verfügung zu stellen. Es kann über das Container-Objekt abgerufen werden. Die wichtigsten neuen Eigenschaften und Funktionen sind nachfolgende beschrieben, zusätzlich erbt das Objekt alle Eigenschaften und Methoden des VB6.Form-Objektes (Top, Left, Width, Height, Visible, Caption, ..).

Function AddButton(ControlName As String, Top As Single, Left As Single, Height As Single, Width As Single, Caption As String) As Object

Fügt einen neuen Button an der angegebenen Position hinzu. Alle Maße werden in Pixeln angegeben, Name gibt den internen Namen und Caption die Beschriftung des Buttons an. Zurückgegeben wird ein VB.CommandButton (VB6-Objekt). Bei einem Klick auf den Button wird die Funktion <Name>_Click() aufgerufen (wenn der Name z.B. cmdOK ist heißt die Eventfunktion cmdOK_Click).

Function AddLabel(ControlName As String, Top As Single, Left As Single, Height As Single, Width As Single, Caption As String) As Object

Fügt ein neues Label (Beschriftung) an der angegebenen Position hinzu. Alle Maße werden in Pixeln angegeben, Name gibt den internen Namen und Caption die Beschriftung des Labels an. Zurückgegeben wird ein VB.Label (VB6-Objekt).

Function AddTextbox(ControlName As String, Top As Single, Left As Single, Height As Single, Width As Single, Text As String) As Object

Fügt eine neue TextBox (Eingabefeld) an der angegebenen Position hinzu. Alle Maße werden in Pixeln angegeben, Name gibt den internen Namen und Text den Inhalt des Textfeldes an. Zurückgegeben wird eine VB.TextBox (VB6-Objekt). Wenn der Inhalt des Textfeldes geändert wird, wird die Funktion <Name>_Change() aufgerufen (wenn der Name z.B. txtOK ist heißt die Eventfunktion txtOK_Change). Dies passiert auch, wenn der Text initial festgelegt wird.

Function AddCheckbox(ControlName As String, Top As Single, Left As Single, Height As Single, Width As Single, Caption As String, Optional Value As Integer) As Object

Fügt eine neuen CheckBox an der angegebenen Position hinzu. Alle Maße werden in Pixeln angegeben, Name gibt den internen Namen, Caption die Beschriftung und Value optional den Zustand der CheckBox an. Zurückgegeben wird eine VB.CheckBox (VB6-Objekt). Bei einem Klick auf die CheckBox wird die Funktion <Name>_Click() aufgerufen (wenn der Name z.B. chkOK ist heißt die Eventfunktion chkOK_Click).

Function AddCombobox(ControlName As String, Top As Single, Left As Single, Height As Single, Width As Single, ParamArray Items() As Variant) As Object

Fügt eine neuen ComboBox an der angegebenen Position hinzu. Alle Maße werden in Pixeln angegeben, Name gibt den internen Namen an. Für das Parameter-Array (beliebig viele Parameter) können beliebig viele anzuzeigende Auswahlmöglichkeiten angegeben werden (bei sehr vielen Möglicheiten sollten diese jedoch nachträglich über .AddItem hinzugefügt werden). Zurückgegeben wird eine VB.ComboBox (VB6-Objekt). Bei der Auswahl eines anderen Eintrages wird die Funktion <Name>_Click() aufgerufen, wenn eine Freitexteingabe möglich ist und der Inhalt geändert wird die <Name>_Change()-Funktion. Wenn der Name z.B. cmbOK ist heißen die Eventfunktionen cmbOK_Click und cmbOK_Change).

Anmerkung: Die gleiche Funktion mit dem Namen AddComboboxEx erwartet abwechselnd einen Eintragnamen (Typ String) und die dafür vorgesehenen Eintrag ItemData (Typ Integer) wobei zuerst der Eintragname stehen muss.

Function AddColorPicker(ControlName As String, Top As Single, Left As Single, Height As Single, Width As Single, Color As Long) As Object

Fügt ein neuenes Farbauswahl-Feld an der angegebenen Position hinzu. Alle Maße werden in Pixeln angegeben, Name gibt den internen Namen und Color die initiale Farbe des Feldes an. Zurückgegeben wird ein Farbauswahlfeld mit den Eigenschaften Color, Visible, Top, Left, Height und Width. Wenn die Farbe geändert wurde wird die Funktion <Name>_Change() aufgerufen (wenn der Name z.B. colOK ist heißt die Eventfunktion colOK_Change).

Function GetControl(Name As String) As Object

Ruft ein vorher per Add.... hinzugefügtes Objekt ab. Funktioniert jedoch z.Zt. nicht für ColorPicker.