Pular para o conteúdo

Dialeto de shader

Um switch opt-in para um caso bem específico: rodar uma persona Windows num host Linux, em que o código-fonte do shader traduzido e a string de renderer, de outro modo, apontariam dois backends gráficos diferentes.

A divergência

WEBGL_debug_shaders.getTranslatedShaderSource() retorna o que o backend ativo do ANGLE tiver produzido. Uma persona Windows anuncia um renderer Direct3D11, mas num host Linux quem responde é o backend Vulkan, com um dump SPIR-V. Os dois valores ficam lado a lado, então perceber a contradição não exige dados de referência nem uma linha de base populacional — basta a página comparar os dois:

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

Isso só se aplica quando o sistema operacional da persona é diferente do sistema do host. Uma persona cujo sistema coincide com o do host já é consistente por si só e não precisa de nada daqui. A opção cobre apenas uma persona Windows num host que não seja Windows; o inverso — uma persona Linux ou macOS num host Windows — não é coberto, então, nesse caso, faça a persona corresponder ao host.

Como ativar

Passe shader_dialect (shaderDialect / ShaderDialect) na inicialização. O motor retraduz o shader para HLSL só para essa consulta; o resultado é idêntico, byte a byte, ao que um build Windows reporta.

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

A imagem Docker oficial liga a opção sozinha para CC_PLATFORM=windows quando o contêiner roda o build licenciado (com CLEARCOTE_LICENSE_KEY definida); sobrescreva com CC_SHADER_DIALECT=hlsl ou =0. Com qualquer outro runner, defina a variável no ambiente do navegador — é ela que a opção do SDK define por baixo dos panos:

bash
CLEARCOTE_SHADER_DIALECT=hlsl

A variável fica no ambiente, e não numa flag de linha de comando, porque esse código roda no processo da GPU, que não recebe os switches de fingerprint.

Por que vem desligado por padrão

A retradução é um caminho de código diferente daquele que renderizou. Um shader que o backend real aceita, mas que o tradutor HLSL rejeita, volta ao dialeto verdadeiro — reintroduzindo a divergência só para esse shader. Todo o resto da opção é deliberadamente conservador:

  • A renderização não é afetada. O backend real continua compilando e desenhando o shader; só a consulta da extensão de debug muda. Um desenho WebGL com leitura de pixels gera o mesmo hash com a opção ligada ou desligada.
  • Sem efeito no Windows. Se o backend ativo já emite HLSL, a opção não faz nada; assim, um host Windows fica intocado mesmo com a variável definida.
  • Falha a favor da verdade. Qualquer falha de tradução retorna a saída real do backend, e não uma saída vazia ou inventada.
  • O SDK aceita apenas "hlsl" e rejeita qualquer outro valor — um erro de digitação que silenciosamente não fizesse nada seria pior do que um erro. Se você mesmo definir a variável, ela precisa ser exatamente hlsl (em minúsculas); o motor ignora qualquer outro valor.

Requisitos

O build licenciado (Grátis com GitHub ou Pro), 151 r15 ou mais recente. O build aberto e os binários mais antigos ignoram a variável e continuam reportando o dialeto real; por isso, passe a sua chave de licença (license_key / CLEARCOTE_LICENSE_KEY) para que os exemplos acima tenham efeito. Veja como a detecção funciona para entender por que corresponder à plataforma declarada é melhor do que retornar um terceiro valor neutro, e implantação para rodar um motor licenciado num contêiner.