Q Light Controller Plus - User Documentation Q Light Controller Plus - User DocumentationRGBマトリックスのアニメーションを作ることができます。基本概念として、大量のRGB値を１フレームごとに操作していくことを覚えておいてください。 パラパラ漫画を想像してもらえればわかりやすいかと思います、１フレームを描画し、また次のフレームを描画するのを繰り返していけばいいのです。
このRGB ScriptはECMAScriptに基づいており、JavaScriptに似た構文です。※APIのメソッド名は基本的にはキャラメルケースにしたがって命名されています。スクリプトを作成する時に参考にしてください。
スクリプトファイル名の拡張子は.jsです。 プリインストールされているRGBスクリプトは以下のパスに保存されています。
スクリプトは必ず無名関数の中に記述してください、C言語のようにinit関数が呼ばれるといったことはなく、ただスクリプトの頭から随時実行されていくだけです。 また、スクリプトは１つのオブジェクトのプロパティーを操作していく構造です。returnでオブジェクトを返り値に持つ必要があります。 以下に必要最低限のコードを示します。
(
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 evaluation
|
return でオブジェクトを返却しないスクリプトは実行されても何も動作しません。QLC+が評価するのは返却したオブジェクトのみです。以下のプロパティーでスクリプトの情報を持たせると、QLC+上に表示されるようになります。これらのプロパティーは必須です。
Sample
(
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;
}
)()
|
Now we are getting to the actual business of producing data for the RGB Matrix. The current API version uses two functions to achieve this:
この関数はQLC+がRGBマトリックスのフィクスチャーの高さと幅からアニメーションを一周再生する際に何ステップかかるかどうかを返り値で返す必要があります。同じ幅と高さが引数で与えられた時の返り値は何回この関数を呼び出しても必ず同じにならなければなりません。
パラメーター：
Sample
(
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;
}
)()
|
このファンクションがアニメーションの描画処理を行います。この関数には必ずheightの数とwidthの数と同じ２次元配列を返り値として持たせてください。返り値の配列はheightとwidthの数分の内容を持ち、QRgbの形式で(0x00RRGGBB)ピクセルの色を32bitの整数型で代入してください。引数rgbには、RGBマトリクスエディタでユーザーが選択した色の整数表現が与えられています。stepには "0" から "rgbMapStepCount(w, h) - 1" の整数が与えられます。
パラメータ:
Sample
(
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_jabberwock;
}
algo.rgbMap = function(width, height, rgb, step) {
...
return a_2d_array_of_arrays;
}
return algo;
}
)()
|
APIバージョン２の文法ではプロパティーの概念が追加されています。 QLC+のエディター上にオプションの設定フィールドを表示させることが可能になり、スクリプト側から希望の形式でユーザーからのプロパティーを取得することができるようになりました。
追加されたプロパティーはアニメーションの向きやレンダリングされるオブジェクト数などです。
実装は以下の説明に従ってください。
Sample
algo.orientation = 0;
algo.properties = new Array();
algo.properties.push("name:orientation|type:list|display:Orientation|values:Horizontal,Vertical|write:setOrientation|read:getOrientation");
ポイントとなるのは３点です。| 属性名: | value |
| name | QLC+側がプロパティーを識別するためのユニークな名前 混乱を避けるため、スクリプト内でreturn のために作成してあるオブジェクト名(Sampleではalgo)を使用することをお勧めします。 |
| type | QLC+上でプロパティーとしてユーザーに入力させる形式を指定できます。'type' 属性は、'values'属性よりも先に記述する必要があります。 形式は以下の通りです。
|
| display | QLC+のエディタ上に文字を表示させることができます。アニメーションの説明文等をエディタ上に表できます。 |
| values | この属性は、typeが 'list'または 'range'の場合にのみ適用できます。これはプロパティが想定できる値を定義します。'list'タイプは 'one,two,three'のようになり、 'range'タイプは '2,10'のようになります。 これらの値は ','カンマ区切りで記述します。'range'で指定できるのは１つの範囲のみです、２個以上は指定できません |
| write | QLC +がプロパティ値を書き込むために呼び出すスクリプト関数の名前を定義します。 この機能では、スクリプトの作者は、プロパティの変更を適用するために必要なすべてのアクションを実装する必要があります。 上記の例のwriteメソッドは次のとおりです。
algo.setOrientation = function(_orientation) {
if (_orientation == "Vertical")
algo.orientation = 1;
else
algo.orientation = 0;
}
|
| read | QLC +がプロパティ値を読み取るために呼び出すスクリプト関数の名前を定義します。 上記の例のreadメソッドは次のとおりです。
algo.getOrientation = function() {
if (algo.orientation == 1)
return "Vertical";
else
return "Horizontal";
}
|
スクリプトの文法チェックを行うことができます。 以下の２ファイルを同じディレクトリに保存しブラウザで実行してください。
/*
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;
}
)()
|