pixijs-color

Color クラスは、色合い、塗りつぶし、ストローク、および PixiJS が ColorSource を受け付けるすべての箇所で使用する色を作成・変換します。ほとんどの API は生の 16 進数値や文字列を直接受け付けるため、形式の変換や値の操作を行う場合にのみ、明示的な 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 integer
new Color(0xff0000);

// Hex strings
new Color("#ff0000");
new Color("#f00");
new Color("ff0000");

// CSS color names
new Color("red");
new Color("dodgerblue");

// RGB/RGBA objects (components 0-255)
new Color({ r: 255, g: 0, b: 0 });
new Color({ r: 255, g: 0, b: 0, a: 0.5 });

// HSL/HSLA objects
new Color({ h: 0, s: 100, l: 50 });
new Color({ h: 0, s: 100, l: 50, a: 0.5 });

// HSV/HSVA objects
new Color({ h: 0, s: 100, v: 100 });

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

// Normalized 0-1 arrays (Float32Array or plain arrays)
new Color([1, 0, 0]); // RGB
new Color([1, 0, 0, 0.5]); // RGBA

// Uint8 arrays (components 0-255)
new Color(new Uint8Array([255, 0, 0]));
new Color(new Uint8ClampedArray([255, 0, 0, 128]));

// 8-digit hex with alpha
new Color("#ff0000ff");
new Color("#f00f");

// Copy from another Color instance
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 with alpha)
color.toNumber(); // 0xff6600
color.toArray(); // [1, 0.4, 0, 1] (normalized RGBA)
color.toRgbArray(); // [1, 0.4, 0] (normalized RGB, no alpha)
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() is the chainable way to change a color's value
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");

// Set alpha (chainable)
color.setAlpha(0.5);

// Multiply with another color (destructive, modifies in place)
color.multiply(0x808080);

// Premultiply alpha (destructive, RGB channels multiplied by alpha)
color.premultiply(0.8);

// Premultiply alpha only (RGB unchanged)
color.premultiply(0.8, false);

// Chain operations
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()	R/B を入れ替えた 24 ビットの 0xBBGGRR 整数
toLittleEndianNumber()	同じ 24 ビットの入れ替え形式。リトルエンディアンの頂点書き込みに便利です

どちらも処理コストが低く、色をパック済みの頂点属性に直接出力する際に便利です。

一時的な操作に使う Color.shared

import { Color } from "pixi.js";

// One-off conversion without allocating a new Color
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";

// Good: reuse shared instance in a per-frame callback
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 (NOT 255, 128, 0)

正しい例：

import { Color } from "pixi.js";

// Use toUint8RgbArray() for 0-255 output
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]); // NOT red; values are interpreted as 0-1

正しい例：

import { Color } from "pixi.js";

new Color([1, 0, 0]); // red via normalized array
new Color(0xff0000); // red via hex
new Color("red"); // red via CSS name
new Color(new Uint8Array([255, 0, 0])); // red via 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