Skip to content

Shader dialect

A switch for one narrow case: running a Windows persona on a Linux host, where the translated shader source and the renderer string would otherwise name two different graphics backends. SDK 0.39.0 and newer turn it on by themselves for that case.

The mismatch

WEBGL_debug_shaders.getTranslatedShaderSource() returns whatever ANGLE's active backend produced. A Windows persona advertises a Direct3D11 renderer, but on a Linux host the Vulkan backend answers with a SPIR-V dump. Both values sit next to each other, so reading the contradiction takes no reference data and no population baseline — a page just compares the two:

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

This only applies when the persona's OS differs from the host's. A persona whose OS matches the host is already self-consistent and needs nothing here. The option covers a Windows persona on a non-Windows host only; the reverse — a Linux or macOS persona on a Windows host — is not covered, so match the persona to the host there.

Turning it on

From SDK 0.39.0 there is nothing to pass: a Windows persona on a Linux or macOS host gets it by default. With an older SDK, pass shader_dialect (shaderDialect / ShaderDialect) at launch. The engine re-translates the shader to HLSL for that query alone; the result is byte-identical to what a Windows build reports.

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",
});

To turn the default off, pass shader_dialect=False (shaderDialect: false / ShaderDialect = "off").

The official Docker image switches it on by itself for CC_PLATFORM=windows when the container runs the licensed build (CLEARCOTE_LICENSE_KEY set); override with CC_SHADER_DIALECT=hlsl or =0. With any other runner, set the environment variable in the browser's environment — it is what the SDK option sets underneath:

bash
CLEARCOTE_SHADER_DIALECT=hlsl

The variable lives in the environment rather than a command-line flag because this code runs in the GPU process, which does not receive the fingerprint switches.

What it can and cannot change

The re-translation is a different code path from the one that rendered. A shader the real backend accepts but the HLSL translator rejects falls back to the honest dialect for that shader — the mismatch returns for that shader alone, which is where every launch was before, so the option never leaves a page worse off. Everything else about the option is deliberately conservative:

  • Rendering is unaffected. The real backend still compiles and draws the shader; only the debug-extension query changes. A WebGL draw with a pixel readback hashes identically with the option on and off.
  • No-op on Windows. If the active backend already emits HLSL, the option does nothing, so a Windows host is untouched even with the variable set.
  • Fails toward the truth. Any translation failure returns the backend's real output rather than an empty or invented one.
  • The SDK accepts only "hlsl", or the off values above, and rejects anything else — a typo that silently did nothing would be worse than an error. If you set the variable yourself, it must be exactly hlsl (lower-case); the engine ignores any other value.

Requirements

The licensed build (Free with GitHub or Pro), 151 r15 or newer. The open build and older binaries ignore the variable and keep reporting their real dialect, so pass your licence key (license_key / CLEARCOTE_LICENSE_KEY) for the samples above to take effect. See how detection works for why matching the claimed platform beats returning a neutral third value, and deployment for running a licensed engine in a container.