Dialecte de shader

Une option à activer explicitement, pour un cas bien précis : faire tourner une persona Windows sur un hôte Linux, où le code source du shader traduit et la chaîne renderer désigneraient sinon deux backends graphiques différents.

L’incohérence

WEBGL_debug_shaders.getTranslatedShaderSource() renvoie ce qu’a produit le backend actif d’ANGLE. Une persona Windows annonce un renderer Direct3D11, mais sur un hôte Linux, c’est le backend Vulkan qui répond, avec un dump SPIR-V. Les deux valeurs se côtoient : pour lire la contradiction, nul besoin de données de référence ni de base de population — il suffit à une page de comparer les deux :

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

Cela ne s’applique que lorsque l’OS de la persona diffère de celui de l’hôte. Une persona dont l’OS correspond à l’hôte est déjà cohérente en elle-même et n’a besoin de rien ici. L’option ne couvre qu’une persona Windows sur un hôte non Windows ; le cas inverse — une persona Linux ou macOS sur un hôte Windows — n’est pas couvert : dans ce cas, alignez la persona sur l’hôte.

L’activer

Passez shader_dialect (shaderDialect / ShaderDialect) au lancement. Le moteur retraduit le shader en HLSL pour cette seule requête ; le résultat est identique, à l’octet près, à ce que rapporte un build Windows.

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

L’image Docker officielle l’active d’elle-même pour CC_PLATFORM=windows lorsque le conteneur exécute le build sous licence (CLEARCOTE_LICENSE_KEY défini) ; pour passer outre, utilisez CC_SHADER_DIALECT=hlsl ou =0. Avec tout autre lanceur, définissez la variable dans l’environnement du navigateur — c’est elle que l’option du SDK définit en coulisse :

CLEARCOTE_SHADER_DIALECT=hlsl

La variable passe par l’environnement plutôt que par un flag de ligne de commande, car ce code s’exécute dans le processus GPU, qui ne reçoit pas les switches d’empreinte.

Pourquoi elle est désactivée par défaut

La retraduction emprunte un chemin de code différent de celui qui a fait le rendu. Un shader que le vrai backend accepte mais que le traducteur HLSL rejette retombe, pour ce shader, sur le dialecte réel — ce qui réintroduit l’incohérence pour lui seul. Pour tout le reste, l’option est volontairement prudente :

• Le rendu n’est pas affecté. Le vrai backend compile et dessine toujours le shader ; seule la requête de l’extension de débogage change. Un dessin WebGL suivi d’une relecture de pixels donne le même hash, que l’option soit activée ou non.
• Sans effet sous Windows. Si le backend actif émet déjà du HLSL, l’option ne fait rien : un hôte Windows reste intact, même avec la variable définie.
• En cas d’échec, c’est la vraie valeur qui ressort. Tout échec de traduction renvoie la sortie réelle du backend plutôt qu’une sortie vide ou inventée.
• Le SDK n’accepte que "hlsl" et rejette tout le reste — une faute de frappe qui passerait silencieusement sans effet serait pire qu’une erreur. Si vous définissez la variable vous-même, elle doit valoir exactement hlsl (en minuscules) ; le moteur ignore toute autre valeur.

Prérequis

Le build sous licence (Gratuit avec GitHub ou Pro), 151 r15 ou plus récent. Le build ouvert et les binaires plus anciens ignorent la variable et continuent de rapporter leur vrai dialecte : passez donc votre clé de licence (license_key / CLEARCOTE_LICENSE_KEY) pour que les exemples ci-dessus prennent effet. Consultez comment fonctionne la détection pour comprendre pourquoi reproduire la plateforme annoncée vaut mieux que renvoyer une troisième valeur neutre, et déploiement pour exécuter un moteur sous licence dans un conteneur.