pixijs-scene-graphics

Graphics は PixiJS v8 のシーングラフにおけるベクタ描画の終端です。v8 API は形状-スタイル順序のパターンに従います。rect、circle、moveTo などで形状またはパスを描画してから、fill および/または stroke を適用します。すべてのメソッドはチェーン用に this を返し、描画命令は複数のインスタンス間で共有できる GraphicsContext に存在します。

pixijs-scene-core-concepts の理解を想定しています。Graphics は終端です。その内部に子要素をネストしないでください。複数の Graphics オブジェクトを Container でラップしてグループ化します。

クイックスタート

const g = new Graphics();

g.rect(10, 10, 200, 100)
  .fill({ color: 0x3498db, alpha: 0.8 })
  .stroke({ width: 3, color: 0x2c3e50 });

g.circle(300, 60, 40).fill(0xe74c3c);

g.moveTo(50, 200)
  .lineTo(200, 200)
  .bezierCurveTo(250, 250, 100, 300, 50, 250)
  .closePath()
  .fill(0x6c5ce7);

app.stage.addChild(g);

関連スキル: pixijs-scene-core-concepts (シーングラフの基本)、pixijs-scene-container (他のオブジェクトとグラフィックスをグループ化)、pixijs-scene-core-concepts/references/masking.md (ステンシルマスクとしての Graphics)、pixijs-filters (エフェクト)、pixijs-performance (バッチング、cacheAsTexture)。

コンストラクタオプション

すべての Container オプション (position、scale、tint、label、filters、zIndex など) もここで有効です。詳細は skills/pixijs-scene-core-concepts/references/constructor-options.md を参照してください。

GraphicsOptions によって追加される終端固有のオプション:

オプション	型	デフォルト	説明
context	GraphicsContext	new GraphicsContext()	共有描画コンテキスト。コンテキストを渡すと、複数の Graphics ノード間でその三角分割されたジオメトリが再利用され、重複する GPU 作業が回避されます。省略すると、各 Graphics は新しいコンテキストを作成・所有します。
roundPixels	boolean	false	最終的な画面上の x/y を最も近いピクセルに丸めます。ピクセルアート スタイルではよりシャープな線が得られますが、スムーズなサブピクセル移動が失われます。

コンストラクタは GraphicsContext インスタンスを単一の引数として受け入れることもできます (new Graphics(ctx))。これは new Graphics({ context: ctx }) の短縮形です。

コアパターン

形状-塗りつぶしのワークフロー

const g = new Graphics();

g.rect(10, 10, 200, 100)
  .fill({ color: 0x3498db, alpha: 0.8 })
  .stroke({ width: 3, color: 0x2c3e50 });

g.circle(150, 200, 40).fill(0xe74c3c);
g.roundRect(300, 10, 150, 80, 12).fill(0x2ecc71);
g.poly([0, 0, 60, 0, 30, 50], true).fill(0x9b59b6);
g.star(400, 200, 5, 40, 20, 0).fill(0xf39c12);
g.ellipse(100, 350, 60, 30).fill(0x1abc9c);

fill() は FillInput を受け入れます。カラー番号/文字列、{ color, alpha, texture, matrix, textureSpace }、FillGradient、FillPattern、または Textureです。テクスチャで塗りつぶす場合、textureSpace は座標マッピングを制御します:

• 'local' (デフォルト): テクスチャは各形状の外接矩形に合わせてスケーリングされます (正規化 0-1 座標)。
• 'global': テクスチャの位置/スケールは Graphics オブジェクトの座標系に対して相対的であり、すべての形状にわたって共有されます。

FillInput は入れ子の fill サブフィールドもサポートしています。FillStyle オプションオブジェクトは FillGradient または FillPattern をその fill キーに埋め込むことができ、これは外側のオブジェクトの color、alpha、texture、matrix 修飾子と一緒にグラデーションまたはパターンを適用します。

stroke() はカラー、FillGradient、FillPattern、または StrokeStyle オブジェクトを受け入れます。StrokeStyle はすべての FillStyle キー (color、alpha、texture、matrix、fill、textureSpace) をストロク属性と組み合わせます:

属性	デフォルト	備考
width	1	ストロークのピクセル幅。
cap	'butt'	'butt'、'round'、'square' のいずれか。開いたパスの終端スタイル。
join	'miter'	'miter'、'round'、'bevel' のいずれか。コーナースタイル。
miterLimit	10	miter ジョイン が どこまで延びるかを制限します。その後ベベルにフォールバックします。
alignment	0.5	1 = 形状の内側、0.5 = 中央、0 = 外側。
pixelLine	false	1 ピクセル線をピクセルグリッドに合わせて鮮明な出力を得ます。Graphics のみ。

ストロークは fill: gradient または texture: tex を使用して、塗りつぶしと同じグラデーションとパターンを使用できます:

const grad = new FillGradient({
  end: { x: 1, y: 0 },
  colorStops: [
    { offset: 0, color: 0xff0000 },
    { offset: 1, color: 0x0000ff },
  ],
});
g.rect(0, 0, 200, 100).stroke({
  width: 8,
  fill: grad,
  join: "round",
  cap: "round",
});

fill() と stroke() の両方を同じ形状の後で呼び出すことができます。stroke() を fill() の直後に呼び出すと、同じパスが再利用されます。

高度な形状プリミティブ

g.regularPoly(100, 100, 50, 6, 0).fill(0x3498db);
g.roundPoly(250, 100, 50, 5, 10).fill(0xe74c3c);
g.chamferRect(350, 50, 100, 80, 15).fill(0x2ecc71);
g.filletRect(500, 50, 100, 80, 15).fill(0x9b59b6);
g.roundShape(
  [
    { x: 50, y: 250, radius: 20 },
    { x: 150, y: 250, radius: 5 },
    { x: 150, y: 350, radius: 10 },
    { x: 50, y: 350, radius: 15 },
  ],
  10,
).fill(0xf39c12);

cut() による穴

g.rect(0, 0, 200, 200).fill(0x00ff00).circle(100, 100, 50).cut();

cut() は現在のアクティブパスを以前に描画された塗りつぶしまたはストロークから減算します。ルール:

• 穴はターゲット形状の完全内部になければなりません。エッジと重なる、または形状の外側に位置する穴は、レンダラーが穴を内部境界として三角分割するため、正しくレンダリングされません。
• cut() は最後の 2 つまでの命令を遡ります。同じパスに fill() してから stroke() する場合、単一の cut() はまずストロークに穴を追加します。2 番目の cut() は下の塗りつぶしに追加します。
• cut() の後、アクティブパスはリセットされるため、moveTo、rect などで次の形状を開始できます。
• cut() はストロークにも適用されます — g.rect(...).stroke(...).circle(...).cut() はストロークアウトラインを通して穴を切ります。

複数の穴を 1 つの cut() で開けるには、cut() を呼び出す前にアクティブパスにいくつかの形状を描画します。各形状は同じ穴パスに蓄積されます:

const g = new Graphics();

g.rect(350, 350, 150, 150).fill(0x00ff00);

// 3 つの円をアクティブパスに描画してから、1 回の呼び出しですべてを切ります
g.circle(375, 375, 25);
g.circle(425, 425, 25);
g.circle(475, 475, 25);
g.cut();

別の塗りつぶされた形状に穴が必要な場合は、各形状に独自の fill() と一致する cut() を与えます:

g.rect(0, 0, 100, 100).fill(0x3498db);
g.circle(50, 50, 20).cut(); // rect の穴

g.rect(120, 0, 100, 100).fill(0xe74c3c);
g.circle(170, 50, 20).cut(); // 2 番目の rect の穴

既に穴がある形状で cut() を呼び出すと、穴パスが置き換わるのではなく追加されます。これを使用して穴を加算的にレイアウトします。

パスと複雑な形状

g.moveTo(50, 50)
  .lineTo(200, 50)
  .bezierCurveTo(250, 100, 250, 150, 200, 200)
  .quadraticCurveTo(100, 250, 50, 200)
  .closePath()
  .fill({ color: 0x6c5ce7, alpha: 0.7 })
  .stroke({ width: 2, color: 0xdfe6e9 });

パスメソッド: moveTo、lineTo、bezierCurveTo、quadraticCurveTo、arc、arcTo、arcToSvg、closePath。現在のパスを破棄して新しいパスを開始するには beginPath() を呼び出します。

// arc(cx, cy, radius, startAngle, endAngle, counterclockwise?)
g.moveTo(80, 50)
  .arc(50, 50, 30, 0, Math.PI)
  .stroke({ width: 4, color: 0x2c3e50 });

// arcTo(x1, y1, x2, y2, radius) — 2 つのラインセグメント間の丸いコーナー
g.moveTo(150, 20)
  .arcTo(200, 20, 200, 80, 20)
  .lineTo(200, 80)
  .stroke({ width: 2 });

// arcToSvg(rx, ry, xAxisRotation, largeArcFlag, sweepFlag, x, y) — SVG `A` コマンドに一致
g.moveTo(250, 50).arcToSvg(40, 20, 0, 1, 0, 330, 50).stroke({ width: 2 });

グラデーションとパターン

// 線形グラデーション
const linear = new FillGradient({
  end: { x: 1, y: 0 },
  colorStops: [
    { offset: 0, color: 0xff0000 },
    { offset: 1, color: 0x0000ff },
  ],
});
g.rect(0, 0, 200, 100).fill(linear);

// 放射グラデーション — 内円が中央、外円がエッジに到達
const radial = new FillGradient({
  type: "radial",
  center: { x: 100, y: 100 },
  innerRadius: 0,
  outerCenter: { x: 100, y: 100 },
  outerRadius: 100,
  colorStops: [
    { offset: 0, color: 0xffffff },
    { offset: 1, color: 0x000000 },
  ],
});
g.circle(100, 100, 100).fill(radial);

const brick = await Assets.load("brick.png");
const pattern = new FillPattern(brick, "repeat"); // 'repeat' | 'repeat-x' | 'repeat-y' | 'no-repeat'
g.rect(0, 120, 200, 100).fill(pattern);

FillGradient のデフォルト type は 'linear' で、start {0,0} から end {0,1} です。放射グラデーションの場合は、center/innerRadius と outerCenter/outerRadius で type: 'radial' を設定します。FillPattern の 2 番目の引数は繰り返しモードを選択し、パターン内のテクスチャをスケーリング、回転、またはオフセットするための setTransform(matrix) を公開します。

テクスチャを直接描画

const tex = await Assets.load("icon.png");

// テクスチャ全体を (x, y) に描画 (オプションのティント付き)
g.texture(tex, 0xffffff, 20, 20);

// サブリージョン (dx, dy, dw, dh) を描画
g.texture(tex, 0xff0000, 100, 20, 64, 64);

Graphics.texture(texture, tint?, dx?, dy?, dw?, dh?) は、fill() を経由せずに単一のテクスチャ付き矩形を描画する短縮形です。アイコンには、完全なスプライト ライフサイクルが不要な場合に便利です。

GraphicsContext 共有

const ctx = new GraphicsContext().rect(0, 0, 50, 50).fill(0xff0000);

const g1 = new Graphics(ctx);
const g2 = new Graphics(ctx);
g2.x = 100;

コンテキスト共有により重複する GPU ジオメトリが回避されます。高価な三角分割は 1 回実行されます。コンストラクション後にコンテキストを割り当てることもできます: g.context = existingContext。

SVG のインポートとエクスポート

svg() を使用して SVG マークアップをアクティブコンテキストに解析します:

g.svg(`<svg viewBox="0 0 100 100">
    <circle cx="50" cy="50" r="40" fill="red"/>
</svg>`);

svg() はパス、基本的な形状、インラインスタイルをサポートしています。複雑な穴のジオメトリは、Pixi の三角分割がパフォーマンス最適化されているため、不正確にレンダリングされる可能性があります。

Graphics または GraphicsContext を graphicsContextToSvg でスタンドアロンの SVG ドキュメント文字列にシリアル化します:

import { Graphics, graphicsContextToSvg } from "pixi.js";

const g = new Graphics()
  .rect(0, 0, 100, 50)
  .fill({ color: 0xff0000 })
  .circle(150, 25, 25)
  .stroke({ color: 0x0000ff, width: 4 });

const svgString = graphicsContextToSvg(g, 2);

graphicsContextToSvg(source, precision = 2) は純粋関数で、コンテキストの命令を読み取り、自動計算された viewBox を持つ完全な <svg> 文字列を返します。Graphics または GraphicsContext を渡します。precision はエミットされた座標の小数位を制御します。すべての形状-塗りつぶし プリミティブ (高度なものは regularPoly/filletRect など形状パスにフォールバック)、すべてのパス メソッド、ストロク属性 (width、cap、join、miterLimit)、fill-opacity/stroke-opacity、および FillGradient (線形と放射) を <defs> ブロック経由でエクスポートします。穴は fill-rule="evenodd" を持つ 1 つの <path> に折りたたまれます。FillPattern とテクスチャ塗りつぶしは SVG に相当するものがありません。パターンは塗りつぶしの固定 color を通過し、texture() 命令は完全にスキップされます。エクスポートされたマークアップはクリーンアップなしで g.svg(...) 経由でラウンドトリップし、形状を保存して後で別の Graphics に再インポートできます。

GraphicsPath の再利用

const arrow = new GraphicsPath()
  .moveTo(0, 0)
  .lineTo(40, 0)
  .lineTo(40, -10)
  .lineTo(60, 10)
  .lineTo(40, 30)
  .lineTo(40, 20)
  .lineTo(0, 20)
  .closePath();

g.path(arrow).fill(0x3498db);
g.translateTransform(80, 0).path(arrow).fill(0xe74c3c);

Graphics.path(graphicsPath) (および GraphicsContext.path()) は、事前構築された GraphicsPath をアクティブパスに追加します。一度構築して、何度も描画します。

描画時変換

Graphics は、Container に適用されたレンダリング出力の変換とは別に、描画中に使用される独自の変換スタックを持っています。描画メソッドは Container.rotation、Container.scale、Container.position との衝突を避けるために名前が変更されました:

描画変換	Container 変換
g.rotateTransform(angle)	g.rotation
g.scaleTransform(x, y?)	g.scale.set(x, y)
g.translateTransform(x, y?)	g.position.set(x, y)
g.setTransform(matrix) または setTransform(a,b,c,d,tx,ty)	g.setFromMatrix(matrix)
g.transform(matrix) または transform(a,b,c,d,tx,ty)	n/a
g.getTransform() / g.resetTransform()	n/a

const g = new Graphics();

g.translateTransform(100, 100)
  .rotateTransform(Math.PI / 4)
  .rect(-25, -25, 50, 50)
  .fill(0x3498db);

// 正方形は、ジオメトリに追加されるときに 45 度回転されます。
// 後で g.rotation を設定すると、画面上の全体の Graphics が回転されます。

描画変換は、コンテキストに追加されるすべての後続の形状とパスコマンドに影響します。save()/restore() を使用してスコープします。

状態の保存/復元

g.save();
g.translateTransform(100, 100);
g.rotateTransform(Math.PI / 4);
g.rect(0, 0, 50, 50).fill(0xff0000);
g.restore();

save() は描画変換、塗りつぶしスタイル、ストロークスタイルをスタックにプッシュします。restore() はそれらをポップします。Graphics は save/restore を直接公開し、基礎となる GraphicsContext の呼び出しをミラーリングしています。

setFillStyle / setStrokeStyle による デフォルトスタイル

g.setFillStyle({ color: 0x3498db, alpha: 0.8 }).setStrokeStyle({
  width: 2,
  color: 0x2c3e50,
});

g.rect(0, 0, 100, 100).fill().stroke();
g.circle(150, 50, 40).fill().stroke();

setFillStyle() と setStrokeStyle() は、引数が渡されないときに後続の fill() / stroke() 呼び出しで使用されるデフォルトスタイルを構成します。現在のスタイルを fillStyle と strokeStyle ゲッター/セッター経由でいつでも読み取るか置き換えます。スタートアップ時に GraphicsContext.defaultFillStyle と GraphicsContext.defaultStrokeStyle を変異させることで、ライブラリ全体のデフォルトをオーバーライドします。

ヒットテスト

const g = new Graphics().star(100, 100, 5, 60, 30).fill(0xf39c12);
g.eventMode = "static";
g.on("pointermove", (e) => {
  if (g.containsPoint(g.toLocal(e.global))) {
    /* 星の上、単なる bbox ではなく */
  }
});

Graphics.containsPoint(pointInLocalSpace) は、穴を含むコンテキスト内のすべてのトポロジ認識塗りつぶしおよびストロークされた形状に対してテストを実行します。グローバルポインタ座標を最初に toLocal() で変換します。

クローン、クリア、および境界

const g = new Graphics().rect(0, 0, 100, 100).fill(0xff0000);

const shallow = g.clone(); // 同じ GraphicsContext を共有
const deep = g.clone(true); // 独立したコンテキストを作成

console.log(g.bounds.width); // 100 - 変換前のジオメトリ境界

g.clear(); // アクティブパス、命令、変換をワイプします。塗りつぶし/ストロークスタイルは保持されます。

• clone() はソースコンテキストを共有する新しい Graphics を返します (低コスト、ジオメトリが再利用されます)。コンテキストが変更されると、両方のオブジェクトが一緒に更新されます。
• clone(true) はコンテキストもクローンするため、新しい Graphics を独立して編集できます。
• bounds は Container 変換の前のジオメトリ境界を返します。レイアウト決定に役立ちます。
• clear() はコンテキストをリセットするため、同じ Graphics を再利用できます。いつ clear するかについてのガイダンスについては、以下の一般的な間違いを参照してください。

GraphicsContext ユーティリティ

メンバー	動作
ctx.path(graphicsPath)	事前構築された GraphicsPath をアクティブパスに適用します。多くのコンテキストまたはフレーム間で 1 つのパスを再利用します。
ctx.beginPath()	現在のアクティブパスを破棄し、確定済み命令に影響を与えずに新しいパスを開始します。
ctx.setFillStyle(style) / ctx.fillStyle	fill() を呼び出さずに後続の形状で使用されるデフォルト塗りつぶしスタイルを設定または読み取ります。
ctx.setStrokeStyle(style) / ctx.strokeStyle	stroke() を呼び出さずに後続の形状で使用されるデフォルトストロークスタイルを設定または読み取ります。
ctx.bounds	すべてのフィル/ストロク/テクスチャ命令間でキャッシュされたジオメトリ境界。
ctx.clear()	命令、アクティブパス、描画変換をワイプします。
ctx.clone()	命令、アクティブパス、変換、スタイル、スタックを含む深いコピー。
ctx.containsPoint(point)	すべての塗りつぶしおよびストロークされた形状 (穴を含む) に対するトポロジ認識ヒットテスト。
ctx.batchMode	'auto'、'batch'、'no-batch' のいずれか — このコンテキスト内の形状のバッチングを強制またはさせます。
ctx.customShader	デフォルトのグラフィックスシェーダーをオーバーライドするために Shader を割り当てます。
GraphicsContext.defaultFillStyle	fill() が引数なしで呼び出され、塗りつぶしスタイルが設定されていない場合に使用される静的フォールバック。
GraphicsContext.defaultStrokeStyle	stroke() が引数なしで呼び出され、ストロークスタイルが設定されていない場合に使用される静的フォールバック。

GraphicsContext は update、destroy、unload イベントを発行する EventEmitter です。ツール化またはプールがコンテキスト ライフサイクルの変更に反応する必要がある場合、ctx.on('update' | 'destroy' | 'unload', cb) を使用してサブスクライブします。

一般的な間違い

[重大] v7 の beginFill/drawRect/endFill を使用

誤り:

const g = new Graphics().beginFill(0xff0000).drawRect(0, 0, 100, 100).endFill();

正解:

const g = new Graphics().rect(0, 0, 100, 100).fill(0xff0000);

v8 では「スタイル設定、描画、終了」を「形状を描画してからスタイルを適用」に置き換えました。beginFill/endFill は存在しません。

[重大] 古い形状メソッド名を使用

誤り:

g.drawCircle(50, 50, 25);

正解:

g.circle(50, 50, 25);

すべての draw* メソッドは v8 で名前が変更されました: drawRect → rect、drawCircle → circle、drawEllipse → ellipse、drawPolygon → poly、drawRoundedRect → roundRect、drawStar → star。

[重大] lineStyle の代わりに stroke を使用

誤り:

g.lineStyle(2, 0xffffff);
g.drawRect(0, 0, 100, 100);

正解:

g.rect(0, 0, 100, 100).stroke({ width: 2, color: 0xffffff });

lineStyle は削除されました。形状を描画した後に stroke() を使用してください。ストロークオプションオブジェクトは width、color、alpha、cap、join、alignment、miterLimit、pixelLine を受け入れます。

[高] 穴に beginHole/endHole を使用

誤り:

g.beginFill(0x00ff00)
  .drawRect(0, 0, 100, 100)
  .beginHole()
  .drawCircle(50, 50, 20)
  .endHole()
  .endFill();

正解:

g.rect(0, 0, 100, 100).fill(0x00ff00).circle(50, 50, 20).cut();

beginHole/endHole は cut() で置き換わりました。外側の形状を描画してそれを塗りつぶし、穴の形状を描画して cut() を呼び出します。

[高] GraphicsGeometry の代わりに GraphicsContext を使用

誤り:

const geom = g.geometry;
const clone = new Graphics(geom);

正解:

const ctx = new GraphicsContext().rect(0, 0, 100, 100).fill(0xff0000);
const g1 = new Graphics(ctx);
const g2 = new Graphics(ctx);

GraphicsGeometry は v8 で GraphicsContext に置き換わりました。.geometry プロパティはありません。

[高] 共有 GraphicsContext を予期せず破棄

const ctx = new GraphicsContext().rect(0, 0, 50, 50).fill(0xff0000);
const g1 = new Graphics(ctx);
const g2 = new Graphics(ctx);

g1.destroy({ context: true }); // g2 のコンテキスト参照も無効にする

共有 GraphicsContext を破棄してもインスタンス共有は破棄されませんが、コンテキスト参照を無効にして破壊します。コンストラクタ経由でコンテキストを渡すとき、destroy() を引数なしで呼び出すとコンテキストが保持されます。明示的にするには destroy({ context: false }) を使用します。すべての共有インスタンスがコンテキストの使用を終了したときのみコンテキストを破棄します。自己所有コンテキスト (コンストラクタ経由で渡されない) は、destroy() を引数なしで呼び出すときに破棄されます。

[高] Graphics をフレームごとにクリアして再描画

Graphics は動的ではなく安定するように設計されています。フレームごとに clear() と再描画を呼び出すと、毎回 GPU ジオメトリが再構築されます。動的なビジュアルの場合:

• 事前レンダリングされたテクスチャと変換の変更を備えた Sprite を使用します。
• 複雑な静的グラフィックスの場合は、cacheAsTexture(true) を使用します。
• リアルタイム形状の変更の場合、カスタムジオメトリ更新を備えた Mesh を検討します。

これは HTML Canvas 2D の逆です。そこではフレームごとに再描画が通常です。PixiJS は形状を GPU 三角形に三角分割するため、初期描画は高価ですが、その後のレンダリングは高速です。Graphics を canvas 描画呼び出しではなく SVG 要素のようなものとして扱います。

[中程度] Graphics 内に子要素をネストしない

Graphics は allowChildren = false を設定します。子を追加するとメモリ不足警告がログに記録され、将来のバージョンでハード エラーになります。複数のグラフィックスと他の終端を単純な Container でラップします:

const group = new Container();
group.addChild(graphics, sprite);

API リファレンス

• Graphics
• GraphicsOptions
• GraphicsContext
• GraphicsPath
• graphicsContextToSvg
• FillGradient
• FillPattern
• FillStyle
• FillInput