Benutzer können ihre eigenen RGB-Skripte schreiben, um mit der Funktion RGB-Matrix eine benutzerdefinierte Grafikprojektion zu erstellen. Das Funktionsprinzip der Skripte besteht darin, eine Reihe von RGB-Karten zu erstellen, die jeweils einen Schritt in der Grafikanimation darstellen. Das Prinzip ist im Grunde dasselbe wie in Filmen: Der Zuschauer sieht ein bewegtes Bild, das in Wirklichkeit nur ein nacheinander abgespielter Strom statischer Bilder ist, die eine Illusion von Bewegung erzeugen.
Die Skripte selbst sind in ECMAScript geschrieben, das auch als JavaScript bekannt ist. Beachten Sie, dass die Sprache Groß-/Kleinschreibung beachtet und standardmäßig den Kamel-Groß-/Kleinschreibungsregeln folgt. 28programming%29#JavaScript), stellen Sie also sicher, dass Sie alles richtig schreiben und achten Sie besonders auf die erforderlichen API-Funktionen.
Skriptdateien sollten nach dem Namen des Skripts benannt werden und die Erweiterung .js haben. Abhängig von der Plattform sollten die Dateien entweder im QLC+-Systemskriptverzeichnis oder vorzugsweise im Benutzerskriptverzeichnis abgelegt werden:
Linux-Benutzerverzeichnis: ~/.qlcplus/rgbscripts/
Linux-Systemverzeichnis: /usr/share/qlcplus/rgbscripts/
OSX-Benutzerverzeichnis: ~/Library/Application Support/QLC+/RGBScripts
OSX-Systemverzeichnis: /Applications/QLC+.app/Contents/Resources/RGBScripts
Windows-Benutzerverzeichnis: %HOMEPATH%\QLC+\RGBScripts
Windows-Systemverzeichnis: C:\QLC+\RGBScripts
Die Skripte müssen selbstausführend sein, d.h. wenn sie ausgewertet werden, wird das Skript selbst in eine anonyme Funktion eingefügt, die sich selbst ausführt und ein Objekt zurückgibt, das die erforderlichen API-Funktionen enthält:
(
function() { // Anonymous function starts here
var algo = new Object;
return algo; // Return the script object
} // Anonymous function ends here
)() // Anonymous function is executed here upon evaluationAllerdings bewirkt ein Skript, das nichts weiter als ein leeres Objekt enthält, nichts, egal wie selbstausführend es auch sein mag. Sie müssen auch einige Eigenschaften für das zurückgegebene Objekt deklarieren, damit QLC+ weiß, wie das Skript verwendet wird und es dem Benutzer (Ihnen) angezeigt wird. Daher müssen Sie die folgenden Eigenschaften für das zurückgegebene Skriptobjekt deklarieren:
Vor diesem Hintergrund fügen wir dem Skript Deklarationen für diese drei Eigenschaften hinzu:
(
function() {
var algo = new Object;
algo.apiVersion = 2; // Can be '1' or '2'
algo.name = "My cool RGB script";
algo.author = "Your name";
algo.acceptColors = 2; // Can be '0', '1' or '2'
return algo;
}
)()Jetzt kommen wir zum eigentlichen Geschäft der Datenerstellung für die RGB-Matrix. Die aktuelle API-Version nutzt dazu zwei Funktionen:
Es sollten keine Annahmen über die Aufrufreihenfolge oder die Unveränderlichkeit der Argumente gemacht werden, d. h. die Werte von keiner der Funktionen zwischenspeichern und davon ausgehen, dass sie bis zum Ende der Welt gültig sind. Die Parameter können sich jederzeit ändern (normalerweise, wenn der Benutzer die Matrixgröße, -farbe oder -richtung ändert), wodurch alle zwischengespeicherten Werte ungültig werden.
Wenn QLC+ diese Funktion aufruft, möchte es die Anzahl der verschiedenen RGB-Karten wissen, die von der Funktion rgbMap() zurückgegeben werden, wenn die RGB-Matrixgröße Breite mal Höhe Pixel beträgt. Es muss immer das gleiche Ergebnis zurückgeben, wenn es erneut mit denselben Parametern Breite und Höhe aufgerufen wird, und das Ergebnis darf sich im Laufe der Zeit nicht ändern.
Parameter:
Nun fügen wir dem Skript diese Unterstützungsfunktion hinzu:
(
function() {
var algo = new Object;
algo.apiVersion = 1;
algo.name = "My cool RGB script";
algo.author = "Your name";
algo.rgbMapStepCount = function(width, height) {
...
return number_of_steps_when_width_is_oranges_and_height_is_jabberwocky;
}
return algo;
}
)()Diese Funktion ist das eigentliche Gehirn des Skripts. Es werden zweidimensionale Arrays erzeugt, deren Größe Höhe mal Breite sein MUSS. D.h. Das von dieser Funktion zurückgegebene Array muss Höhe-Elemente enthalten und jedes dieser Elemente muss ein Array sein, das Breite-Elemente enthält, die 32-Bit-Ganzzahlen sein müssen und eine RGB-Farbe im Sinne von [QRgb](https: //doc.qt.io/qt-5/qcolor.html#QRgb-typedef) ohne Alphakanal (0x00RRGGBB). Der Parameter rgb ist eine ganzzahlige Darstellung der vom Benutzer im RGB-Matrix-Editor ausgewählten Farbe. Der Parameter step gibt die von der RGB-Matrixfunktion angeforderte Schrittnummer an und liegt garantiert innerhalb von (0, rgbMapStepCount(w, h) – 1).
Parameter:
Genau wie die vorherige Funktion fügen wir auch diese andere zum Skript hinzu. Jetzt haben wir eine vollständige und fertige Vorlage für jedes RGB-Skript zu Ihrem Vergnügen.
(
function() {
var algo = new Object;
algo.apiVersion = 1;
algo.name = "My cool RGB script";
algo.author = "Your name";
algo.rgbMapStepCount = function(width, height) {
...
return number_of_steps_when_width_is_oranges_and_height_is_jabberwocky;
}
algo.rgbMap = function(width, height, rgb, step) {
...
return a_2d_array_of_arrays;
}
return algo;
}
)()RGB Script API Version 2 führt das Konzept der Eigenschaften ein. Mit Eigenschaften kann ein Skript durch den Austausch von Parametern mit der QLC+-Engine interagieren und so die Möglichkeiten eines RGB-Skripts erweitern.
Beispiele für solche Eigenschaften können die Animationsausrichtung, die Anzahl der zu rendernden Objekte usw. sein.
Das Hinzufügen von Eigenschaften zu Ihrem Skript ist recht einfach, erfordert jedoch eine bestimmte Syntax, die in diesem Absatz erläutert wird.
Machen wir ein Beispiel:v
algo.orientation = 0;
algo.properties = new Array();
algo.properties.push("name:orientation|type:list|display:Orientation|values:Horizontal,Vertical|write:setOrientation|read:getOrientation");Die drei Zeilen oben geben Folgendes an:
| Attributname | Attributwert |
| Name | Der von QLC+ verwendete Name zur eindeutigen Identifizierung einer Eigenschaft. Der gleiche Name darf in einem Skript nicht zweimal verwendet werden. Es empfiehlt sich, denselben Namen wie die Variable „algo“ zu verwenden, in der die Eigenschaft tatsächlich gespeichert ist. |
| Typ | Dies ist ein grundlegendes Attribut, damit QLC+ eine Eigenschaft korrekt verarbeiten kann. Das Attribut „type“ muss vor dem Attribut „values“ platziert werden. Akzeptierte Werte sind: list: definiert eine Liste von Zeichenfolgen, die vom QLC+ RGB Matrix Editor angezeigt werden range: definiert einen Bereich von ganzzahligen Werten, die Diese Eigenschaft kann verarbeiten float: ein Float-Wert, den QLC+ mit dem Skript austauschen kann string: ein String, den QLC+ mit dem Skript austauschen kann Das Typattribut Definiert implizit auch, wie der QLC+ RGB-Matrix-Editor funktioniert zeigt die Eigenschaft an. Beispielsweise wird eine „Liste“ wie ein Dropdown-Feld angezeigt, ein „Bereich“ und eine „Ganzzahl“ werden als Drehfeld angezeigt, eine „Zeichenfolge“ wird als bearbeitbares Textfeld angezeigt. |
| Anzeige | Eine Zeichenfolge, die QLC+ dem Benutzer im RGB-Matrix-Editor anzeigt. Es empfiehlt sich, eine aussagekräftige und für Menschen lesbare Zeichenfolge zu verwenden, damit Benutzer sofort verstehen, was eine Eigenschaft bewirkt |
| Werte | Dieses Attribut kann nur angewendet werden, wenn der Typ „Liste“ oder „Bereich“ ist. Es definiert die möglichen Werte, die die Eigenschaft annehmen kann. Der Typ „Liste“ sieht wie „eins, zwei, drei“ aus, während der Typ „Bereich“ wie „2,10“ aussieht. Werte müssen durch ein Komma „,“ getrennt werden. Ein Bereichstyp kann nicht mehr als zwei Werte haben. |
| schreiben | Definiert den Namen der Skriptfunktion, die QLC+ aufrufen soll, um den Eigenschaftswert zu schreiben. In dieser Funktion sollte der Autor des Skripts alle notwendigen Aktionen implementieren, um die Eigenschaftsänderung anzuwenden. Die Schreibmethode des obigen Beispiels ist die folgende: algo.setOrientation = function(_orientation) { if (_orientation == "Vertical") algo. Orientierung = 1; else algo.orientation = 0; } |
| lesen | Definiert den Namen der Skriptfunktion, die QLC+ aufrufen soll, um den Eigenschaftswert zu lesen. Die Lesemethode des obigen Beispiels ist die folgende: algo.getOrientation = function() { if (algo.orientation == 1) return "Vertical "; else return "Horizontal"; } |
Im QLC+-Quell-Repository steht ein Entwicklungstool zur Verfügung, das das Debuggen und Testen Ihrer benutzerdefinierten Skripte mit einem Webbrowser erleichtert. Um das Tool zu verwenden, müssen Sie die folgenden zwei Dateien in ein Verzeichnis auf Ihrer Festplatte herunterladen, die Datei devtool.html mit Ihrem Browser öffnen und deren Anweisungen befolgen:
(Rechtsklick und „Link-Speicherort kopieren“ funktioniert wahrscheinlich am besten.)
/*
Q Light Controller Plus
fullcolumns.js
Copyright (c) Heikki Junnila
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0.txt
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
(
/\*\*
\* This algorithm produces fully-lit columns, meaning all pixels on a single
\* column are lit together.
*/
function()
{
var algo = new Object;
algo.apiVersion = 1;
algo.name = "Full Columns";
algo.author = "Heikki Junnila";
/\*\*
\* The actual "algorithm" for this RGB script. Produces a map of
\* size($width, $height) each time it is called.
\*
\* @param step The step number that is requested (0 to (algo.rgbMapStepCount - 1))
\* @param rgb Tells the color requested by user in the UI.
\* @return A two-dimensional array\[height\]\[width\].
*/
algo.rgbMap = function(width, height, rgb, step)
{
var map = new Array(height);
for (var y = 0; y < height; y++)
{
map\[y\] = new Array();
for (var x = 0; x < width; x++)
{
if (x == step)
map\[y\]\[x\] = rgb;
else
map\[y\]\[x\] = 0;
}
}
return map;
}
/\*\*
\* Tells RGB Matrix how many steps this algorithm produces with size($width, $height)
\*
\* @param width The width of the map
\* @param height The height of the map
\* @return Number of steps required for a map of size($width, $height)
*/
algo.rgbMapStepCount = function(width, height)
{
// Each column is lit completely at a time, so because there are $width
// columns in the map, the number of steps must be $width to light all
// columns per round.
return width;
}
return algo;
}
)()Version 3 der RGB-Skript-API führt den Zugriff auf rawColors ein und bietet Skripten die Möglichkeit, die im RGB-Matrix-Editor ausgewählten Farben direkt zu verwenden. Diese Verbesserung ermöglicht dynamischere und synchronisiertere Lichteffekte, insbesondere bei mehrfarbigen Animationen.
Der Parameter „rawColors“ wird an die Funktion „rgbMap“ übergeben und enthält ein Array der vom Benutzer ausgewählten RGB-Werte. Dadurch können Skripte Animationen basierend auf Benutzereingaben dynamisch anpassen.
Ein Beispiel für die Verwendung der neuen API finden Sie inballs.js.