Lo que el motor le da a un shader

Un material es una función pequeña que escribes tú: el motor la ejecuta en cada píxel (y, en un modelo, en cada esquina) y le da lo que sabe de ese sitio. Esta página lo lista todo. Los nombres son una promesa: un shader escrito con ellos sigue funcionando en versiones futuras, así que ninguno se renombra nunca. Las pruebas del motor comprueban que cada nombre de esta página existe en las dos tarjetas gráficas.

Para ver cada entrada trabajando, cada una dibujando algo que se ve, abre el ejemplo Lo que recibe un shader.

Las funciones se escriben en WGSL para WebGPU (fragment, vertex) y en GLSL para WebGL2 (fragmentGlsl, vertexGlsl). Los nombres son los mismos en los dos; solo los tipos se escriben a la manera de GLSL (vec4 por vec4<f32>). Si construyes el material con el compositor de shaders, él escribe los dos por ti.

En todos los shaders: mu

Los parámetros de un material llegan en mu. Primero van los del motor, siempre en el mismo orden, y después los tuyos, con el nombre que les diste: uniforms: { charge: 0 } se lee como mu.charge.

Fuera de un cambio de escena, progress y phase valen 0. Esos cuatro nombres están ocupados: un parámetro tuyo no puede llamarse así.

Un parámetro es de uno de cuatro tipos: f32, vec2<f32>, vec3<f32> o vec4<f32>. El bloque entero cabe en 64 números, contando los del motor. Un vec3 o un vec4 empieza en un múltiplo de cuatro, así que un número suelto justo antes deja un hueco pequeño. Un material que declara más de lo que cabe se dibuja con el aspecto de serie, y la consola dice por qué.

Sprites, textos y capas de mapa

Un material con shader: 'sprite2d' (el de serie) tiene una función:

fn effect(color: vec4<f32>, uv: vec2<f32>) -> vec4<f32> {
    return color;
}

• color es la imagen ya leída y ya tintada. return color; dibuja exactamente lo que habría dibujado el motor, así que un efecto es un cambio sobre eso.
• En las letras de una fuente vectorial, color es el tinte del texto, con el borde de la letra en su alfa.
• uv es el sitio en la hoja. No se queda dentro del recorte del sprite: leer en otra parte de la hoja está permitido.
• sampleTexture(uv) lee la hoja en cualquier sitio, también dentro de un if o de un bucle.

El mismo material funciona en una capa de mapa sin cambiar una palabra.

Modelos

Un material con shader: 'mesh3d' tiene dos funciones. Las dos son opcionales: la que no escribas hace lo que hace el motor.

fn vertex(pos: vec3<f32>, ctx: VertContext) -> vec3<f32> {
    return pos;
}
 
fn effect(surface: vec4<f32>, ctx: FragContext) -> vec4<f32> {
    return vec4<f32>(surface.rgb * ctx.light + ctx.shine + ctx.emissive, surface.a);
}

Ese effect es el del motor, palabra por palabra: un buen punto de partida.

• vertex mueve una esquina, en el espacio del propio modelo. Escribirla cuesta un poco: la superficie se vuelve a medir después de moverla, y eso la llama dos veces más por esquina.
• vertex también puede pasarle cuatro números a effect: carry = vec4<f32>(...). Llegan como ctx.carry, mezclados a lo largo del triángulo. La altura de una ola para poner espuma en las crestas, una luz calculada en las esquinas, o el propio pos, para que unas rayas se queden en el modelo cuando se mueve.
• surface es la imagen por el tinte por el color pintado en las esquinas.
• La niebla va encima de lo que devuelve effect, y alphaCutoff recorta por su alfa.

Lo que recibe la función de la esquina:

Lo que recibe la función del color:

light y shine se calculan en las esquinas y se mezclan a lo largo del triángulo; no se vuelven a calcular en cada píxel. Así iluminaban un modelo las consolas de la época, y es el aspecto que busca el motor.

Ayudantes que puede llamar el shader de un modelo:

• sampleTexture(uv): la imagen del modelo.
• sampleMap_<nombre>(uv): uno de los maps del material, por su nombre (maps: { noise } se lee con sampleMap_noise(ctx.uv)). Un mapa que el material no tiene se lee blanco.
• envUv(ctx): dónde cae un reflejo cromado en una imagen redonda de lo que rodea al modelo. Se lee con sampleMap_env(envUv(ctx)).

Efectos de pantalla

Un efecto sobre la pantalla entera (usePostProcess({ fragment })) tiene la misma función que un sprite. color es el fotograma ya leído en uv.

Un efecto lee una sola imagen de datos: una paleta o una tabla de color, nunca las dos.