エンジンと高速化

このプラグインには複数の実行エンジンがあります。標準は同梱の LuaJIT ネイティブレーンで、 決まった形の重いピクセル処理はさらに CPU カーネルへ変換されます。Lua 5.2 互換の MoonSharp は フォールバック用の従来エンジンです。指定子を書かなくても、内容に応じて自動で最適なレーンが選ばれます。

エンジンの種類

指定子の書き方

エンジンの指定子は --! で始まる 1 行です。トークンの前後の空白以外に文字があってはいけません。 スクリプトのどの行に書いても構いません。

--!native
for y = 0, obj.h - 1 do
    for x = 0, obj.w - 1 do
        local r, g, b, a = obj.getpixel(x, y)
        obj.setpixel(x, y, 255 - r, 255 - g, 255 - b, a)
    end
end

自動振り分け

指定子が無いときは、スクリプトの内容から自動でエンジンが選ばれます。

• 後述のカーネル条件に当てはまるピクセルループは、まず GPU カーネルを試します。初回に実機の GPU で 処理し、CPU カーネルと出力が許容差に収まるか検証します。収まれば以後は GPU カーネル、収まらなければ CPU カーネルで実行します。CPU カーネルの結果は MoonSharp と一致します。
• それ以外のスクリプトは、同梱の LuaJIT ネイティブで実行します。結果は MoonSharp と一致します。
• native フォルダが配備されていない環境と空のスクリプトは、MoonSharp で実行します。

カーネルに変換できる形

CPU / GPU カーネルは、次の決まった形のスクリプトだけを変換します。条件に合わないスクリプトは カーネルにならず、自動でほかのエンジンへフォールバックします（結果は変わりません）。

• 先頭に local 宣言を置いてもよい。
• 本体は二重の数値 for ループ 1 組だけ。外側と内側で obj.h と obj.w をそれぞれ 0 から -1 まで回す。上限には local w = obj.w のような別名も使える。
• 内側ループの最初が local r, g, b[, a] = obj.getpixel(x, y)、最後が obj.setpixel(x, y, ...)。
• その間は local 宣言と代入、および if / elseif / else による local 変数への条件代入のみ。

obj.getpixeldata() で得たハンドルの get / set を local i = (y * data.width + x) * 4 の基底インデックスで使う形も同様にカーネル化されます。 ループの後の obj.putpixeldata(data) は置いても置かなくてもかまいません。 if 文の中で obj.setpixel や set を呼ぶ形はカーネル化されません。

カーネル内で使える要素は限られます。

カーネルになるグレースケールの例

for y = 0, obj.h - 1 do
    for x = 0, obj.w - 1 do
        local r, g, b, a = obj.getpixel(x, y)
        local gray = r * 0.299 + g * 0.587 + b * 0.114
        obj.setpixel(x, y, gray, gray, gray, a)
    end
end

フォールバックの動き

• --!native を指定しても、プラグインの隣に native フォルダが配置されていない場合は MoonSharp で実行されます（ログに一度だけ警告が出ます）。期待した高速化が得られないときは、 ビルド・配置に native フォルダが含まれているか確認してください。
• --!gpu を指定しても、GPU カーネルを初期化できない場合は CPU カーネル、さらに MoonSharp の順で フォールバックします。
• --!cpu を指定してもカーネル条件に合わないスクリプトは、ほかのエンジンで実行されます。
• MoonSharp では tempbuffer への描画合成を GPU で実行し、GPU を利用できない環境では CPU の合成へ自動的に切り替わります。丸めの違いにより、合成の結果はエンジン間で ごく僅かに異なることがあります。