pixijs-custom-rendering

Os shaders personalizados vinculam programas GLSL e WGSL aos objetos da cena por meio de Shader.from({ gl, gpu, resources }). Os uniformes ficam em UniformGroupstipados, as texturas são passadas como recursos separados, e o mesmo shader pode ser direcionado tanto para WebGL quanto para WebGPU.

Introdução rápida

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 (geometria personalizada), pixijs-performance (otimização em lote), pixijs-migration-v8 (migração da API de shaders da v7).

Padrões principais

Shader com renderizador duplo (WebGL + WebGPU)

import { Shader, GlProgram, GpuProgram, UniformGroup } from "pixi.js";const glVertex = `...`; // vértice GLSL (escreva `#version 300 es` manualmente se desejar WebGL2/GLSL ES 3.0)
const glFragment = `...`; // fragmento GLSL
const wgslSource = `...`; // WGSLcombinado
 const shader = Shader.from({
  gl: { vertex: glVertex, fragment: glFragment },
 gpu: {
    // os nomes dos entryPoints são arbitrários; eles devem corresponder  aos nomes das funções @vertex / @fragment
    // em sua fonte WGSL. O PixiJS fornece exemplos usando
    // 'mainVert' / 'mainFrag', mas `main` também é 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" },
    }),
  },
});

Se apenas `gl` for fornecido, o shader funciona apenas com WebGL. Se apenas `gpu` for fornecido, ele funciona apenas com WebGPU. A máscara de bits `compatibleRenderers` é definida automaticamente.

O `GlProgram ` não injeta automaticamente ` #version 300 es`. Se você mesmo escrever #version 300 es, o PixiJS o preserva e trata o shader como GLSL ES 3.0; caso contrário, ele injeta macros de compatibilidade com WebGL1 (#define em varying, #define texture texture2D) e executa o shader como GLSL no estilo WebGL1. O GlProgram sempre injeta uma precisão padrão (highp para vértices, mediump para fragmentos) e o nome do programa. Para GLSL ES 3.0, usein/out em vez deattribute/varying, texture() em vez de texture2D() e um out vec4 em vez de gl_FragColor.

Texturas como recursos

Texturas são recursos, não uniformes. Passe a fonte e o estilo da textura separadamente:

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" },
    }),
  },
});// Trocar a textura em tempo de execução
shader.resources.uTexture = otherTexture.source;

Os recursos são um mapa simples de chave-valor. A chave deve corresponder ao nome do uniforme/binding no código-fonte do shader.

Os recursos também podem ser objetos simples (automaticamente encapsulados em UniformGroup):

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

Modo UBO (Uniform Buffer Objects)

O modo UBO agrupa uniformes em um único buffer da GPU. Obrigatório 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 },
);// É necessário chamar update() manualmente quando isStatic for true
ubo.uniforms.uAlpha = 0.5;
ubo.update();

Regras do UBO:

• Apenas tipos baseados em f32 e i32 são suportados (não u32). Matrizes são apenas do tipo float.
• Amostradores/texturas não podem ser incluídos em um UBO.
• O nome do UniformGroup nos recursos deve corresponder exatamente ao nome do bloco UBO no shader.
• A estrutura e a ordem devem corresponder exatamente ao layout do shader.
• A sincronização do UBO utiliza a nova função internamente. Em ambientes CSP estritos (sem unsafe-eval), importe pixi.js/unsafe-eval uma vez na inicialização para ativar o caminho de sincronização alternativo; sem isso, os shaders baseados em UBO (e, portanto, o WebGPU) apresentarão erros na primeira utilização.

Filtro personalizado

Filter.from({ gl, resources }) é a sintaxe abreviada. Passe apenas um shader de fragmento; o PixiJS fornece um shader de vértice padrão que lida com o posicionamento do quadro de saída.

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 um shader de vértice personalizado, use new Filter({ glProgram: new GlProgram({ vertex, fragment }), resources }).

Convenções de shader de filtro (GLSL ES 3.0)

• em vec2 vTextureCoord; em vez de varying vec2 vTextureCoord;
• out vec4 finalColor; em vez de gl_FragColor
• texture(uTexture, uv) em vez de texture2D(uTexture, uv)
• O shader de vértices padrão expõe uInputSize, uOutputFrame, uOutputTexture e as funções auxiliares filterVertexPosition() / filterTextureCoord()

Amostragem do alvo de renderização por trás do filtro

Defina blendRequired: true e amostre uBackTexture no shader de fragmento. O PixiJS copia os pixels de destino para esse uniforme antes de executar o filtro:

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

Ative blendRequired somente quando for necessário; isso força uma cópia extra na GPU a cada quadro.

Atualizando uniformes em tempo de execução

// Acesse o UniformGroup por meio de resources
shader.resources.myUniforms.uniforms.uTime = performance.now() / 1000;// Para UBOs isStatic, chame update() após alterar os valores
shader.resources.myUniforms.update();

Referência de tipos de uniformes

Consulte references/uniform-types.md para ver a tabela completa dos tipos suportados, seus equivalentes em WGSL/GLSL e formatos de valor.

Batcher personalizado (baseado em extensão)

A classe abstrata `Batcher ` permite o agrupamento personalizado para renderização especializada. Crie uma subclasse dela e registre-a por meio de extensões:

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; // floats por vértice
  public geometry: Geometry;
  public shader: Shader;  constructor(options: BatcherOptions) {
    super(options);
    // Inicializar geometria e shader
  }  public packAttributes(
    element: BatchableMeshElement,
    float32View: Float32Array,
    uint32View: Uint32Array,
    index: number,
    textureId: number,
  ): void {
   // Empacota os atributos dos vértices da malha no buffer de lote
  }  public packQuadAttributes(
    element: BatchableQuadElement,
    float32View: Float32Array,
    uint32View: Uint32Array,
    index: number,
    textureId: number,
  ): void {
   // Empacota os atributos dos vértices do quad no buffer de lote
  }
}extensions.add(MyBatcher);

Os elementos fazem referência ao batcher por meio de batcherName. A interface BatchableElement requer: batcherName, texture, blendMode, indexSize, attributeSize, topology e packAsQuad.

Erros comuns

[CRÍTICO] Construtor antigo Shader.from(vertex, fragment, uniforms)

Errado:

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

Correto:

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

O v8 exige um objeto de opções com programasgl/gpu e recursos. A API posicional foi removida.

[CRÍTICO] UniformGroup sem anotação de tipo

Errado:

new UniformGroup({ uTime: 1 });

Correto:

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

Todo uniform requer um par explícito { value, type }. A omissão do tipo causa um erro de tempo de execução: “O tipo de uniform indefinido não é suportado.”

[ALTO] UBO com tipos não suportados ou estrutura incorreta

O modo UBO suporta tipos baseados em f32 e i32 (escalares e vetores). u32 não está na lista de tipos suportados pelo UniformGroup e causará uma exceção. Matriz são apenas do tipo float (mat*). Amostradores não podem ser colocados em UBOs.

O nome da estrutura e a ordem dos campos devem corresponder exatamente à declaração do UBO no shader. Incompatibilidades resultam em renderização distorcida, sem exibição de erro.

[ALTO] Colocando texturas no UniformGroup

Errado:

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

Correto:

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

Texturas são recursos, não uniformes. Passe texture.source (TextureSource) e texture.source.style (TextureStyle) como entradas de recurso de nível superior.

Referência da API

• Shader
• GlProgram
• GpuProgram
• UniformGroup
• Filtro
• Batcher
• Canal de agrupamento