Version: 2021.3
言語: 日本語
HLSL の include と include_with_pragmas ディレクティブ
HLSL でシェーダーモデルと GPU 機能を特定する

HLSL のプラグマディレクティブ

HLSL では、#pragma ディレクティブは プリプロセッサーディレクティブ の一種です。他のタイプのプリプロセッサーディレクティブではカバーされていない追加情報をシェーダーコンパイラーに提供します。

pragma ディレクティブの使用

#pragma ディレクティブは HLSL コードのどこにでも入れることができますが、以下のように先頭に入れるのが一般的です。

# pragma target 3.0
# pragma exclude_renderers vulkan
# pragma vertex vert
# pragma fragment frag

// 残りの HLSL コードをここに記述

制限

There are some limitations around the use of #pragma directives:

  • 式が以下のものだけに依存している場合は、#pragma ディレクティブを条件 (#if) ディレクティブの中で使用することができます。
    • 独自コードのカスタムの #define ディレクティブ
    • 以下のプラットフォームキーワード: SHADER_API_MOBILE, SHADER_API_DESKTOP, UNITY_NO_RGBM, UNITY_USE_NATIVE_HDR, UNITY_FRAMEBUFFER_FETCH_AVAILABLE, UNITY_NO_CUBEMAP_ARRAY
    • UNITY_VERSION マクロ
  • Unity 固有の #pragma ディレクティブは、 .shader ファイルと、 #include_with_pragmas ディレクティブでインクルードしたファイルでのみ使用できます。Unityは、#include ディレクティブでインクルードするファイルではサポートしていません。コンパイラーはこれらを無視します。
  • #include ディレクティブでインクルードするファイルでは、標準の HLSL #pragma ディレクティブのみを使用できます。Unity は .shader ファイルや #include_with_pragmas ディレクティブでインクルードするファイルではそれらをサポートしません。コンパイラーはこれらを無視します。

サポートされているプラグマディレクティブのリスト

Unity は、標準的な HLSL の一部である #pragma ディレクティブが通常のインクルードファイルに含まれている限り、すべてサポートします。これらのディレクティブの詳細については、HLSL のドキュメント [#pragma ディレクティブ](https://docs.microsoft.com/ja-jp/windows/win32/direct3dhlsl/dx-graphics-hlsl-appendix-pre-pragma) を参照してください。

さらに、Unity は以下の Unity 固有の #pragma ディレクティブをサポートします。

サーフェスシェーダー

サーフェスシェーダー を書く場合は、このディレクティブを使って サーフェス関数 として使用する関数をコンパイラーに指示し、その関数にデータを渡します。

ステートメント 機能
#pragma surface <surface function> <lighting model> <optional parameters> 関数を与えられた名前でサーフェスシェーダーとしてコンパイルすると、与えられたライティングモデルで動作します。詳細は、サーフェスシェーダー を参照してください。

シェーダーステージ

通常のグラフィックスシェーダーを書いている場合は、これらのディレクティブを使って、シェーダーの各ステージで使用する関数をコンパイラーに伝えます。#pragma vertex#pragma fragment ディレクティブは必須ですが、その他のステージは任意です。

ステートメント 機能
#pragma vertex <name> 指定された名前の関数を頂点シェーダーとしてコンパイルします。<name> を関数名に置き換えてください。このディレクティブは、通常のグラフィックスシェーダーでは必須です。
#pragma fragment <name> 指定された名前の関数をフラグメントシェーダーとしてコンパイルします。<name> を関数名に置き換えてください。このディレクティブは、通常のグラフィックスシェーダーでは必須です。
#pragma geometry <name> 指定された名前の関数をジオメトリシェーダーとしてコンパイルします。<name> を関数名に置き換えてください。このオプションは、自動的に #pragma require geometry をオンにします。詳細は、HLSL の適用シェーダーモデルと GPU 機能 を参照してください。

ノート: Metal はジオメトリシェーダーをサポートしていません。
#pragma hull <name> 指定された名前の関数を DirectX 11 ハルシェーダーとしてコンパイルします。<name> を関数名に置き換えてください。このオプションは、自動的に #pragma require tessellation を加えます。詳細は、HLSL の適用シェーダーモデルと GPU 機能 を参照してください。
#pragma domain <name> 指定された名前の関数を DirectX 11 ドメインシェーダーとしてコンパイルします。<name> を関数名に置き換えてください。このオプションは、自動的に #pragma require tessellation をオンにします。詳細は、HLSL の適用シェーダーモデルと GPU 機能 を参照してください。

Shader variants and keywords

Use these directives to tell the shader compiler how to handle shader variants and keywords. For more information, see Declaring and using shader keywords in HLSL.

ディレクティブ 説明
#pragma multi_compile <keywords> Declares a collection of keywords. The compiler includes all of the keywords in the build.

You can use suffixes such as _local to set additional options.

For more information and a list of supported suffixes, see Declaring and using shader keywords in HLSL.
#pragma shader_feature <keywords> Declares a collection of keywords. The compiler excludes unused keywords from the build.

You can use suffixes such as _local to set additional options.

For more information and a list of supported suffixes, see Declaring and using shader keywords in HLSL.
#pragma hardware_tier_variants <values> ビルトインレンダーパイプラインのみ。指定のグラフィックス API 用にコンパイルする際に、グラフィックスティア のキーワードを加えます。詳細は、グラフィックスティア を参照してください。
#pragma skip_variants <list of keywords> 指定したキーワードを削除します。

GPU 要件とシェーダーモデルサポート

以下のディレクティブを使用して、シェーダーが特定の GPU 機能を必要とすることをコンパイラーに伝えます。

ステートメント 機能
#pragma target <value> このシェーダープログラムが互換する最小のシェーダーモデルです。<value> を有効な値に置き換えてください。有効な値のリストについては、シェーダーコンパイル: HLSL の適応シェーダーモデルと GPU 機能 を参照してください。
#pragma require <value> このシェーダープログラムが互換する最小の GPU 機能です。<value> を有効な値、または、スペースで区切られた複数の有効な値に置き換えてください。有効な値のリストについては、シェーダーコンパイル: HLSL の適応シェーダーモデルと GPU 機能 を参照してください。

グラフィックス API

以下のディレクティブを使用して、特定のグラフィックス API 用のコードを含む、または除外するように指示します。

ステートメント 機能
#pragma only_renderers <value> 指定したグラフィックス API に対してのみ、このシェーダープログラムをコンパイルします。<values> をスペースで区切られた有効な値のリストに置き換えます。詳細と有効な値のリストについては、HLSL の適応グラフィックス API とプラットフォーム を参照してください。
#pragma exclude_renderers <value> 指定したグラフィックス API に対して、このシェーダープログラムをコンパイルしません。<values> をスペースで区切られた有効な値のリストに置き換えます。詳細と有効な値のリストについては、HLSL の適応グラフィックス API とプラットフォーム を参照してください。

その他の pragma ディレクティブ

ステートメント 機能
#pragma instancing_options <options> 指定したオプションを使って、このシェーダーで GPU インスタンシングを有効にします。詳細については、GPU インスタンシング を参照してください。
#pragma once このディレクティブをファイルに入れて、コンパイラーがシェーダープログラムでファイルを 1 回だけ加えるようにします。

ノート: Unity は、シェーダーキャッシングプリプロセッサー が有効な場合にのみ、このディレクティブをサポートします。
#pragma enable_d3d11_debug_symbols サポートされているグラフィックス API 用のシェーダーデバッグシンボルを生成し、すべてのグラフィックス API の最適化を無効にします。

Unity は、Vulkan、DirectX 11 と 12、およびサポートされているコンソールプラットフォーム用のデバッグシンボルを生成します。

注意: これを使用するとファイルサイズが大きくなり、シェーダーのパフォーマンスが低下します。シェーダーのデバッグが終わり、アプリケーションの最終ビルドを行う準備ができたら、シェーダーのソースコードからこの行を削除し、シェーダーを再コンパイルしてください。
#pragma skip_optimizations <value> 指定したグラフィックス API に対して、強制的に最適化をオフにします。<values> をスペースで区切られた有効な値のリストに置き換えます。詳細と有効な値のリストについては、HLSL の適応グラフィックス API とプラットフォーム を参照してください。
#pragma hlslcc_bytecode_disassembly 逆アセンブルされた HLSLcc バイトコードを変換したシェーダーに埋め込みます。
#pragma disable_fastmath NaN 処理を含む正確な IEEE 754 規則を有効にします。現在、これは Metal プラットフォームにのみ影響します。
#pragma editor_sync_compilation 同期コンパイルを強制します。これは Unity エディターにのみ影響します。詳細については、非同期シェーダーコンパイル を参照してください。
#pragma enable_cbuffer 現在のプラットフォームが定数バッファをサポートしていない場合でも、HLSLSupport から CBUFFER_START(name)CBUFFER_END マクロを使用する場合に cbuffer(name) を放出します。
HLSL の include と include_with_pragmas ディレクティブ
HLSL でシェーダーモデルと GPU 機能を特定する