pixijs-scene-mesh

メッシュは、テクスチャまたはカスタムシェーダーを使用して任意の 2D (またはパースペクティブ投影された) ジオメトリをレンダリングします。PixiJS には基本的な Mesh クラスに加えて、一般的な形状用の 4 つの特殊なサブクラスが付属しています: MeshSimple、MeshPlane、MeshRope、および PerspectiveMesh。あなたの形状に合わせてサブクラスを選択してください。頂点レベルの完全な制御またはカスタムシェーダーが必要な場合は、基本的な Mesh にドロップします。

pixijs-scene-core-concepts の理解を前提としています。メッシュはリーフノードです。子を持つことはできません。複数のメッシュをグループ化するには、Container でラップします。

クイックスタート

const texture = await Assets.load("pattern.png");

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]),
  topology: "triangle-list",
});

const mesh = new Mesh({
  geometry,
  texture,
  roundPixels: false,
});
app.stage.addChild(mesh);

すべての Mesh サブクラスは単一のオプションオブジェクトを受け取ります。基本的な Mesh は geometry が必須です。サブクラス (MeshSimple、MeshPlane、MeshRope、PerspectiveMesh) はジオメトリを内部的に構築し、代わりに texture が必須です。フィールド一覧の詳細は各バリアントのリファレンスを参照してください。

バリアント

バリアント	用途	トレードオフ	リファレンス
Mesh	完全な制御、カスタムジオメトリ、カスタムシェーダー	自分で MeshGeometry を構築する必要があります	references/mesh.md
MeshSimple	フレームごとの頂点アニメーション付きのシンプルなテクスチャ形状	シンテティック ラッパー。頂点バッファを自動更新	references/mesh-simple.md
MeshPlane	変形エフェクト用の細分化されたテクスチャ矩形	固定トポロジー。verticesX/verticesY が密度を制御	references/mesh-plane.md
MeshRope	ポリラインパスに沿うテクスチャ	各ポイントで折り曲がります。スムーズなカーブには多くのポイントが必要	references/mesh-rope.md
PerspectiveMesh	パースペクティブコーナーを持つ 2D プレーン	真の 3D ではありません。UV レベルのパースペクティブ補正のみ	references/mesh-perspective.md

どれを使うか

• 「テクスチャ付きの四角形が必要」 → Sprite (pixijs-scene-sprite を参照)。メッシュではありません。メッシュは Sprite では表現できない場合のためです。
• 「テクスチャ付き矩形を変形させたい」 → MeshPlane。verticesX/verticesY を目的の滑らかさに設定します。
• 「ポイントに沿うロープまたはトレイルが必要」 → MeshRope。width で厚さを制御します。textureScale: 0 で引き伸ばすか、> 0 で繰り返します。
• 「傾いた 2D カードまたは床が必要」 → PerspectiveMesh。4 つのコーナーポジションを渡します。真の 3D ではありませんが、2.5D エフェクトには十分です。
• 「フレームごとにアニメーション化された頂点でシンプルな形状が必要」 → MeshSimple。バッファ更新の処理を自動で行います。
• 「カスタムシェーダーまたは異常なジオメトリが必要」 → 手動で構築した MeshGeometry と基本的な Mesh。シェーダーの作成については pixijs-custom-rendering を参照してください。
• 「真の 3D レンダリングが必要」 → 専用の 3D ライブラリを使用してください。PerspectiveMesh は UV レベルでパースペクティブをシミュレートしますが、深度バッファはありません。

クイックコンセプト

MeshGeometry が頂点データを所有

MeshGeometry は positions、uvs、indices、および topology を保持します。複数の Mesh インスタンス間で 1 つのジオメトリを共有できます。ポジションは参照カウントされます。

バッチング

メッシュは MeshGeometry を使用し、カスタムシェーダーがなく、深度またはカリング状態がなく、'auto' ルール (batchMode = 'auto' および ≤100 頂点) の場合のみバッチ処理されます (他のドロー呼び出しと結合)。カスタムシェーダーは常に独立してレンダリングされます。

トポロジーはメッシュではなくジオメトリ上にあります

new MeshGeometry({ topology: 'triangle-strip' })。トポロジーはジオメトリプロパティです。デフォルトは 'triangle-list' です。データが異なる方法で整理されている場合は明示的に設定してください。

追加オプション

• new MeshGeometry({ shrinkBuffersToFit: true }) — GPU バッファストレージを作成時の実際の頂点数にトリミングします。大規模な 1 回限りのジオメトリを供給する場合に使用します。
• Mesh.containsPoint(point) — トポロジーを認識したヒットテスト。三角形をウォークします。カスタムレイアウトを含む任意の MeshGeometry で機能します。
• new Mesh({ geometry, state }) — ブレンド、深度、およびカリングを制御する State オブジェクトを渡します。深度またはカリングフラグが設定されている場合、バッチ処理は自動的に無効になります。省略された場合、デフォルトは State.for2d() です。

よくあるエラー

[高] 古い SimpleMesh / SimplePlane / SimpleRope 名の使用

誤り:

import { SimpleRope } from "pixi.js";
const rope = new SimpleRope(texture, points);

正解:

import { MeshRope } from "pixi.js";
const rope = new MeshRope({ texture, points });

v8 で名前変更: SimpleMesh → MeshSimple、SimplePlane → MeshPlane、SimpleRope → MeshRope。すべてオプションオブジェクトコンストラクタに切り替わりました。

[高] MeshGeometry の位置付き引数

誤り:

const geom = new MeshGeometry(vertices, uvs, indices);

正解:

const geom = new MeshGeometry({
  positions: vertices,
  uvs,
  indices,
  topology: "triangle-list",
});

v8 はオプションオブジェクトを使用します。プロパティは positions であり、vertices ではありません。vertices 名は MeshSimple でのみ使用されます。

[中] メッシュに子を追加

誤り:

mesh.addChild(otherMesh);

正解:

const group = new Container();
group.addChild(mesh, otherMesh);

Mesh は allowChildren = false を設定します。子を追加するとデプリケーション警告がログされます。メッシュを単純な Container 内にグループ化してください。

API リファレンス

• Mesh
• MeshGeometry
• MeshSimple
• MeshPlane
• MeshRope
• PerspectiveMesh