pixijs-custom-rendering

Los shaders personalizados vinculan los programas GLSL y WGSL a los objetos de la escena mediante Shader.from({ gl, gpu, resources }). Las variables uniformes se almacenan en UniformGroupstipados, las texturas se pasan como recursos independientes, y un mismo shader puede estar destinado tanto a WebGL como a WebGPU.

Inicio rápido

const uniforms = new UniformGroup({
  uTime: { value: 0, type: "f32" },
});const shader = Shader.from({
  gl: { vertex: vertexSrc, fragment: fragmentSrc },
 resources: { uniforms },
});const geometry = new MeshGeometry({
  positions: new Float32Array([0, 0, 100, 0, 100, 100, 0, 100]),
 uvs: new Float32Array([0, 0, 1, 0, 1, 1, 0, 1]),
 índices: new Uint32Array([0, 1, 2, 0, 2, 3]),
});const mesh = new Mesh({ geometry, shader });
app.stage.addChild(mesh);app.ticker.add(() => {
  shader.resources.uniforms.uniforms.uTime = performance.now() / 1000;
});

Habilidades relacionadas: pixijs-filters (filtros integrados), pixijs-scene-mesh (geometría personalizada), pixijs-performance (optimización por lotes), pixijs-migration-v8 (migración de la API de shaders desde la v7).

Patrones básicos

Shader con doble renderizador (WebGL + WebGPU)

import { Shader, GlProgram, GpuProgram, UniformGroup } from "pixi.js";const glVertex = `...`; // vértice GLSL (escribe tú mismo `#version 300 es` si quieres WebGL2/GLSL ES 3.0)
const glFragment = `...`; // Fragmento GLSL
const wgslSource = `...`; // WGSLcombinado
 const shader = Shader.from({
  gl: { vertex: glVertex, fragment: glFragment },
 gpu: {
    // Los nombres de los puntos de entrada son arbitrarios; deben coincidir con  los nombres de las funciones @vertex / @fragment
    // de tu código fuente WGSL. PixiJS incluye ejemplos que utilizan
    // «mainVert» / «mainFrag», pero «main» es igualmente válido.
   vertex: { entryPoint: "mainVert", source: wgslSource },
    fragment: { entryPoint: "mainFrag", source: wgslSource },
  },
 resources: {
    myUniforms: new UniformGroup({
      uColor: { value: new Float32Array([1, 0, 0, 1]), type: "vec4" },
     uMatrix: { value: new Float32Array(16), type: "mat4x4" },
    }),
  },
});

Si solo se proporciona «gl», el shader funciona únicamente con WebGL. Si solo se proporciona «gpu», funciona únicamente con WebGPU. La máscara de bits «compatibleRenderers» se establece automáticamente.

GlProgram no inserta automáticamente #version 300 es. Si escribes tú mismo #version 300 es, PixiJS lo conserva y trata el shader como GLSL ES 3.0; de lo contrario, inyecta macros de compatibilidad con WebGL1 (#define en varying, #define texture texture2D) y ejecuta el shader como GLSL al estilo de WebGL1. GlProgram siempre inyecta una precisión predeterminada (highp para vértices, mediump para fragmentos) y el nombre del programa. Para GLSL ES 3.0, utilizain/out en lugar deattribute/varying, texture() en lugar de texture2D(), y un out vec4 en lugar de gl_FragColor.

Texturas como recursos

Las texturas son recursos, no uniformes. Pasa la fuente y el estilo de la textura por separado:

import { Shader, UniformGroup, Texture, Assets } from "pixi.js";const texture = await Assets.load("myImage.png");const shader = Shader.from({
  gl: { vertex: vertSrc, fragment: fragSrc },
 resources: {
    uTexture: texture.source,
    uSampler: texture.source.style,
    myUniforms: new UniformGroup({
      uAlpha: { value: 1.0, type: "f32" },
    }),
  },
});// Cambiar la textura en tiempo de ejecución
shader.resources.uTexture = otherTexture.source;

Los recursos son un mapa plano de clave-valor. La clave debe coincidir con el nombre del uniforme o del enlace en el código fuente del sombreador.

Los recursos también pueden ser objetos simples (que se envuelven automáticamente en un `UniformGroup`):

const shader = Shader.from({
  gl: { vertex: vertSrc, fragment: fragSrc },
 resources: {
    myUniforms: {
      uTime: { value: 0, type: "f32" },
    },
  },
});

Modo UBO (Uniform Buffer Objects)

El modo UBO agrupa los uniformes en un único búfer de la GPU. Es obligatorio para WebGPU; opcional (WebGL2+) para WebGL.

import { UniformGroup } from "pixi.js";const ubo = new UniformGroup(
  {
    uProjection: { value: new Float32Array(16), type: "mat4x4" },
   uAlpha: { value: 1.0, type: "f32" },
  },
  { ubo: true, isStatic: true },
);// Hay que llamar a update() manualmente cuando isStatic es true
ubo.uniforms.uAlpha = 0.5;
ubo.update();

Reglas de UBO:

• Solo se admiten tipos basados en f32 e i32 (no u32). Las matrices son únicamente de tipo float.
• Los muestreadores y las texturas no pueden incluirse en un UBO.
• El nombre del UniformGroup en los recursos debe coincidir exactamente con el nombre del bloque UBO en el shader.
• La estructura y el orden deben coincidir exactamente con la disposición del shader.
• La sincronización de UBO utiliza la nueva función «Function» en segundo plano. En entornos CSP estrictos (sin «unsafe-eval»), importa «pixi.js/unsafe-eval» una vez al iniciar para activar la ruta de sincronización alternativa; sin ello, los shaders basados en UBO (y, por lo tanto, WebGPU) generarán un error en su primer uso.

Filtro personalizado

Filter.from({ gl, resources }) es la sintaxis abreviada. Pasa únicamente un sombreador de fragmentos; PixiJS proporciona un sombreador de vértices predeterminado que se encarga del posicionamiento del fotograma de salida.

import { Filter } from "pixi.js";const filter = Filter.from({
  gl: {
    fragment: `
            in vec2 vTextureCoord;
            out vec4 finalColor;
            uniform sampler2D uTexture;
            uniform float uStrength;            void main(void) {
                vec4 color = texture(uTexture, vTextureCoord);
                finalColor = mix(color, vec4(1.0 - color.rgb, color.a), uStrength);
            }
        `,
  },
  resources: {
    filterUniforms: {
      uStrength: { value: 0.5, type: "f32" },
    },
  },
});filter.resources.filterUniforms.uniforms.uStrength = 1.0;

Para un sombreador de vértices personalizado, utiliza new Filter({ glProgram: new GlProgram({ vertex, fragment }), resources }).

Convenciones de los sombreadores de Filter (GLSL ES 3.0)

• en vec2 vTextureCoord; en lugar de varying vec2 vTextureCoord;
• out vec4 finalColor; en lugar de gl_FragColor
• texture(uTexture, uv) en lugar de texture2D(uTexture, uv)
• El sombreador de vértices predeterminado expone uInputSize, uOutputFrame, uOutputTexture y las funciones auxiliares filterVertexPosition() / filterTextureCoord()

Muestreo del destino de renderizado detrás del filtro

Establece blendRequired: true y muestrea uBackTexture en el sombreador de fragmentos. PixiJS copia los píxeles de destino en ese uniforme antes de ejecutar el filtro:

const blendFilter = Filter.from({
  gl: { fragment: blendFragSrc },
  resources: { uniforms: { uAmount: { value: 0.5, type: "f32" } } },
  blendRequired: true,
});

Activa blendRequired solo cuando lo necesites; obliga a realizar una copia adicional en la GPU en cada fotograma.

Actualización de uniformes en tiempo de ejecución

// Accede al UniformGroup a través de resources
shader.resources.myUniforms.uniforms.uTime = performance.now() / 1000;// Para los UBO de tipo isStatic, llama a update() después de cambiar los valores
shader.resources.myUniforms.update();

Referencia de tipos de uniformes

Consulta references/uniform-types.md para ver la tabla completa de tipos admitidos, sus equivalentes en WGSL/GLSL y los formatos de valor.

Batcher personalizado (basado en extensiones)

La clase abstracta ` Batcher ` permite la agrupación personalizada para un renderizado especializado. Crea una subclase y regístrala mediante extensiones:

import { Batcher, extensions, ExtensionType } from "pixi.js";
import type {
  BatcherOptions,
  BatchableMeshElement,
  BatchableQuadElement,
  Geometry,
  Shader,
} from "pixi.js";class MyBatcher extends Batcher {
 public static extension = {
    type: [ExtensionType.Batcher],
    name: "my-batcher",
  };  public name = "my-batcher";
 protected vertexSize = 6; // flotantes por vértice
  public geometry: Geometry;
  public shader: Shader;  constructor(options: BatcherOptions) {
    super(options);
    // Inicializar la geometría y el shader
  }  public packAttributes(
    element: BatchableMeshElement,
    float32View: Float32Array,
    uint32View: Uint32Array,
    index: number,
    textureId: number,
  ): void {
   // Empaqueta los atributos de vértices de la malla en el búfer de lotes
  }  public packQuadAttributes(
    element: BatchableQuadElement,
    float32View: Float32Array,
    uint32View: Uint32Array,
    index: number,
    textureId: number,
  ): void {
   // Empaqueta los atributos de vértices del cuadrilátero en el búfer de lote
  }
}extensions.add(MyBatcher);

Los elementos hacen referencia al «batcher» mediante «batcherName». La interfaz «BatchableElement» requiere: «batcherName», «texture», «blendMode», «indexSize», «attributeSize», «topology» y «packAsQuad».

Errores comunes

[CRÍTICO] Antiguo constructor Shader.from(vertex, fragment, uniforms)

Incorrecto:

const shader = Shader.from(vertex, fragment, { uTime: 1 });

Correcto:

const shader = Shader.from({
  gl: { vertex, fragment },
  resources: {
    uniforms: new UniformGroup({
      uTime: { value: 1, type: "f32" },
    }),
  },
});

v8 requiere un objeto de opciones con programasgl/gpu y recursos. Se ha eliminado la API posicional.

[CRÍTICO] UniformGroup sin anotación de tipo

Incorrecto:

new UniformGroup({ uTime: 1 });

Correcto:

new UniformGroup({ uTime: { value: 1, type: "f32" } });

Cada uniforme requiere un par explícito { valor, tipo }. Si se omite el tipo, se produce un error en tiempo de ejecución: «El tipo de uniforme indefinido no es compatible».

[ALTO] UBO con tipos no admitidos o estructura incorrecta

El modo UBO admite tipos basados en f32 e i32 (escalares y vectores). u32 no figura en la lista de tipos admitidos por UniformGroup y provocará un error. Las matrices son solo de tipo float (mat*). Los muestreadores no se pueden colocar en UBO.

El nombre de la estructura y el orden de los campos deben coincidir exactamente con la declaración del UBO en el shader. Las discrepancias producen un renderizado distorsionado sin que se muestre ningún error.

[ALTO] Colocar texturas en UniformGroup

Incorrecto:

new UniformGroup({
  uTexture: { value: texture, type: "f32" },
});

Correcto:

const shader = Shader.from({
  gl: { vertex, fragment },
  resources: {
   uTexture: texture.source,
    uSampler: texture.source.style,
    myUniforms: new UniformGroup({
      uAlpha: { value: 1.0, type: "f32" },
    }),
  },
});

Las texturas son recursos, no uniformes. Pasa texture.source (TextureSource) y texture.source.style (TextureStyle) como entradas de recursos de primer nivel.

Referencia de la API

• Shader
• GlProgram
• GpuProgram
• UniformGroup
• Filtro
• Agrupador
• Canal de agrupador