pixijs-color

La classe Color crée et convertit les couleurs pour les teintes, remplissages, contours et partout où PixiJS accepte une ColorSource. La plupart des APIs acceptent directement les chaînes/hex brutes, donc new Color(...) explicite n'est nécessaire que pour convertir les formats ou manipuler les valeurs.

Quick Start

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;

Skills connexes : pixijs-scene-graphics (couleurs de remplissage/contour), pixijs-scene-sprite (teinte), pixijs-blend-modes (composition).

Core Patterns

Formats d'entrée acceptés

import { Color } from "pixi.js";

// Entier hexadécimal
new Color(0xff0000);

// Chaînes hexadécimales
new Color("#ff0000");
new Color("#f00");
new Color("ff0000");

// Noms de couleurs CSS
new Color("red");
new Color("dodgerblue");

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

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

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

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

// Tableaux normalisés 0-1 (Float32Array ou tableaux simples)
new Color([1, 0, 0]); // RGB
new Color([1, 0, 0, 0.5]); // RGBA

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

// Hex 8 chiffres avec alpha
new Color("#ff0000ff");
new Color("#f00f");

// Copier depuis une autre instance Color
const red = new Color("red");
const copy = new Color(red);

Méthodes de conversion

import { Color } from "pixi.js";

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

color.toHex(); // '#ff6600'
color.toHexa(); // '#ff6600ff' (hex avec alpha)
color.toNumber(); // 0xff6600
color.toArray(); // [1, 0.4, 0, 1] (RGBA normalisé)
color.toRgbArray(); // [1, 0.4, 0] (RGB normalisé, sans 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() est la façon chaînable de changer la valeur d'une couleur
color.setValue(0xff0000).toHex(); // '#ff0000'

Accès aux composants

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

Tous les getters de composants retournent des valeurs normalisées 0-1.

Manipulation

import { Color } from "pixi.js";

const color = new Color("red");

// Définir alpha (chaînable)
color.setAlpha(0.5);

// Multiplier par une autre couleur (destructive, modifie sur place)
color.multiply(0x808080);

// Prémultiplier alpha (destructive, canaux RGB multipliés par alpha)
color.premultiply(0.8);

// Prémultiplier alpha uniquement (RGB inchangé)
color.premultiply(0.8, false);

// Chaîner les opérations
new Color("white").setAlpha(0.5).multiply([0.8, 0.2, 0.2]);

multiply() et premultiply() sont destructives ; elles modifient la couleur et définissent value à null (le format original est perdu).

Sortie prémultipliée non-destructive

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?) retourne un entier 32-bit 0xAARRGGBB sans muter this. Utilisez-le dans les batchers et les calculs de teinte où la couleur source doit être réutilisée. Quand applyToRGB est false, seul le byte alpha est emballé ; le RGB reste à sa valeur complète.

Réutiliser les buffers de sortie

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?) et toUint8RgbArray(out?) acceptent un number[], Float32Array, Uint8Array ou Uint8ClampedArray réutilisable et écrivent dedans. Passez votre propre buffer dans les hot paths pour éviter d'allouer par frame ; omettez l'argument et l'instance Color retourne son tableau cache interne.

Emballage pour les buffers GPU

Les deux sont peu coûteux et utiles lors de l'émission de couleurs directement dans les attributs vertex emballés.

Color.shared pour les opérations temporaires

import { Color } from "pixi.js";

// Conversion ponctuelle sans allouer un nouveau Color
const hex = Color.shared.setValue("#ff6600").toNumber();
const arr = Color.shared.setValue(0xff0000).toArray();

Color.shared est un singleton qui évite d'allouer un nouveau Color à chaque appel. C'est important dans les hot paths comme les boucles de rendu ou les calculs de teinte par frame où new Color() répété crée une pression GC. Ne stockez pas de références à celui-ci ; d'autres codes pourraient le muter.

import { Color } from "pixi.js";

// Bon : réutiliser l'instance partagée dans un callback par frame
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();
});

Valider l'entrée

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() vérifie la forme structurelle (chaîne, nombre, tableau ou objet reconnu). Elle ne valide pas qu'une chaîne est un vrai nom de couleur CSS, ni que les valeurs du tableau sont dans la plage. Utilisez-la comme type guard avant de passer l'entrée utilisateur à new Color() ou setValue().

Common Mistakes

[MEDIUM] S'attendre à ce que toRgba() retourne des valeurs 0-255

Incorrect :

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 (PAS 255, 128, 0)

Correct :

import { Color } from "pixi.js";

// Utiliser toUint8RgbArray() pour une sortie 0-255
const [r, g, b] = new Color({ r: 255, g: 128, b: 0 }).toUint8RgbArray();
// r = 255, g = 128, b = 0

Les entrées d'objets RGB utilisent la plage 0-255 ({ r: 255, g: 0, b: 0 }), mais toutes les méthodes de sortie (toRgba(), toRgb(), toArray(), toRgbArray()) se normalisent à 0-1. Utilisez toUint8RgbArray() quand vous avez besoin d'entiers 0-255 pour CSS ou des APIs externes.

[MEDIUM] Utiliser la plage 0-255 dans les tableaux de couleurs

Incorrect :

import { Color } from "pixi.js";

new Color([255, 0, 0]); // PAS rouge ; les valeurs sont interprétées comme 0-1

Correct :

import { Color } from "pixi.js";

new Color([1, 0, 0]); // rouge via tableau normalisé
new Color(0xff0000); // rouge via hex
new Color("red"); // rouge via nom CSS
new Color(new Uint8Array([255, 0, 0])); // rouge via Uint8Array (0-255)

Les tableaux de nombres simples (number[] et Float32Array) utilisent la plage normalisée 0-1. [255, 0, 0] est limité à [1, 0, 0] parce que les valeurs sont limitées, mais [200, 100, 50] ne produit pas la couleur attendue. Utilisez Uint8Array ou Uint8ClampedArray pour l'entrée 0-255.

[MEDIUM] Utiliser utils.string2hex ou utils.hex2string

Incorrect :

import { utils } from "pixi.js";

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

Correct :

import { Color } from "pixi.js";

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

L'espace de noms utils a été supprimé en v8. Utilisez la classe Color pour toutes les conversions de couleurs.

API Reference

• Color
• ColorSource