pixijs-custom-rendering

Benutzerdefinierte Shader binden GLSL- und WGSL-Programme über `Shader.from({ gl, gpu, resources })` an Szenenobjekte. Uniforms werden in typisierten `UniformGroups`gespeichert, Texturen werden als separate Ressourcen übergeben, und derselbe Shader kann sowohl für WebGL als auch für WebGPU verwendet werden.

Schnellstart

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]),
 indices: 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;
});

Verwandte Funktionen: pixijs-filters (integrierte Filter), pixijs-scene-mesh (benutzerdefinierte Geometrie), pixijs-performance (Batch-Optimierung), pixijs-migration-v8 (Migration der Shader-API von v7).

Kernmuster

Shader mit zwei Renderern (WebGL + WebGPU)

import { Shader, GlProgram, GpuProgram, UniformGroup } from "pixi.js";const glVertex = `...`; // GLSL-Vertex (füge selbst `#version 300 es` ein, wenn du WebGL2/GLSL ES 3.0 verwenden möchtest)
const glFragment = `...`; // GLSL-Fragment
const wgslSource = `...`; //WGSL-Kombinationconst shader = Shader.from({
  gl: { vertex: glVertex, fragment: glFragment },
 gpu: {
    // Die Namen der Einstiegspunkte sind beliebig; sie müssen mit den @vertex- bzw. @fragment-
    // Funktionsnamen in Ihrer WGSL-Quelle  übereinstimmen . PixiJS liefert Beispiele mit
    // „mainVert“ / „mainFrag“, aber „main“ ist ebenso gültig.
   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" },
    }),
  },
});

Wenn nur „gl“ angegeben wird, funktioniert der Shader nur mit WebGL. Wenn nur „gpu“ angegeben wird, funktioniert er nur mit WebGPU. Die Bitmaske „compatibleRenderers“ wird automatisch gesetzt.

„GlProgram“ fügt „#version 300 es“ nicht automatisch ein. Wenn Sie #version 300 es selbst schreiben, behält PixiJS dies bei und behandelt den Shader als GLSL ES 3.0; andernfalls fügt es WebGL1-Kompatibilitätsmakros ein (#define in varying, #define texture texture2D) und führt den Shader als GLSL im WebGL1-Stil aus. GlProgram fügt immer eine Standardpräzision (highp für Vertex, mediump für Fragment) sowie den Programmnamen ein. Für GLSL ES 3.0 verwenden Sie„in/out“ anstelle von„attribute/varying“, „texture()“ anstelle von „texture2D()“ und ein „out vec4“ anstelle von „gl_FragColor“.

Texturen als Ressourcen

Texturen sind Ressourcen, keine Uniforms. Übergeben Sie die Quelle und den Stil der Textur separat:

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" },
    }),
  },
});// Textur zur Laufzeit austauschen
shader.resources.uTexture = otherTexture.source;

Ressourcen sind eine flache Schlüssel-Wert-Zuordnung. Der Schlüssel muss mit dem Namen des Uniforms bzw. der Bindung in der Shader-Quelle übereinstimmen.

Ressourcen können auch einfache Objekte sein (die automatisch in eine `UniformGroup` verpackt werden):

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

UBO-Modus (Uniform Buffer Objects)

Der UBO-Modus bündelt Uniforms in einem einzigen GPU-Puffer. Erforderlich für WebGPU; optional (WebGL2+) für 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 },
);// Bei „isStatic“ = true muss „update()“ manuell aufgerufen werden
ubo.uniforms.uAlpha = 0.5;
ubo.update();

UBO-Regeln:

• Es werden nur auf f32 und i32 basierende Typen unterstützt (kein u32). Matrizen sind ausschließlich vom Typ „float“.
• Sampler/Texturen können nicht in einem UBO enthalten sein.
• Der Name der „UniformGroup“ in den Ressourcen muss exakt mit dem Namen des UBO-Blocks im Shader übereinstimmen.
• Struktur und Reihenfolge müssen genau mit dem Shader-Layout übereinstimmen.
• Die UBO-Synchronisation nutzt intern die neue „Function“-Funktion. In strengen CSP-Umgebungen (ohne „unsafe-eval“) muss „pixi.js/unsafe-eval“ einmalig beim Start importiert werden, um auf den Fallback-Synchronisationspfad umzuschalten; andernfalls lösen UBO-gestützte Shader (und damit WebGPU) bei der ersten Verwendung einen Fehler aus.

Benutzerdefinierter Filter

Filter.from({ gl, resources }) ist die Kurzschreibweise. Übergeben Sie nur einen Fragment-Shader; PixiJS stellt einen Standard-Vertex-Shader bereit, der die Positionierung des Ausgabeframes übernimmt.

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;

Für einen benutzerdefinierten Vertex-Shader verwenden Sie new Filter({ glProgram: new GlProgram({ vertex, fragment }), resources }).

Filter-Shader-Konventionen (GLSL ES 3.0)

• in vec2 vTextureCoord; anstelle von varying vec2 vTextureCoord;
• out vec4 finalColor; anstelle von gl_FragColor
• texture(uTexture, uv) anstelle von texture2D(uTexture, uv)
• Der Standard-Vertex-Shader stellt uInputSize, uOutputFrame, uOutputTexture sowie die Hilfsfunktionen filterVertexPosition() und filterTextureCoord() bereit

Abtasten des Renderziels hinter dem Filter

Setze `blendRequired: true ` und sample ` uBackTexture ` im Fragment-Shader. PixiJS kopiert die Zielpixel in dieses Uniform, bevor der Filter ausgeführt wird:

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

Aktivieren Sie `blendRequired` nur, wenn Sie es benötigen; es erzwingt in jedem Frame eine zusätzliche GPU-Kopie.

Uniforms zur Laufzeit aktualisieren

// Zugriff auf die „UniformGroup“ über „resources“
shader.resources.myUniforms.uniforms.uTime = performance.now() / 1000;// Bei „isStatic“-UBOs rufen Sie nach einer Wertänderung „update()“ auf
shader.resources.myUniforms.update();

Referenz zu Uniform-Typen

Eine vollständige Tabelle der unterstützten Typen, ihrer WGSL-/GLSL-Entsprechungen und Wertformate finden Sie in „references/uniform-types.md “.

Benutzerdefinierter Batcher (erweiterungsbasiert)

Die abstrakte Klasse `Batcher` ermöglicht benutzerdefiniertes Batching für spezielle Rendering-Anwendungen. Erstellen Sie eine Unterklasse davon und registrieren Sie diese über Erweiterungen:

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 pro Scheitelpunkt
  public geometry: Geometry;
  public shader: Shader;  constructor(options: BatcherOptions) {
    super(options);
    // Geometrie und Shader initialisieren
  }  public packAttributes(
    element: BatchableMeshElement,
    float32View: Float32Array,
    uint32View: Uint32Array,
    index: number,
    textureId: number,
  ): void {
   // Mesh-Vertex-Attribute in den Batch-Puffer packen
  }  public packQuadAttributes(
    element: BatchableQuadElement,
    float32View: Float32Array,
    uint32View: Uint32Array,
    index: number,
    textureId: number,
  ): void {
   // Quad-Vertex-Attribute in den Batch-Puffer packen
  }
}extensions.add(MyBatcher);

Elemente verweisen über `batcherName` auf den Batcher. Die Schnittstelle `BatchableElement` erfordert folgende Parameter: `batcherName`, `texture`, `blendMode`, `indexSize`, `attributeSize`, `topology` und `packAsQuad`.

Häufige Fehler

[KRITISCH] Veralteter Konstruktor `Shader.from(vertex, fragment, uniforms)`

Falsch:

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

Richtig:

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

v8 erfordert ein Options-Objekt mitgl/gpu -Programmen und Ressourcen. Die Positions-API wurde entfernt.

[KRITISCH] „UniformGroup“ ohne Typangabe

Falsch:

new UniformGroup({ uTime: 1 });

Richtig:

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

Jede Uniform erfordert ein explizites { value, type } -Paar. Das Weglassen des Typs führt zu einem Laufzeitfehler: „Der Uniform-Typ ‚undefined‘ wird nicht unterstützt.“

[HIGH] UBO mit nicht unterstützten Typen oder falscher Struktur

Der UBO-Modus unterstützt auf f32 und i32 basierende Typen (Skalaren und Vektoren). u32 ist nicht in der Liste der unterstützten UniformGroup-Typen enthalten und löst einen Fehler aus. Matrizen sind ausschließlich vom Typ „float“ (mat*). Sampler können nicht in UBOs platziert werden.

Der Struktur-Name und die Feldreihenfolge müssen exakt mit der UBO-Deklaration des Shaders übereinstimmen. Abweichungen führen zu einer verzerrten Darstellung ohne Fehlermeldung.

[HIGH] Einfügen von Texturen in eine UniformGroup

Falsch:

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

Richtig:

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

Texturen sind Ressourcen, keine Uniforms. Übergeben Sie `texture.source ` (TextureSource) und `texture.source.style ` (TextureStyle) als Ressourceneinträge auf oberster Ebene.

API-Referenz

• Shader
• GlProgram
• GpuProgram
• UniformGroup
• Filter
• Batcher
• Batcher-Pipe