Version: 2022.3
言語: 日本語
ShaderLab: シェーダープログラムの追加
ShaderLab: コマンド

ShaderLab: パッケージの要件を指定する

シェーダーによっては、複数のレンダーパイプラインを同時にサポートする必要があります。SubShader (サブシェーダー) と Pass (パス) にパッケージ要件を追加すると、シェーダーコードがインストールされていないパッケージのインクルードファイルを使用したり、コンパイルに特定のバージョンのパッケージ を必要とする場合に、コンパイルエラーを回避することができるようになります。

レンダーパイプラインの互換性

機能名 ビルトインレンダーパイプライン ユニバーサルレンダーパイプライン (URP) HD レンダーパイプライン (HDRP) カスタム SRP
ShaderLab:PackageRequirements ブロック

PackageRequirements ブロックの使用

サブシェーダーまたはパスのパッケージ要件を指定するには、PackageRequirements ブロックを使用します。ShaderLab は 1 つのサブシェーダーまたはパスにつき 1 つの PackageRequirements ブロックをサポートしますが、各ブロックは複数のパッケージ要件を指定することができます。

ノート: PackageRequirements ブロックを提供する場合、これは、サブシェーダーまたは パス内の他のすべての宣言の前に来る必要があります。

シグネチャ 機能
PackageRequirements{ [要件定義]} パスまたはサブシェーダーのパッケージ要件を定義します。

パッケージの要求事項を宣言する方法は複数あります。それぞれ、異なる動作を提供します。それらは以下の通りです。

  • “<package name>”: サブシェーダーまたはパスが、どのバージョンのパッケージでも動作することを指定します。
  • “<package name>”: “<version restrictions>”: サブシェーダーまたはパスが、パッケージバージョンのサブセットでのみ動作することを指定します。
  • “<package name>”: “unity=<version restrictions>”: サブシェーダーまたはパスが Unity バージョンのサブセットでのみ動作し、指定した名前のパッケージが必要であることを指定します。
  • “unity”:“<version restrictions>”: サブシェーダーまたはパスが、Unity バージョンのサブセットでのみ動作することを指定します。

バージョン制限では、一連のバージョン範囲を定義します。必要なパッケージのインストール済みバージョンが、この範囲のいずれにも含まれていない場合、そのパッケージの要件は満たされていません。同様に、要件で Unity のバージョン制限のセットが指定されている場合は、Unity の現在のバージョンに適用されます。バージョン制限の構文については、バージョンの構文 を参照してください。

サブシェーダーやパスが、プロジェクトが満たさないパッケージ要件を宣言している場合、Unity はそのサブシェーダーやパスを以降の処理およびコンパイルから除外します。これは、プロジェクトに必要なパッケージが含まれていないか、含まれていても互換性のあるバージョンでない場合に起こります。シェーダーに要件を満たすサブシェーダーが 1 つもない場合、またはサブシェーダーに要件を満たすパスが 1 つもない場合、コンソールウィンドウに警告メッセージが表示されます。

バージョン構文

ShaderLab のパッケージ要件では、バージョンは major.minor または major.minor.patch の形式を使用します。major.minor のみを使用する場合、Unity は patch0 を使用します。パッケージのバージョンには -preview-preview.n という postfix (接尾辞) を入れることもできます。ここで -preview-preview.0 と同じ意味です。プレビュー版は非プレビュー版の前に置かれます。ですから、 1.2.3-preview.41.2.2 の後、かつ 1.2.3 の前にきます。

バージョン範囲を指定する方法は複数あります。それぞれ、異なる動作を提供します。それらは以下の通りです。

  • <version>: 入力したバージョンと、それ以降のすべてのバージョンを含みます。例えば、1.2.3 は、1.2.3 から始まるすべてのバージョンを含みます。
  • [<version>]: 正確なバージョンを指定します。例えば、[1.2.3] は、バージョン 1.2.3 のみを含みます。
  • [<version1>,<version2>]: <version1> と <version2> の間の範囲を指定します。角かっこと丸かっこを使用すると、それぞれを含む範囲と除外する範囲がそれぞれ、バージョンに含まれます/除外されます。開き角かっこは <version1> に、閉じ角かっこは <version2> に作用します。例えば、[1.2.3,2.3.4] は、1.2.3 から 2.3.3 までのすべてのバージョンを含みます。

また、1 つのパッケージに対して、バージョン範囲のセットを指定することもできます。個々の範囲からバージョン範囲のセットを作成するには、セパレーター文字としてセミコロンを使用します。例えば、[2.0,3.4.5];[3.7];4.0 は、バージョン 2.0.0 から 3.4.5 まで、バージョン 3.7.0、そしてバージョン 4.0.0 以降のバージョンを含んでいます。

パッケージのバージョンを設定する場合、以下の点に注意してください。

  • バージョン、バージョン範囲、およびバージョン範囲のセットには、余分な文字を含むことはできません。
  • バージョン範囲は空にできません。
  • 一揃いのバージョン範囲は、交差することはありません。
  • パッケージ要件は空白も違いとして認識します。

構文が上記に従わない場合、そのバージョン制限は無効です。無効なパッケージの要件で何が起こるかについての詳細は、エラーチェック を参照してください。

次のコード例は、サブシェーダーとパスの両方でパッケージ要件を指定する方法を示しています。サブシェーダーは、“com.my.package” というパッケージに対する単一のパッケージ要件を宣言しており、このパッケージの 2.2.0 以降のすべてのバージョンで動作します。サブシェーダーは、2 つのパスを持ちます。

最初の Pass は以下を必要とします。 * バージョン 10.2.1 から 11.0 までの Universal Render Pipeline パッケージ。 * バージョン 3.2 以上の Text Mesh Pro パッケージ。

2 つ目の Pass は以下を必要とします。 * バージョン 8.0 から 8.5 までの High-Definition Render Pipeline パッケージ。

Shader "Examples/ExampleShader"
{
    SubShader
    {
        PackageRequirements
        {
            "com.my.package": "2.2"
        }
        Pass
        {
            PackageRequirements
            {
                "com.unity.render-pipelines.universal": "[10.2.1,11.0]"
                "com.unity.textmeshpro": "3.2"
            }
        }
        Pass
        {
            PackageRequirements
            {
                "com.unity.render-pipelines.high-definition": "[8.0,8.5]"
            }
        }
    }
}

エラーチェック

決して満たすことができないパッケージ要件を定義した場合、シェーダーインポート処理はエラーにより失敗します。このセクションでは、最も一般的な無効なパッケージ要件定義の例について説明します。

不正なバージョンまたは空のパッケージ名

PackageRequirements {
  "com.some.package.x": "[10.2.1,9.0]"        // Error, empty version range
  "com.some.package.y": "[10.2.1.9,11.0]"     // Error, incorrect version format
  "com.some.package.z": "[2.3,3.5],[3.0,4.0]" // Error, ranges intersect
  "com.some.package.z" : "[10.2.1,11.0]"      // Error, extra whitespace after the package name
  "" : "[2.3.4,3.4.5]"                        // Error, no package name provided
}

同じパッケージに複数の依存関係がある

PackageRequirements {
  "com.some.package.x": "[10.2.1,11.0]"
  "com.some.package.x": "[11.2.1,12.0]" // Error, dependency on "com.some.package.x" declared twice
  "unity" : "2021.2"
  "unity" : "2021.3" // Error, dependency on Unity version declared twice
}

依存関係の宣言が矛盾している

PackageRequirements {
  "com.some.package.x": "unity=[2021.2.1,2021.3.3]"
  "unity" : "2021.2"    // Error: Unity version requirement cannot be declared on a package and on its own simultaneously
}

サブシェーダーとパスの依存関係の宣言が矛盾している

SubShader {
  PackageRequirements {
    "com.some.package.x": "[2.3.4,3.4.5]"
    "com.some.package.z": "[1.1,3.2]"
    "unity": "2021.2"
  }
  Pass {
    PackageRequirements {
      "com.some.package.y": "[1.2.2,2.5]"               // Fine, SubShader doesn’t declare a dependency on "com.some.package.y"
      "com.some.package.z": "[2.0,3.1]"                 // Fine, SubShader dependency intersects the provided version range
      "com.some.package.x": "[1.1.1, 2.2.2]"            // Error, SubShader version range for "com.some.package.x" does not intersect the provided range
      "com.some.package.w": "unity=[2021.2.1,2021.2.5]" // Fine, SubShader dependency intersects the provided version range
      "com.some.package.u": "unity=[2020.2.1,2020.2.5]" // Error, SubShader Unity version range does not intersect the provided range
    }
  }
}
ShaderLab: シェーダープログラムの追加
ShaderLab: コマンド