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 を使います。四隅の位置を渡します。真の3Dではありませんが、2.5Dエフェクトには十分です。
• 「シンプルな形状の頂点をフレームごとにアニメーションさせたい」 → MeshSimple を使います。バッファー更新の手間を処理してくれます。
• 「カスタムシェーダーや特殊なジオメトリが必要」 → 手作業で構築した MeshGeometry を使う基本クラスの Mesh を使います。シェーダーの作成については pixijs-custom-rendering を参照してください。
• 「真の3D描画が必要」 → 専用の3Dライブラリを使います。PerspectiveMesh はUVレベルで透視投影をシミュレートしますが、深度バッファーはありません。

基本概念

MeshGeometry が頂点データを保持する

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

バッチ処理

メッシュがバッチ処理（他の描画呼び出しとの結合）の対象になるのは、MeshGeometry を使用し、カスタムシェーダー、深度状態、カリング状態がなく、さらに 'auto' ルール（batchMode = 'auto' かつ頂点数が100以下）を満たす場合に限られます。カスタムシェーダーは常に個別に描画されます。

トポロジーはメッシュではなくジオメトリに属する

new MeshGeometry({ topology: 'triangle-strip' }) のように指定します。トポロジーはジオメトリのプロパティです。デフォルトは 'triangle-list' です。データが別の形式で構成されている場合は、明示的に設定してください。

追加の設定項目

• new MeshGeometry({ shrinkBuffersToFit: true }) — 作成時に、GPU バッファーのストレージを実際の頂点数に合わせて縮小します。大きなジオメトリを一度だけ渡す場合に使用してください。
• Mesh.containsPoint(point) — 三角形をたどる、トポロジーを考慮したヒットテストです。カスタムレイアウトを含む、あらゆる MeshGeometry で動作します。
• new Mesh({ geometry, state }) — ブレンド、深度、カリングを制御する State オブジェクトを渡します。深度またはカリングのフラグが設定されている場合、バッチ処理は自動的に無効になります。省略した場合は State.for2d() がデフォルトになります。

よくある間違い

[HIGH] 古い 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。すべてオプションオブジェクトを受け取るコンストラクターに変更されました。

[HIGH] MeshGeometry に位置引数を渡す

誤り：

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

正しい例：

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

v8 ではオプションオブジェクトを使用します。プロパティ名は vertices ではなく positions です。vertices という名前を使用するのは MeshSimple だけです。

[MEDIUM] メッシュに子要素を追加する

誤り：

mesh.addChild(otherMesh);

正しい例：

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

Mesh は allowChildren = false に設定されています。子要素を追加すると、非推奨の警告がログに記録されます。メッシュは通常の Container 内にまとめてください。

API リファレンス

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