Saltar al contenido

Dialecto de shaders

Un switch opcional para un caso muy concreto: ejecutar una persona de Windows en un host Linux, donde el código fuente del shader traducido y la cadena del renderer nombrarían, de lo contrario, dos backends gráficos distintos.

La discrepancia

WEBGL_debug_shaders.getTranslatedShaderSource() devuelve lo que haya producido el backend activo de ANGLE. Una persona de Windows anuncia un renderer Direct3D11, pero en un host Linux responde el backend Vulkan con un volcado SPIR-V. Los dos valores están uno al lado del otro, así que leer la contradicción no requiere datos de referencia ni una línea base de población: a la página le basta con compararlos:

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

Esto solo aplica cuando el sistema operativo de la persona es distinto del del host. Una persona cuyo sistema operativo coincide con el del host ya es consistente en sí misma y no necesita nada de esto. La opción cubre solo una persona de Windows en un host que no es Windows; el caso inverso —una persona de Linux o macOS en un host Windows— no está cubierto, así que ahí haz coincidir la persona con el host.

Cómo activarlo

Pasa shader_dialect (shaderDialect / ShaderDialect) al lanzar. El motor vuelve a traducir el shader a HLSL solo para esa consulta; el resultado es idéntico, byte a byte, a lo que reporta un build de Windows.

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

La imagen oficial de Docker lo activa por sí sola para CC_PLATFORM=windows cuando el contenedor ejecuta el build con licencia (con CLEARCOTE_LICENSE_KEY definida); puedes sobrescribirlo con CC_SHADER_DIALECT=hlsl o =0. Con cualquier otro runner, define la variable en el entorno del navegador: es lo que la opción del SDK configura por debajo:

bash
CLEARCOTE_SHADER_DIALECT=hlsl

La variable va en el entorno y no en un flag de línea de comandos porque este código se ejecuta en el proceso de GPU, que no recibe los switches de huella digital.

Por qué está desactivado por defecto

La retraducción es una ruta de código distinta de la que renderizó. Un shader que el backend real acepta pero que el traductor HLSL rechaza vuelve al dialecto real para ese shader, lo que reintroduce la discrepancia solo para él. Todo lo demás de la opción es deliberadamente conservador:

  • El renderizado no se ve afectado. El backend real sigue compilando y dibujando el shader; solo cambia la consulta a la extensión de depuración. Una operación de dibujo WebGL con lectura de píxeles da el mismo hash con la opción activada y desactivada.
  • Sin efecto en Windows. Si el backend activo ya emite HLSL, la opción no hace nada, así que un host Windows queda intacto aunque la variable esté definida.
  • Ante un fallo, devuelve la verdad. Cualquier fallo de traducción devuelve la salida real del backend en lugar de una vacía o inventada.
  • El SDK solo acepta "hlsl" y rechaza cualquier otro valor: un typo que no hiciera nada sin avisar sería peor que un error. Si defines la variable tú mismo, tiene que ser exactamente hlsl (en minúsculas); el motor ignora cualquier otro valor.

Requisitos

El build con licencia (Gratis con GitHub o Pro), 151 r15 o posterior. El build abierto y los binarios anteriores ignoran la variable y siguen reportando su dialecto real, así que pasa tu clave de licencia (license_key / CLEARCOTE_LICENSE_KEY) para que los ejemplos de arriba surtan efecto. Consulta cómo funciona la detección para ver por qué coincidir con la plataforma declarada es mejor que devolver un tercer valor neutro, y despliegue para ejecutar un motor con licencia en un contenedor.