Skip to content

Shader dialect

An opt-in 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.

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 (0xA780) 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 Linux persona on Linux, or any persona on Windows, is already self-consistent and needs nothing here.

Turning it on

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
var ctx = await Clearcote.LaunchPersistentContextAsync("./profile", new LaunchOptions
{
    Fingerprint = new Fingerprint { Platform = "windows" },
    ShaderDialect = "hlsl",
});

In Docker, or with any other runner, set the environment variable directly — it is what the SDK option sets underneath:

bash
docker run -e 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.

Why it is off by default

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 — reintroducing the mismatch for it alone. 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.
  • Only "hlsl" is accepted. Any other value is rejected outright — a typo that silently did nothing would be worse than an error.

Requirements

A PRO engine that carries the option (151 r15+). Older binaries ignore the variable and keep reporting their real dialect. 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.