Skip to main content
Version: Phaser v4.0.0

ColorBand

The ColorBand class represents a transition from one color to another. It is used in a {@see Phaser.Display.ColorRamp}, and forms the basis of a {@see Phaser.GameObjects.Gradient}.

ColorBand can control the transition by setting a middle point, a color space for blending, and an interpolation style.

This class also records start and end points for use in a ramp. These indicate its position within the ramp.

Colors are handled unpremultiplied, so RGB values may be larger than alpha.

Constructor

new ColorBand([config])

Parameters

nametypeoptionaldescription
configPhaser.Types.Display.ColorBandConfigYesThe configuration to use for the band.

Scope: static

Source: src/display/ColorBand.js#L13
Since: 4.0.0

Public Members​

colorEnd​

colorEnd: Phaser.Display.Color​

Description:

The color at the end of the color band.

Source: src/display/ColorBand.js#L60
Since: 4.0.0

colorSpace​

colorSpace: number​

Description:

The color space where interpolation should be done. This can be one of the following codes:

  • 0: RGBA - channels are blended directly.

    This can produce perceptually inaccurate results, as blending

    in RGB space does not account for how humans perceive color.

  • 1: HSVA_NEAREST - colors are blended in HSVA space,

    better preserving saturation and lightness.

    The hue is blended with the shortest angle, e.g. red and blue

    blend via purple, not green.

  • 2: HSVA_PLUS - as HSVA_NEAREST, but hue angle always increases.

  • 3: HSVA_MINUS - as HSVA_NEAREST, but hue angle always decreases.

Source: src/display/ColorBand.js#L135
Since: 4.0.0

colorStart​

colorStart: Phaser.Display.Color​

Description:

The color at the start of the color band.

Source: src/display/ColorBand.js#L51
Since: 4.0.0

end​

end: number​

Description:

The end point of this band within a ColorRamp. This value should be normalized within the ramp, between 0 (ramp start) and 1 (ramp end).

Source: src/display/ColorBand.js#L98
Since: 4.0.0

interpolation​

interpolation: number​

Description:

The color interpolation. This can be one of the following codes:

  • 0: LINEAR - a straight blend.

  • 1: CURVED - color changes quickly at start and end,

    flattening in the middle. Good for convex surfaces.

  • 2: SINUSOIDAL - color changes quickly in the middle,

    flattening at start and end. Good for smooth transitions.

  • 3: CURVE_START - color changes quickly at the start,

    flattening at the end.

  • 4: CURVE_END - color changes quickly at the end,

    flattening at the start.

Modes 2, 3, and 4 use the circular easing function directly. Mode 1 uses a related custom formula based on the unit circle.

Source: src/display/ColorBand.js#L111
Since: 4.0.0

isColorBand​

isColorBand: boolean​

Description:

Identifies this object as a ColorBand. This property is read-only and must not be modified.

Source: src/display/ColorBand.js#L39
Since: 4.0.0

middle​

middle: number​

Description:

The middle point of this band within a ColorRamp. This value should be normalized within the band, between 0 (band start) and 1 (band end). Middle point alters the shape of the color interpolation.

Mathematically, the gradient should be 0.5 at the middle. We use a gamma curve to adjust the gradient. Thus, 0.5 = middle^gamma. By the properties of logarithms, therefore, gamma = log base middle of 0.5.

Source: src/display/ColorBand.js#L80
Since: 4.0.0

start​

start: number​

Description:

The start point of this band within a ColorRamp. This value should be normalized within the ramp, between 0 (ramp start) and 1 (ramp end).

Source: src/display/ColorBand.js#L69
Since: 4.0.0

Public Methods​

getColor​

<instance> getColor(index)​

Description:

Returns the blended color at a normalized position within this band. The middle point gamma curve, interpolation mode, and color space are all applied before blending between colorStart and colorEnd.

Parameters:

nametypeoptionaldescription
indexnumberNoThe normalized position within the band, where 0 is the band start and 1 is the band end.

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

Source: src/display/ColorBand.js#L225
Since: 4.0.0

setColors​

<instance> setColors([start], [end])​

Description:

Set the colors of the band, from a variety of color formats.

  • A number is expected to be a 24 or 32 bit RGB or ARGB value.

  • A string is expected to be a hex code.

  • An array of numbers is expected to be RGB or RGBA in the range 0-1.

  • A Color object can be used.

Parameters:

nametypeoptionaldefaultdescription
startnumber | stringArray.<number>Phaser.Display.ColorYes
endnumber | stringArray.<number>Phaser.Display.ColorYes

Returns: Phaser.Display.ColorBand - This ColorBand.

Source: src/display/ColorBand.js#L159
Since: 4.0.0