Q Light Controller Plus - RGB Script API

# RGB Script API

RGBマトリックスのアニメーションを作ることができます。基本概念として、大量のRGB値を１フレームごとに操作していくことを覚えておいてください。 　パラパラ漫画を想像してもらえればわかりやすいかと思います、１フレームを描画し、また次のフレームを描画するのを繰り返していけばいいのです。

このRGB ScriptはECMAScriptに基づいており、JavaScriptに似た構文です。※APIのメソッド名は基本的にはキャラメルケースにしたがって命名されています。スクリプトを作成する時に参考にしてください。

スクリプトファイル名の拡張子は.jsです。 　プリインストールされているRGBスクリプトは以下のパスに保存されています。

- Linux user dir: ~/.qlcplus/rgbscripts/
- Linux system dir: /usr/share/qlcplus/rgbscripts/

- OSX user dir: ~/Library/Application Support/QLC+/RGBScripts
- OSX system dir: /Applications/QLC+.app/Contents/Resources/RGBScripts

- Windows user dir: %HOMEPATH%\QLC+\RGBScripts
- Windows system dir: C:\QLC+\RGBScripts

# RGB Script API

## Foundation

スクリプトは必ず無名関数の中に記述してください、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+上に表示されるようになります。これらのプロパティーは必須です。

- {Object}.apiVersion: 指定したバージョンのAPIで実行されます。今のところAPIのバージョンは ' 1 'と' 2 'があります。
  APIバージョン１では簡単にスクリプトが作成できるような機能が実装されていました、バージョン２ではさらに高度なアニメーションを実現できるような機能が実装されています。詳しくはこちら
  それ以外の数値を指定するとスクリプトは実行されません。
- {Object}.name: スクリプト名ここで設定した名前がRGB マトリックスエディターに表示されます。
- {Object}.author: 作者名を設定してください。
- {Object}.acceptColors 【必須ではありません】: 開始色と終了色を設定できるかどうかをQLC+に通知します。
  '{Object}.acceptColors = 0' 選択された色をスクリプトに渡しません。
  '{Object}.acceptColors = 1' 開始色のみスクリプトに渡します。
  '{Object}.acceptColors = 2' 【デフォルト】開始色と終了色のどちらもスクリプトに渡します。
  このプロパティーが設定されていない場合は2が設定された時と同じ扱いになります。

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;
        }
        )()

## Functions

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:

- rgbMapStepCount(width, height)
- rgbMap(width, height, rgb, step)

これらの関数に同じ引数を与えた時に必ず同じ返り値を返す必要があり、乱数などを使用することは避けてください。 　これらの関数が呼び出される際の引数はQLC+上でユーザーが設定を変更したタイミングで変更されます。

### rgbMapStepCount(width, height)

この関数はQLC+がRGBマトリックスのフィクスチャーの高さと幅からアニメーションを一周再生する際に何ステップかかるかどうかを返り値で返す必要があります。同じ幅と高さが引数で与えられた時の返り値は何回この関数を呼び出しても必ず同じにならなければなりません。

パラメーター：

- width: フィクスチャーの横の列数
- height: フィクスチャーの縦の行数
- 返り値: 再生にかかるステップ数を整数型で返却してください。

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;
        }
        )()

### rgbMap(width, height, rgb, step)

このファンクションがアニメーションの描画処理を行います。この関数には必ずheightの数とwidthの数と同じ２次元配列を返り値として持たせてください。返り値の配列はheightとwidthの数分の内容を持ち、QRgbの形式で(0x00RRGGBB)ピクセルの色を32bitの整数型で代入してください。引数rgbには、RGBマトリクスエディタでユーザーが選択した色の整数表現が与えられています。stepには "0" から "rgbMapStepCount(w, h) - 1" の整数が与えられます。

パラメータ:

- width: フィクスチャーの横の列数
- height: フィクスチャーの縦の行数
- rgb:エディターでユーザーが指定したカラーコード
- stepには "0" から "rgbMapStepCount(w, h) - 1" の整数が与えられます。
- 返り値: Array[{height}][{width}]で表される２次元配列を返却してください。

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 バージョン2

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");

ポイントとなるのは３点です。

1. ユーザーが設定した値を格納する変数名を指定してください。
2. オブジェクトの{Object},propertiesを配列で初期化します。一度だけこの作業を行なってください。
3. Push (add) メソッドに後述の記法に従ってユーザーに設定させたいプロパティー項目等をQLC+側に通知します。

記法は'name:value' で構成されており、'|'パイプを使って情報を区切る必要があります。
属性の一覧は以下の通りです。

属性名: | value
name | QLC+側がプロパティーを識別するためのユニークな名前 　混乱を避けるため、スクリプト内でreturn のために作成してあるオブジェクト名(Sampleではalgo)を使用することをお勧めします。
type | QLC+上でプロパティーとしてユーザーに入力させる形式を指定できます。'type' 属性は、'values'属性よりも先に記述する必要があります。 形式は以下の通りです。 list: プルダウンメニューからユーザーに選択させることができます。 range ：このプロパティが扱うことができる整数値の範囲 integer:整数値 string:文字列
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";
        }

## Development Tool

スクリプトの文法チェックを行うことができます。　以下の２ファイルを同じディレクトリに保存しブラウザで実行してください。

- devtool.html
- devtool.js

## Example Script: Full Columns

        /*
          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;
        }
        )()