Shader-Dialekt

Ein Opt-in-Switch für einen eng umrissenen Fall: eine Windows-Persona auf einem Linux-Host, bei der der übersetzte Shader-Quelltext und der Renderer-String sonst zwei verschiedene Grafik-Backends nennen würden.

Der Widerspruch

WEBGL_debug_shaders.getTranslatedShaderSource() liefert, was das aktive Backend von ANGLE erzeugt hat. Eine Windows-Persona gibt einen Direct3D11-Renderer an, doch auf einem Linux-Host antwortet das Vulkan-Backend mit einem SPIR-V-Dump. Beide Werte liegen direkt nebeneinander; um den Widerspruch zu erkennen, braucht es daher weder Referenzdaten noch eine statistische Vergleichsbasis – eine Seite vergleicht einfach die beiden:

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

Das betrifft nur Fälle, in denen das Betriebssystem der Persona von dem des Hosts abweicht. Eine Persona mit demselben OS wie der Host ist bereits in sich stimmig und braucht hier nichts. Die Option deckt ausschließlich eine Windows-Persona auf einem Nicht-Windows-Host ab; der umgekehrte Fall – eine Linux- oder macOS-Persona auf einem Windows-Host – ist nicht abgedeckt. Passen Sie die Persona dort also an den Host an.

Einschalten

Übergeben Sie beim Start shader_dialect (shaderDialect / ShaderDialect). Die Engine übersetzt den Shader allein für diese Abfrage erneut nach HLSL; das Ergebnis ist Byte für Byte identisch mit dem, was ein Windows-Build meldet.

from clearcote import launch_persistent_context

ctx = launch_persistent_context("./profile", platform="windows", shader_dialect="hlsl")

import { launchPersistentContext } from "clearcote";

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

using Clearcote;

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

Das offizielle Docker-Image schaltet die Option bei CC_PLATFORM=windows von selbst ein, wenn im Container der lizenzierte Build läuft (CLEARCOTE_LICENSE_KEY gesetzt); überschreiben lässt sich das mit CC_SHADER_DIALECT=hlsl oder =0. Bei jedem anderen Runner setzen Sie die Umgebungsvariable in der Umgebung des Browsers – genau sie setzt auch die SDK-Option unter der Haube:

CLEARCOTE_SHADER_DIALECT=hlsl

Die Variable steckt in der Umgebung statt in einem Kommandozeilen-Flag, weil dieser Code im GPU-Prozess läuft, der die Fingerprint-Switches nicht erhält.

Warum die Option standardmäßig aus ist

Die erneute Übersetzung ist ein anderer Codepfad als der, der gerendert hat. Ein Shader, den das echte Backend akzeptiert, der HLSL-Übersetzer aber ablehnt, fällt für diesen Shader auf den echten Dialekt zurück – womit der Widerspruch für genau diesen Shader wieder auftaucht. Alles andere an der Option ist bewusst konservativ ausgelegt:

• Das Rendering bleibt unberührt. Das echte Backend kompiliert und zeichnet den Shader weiterhin; nur die Abfrage über die Debug-Extension ändert sich. Ein WebGL-Draw mit Pixel-Readback ergibt mit und ohne Option denselben Hash.
• Unter Windows ein No-op. Gibt das aktive Backend bereits HLSL aus, tut die Option nichts; ein Windows-Host bleibt also selbst bei gesetzter Variable unberührt.
• Im Fehlerfall gewinnt die Wahrheit. Scheitert die Übersetzung, kommt die echte Ausgabe des Backends zurück, keine leere oder erfundene.
• Das SDK akzeptiert nur "hlsl" und lehnt alles andere ab – ein Tippfehler, der stillschweigend nichts bewirkt, wäre schlimmer als eine Fehlermeldung. Wenn Sie die Variable selbst setzen, muss sie exakt hlsl lauten (kleingeschrieben); jeden anderen Wert ignoriert die Engine.

Voraussetzungen

Der lizenzierte Build (Kostenlos mit GitHub oder Pro), 151 r15 oder neuer. Der offene Build und ältere Binaries ignorieren die Variable und melden weiterhin ihren echten Dialekt; übergeben Sie daher Ihren Lizenzschlüssel (license_key / CLEARCOTE_LICENSE_KEY), damit die Beispiele oben greifen. Warum es besser ist, zur angegebenen Plattform zu passen, als einen neutralen dritten Wert zu liefern, erklärt Wie Erkennung funktioniert; wie Sie eine lizenzierte Engine im Container betreiben, steht unter Deployment.