pixijs-color

Color クラスは、PixiJS で色合い、塗りつぶし、ストローク、そして ColorSource を受け入れるあらゆる場所で、色を作成し変換します。ほとんどの API は hex や文字列を直接受け入れるため、形式の変換や値の操作が必要な場合のみ new Color(...) が必要です。

クイックスタート

const fillColor = new Color("#ff6600");
console.log(fillColor.toHex()); // '#ff6600'
console.log(fillColor.toNumber()); // 0xff6600
console.log(fillColor.toArray()); // [1, 0.4, 0, 1]

const g = new Graphics().rect(0, 0, 200, 100).fill(fillColor);
app.stage.addChild(g);

const sprite = Sprite.from("hero.png");
sprite.tint = "dodgerblue";
app.stage.addChild(sprite);

const t = Color.shared.setValue(0xffffff).multiply([1, 0.5, 0.5]).toNumber();
sprite.tint = t;

関連スキル: pixijs-scene-graphics (塗りつぶし / ストロークの色)、pixijs-scene-sprite (色合い)、pixijs-blend-modes (合成)。

コアパターン

受け入れられる入力形式

import { Color } from "pixi.js";

// Hex 整数
new Color(0xff0000);

// Hex 文字列
new Color("#ff0000");
new Color("#f00");
new Color("ff0000");

// CSS カラー名
new Color("red");
new Color("dodgerblue");

// RGB/RGBA オブジェクト（成分 0-255）
new Color({ r: 255, g: 0, b: 0 });
new Color({ r: 255, g: 0, b: 0, a: 0.5 });

// HSL/HSLA オブジェクト
new Color({ h: 0, s: 100, l: 50 });
new Color({ h: 0, s: 100, l: 50, a: 0.5 });

// HSV/HSVA オブジェクト
new Color({ h: 0, s: 100, v: 100 });

// CSS 文字列
new Color("rgb(255, 0, 0)");
new Color("rgba(255, 0, 0, 0.5)");
new Color("hsl(0, 100%, 50%)");

// 正規化された 0-1 配列（Float32Array または通常の配列）
new Color([1, 0, 0]); // RGB
new Color([1, 0, 0, 0.5]); // RGBA

// Uint8 配列（成分 0-255）
new Color(new Uint8Array([255, 0, 0]));
new Color(new Uint8ClampedArray([255, 0, 0, 128]));

// 8 桁 hex（アルファ付き）
new Color("#ff0000ff");
new Color("#f00f");

// 別の Color インスタンスからコピー
const red = new Color("red");
const copy = new Color(red);

変換メソッド

import { Color } from "pixi.js";

const color = new Color("#ff6600");

color.toHex(); // '#ff6600'
color.toHexa(); // '#ff6600ff'（アルファ付き hex）
color.toNumber(); // 0xff6600
color.toArray(); // [1, 0.4, 0, 1]（正規化 RGBA）
color.toRgbArray(); // [1, 0.4, 0]（正規化 RGB、アルファなし）
color.toRgbaString(); // 'rgba(255,102,0,1)'
color.toRgba(); // { r: 1, g: 0.4, b: 0, a: 1 }
color.toRgb(); // { r: 1, g: 0.4, b: 0 }
color.toUint8RgbArray(); // [255, 102, 0]

// setValue() はチェーン可能な方法で色の値を変更する
color.setValue(0xff0000).toHex(); // '#ff0000'

コンポーネントアクセス

import { Color } from "pixi.js";

const color = new Color("rgba(255, 128, 0, 0.8)");

color.red; // 1
color.green; // ~0.502
color.blue; // 0
color.alpha; // 0.8

すべてのコンポーネントゲッターは 0-1 の正規化値を返します。

操作

import { Color } from "pixi.js";

const color = new Color("red");

// アルファをセット（チェーン可能）
color.setAlpha(0.5);

// 別の色と乗算（破壊的、インプレースで変更）
color.multiply(0x808080);

// アルファを事前乗算（破壊的、RGB チャネルがアルファで乗算）
color.premultiply(0.8);

// アルファのみを事前乗算（RGB は変更なし）
color.premultiply(0.8, false);

// 操作をチェーン
new Color("white").setAlpha(0.5).multiply([0.8, 0.2, 0.2]);

multiply() と premultiply() は破壊的です。色を変更して value を null に設定します（元の形式は失われます）。

非破壊的な事前乗算出力

import { Color } from "pixi.js";

const color = new Color("red").setAlpha(0.5);

const packed = color.toPremultiplied(color.alpha); // 0x7F7F0000
const alphaOnly = color.toPremultiplied(color.alpha, false); // 0x7FFF0000

toPremultiplied(alpha, applyToRGB?) は this を変更せずに 32 ビット 0xAARRGGBB 整数を返します。バッチャーと色合い計算で、ソース色を再利用する必要がある場合に使用します。applyToRGB が false の場合、アルファバイトのみパックされ、RGB は完全な値のままです。

出力バッファの再利用

import { Color } from "pixi.js";

const rgba = new Float32Array(4);
const rgb = new Float32Array(3);
const rgb8 = new Uint8Array(3);

app.ticker.add(() => {
  Color.shared.setValue(sprite.tint).toArray(rgba).toRgbArray(rgb);

  Color.shared.toUint8RgbArray(rgb8);
});

toArray(out?)、toRgbArray(out?)、toUint8RgbArray(out?) は再利用可能な number[]、Float32Array、Uint8Array、または Uint8ClampedArray を受け入れて、その中に書き込みます。ホットパスで独自のバッファを渡してフレームごとの割り当てを避けます。引数を省略すると、Color インスタンスは内部キャッシュ配列を返します。

GPU バッファへのパッキング

メソッド	戻り値
toBgrNumber()	24 ビット 0xBBGGRR 整数（R/B スワップ）
toLittleEndianNumber()	同じ 24 ビットスワップ、リトルエンディアン頂点書き込みに便利

どちらも低コストで、パックされた頂点属性に色を直接出力する場合に便利です。

一時的な操作のための Color.shared

import { Color } from "pixi.js";

// 新しい Color を割り当てずに 1 回限りの変換
const hex = Color.shared.setValue("#ff6600").toNumber();
const arr = Color.shared.setValue(0xff0000).toArray();

Color.shared はシングルトンで、毎回新しい Color を割り当てることを避けます。これはレンダリングループやフレームごとの色合い計算などのホットパスで重要です。ここで繰り返し new Color() を実行すると GC 圧力が生まれます。このインスタンスへの参照を保存しないでください。他のコードがそれを変更する可能性があります。

import { Color } from "pixi.js";

// 良い例：フレームごとのコールバック内で shared インスタンスを再利用
app.ticker.add(() => {
  const t = performance.now() / 1000;
  sprite.tint = Color.shared
    .setValue("white")
    .multiply([Math.sin(t) * 0.5 + 0.5, 0.2, 0.8])
    .toNumber();
});

入力の検証

import { Color } from "pixi.js";

Color.isColorLike("red"); // true
Color.isColorLike("#ff0000"); // true
Color.isColorLike(0xff0000); // true
Color.isColorLike([1, 0, 0]); // true
Color.isColorLike({ r: 1, g: 0, b: 0 }); // true
Color.isColorLike({ foo: 1 }); // false
Color.isColorLike(null); // false

Color.isColorLike() は構造的な形状（文字列、数値、配列、または認識されたオブジェクト）をチェックします。文字列が実際の CSS カラー名であるか、配列値が範囲内にあるかは検証しません。ユーザー入力を new Color() または setValue() に渡す前に、型ガードとして使用します。

よくある間違い

[MEDIUM] toRgba() が 0-255 値を返すと期待する

間違い：

import { Color } from "pixi.js";

const { r, g, b } = new Color({ r: 255, g: 128, b: 0 }).toRgba();
// r = 1, g = ~0.502, b = 0（255, 128, 0 ではない）

正解：

import { Color } from "pixi.js";

// 0-255 出力には toUint8RgbArray() を使用
const [r, g, b] = new Color({ r: 255, g: 128, b: 0 }).toUint8RgbArray();
// r = 255, g = 128, b = 0

RGB オブジェクト 入力 は 0-255 範囲を使用します（{ r: 255, g: 0, b: 0 }）が、すべての出力メソッド（toRgba()、toRgb()、toArray()、toRgbArray()）は 0-1 に正規化します。CSS または外部 API に 0-255 整数が必要な場合は toUint8RgbArray() を使用します。

[MEDIUM] 色配列で 0-255 範囲を使用する

間違い：

import { Color } from "pixi.js";

new Color([255, 0, 0]); // 赤ではない。値は 0-1 として解釈される

正解：

import { Color } from "pixi.js";

new Color([1, 0, 0]); // 正規化配列経由で赤
new Color(0xff0000); // hex 経由で赤
new Color("red"); // CSS 名経由で赤
new Color(new Uint8Array([255, 0, 0])); // Uint8Array 経由で赤（0-255）

通常の数値配列（number[] と Float32Array）は正規化 0-1 範囲を使用します。[255, 0, 0] は値がクランプされるため [1, 0, 0] にクランプされますが、[200, 100, 50] は期待される色を生成しません。0-255 入力には Uint8Array または Uint8ClampedArray を使用します。

[MEDIUM] utils.string2hex または utils.hex2string を使用する

間違い：

import { utils } from "pixi.js";

const hex = utils.string2hex("#ff0000");

正解：

import { Color } from "pixi.js";

const hex = new Color("#ff0000").toNumber();
const str = new Color(0xff0000).toHex();

utils 名前空間は v8 で削除されました。すべての色変換には Color クラスを使用します。

API リファレンス

• Color
• ColorSource