ColorRamp

The ColorRamp class represents a series of color transitions. It is intended for use in a {@see Phaser.GameObjects.Gradient}.

You should make sure that your bands are arranged end-to-end, with no gaps. The Gradient shader assumes this is so. You may leave gaps at the start and end. Overlaps and gaps may not act as expected.

By default, ColorRamp stores its data for use on the GPU in a data texture. This is updated automatically on creation and when you run setBands(), but if you edit the bands manually, you should run encode() to rebuild the texture. We don't update it automatically because we don't want to waste cycles on rebuilds that you're about to overwrite.

Constructor

new ColorRamp(scene, bands, [gpuEncode])

Parameters

name	type	optional	default	description
scene	Phaser.Scene	No		The current scene.
bands	Phaser.Types.Display.ColorBandConfig | Phaser.Display.ColorBand	Array.<(Phaser.Types.Display.ColorBandConfig	Phaser.Display.ColorBand)>	No
gpuEncode	boolean	Yes	true	Whether to create a data texture to use this ramp in shaders.

---

Scope: static

Source: src/display/ColorRamp.js#L15
Since: 4.0.0

Public Members

bands

bands: Array.<Phaser.Display.ColorBand>

Description:

The color bands that make up this ramp.

Source: src/display/ColorRamp.js#L56
Since: 4.0.0

---

bandTreeDepth

bandTreeDepth: number

Description:

The number of levels in the band tree. This is used internally to decode the data texture.

Source: src/display/ColorRamp.js#L112
Since: 4.0.0

---

dataTexture

dataTexture: Phaser.Textures.Texture

Description:

The Phaser Texture wrapping the GPU data texture for this ramp. This is registered with the Scene's Texture Manager under a unique key so it can be referenced elsewhere. It is not intended for display.

Source: src/display/ColorRamp.js#L76
Since: 4.0.0

---

dataTextureFirstBand

dataTextureFirstBand: number

Description:

The texel index which contains the first band data in glTexture if it has been encoded. This is used internally.

Source: src/display/ColorRamp.js#L100
Since: 4.0.0

---

dataTextureResolution

dataTextureResolution: Array.<number>

Description:

The resolution of the data texture, if it has been encoded. This is used internally.

Source: src/display/ColorRamp.js#L123
Since: 4.0.0

---

glTexture

glTexture: Phaser.Renderer.WebGL.Wrappers.WebGLTextureWrapper

Description:

The texture containing the ramp encoded for the GPU. This is used internally by effects such as the Gradient game object to read complex ramp data.

Source: src/display/ColorRamp.js#L88
Since: 4.0.0

---

gpuEncode

gpuEncode: boolean

Description:

Whether to encode the ramp for shaders to use on the GPU. An encoded ramp is stored as a texture.

Source: src/display/ColorRamp.js#L65
Since: 4.0.0

---

scene

scene: Phaser.Scene

Description:

The scene where the ColorRamp was created.

Source: src/display/ColorRamp.js#L46
Since: 4.0.0

---

Public Methods

destroy

<instance> destroy()

Description:

Destroy this ColorRamp. If it has a data texture, destroy it.

Source: src/display/ColorRamp.js#L497
Since: 4.0.0

---

encode

<instance> encode()

Description:

Encode a data texture from the color ramp bands.

This process runs automatically when gpuEncode is enabled and the bands are set or updated with setBands. If you modify the bands directly, you must call encode yourself.

The data is encoded in texels as follows:

Numbers are encoded in "RG.BA" form. The number equals R * 255 + G + B / 255 + A / 255 / 255.

• First 2 texels: start and end.

  • Start is the start of the first band.

  • End is the end of the last band.

• Next block of texels: binary symmetrical tree of band ranges,

  represented as the end value of the midpoint band.

• Final block of texels, starting at dataTextureFirstBand:

  the band data, in blocks of 3:

  • colorStart

  • colorEnd

  • colorSpace * 255 + interpolation + (middle / 2)

The binary symmetrical tree breaks the bands list in half with every node. It is intended to quickly find the band corresponding to a given progress along the ramp. For example, a ramp with 10 bands would store the ends in this order:

[ 7, 3, 11, 1, 5, 9, 13, 0, 2, 4, 6, 8, 10, 12, 14 ]

But because it doesn't have bands from index 10 and up, it's actually:

[ 7, 3, 9, 1, 5, 9, 9, 0, 2, 4, 6, 8, 9, 9, 9 ]

Note that, if you change the number of bands in the ramp, dataTexture may no longer have the correct resolution. It is not intended for display.

Source: src/display/ColorRamp.js#L191
Since: 4.0.0

---

fixFit

<instance> fixFit(start, end, purgeZeroLength, encode)

Description:

Fix the fit of bands within this ColorRamp.

This sets the start of each band to the end of the previous band, ensuring that there are no gaps.

Optionally, you can define start and end values to stretch the ramp to some specific range, e.g. 0-1.

By default, any band that is now 0 length will be removed.

Parameters:

name	type	optional	description
start	number	No	Override the start of the first band.
end	number	No	Override the end of the last band.
purgeZeroLength	boolean	No	Whether to discard bands that now have 0 size.
encode	boolean	No	Whether to reencode the data texture.

Returns: Phaser.Display.ColorRamp - - This ColorRamp instance.

Source: src/display/ColorRamp.js#L324
Since: 4.0.0

---

getColor

<instance> getColor(index)

Description:

Get the color value at the given index within this ramp.

If there is no band at that location, the color is transparent.

Parameters:

name	type	optional	description
index	number	No	Index of the color to get, from 0 (start) to 1 (end).

Returns: Phaser.Types.Display.ColorObject - The color at that index.

Source: src/display/ColorRamp.js#L462

---

setBands

<instance> setBands(bands, [encode])

Description:

Set or replace the color bands in this ramp. Use this after creation to update the bands.

This will re-encode the data texture if gpuEncode is set and encode is not false.

Parameters:

name	type	optional	default	description
bands	Phaser.Types.Display.ColorBandConfig | Phaser.Display.ColorBand	Array.<(Phaser.Types.Display.ColorBandConfig	Phaser.Display.ColorBand)>	No
encode	boolean	Yes	true	Whether to encode the new ramp data to a data texture for use in shaders.

Returns: Phaser.Display.ColorRamp - - This ColorRamp instance.

Source: src/display/ColorRamp.js#L137
Since: 4.0.0

---

splitBand

<instance> splitBand(band, steps, [quantize], [encode])

Description:

Split a band from this ramp into several bands, and insert them into the ramp.

You can choose whether to "quantize" the bands, where each of them has a flat color.

Parameters:

name	type	optional	default	description
band	number | Phaser.Display.ColorBand	No		The band to split, either an index on this ramp or the band instance. The band must be on this ramp.
steps	number	No		The number of bands to create.
quantize	boolean	Yes	false	Whether to quantize the bands to a single color.
encode	boolean	Yes	true	Whether to rebuild the data texture.

Returns: Phaser.Display.ColorRamp - This ColorRamp instance.

Source: src/display/ColorRamp.js#L387
Since: 4.0.0

---