本文へスキップ

シェーダーの方言

ある限られたケースのためのオプトインのスイッチです。Linux ホストで Windows ペルソナを動かす場合、何もしなければ、変換後のシェーダーソースと renderer 文字列がそれぞれ別のグラフィックスバックエンドを示してしまいます。

何が食い違うのか

WEBGL_debug_shaders.getTranslatedShaderSource() は、ANGLE のアクティブなバックエンドが生成したものをそのまま返します。Windows ペルソナは Direct3D11 の renderer を名乗りますが、Linux ホストでは Vulkan バックエンドが SPIR-V のダンプを返します。2 つの値は並べて取得できるため、この矛盾を読み取るのに参照データも母集団のベースラインも要りません。ページは 2 つを比べるだけです：

javascript
const gl = document.createElement("canvas").getContext("webgl");
const info = gl.getExtension("WEBGL_debug_renderer_info");
gl.getParameter(info.UNMASKED_RENDERER_WEBGL);
// "ANGLE (Intel, Intel(R) UHD Graphics 770 (0x0000A780) Direct3D11 vs_5_0 ps_5_0, D3D11)"

const dbg = gl.getExtension("WEBGL_debug_shaders");
dbg.getTranslatedShaderSource(vertexShader);
// on Windows: "// INITIAL HLSL BEGIN ... #pragma warning( disable: 3081 ..."
// on Linux:   "Outputs: gl_Position ... Paste the following SPIR-V binary ..."   <- contradicts the renderer

これが問題になるのは、ペルソナの OS がホストの OS と異なる場合だけです。OS がホストと一致するペルソナはもともと整合しているので、ここで何かをする必要はありません。このオプションが対象とするのは、Windows 以外のホストで動く Windows ペルソナだけです。逆のケース（Windows ホスト上の Linux または macOS ペルソナ）は対象外なので、その場合はペルソナをホストに合わせてください。

有効にする

起動時に shader_dialect（shaderDialect / ShaderDialect）を指定します。エンジンは、その問い合わせに対してだけシェーダーを HLSL に変換し直します。結果は Windows ビルドが報告するものとバイト単位で同一です。

python
from clearcote import launch_persistent_context

ctx = launch_persistent_context("./profile", platform="windows", shader_dialect="hlsl")
javascript
import { launchPersistentContext } from "clearcote";

const ctx = await launchPersistentContext("./profile", { platform: "windows", shaderDialect: "hlsl" });
csharp
using Clearcote;

var ctx = await Clearcote.Clearcote.LaunchPersistentContextAsync("./profile", new LaunchOptions
{
    Platform = "windows",
    ShaderDialect = "hlsl",
});

公式の Docker イメージでは、コンテナがライセンスビルドを実行している場合（CLEARCOTE_LICENSE_KEY を設定済み）、CC_PLATFORM=windows なら自動で有効になります。CC_SHADER_DIALECT=hlsl または =0 で上書きできます。それ以外の実行環境では、ブラウザの環境に環境変数を設定してください。SDK のオプションも、内部ではこの変数を設定しています：

bash
CLEARCOTE_SHADER_DIALECT=hlsl

コマンドラインフラグではなく環境変数にしているのは、このコードが GPU プロセスで実行され、GPU プロセスにはフィンガープリント系のスイッチが渡されないためです。

デフォルトでオフになっている理由

再変換は、実際の描画とは別のコードパスです。実際のバックエンドは受け付けても HLSL トランスレーターが拒否するシェーダーは、そのシェーダーについては本来の方言にフォールバックします。つまり、そのシェーダーに限っては不一致が再び生じます。それ以外の点では、このオプションはあえて保守的に作られています：

  • 描画には影響しません。シェーダーのコンパイルと描画は引き続き実際のバックエンドが行い、変わるのはデバッグ拡張への問い合わせ結果だけです。ピクセルを読み出す WebGL の描画は、オプションのオン・オフにかかわらず同じハッシュになります。
  • Windows では何もしません。アクティブなバックエンドがすでに HLSL を出力している場合、オプションは何もしないため、変数を設定していても Windows ホストには影響しません。
  • 失敗したときは本来の値に倒れます。変換に失敗した場合は、空の出力やでっち上げた出力ではなく、バックエンドの実際の出力を返します。
  • SDK が受け付けるのは "hlsl" のみで、それ以外は拒否します。タイプミスが黙って何もしないほうが、エラーよりたちが悪いからです。変数を自分で設定する場合は、正確に hlsl（小文字）でなければなりません。エンジンはそれ以外の値を無視します。

要件

ライセンスビルド（「GitHub で無料」または Pro）の 151 r15 以降が必要です。オープンビルドと古いバイナリはこの変数を無視し、実際の方言を報告し続けます。上のサンプルを有効にするには、ライセンスキー（license_key / CLEARCOTE_LICENSE_KEY）を渡してください。名乗っているプラットフォームに合わせるほうが、中立的な第三の値を返すより優れている理由は検知の仕組みを、コンテナでライセンスビルドのエンジンを動かす方法はデプロイを参照してください。