pixijs-custom-rendering

カスタムシェーダーは Shader.from({ gl, gpu, resources }) を使用してGLSLおよびWGSLプログラムをシーンオブジェクトにバインドします。ユニフォームは型付き UniformGroup に格納され、テクスチャは個別のリソースとして渡され、同じシェーダーでWebGLとWebGPUの両方をターゲットにできます。

クイックスタート

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

関連スキル: pixijs-filters (組み込みフィルター)、pixijs-scene-mesh (カスタムジオメトリ)、pixijs-performance (バッチ最適化)、pixijs-migration-v8 (v7からのシェーダーAPI移行)。

コアパターン

デュアルレンダラーシェーダー (WebGL + WebGPU)

import { Shader, GlProgram, GpuProgram, UniformGroup } from "pixi.js";

const glVertex = `...`; // GLSLバーテックス (必要に応じて `#version 300 es` を自分で記述してください)
const glFragment = `...`; // GLSLフラグメント
const wgslSource = `...`; // WGSL統合

const shader = Shader.from({
  gl: { vertex: glVertex, fragment: glFragment },
  gpu: {
    // entryPoint名は任意です。WGSLソース内の @vertex / @fragment
    // 関数名と一致する必要があります。PixiJSは
    // 'mainVert' / 'mainFrag' を使用した例を提供していますが、`main` も同様に有効です。
    vertex: { entryPoint: "mainVert", source: wgslSource },
    fragment: { entryPoint: "mainFrag", source: wgslSource },
  },
  resources: {
    myUniforms: new UniformGroup({
      uColor: { value: new Float32Array([1, 0, 0, 1]), type: "vec4<f32>" },
      uMatrix: { value: new Float32Array(16), type: "mat4x4<f32>" },
    }),
  },
});

gl のみが指定されている場合、シェーダーはWebGLのみで動作します。gpu のみが指定されている場合、WebGPUのみで動作します。compatibleRenderers ビットマスクは自動的に設定されます。

GlProgram は 自動的に #version 300 es を注入しません。#version 300 es を自分で記述すると、PixiJSはそれを保持してシェーダーをGLSL ES 3.0として扱います。そうでない場合は、WebGL1互換マクロ (#define in varying、#define texture texture2D) を注入し、WebGL1スタイルのGLSLとして実行します。GlProgram は常にデフォルト精度 (バーテックス highp、フラグメント mediump) とプログラム名を注入します。GLSL ES 3.0の場合、attribute/varying の代わりに in/out を使用し、texture2D() の代わりに texture() を使用し、gl_FragColor の代わりに out vec4 を使用します。

リソースとしてのテクスチャ

テクスチャはリソースであり、ユニフォームではありません。テクスチャの source と style を個別に渡します:

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

// 実行時にテクスチャをスワップ
shader.resources.uTexture = otherTexture.source;

リソースはフラットなキー値マップです。キーはシェーダーソース内のユニフォーム/バインディング名と一致する必要があります。

リソースは、プレーンオブジェクトにすることもできます (自動的に UniformGroup にラップされます):

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

UBOモード (Uniform Buffer Objects)

UBOモードは、ユニフォームを単一のGPUバッファーに詰め込みます。WebGPUでは必須です。WebGLでは随意です (WebGL2+)。

import { UniformGroup } from "pixi.js";

const ubo = new UniformGroup(
  {
    uProjection: { value: new Float32Array(16), type: "mat4x4<f32>" },
    uAlpha: { value: 1.0, type: "f32" },
  },
  { ubo: true, isStatic: true },
);

// isStatic が true の場合、手動で update() を呼び出す必要があります
ubo.uniforms.uAlpha = 0.5;
ubo.update();

UBOのルール:

• f32 および i32 ベースの型のみがサポートされます (u32 は不可)。行列はfloatのみです。
• サンプラー/テクスチャはUBOに置くことはできません。
• リソース内のUniformGroup名は、シェーダー内のUBOブロック名と正確に一致する必要があります。
• 構造と順序は、シェーダーレイアウトと正確に一致する必要があります。
• UBO同期は、内部で new Function を使用します。厳密なCSP環境 (unsafe-eval なし) では、起動時に pixi.js/unsafe-eval をインポートしてフォールバック同期パスに切り替えます。これなしでは、UBOバック付きシェーダー (したがってWebGPU) は最初の使用時にエラーを投げます。

カスタムフィルター

Filter.from({ gl, resources }) は短縮形です。フラグメントシェーダーのみを渡します。PixiJSは、出力フレーム配置を処理するデフォルトバーテックスシェーダーを提供します。

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;

カスタムバーテックスシェーダーの場合、new Filter({ glProgram: new GlProgram({ vertex, fragment }), resources }) を使用します。

フィルターシェーダーの規約 (GLSL ES 3.0)

• varying vec2 vTextureCoord; の代わりに in vec2 vTextureCoord;
• gl_FragColor の代わりに out vec4 finalColor;
• texture2D(uTexture, uv) の代わりに texture(uTexture, uv)
• デフォルトバーテックスシェーダーは uInputSize、uOutputFrame、uOutputTexture およびヘルパー filterVertexPosition() / filterTextureCoord() を公開します

フィルターの背後にあるレンダーターゲットのサンプリング

blendRequired: true を設定し、フラグメントシェーダーで uBackTexture をサンプリングします。PixiJSはフィルターを実行する前に、ピクセルをそのユニフォームにコピーします:

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

必要な場合にのみ blendRequired を有効にしてください。毎フレーム追加のGPUコピーを強制します。

実行時にユニフォームを更新する

// リソースを通じてUniformGroupにアクセス
shader.resources.myUniforms.uniforms.uTime = performance.now() / 1000;

// isStatic UBOの場合、値を変更した後に update() を呼び出す
shader.resources.myUniforms.update();

ユニフォーム型リファレンス

サポートされている型の完全な表、WGSL/GLSL同等物、および値形式については、references/uniform-types.md を参照してください。

カスタムBatcher (拡張ベース)

Batcher 抽象クラスは、特殊なレンダリング用のカスタムバッチングを有効にします。サブクラス化し、拡張を通じて登録します:

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; // 頂点あたりのfloat数
  public geometry: Geometry;
  public shader: Shader;

  constructor(options: BatcherOptions) {
    super(options);
    // ジオメトリとシェーダーを初期化
  }

  public packAttributes(
    element: BatchableMeshElement,
    float32View: Float32Array,
    uint32View: Uint32Array,
    index: number,
    textureId: number,
  ): void {
    // メッシュの頂点属性をバッチバッファーにパック
  }

  public packQuadAttributes(
    element: BatchableQuadElement,
    float32View: Float32Array,
    uint32View: Uint32Array,
    index: number,
    textureId: number,
  ): void {
    // クワッド頂点属性をバッチバッファーにパック
  }
}

extensions.add(MyBatcher);

要素は batcherName によってBatcherを参照します。BatchableElement インターフェースには、batcherName、texture、blendMode、indexSize、attributeSize、topology、および packAsQuad が必要です。

よくある間違い

[重大] 古い Shader.from(vertex, fragment, uniforms) コンストラクター

間違い:

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

正しい:

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

v8では、gl/gpu プログラムと resources を含むオプションオブジェクトが必要です。位置引数APIは削除されました。

[重大] 型注釈のないUniformGroup

間違い:

new UniformGroup({ uTime: 1 });

正しい:

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

すべてのユニフォームには、明示的な { value, type } ペアが必要です。型を省略すると、実行時エラーが発生します: "Uniform type undefined is not supported."

[高] サポートされていない型または間違った構造を持つUBO

UBOモードは、f32 および i32 ベースの型 (スカラーとベクトル) をサポートしています。u32 はサポートされているUniformGroup型リストにはなく、エラーを投げます。行列はfloatのみです (mat*<f32>)。サンプラーはUBOに置くことはできません。

構造名とフィールド順序は、シェーダーのUBO宣言と正確に一致する必要があります。不一致は、エラーなしでガベージレンダリングを生成します。

[高] UniformGroupにテクスチャを配置する

間違い:

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

正しい:

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

テクスチャはリソースであり、ユニフォームではありません。texture.source (TextureSource) と texture.source.style (TextureStyle) をトップレベルのリソースエントリとして渡します。

APIリファレンス

• Shader
• GlProgram
• GpuProgram
• UniformGroup
• Filter
• Batcher
• BatcherPipe