スクリプトリファレンス（[RootEffect]マテリアル） - SpriteStudio/SS6PlayerForUnity GitHub Wiki

SS6Player for Unity（以降「SS6PU」）のエフェクト制御用クラス（Script_SpriteStudio6_RootEffect）のマテリアル管理関係の機能群のスクリプトリファレンスです。

SS6PU Ver.1.x系まではエフェクトの単独の設置が非推奨だったため、本リファレンスで解説しているのは「Ver.2.0以降」のみとなっています。

エフェクト描画用マテリアルの取得

関数（動的）

UnityEngine.Material MaterialGet(
        int indexCellMap,
        Library_SpriteStudio6.KindOperationBlendEffect operationBlend,
        Library_SpriteStudio6.KindMasking masking,
        string nameShader,
        bool flagCreateNew,
        UnityEngine.Shader shader=null,
        Library_SpriteStudio6.CallBack.FunctionMaterialSetUp functionMaterialSetUp=null
    )

引数

  • indexCellMap : セルマップ番号
  • operationBlend : ブレンド種別
  • masking : マスキング種別
  • nameShader : シェーダ名
  • flagCreateNew : 既存しなかった場合に新規作成するか？
  • shader : 使用するシェーダ
  • functionMaterialSetUp : マテリアル作成時に呼ばれる追加設定関数

返値

対象マテリアルの参照
null ... マテリアルが既存していない / 失敗（エラー）

解説

現在エフェクトが使用しているマテリアルキャッシュから、下記の完全一致で特定される描画用マテリアルを取得します。

  • indexCellMap : セルマップ番号
  • operationBlend : ブレンド種別
  • masking : マスキング種別
  • nameShader : シェーダ名

本関数は「エフェクト」用のマテリアルしか取得することはできません（アニメーション用のマテリアルは取得できません）。

基本的に、SS6PUの内部処理以外からはあまり使用する機会はないと思われ、「アプリケーション専用のシェーダなどで描画するための専用マテリアルを事前定義したい」場合などが使用機会として存在する程度だと思われます。
Ver.2.0以降では描画用のマテリアルが描画時に動的に作成されるようになったため、「まだ描画に一度も使用されていないマテリアル」については、実際に描画で使用されるタイミングになるまでマテリアルキャッシュの中に登録されていない状態になることに注意してください。
つまり「既存のシェーダを代替して・機能を差し替える（既存シェーダをオーバーライドするよう）」シェーダを作成して・運用するような場合に「事前にマテリアルキャッシュに登録しておかないと、（マテリアルの作成される瞬間が特定できないため）MaterialReplaceAnimation関数などではシェーダ差し替えができないシチュエーションを回避するために「事前に使用するマテリアルを登録してしまう（エフェクトで必要になった瞬間には既存としておく）」ような処理を行うために本関数を使用します。

indexCellMapは対象とするセルマップで、0オリジンの番号（インデックス）です。

operationBlendは対象とするブレンド種別で、下記の指定となります。

  • MIX : 描画モード「ミックス」用
  • ADD : 描画モード「加算」用

maskingは対象とするマスキング種別で、下記の指定となります。

  • THROUGH : マスク対象非チェック（マスキングなし）用
  • MASK : マスク対象チェック（マスキングあり）用

nameShaderはアニメーションデータ中で指定している「描画に使用するシェーダ名」で、SpriteStudio6の「シェーダ」アトリビュートで指定している「シェーダID」と結びついている「シェーダのファイル名」と同一です。
ただし、現在SpriteStudio6上では、エフェクトでユーザーシェーダを適用する方法がありませんので、現状は「ほぼ任意」となり「null（標準指定）」以外の指定についてはほぼ効果できない形となります。
nullを指定すると「標準シェーダ」の指定となります。

flagCreateNewは、trueを指定するとマテリアルキャッシュ内に該当するマテリアルが既存しない場合に、新しくマテリアルを作成して・マテリアルキャッシュに登録し・そのマテリアルを返します。
falseを指定するとマテリアルキャッシュに該当するマテリアルが既存しない場合は、null（該当マテリアルなし）を返します。

shaderは、（マテリアルを新規作成する場合に）マテリアルに使用するシェーダを指定します。
nullを指定すると「標準シェーダ」の指定となります。

functionMaterialSetUpは、（マテリアルを新規作成する場合に）シェーダとテクスチャを割り当てたマテリアルに追加設定などを行うための関数を指定します。
通常は指定された「ブレンド種別」「マスキング」に妥当な設定をマテリアルに行う処理を担当します。
nullを指定するとSS6PUの通常のマテリアルへの設定処理を行います。
本関数を指定しなくてはならないシチュエーションとしては、自作したシェーダなどをshaderに指定し・かつ「（その）シェーダがSS6PUの標準シェーダと各種設定などの非互換性を持つ（＝SS6PUが持つ設定処理の代替処理が必要）」などが挙げられます。

このfunctionMaterialSetUpは下記の仕様を持った関数です。

UnityEngine.Material FunctionMaterialSetUp(
        UnityEngine.Material material,
        int operationBlend, 
        Library_SpriteStudio6.KindMasking masking,
        bool flagZWrite
    )

  • 引数

    • material : 新規作成されたマテリアル
    • operationBlend : 描画時のブレンド種別（実値がLibrary_SpriteStudio6.KindOperationBlend型か Library_SpriteStudio6.KindOperationBlendEffect型の場合があるので、intにキャストされています）
    • masking : マスキングの種別
    • flagZWrite : Zバッファへの書き込みを行うかのフラグです（trueで書き込みを行う）

  • 返値
    設定が終了したマテリアルへの参照（通常は引数のmaterialを返します）
    null : 処理が失敗した

エフェクト描画用マテリアルの差し替え

関数（動的）

UnityEngine.Material MaterialReplace(
        int indexCellMap,
        Library_SpriteStudio6.KindOperationBlendEffect operationBlend,
        Library_SpriteStudio6.KindMasking masking,
        string nameShader,
        UnityEngine.Material material,
        bool flagGlobal=false
    )

引数

  • indexCellMap : セルマップ番号
  • operationBlend : ブレンド種別
  • masking : マスキング種別
  • nameShader : シェーダ名
  • material : 新しく設定するマテリアル
  • flagGlobal : グローバルのマテリアルキャッシュが対象か？

返値

元々設定されていたマテリアル
null ... 対象マテリアルが存在していない / 失敗（エラー）

解説

現在エフェクトが使用しているマテリアルキャッシュから、下記の完全一致で特定されるエフェクト描画用マテリアルを取得します。

  • indexCellMap : セルマップ番号
  • operationBlend : ブレンド種別
  • masking : マスキング種別
  • nameShader : シェーダ名

本関数の注意点として、「マテリアルキャッシュに既存しているマテリアル（＝描画で使用されたことがあるマテリアル）」しか対象とできないことにあります。
つまり、「将来描画に使用されることが解っている」マテリアルでも、まだ描画に使用されていない場合にはマテリアルキャッシュ内に存在しないために、対象とすることができません（検索で発見できない）。 そのような「先行的に使用されると解っているマテリアル」を定義したい場合については、MaterialGet関数などを使用して新規定義するようにしてください。

indexCellMapは対象とするセルマップで、0オリジンの番号（インデックス）です。

operationBlendは対象とするブレンド種別で、下記の指定となります。

  • MIX : 描画モード「ミックス」用
  • ADD : 描画モード「加算」用

maskingは対象とするマスキング種別で、下記の指定となります。

  • THROUGH : マスク対象非チェック（マスキングなし）用
  • MASK : マスク対象チェック（マスキングあり）用

nameShaderはアニメーションデータ中で指定している「描画に使用するシェーダ名」で、SpriteStudio6の「シェーダ」アトリビュートで指定している「シェーダID」と結びついている「シェーダのファイル名」と同一です。
ただし、現在SpriteStudio6上では、エフェクトでユーザーシェーダを適用する方法がありませんので、現状は「ほぼ任意」となり「null（標準指定）」以外の指定についてはほぼ効果できない形となります。
nullを指定すると「標準シェーダ」の指定となります。

materialは、新しく設定する（差し替える）マテリアルです。
nullを指定すると、その特定されたマテリアルをマテリアルキャッシュから消去します。

flagGlobalは、trueで大域（現時点描画されている全てのSS6PU描画オブジェクト間で共用されている）マテリアルキャッシュ内のマテリアル群が対象です。
falseで局所（単体のエフェクトでのみ使用している）マテリアルキャッシュ内のマテリアルが対象となります。

エフェクト用標準シェーダの設定

関数（動的）

UnityEngine.Shader ShaderSetStandardEffect(
        UnityEngine.Shader shader,
        Library_SpriteStudio6.CallBack.FunctionMaterialSetUp functionMaterialSetUp,
        bool flagReplaceMaterialCache,
        bool flagGlobal = false
    )

引数

  • shader : 新規設定するシェーダ
  • functionMaterialSetUp : shaderを使用したマテリアルを初期設定するための関数
  • flagReplaceMaterialCache : 既存のキャッシュの内容も置き換えるか？
  • flagGlobal : グローバルのマテリアルキャッシュが対象か？

返値

元々設定されていたシェーダ
null ... 失敗（エラー）

解説

SS6PUが持っているエフェクト描画用（のマテリアルに割り当てられる）標準シェーダを変更します。

shaderは新しく標準シェーダに設定するシェーダです。
nullを指定すると、本来SS6PUが持っている標準シェーダを設定します。

functionMaterialSetUpは、（マテリアルを新規作成する場合に）シェーダとテクスチャを割り当てたマテリアルに追加設定などを行うための関数を指定します。
通常は指定された「ブレンド種別」「マスキング」に妥当な設定をマテリアルに行う処理を担当します。
nullを指定するとSS6PUの通常のマテリアルへの設定処理を行います。
本関数を指定しなくてはならないシチュエーションとしては、自作したシェーダなどをshaderに指定し・かつ「（その）シェーダがSS6PUの標準シェーダと各種設定などの非互換性を持つ（＝SS6PUが持つ設定処理の代替処理が必要）」などが挙げられます。
本関数の仕様は、MaterialGet関数の解説を参照してください。

flagReplaceMaterialCacheは、trueを設定すると「現在マテリアルキャッシュに既存している標準シェーダを使用しているマテリアル」のシェーダを全て置き換えます。
falseを設定すると「既存のマテリアルキャッシュ内のマテリアルはそのままで、本関数以降で新規作成される標準シェーダを使用したマテリアル」に対して設定したシェーダを使用します。

flagGlobalは、trueで大域（現時点描画されている全てのSS6PU描画オブジェクト間で共用されている）マテリアルキャッシュが用いるシェーダを置き換えます。
falseで局所（単体のアニメーションでのみ使用している）マテリアルキャッシュが用いるシェーダを置き換えます。

この関数は、（特にflagReplaceMaterialCacheをtrueに設定した場合）マテリアルの再構築と再建策行うため、パフォーマンスに悪影響を及ぼす可能性があります。
ですので、必要がない場合、本関数をみだりに呼び出すことは推奨しません。

エフェクト専用マテリアルキャッシュの作成

関数（動的）

bool CacheBootUpMaterial()

引数

返値

true ... 成功
false ... 失敗（エラー）

解説

再生しているエフェクトオブジェクトに局所（ローカル）マテリアルキャッシュを作成します。
通常、マテリアルキャッシュは大域（プロジェクトデータ毎）に存在していますが、本関数を使用して単独のマテリアルキャッシュを作成することで、（マテリアルの変更などを）エフェクトオブジェクトの中だけで共有される範囲として扱うことが可能です。
本関数で設置した局所マテリアルキャッシュが不要になった場合は、CacheShutDownMaterial関数関数を使用して解放してください。

このマテリアルキャッシュで管理されるリソースとしては下記が存在します。

  • 描画のために作成されたマテリアル群
  • エフェクト用の標準シェーダ
  • 使用するセルマップ用テクスチャ

基本的にこれらの内、「標準シェーダ」と「使用するセルマップ用テクスチャ」について、（ローカルのマテリアルキャッシュが作成されていても）内容の変更が行われていない場合には大域マテリアルキャッシュが使用され、変更されている場合には局所マテリアルキャッシュが使用されます。

エフェクト専用マテリアルキャッシュの解放

関数（動的）

void CacheShutDownMaterial()

引数

返値

解説

現在割り当たっている局所マテリアルキャッシュを解放します。
CacheBootUpMaterial関数を使用して設置した局所マテリアルキャッシュは、必ず本関数を使用して解放してください。