# Color

Class · category: Math

Source: https://github.com/playcanvas/engine/blob/970d89f6d3bc6667f4e1f88153abd6e7e82ed52c/src/core/math/color.js#L30

An RGBA color.

Each color component is a floating point value in the range 0 to 1. The [r](https://api.playcanvas.com/engine/classes/Color.md#r) (red),
[g](https://api.playcanvas.com/engine/classes/Color.md#g) (green) and [b](https://api.playcanvas.com/engine/classes/Color.md#b) (blue) components define a color in RGB color space. The
[a](https://api.playcanvas.com/engine/classes/Color.md#a) (alpha) component defines transparency. An alpha of 1 is fully opaque. An alpha of 0 is
fully transparent.

A Color stores the values it is given and does not track whether they are in linear or gamma
(sRGB) space. Convert explicitly with [linear](https://api.playcanvas.com/engine/classes/Color.md#linear) and [gamma](https://api.playcanvas.com/engine/classes/Color.md#gamma) when a value crosses that
boundary. [fromString](https://api.playcanvas.com/engine/classes/Color.md#fromstring) and [toString](https://api.playcanvas.com/engine/classes/Color.md#tostring) exchange colors with the `#RRGGBB` and
`#RRGGBBAA` notation used by CSS, and [lerp](https://api.playcanvas.com/engine/classes/Color.md#lerp) blends two colors.

Methods modify the color they are called on and return it for chaining. Use [clone](https://api.playcanvas.com/engine/classes/Color.md#clone) for an
independent copy and [copy](https://api.playcanvas.com/engine/classes/Color.md#copy) to overwrite. The named constants such as [WHITE](https://api.playcanvas.com/engine/classes/Color.md#white) and
[RED](https://api.playcanvas.com/engine/classes/Color.md#red) are frozen shared instances, so copy one before modifying it.

**Example**

```ts
// Set a material color from a CSS hex string
material.diffuse.fromString('#ff8800');
material.update();
```

**Example**

```ts
// Fade between two colors without allocating
const tint = new Color();
tint.lerp(Color.RED, Color.BLUE, t);
```

## Constructors

### constructor

```ts
new Color(r?: number, g?: number, b?: number, a?: number)
```

Creates a new Color instance.

**Parameters**

- `r` (`number`, optional): The r value. Defaults to 0.
- `g` (`number`, optional): The g value. Defaults to 0.
- `b` (`number`, optional): The b value. Defaults to 0.
- `a` (`number`, optional): The a value. Defaults to 1.

**Example**

```ts
const c1 = new Color(); // defaults to 0, 0, 0, 1
const c2 = new Color(0.1, 0.2, 0.3, 0.4);
```

```ts
new Color(arr: number[])
```

Creates a new Color instance.

**Parameters**

- `arr` (`number[]`): The array to set the color values from.

**Example**

```ts
const c = new Color([0.1, 0.2, 0.3, 0.4]);
```

## Properties

### a

```ts
a: number
```

The alpha component of the color.

### b

```ts
b: number
```

The blue component of the color.

### g

```ts
g: number
```

The green component of the color.

### r

```ts
r: number
```

The red component of the color.

### BLACK

```ts
static readonly BLACK: Color
```

A constant color set to black [0, 0, 0, 1].

### BLUE

```ts
static readonly BLUE: Color
```

A constant color set to blue [0, 0, 1, 1].

### CYAN

```ts
static readonly CYAN: Color
```

A constant color set to cyan [0, 1, 1, 1].

### GRAY

```ts
static readonly GRAY: Color
```

A constant color set to gray [0.5, 0.5, 0.5, 1].

### GREEN

```ts
static readonly GREEN: Color
```

A constant color set to green [0, 1, 0, 1].

### MAGENTA

```ts
static readonly MAGENTA: Color
```

A constant color set to magenta [1, 0, 1, 1].

### RED

```ts
static readonly RED: Color
```

A constant color set to red [1, 0, 0, 1].

### WHITE

```ts
static readonly WHITE: Color
```

A constant color set to white [1, 1, 1, 1].

### YELLOW

```ts
static readonly YELLOW: Color
```

A constant color set to yellow [1, 1, 0, 1].

## Methods

### clone

```ts
clone(): Color
```

Returns a clone of the specified color.

**Returns** [`Color`](https://api.playcanvas.com/engine/classes/Color.md): A duplicate color object.

**Example**

```ts
const c = new Color(1, 0, 0, 1);
const cClone = c.clone();
// cClone is [1, 0, 0, 1]
```

### copy

```ts
copy(rhs: Color): Color
```

Copies the contents of a source color to a destination color.

**Parameters**

- `rhs` ([`Color`](https://api.playcanvas.com/engine/classes/Color.md)): A color to copy to the specified color.

**Returns** [`Color`](https://api.playcanvas.com/engine/classes/Color.md): Self for chaining.

**Example**

```ts
const src = new Color(1, 0, 0, 1);
const dst = new Color();

dst.copy(src);

console.log("The two colors are " + (dst.equals(src) ? "equal" : "different"));
```

### equals

```ts
equals(rhs: Color): boolean
```

Reports whether two colors are equal.

**Parameters**

- `rhs` ([`Color`](https://api.playcanvas.com/engine/classes/Color.md)): The color to compare to the specified color.

**Returns** `boolean`: True if the colors are equal and false otherwise.

**Example**

```ts
const a = new Color(1, 0, 0, 1);
const b = new Color(1, 1, 0, 1);
console.log("The two colors are " + (a.equals(b) ? "equal" : "different"));
```

### fromArray

```ts
fromArray(arr: number[], offset?: number): Color
```

Set the values of the color from an array.

**Parameters**

- `arr` (`number[]`): The array to set the color values from.
- `offset` (`number`, optional, default `0`): The zero-based index at which to start copying elements from the
  array. Default is 0.

**Returns** [`Color`](https://api.playcanvas.com/engine/classes/Color.md): Self for chaining.

**Example**

```ts
const c = new Color();
c.fromArray([1, 0, 1, 1]);
// c is set to [1, 0, 1, 1]
```

### fromString

```ts
fromString(hex: string): Color
```

Set the values of the color from a string representation '#11223344' or '#112233'.

**Parameters**

- `hex` (`string`): A string representation in the format '#RRGGBBAA' or '#RRGGBB'. Where
  RR, GG, BB, AA are red, green, blue and alpha values. This is the same format used in
  HTML/CSS.

**Returns** [`Color`](https://api.playcanvas.com/engine/classes/Color.md): Self for chaining.

**Example**

```ts
const c = new Color();
c.fromString('#ff0000');
// c is now [1, 0, 0, 1]
```

### gamma

```ts
gamma(src?: Color): Color
```

Converts the color from linear to gamma color space.

**Parameters**

- `src` ([`Color`](https://api.playcanvas.com/engine/classes/Color.md), optional): The color to convert to gamma color space. If not set, the operation is
  done in place.

**Returns** [`Color`](https://api.playcanvas.com/engine/classes/Color.md): Self for chaining.

**Example**

```ts
const c = new Color(0.218, 0.218, 0.218, 1);
c.gamma();
// c is now approximately [0.5, 0.5, 0.5, 1]
```

### lerp

```ts
lerp(lhs: Color, rhs: Color, alpha: number): Color
```

Returns the result of a linear interpolation between two specified colors.

**Parameters**

- `lhs` ([`Color`](https://api.playcanvas.com/engine/classes/Color.md)): The color to interpolate from.
- `rhs` ([`Color`](https://api.playcanvas.com/engine/classes/Color.md)): The color to interpolate to.
- `alpha` (`number`): The value controlling the point of interpolation. Between 0 and 1,
  the linear interpolant will occur on a straight line between lhs and rhs. Outside of this
  range, the linear interpolant will occur on a ray extrapolated from this line.

**Returns** [`Color`](https://api.playcanvas.com/engine/classes/Color.md): Self for chaining.

**Example**

```ts
const a = new Color(0, 0, 0);
const b = new Color(1, 1, 0.5);
const r = new Color();

r.lerp(a, b, 0);   // r is equal to a
r.lerp(a, b, 0.5); // r is 0.5, 0.5, 0.25
r.lerp(a, b, 1);   // r is equal to b
```

### linear

```ts
linear(src?: Color): Color
```

Converts the color from gamma to linear color space.

**Parameters**

- `src` ([`Color`](https://api.playcanvas.com/engine/classes/Color.md), optional): The color to convert to linear color space. If not set, the operation
  is done in place.

**Returns** [`Color`](https://api.playcanvas.com/engine/classes/Color.md): Self for chaining.

**Example**

```ts
const c = new Color(0.5, 0.5, 0.5, 1);
c.linear();
// c is now approximately [0.218, 0.218, 0.218, 1]
```

### mulScalar

```ts
mulScalar(scalar: number): Color
```

Multiplies RGB elements of a Color by a number. Note that the alpha value is left unchanged.

**Parameters**

- `scalar` (`number`): The number to multiply by.

**Returns** [`Color`](https://api.playcanvas.com/engine/classes/Color.md): Self for chaining.

**Example**

```ts
const c = new Color(0.2, 0.4, 0.6, 1);
c.mulScalar(2);
// c is now [0.4, 0.8, 1.2, 1]
```

### set

```ts
set(r: number, g: number, b: number, a?: number): Color
```

Assign values to the color components, including alpha.

**Parameters**

- `r` (`number`): The value for red (0-1).
- `g` (`number`): The value for green (0-1).
- `b` (`number`): The value for blue (0-1).
- `a` (`number`, optional, default `1`): The value for the alpha (0-1), defaults to 1.

**Returns** [`Color`](https://api.playcanvas.com/engine/classes/Color.md): Self for chaining.

**Example**

```ts
const c = new Color();
c.set(1, 0, 0, 1);
// c is now red [1, 0, 0, 1]
```

### toArray

```ts
toArray(arr?: number[], offset?: number): number[]
```

**Parameters**

- `arr` (`number[]`, optional): The array to populate with the color's number
  components. If not specified, a new array is created.
- `offset` (`number`, optional): The zero-based index at which to start copying elements to the
  array. Default is 0.

**Returns** `number[]`: The color as an array.

```ts
toArray(arr: ArrayBufferView, offset?: number): ArrayBufferView
```

**Parameters**

- `arr` (`ArrayBufferView`): The array to populate with the color's number
  components. If not specified, a new array is created.
- `offset` (`number`, optional): The zero-based index at which to start copying elements to the
  array. Default is 0.

**Returns** `ArrayBufferView`: The color as an array.

### toString

```ts
toString(alpha: boolean, asArray?: boolean): string
```

Converts the color to string form. The format is '#RRGGBBAA', where RR, GG, BB, AA are the
red, green, blue and alpha values. When the alpha value is not included (the default), this
is the same format as used in HTML/CSS.

**Parameters**

- `alpha` (`boolean`): If true, the output string will include the alpha value.
- `asArray` (`boolean`, optional): If true, the output will be an array of numbers. Defaults to false.

**Returns** `string`: The color in string form.

**Example**

```ts
const c = new Color(1, 1, 1);
// Outputs #ffffff
console.log(c.toString());
```