Modules · Interface · Colour

Colour

RGB colours and blending. Colour models a colour as red, green, blue, and alpha channels from 0.0 to 1.0 — the Colour value type, which doubles as a namespace holding a palette of named colour constants plus channel-wise arithmetic, lightening and darkening, clamping, interpolation and blend helpers. Every operation is reactive, recomputing whenever a colour it reads changes.

Types

Colour

Constants

Functions

Types

Colour

A colour as red, green, blue, and alpha (opacity) channels from 0.0 to 1.0. It also groups the colour constants and operations.

Fields

Field	Type	Description
`red`	`Maths.Real`	Red channel, 0.0 to 1.0.
`green`	`Maths.Real`	Green channel, 0.0 to 1.0.
`blue`	`Maths.Real`	Blue channel, 0.0 to 1.0.
`alpha`	`Maths.Real`	Alpha (opacity) channel, 0.0 to 1.0.

Definition

TYPE Colour
  FIELD Maths.Real red
  FIELD Maths.Real green
  FIELD Maths.Real blue
  FIELD Maths.Real alpha

Three colour channels plus an alpha (opacity) channel, each from 0.0 to 1.0.

Example

LET Colour glass = Colour 0.2 0.4 0.9 0.5

A half-transparent blue built from its four channels.

Constants

Colour.Black

The predefined black colour.

Definition

LET Black = Colour 0.0 0.0 0.0 1.0

Colour.Blue

The predefined blue colour.

Definition

LET Blue = Colour 0.0 0.0 1.0 1.0

Colour.Brown

The predefined brown colour.

Definition

LET Brown = Colour 0.5 0.25 0.0 1.0

Colour.Cyan

The predefined cyan colour.

Definition

LET Cyan = Colour 0.0 1.0 1.0 1.0

Colour.Green

The predefined green colour.

Definition

LET Green = Colour 0.0 1.0 0.0 1.0

Colour.Grey1

Preset grey shade 1 of nine, from dark to light.

Definition

LET Grey1 = Colour 0.1 0.1 0.2 1.0

Colour.Grey2

Preset grey shade 2 of nine, from dark to light.

Definition

LET Grey2 = Colour 0.2 0.2 0.3 1.0

Colour.Grey3

Preset grey shade 3 of nine, from dark to light.

Definition

LET Grey3 = Colour 0.3 0.3 0.3 1.0

Colour.Grey4

Preset grey shade 4 of nine, from dark to light.

Definition

LET Grey4 = Colour 0.4 0.4 0.4 1.0

Colour.Grey5

Preset grey shade 5 of nine, from dark to light.

Definition

LET Grey5 = Colour 0.5 0.5 0.5 1.0

Colour.Grey6

Preset grey shade 6 of nine, from dark to light.

Definition

LET Grey6 = Colour 0.6 0.6 0.6 1.0

Colour.Grey7

Preset grey shade 7 of nine, from dark to light.

Definition

LET Grey7 = Colour 0.7 0.7 0.7 1.0

Colour.Grey8

Preset grey shade 8 of nine, from dark to light.

Definition

LET Grey8 = Colour 0.8 0.8 0.8 1.0

Colour.Grey9

Preset grey shade 9 of nine, from dark to light.

Definition

LET Grey9 = Colour 0.9 0.9 0.9 1.0

Colour.Magenta

The predefined magenta colour.

Definition

LET Magenta = Colour 1.0 0.0 1.0 1.0

Colour.Orange

The predefined orange colour.

Definition

LET Orange = Colour 1.0 0.75 0.0 1.0

Colour.Pink

The predefined pink colour.

Definition

LET Pink = Colour 1.0 0.66 0.66 1.0

Colour.Purple

The predefined purple colour.

Definition

LET Purple = Colour 0.75 0.0 1.0 1.0

Colour.Red

The predefined red colour.

Definition

LET Red = Colour 1.0 0.0 0.0 1.0

Colour.White

The predefined white colour.

Definition

LET White = Colour 1.0 1.0 1.0 1.0

Colour.Yellow

The predefined yellow colour.

Definition

LET Yellow = Colour 1.0 1.0 0.0 1.0

Functions

Colour.Add

Adds two colours channel by channel.

Parameters

Name	Type	Description
`colour1`	`Colour`	First colour.
`colour2`	`Colour`	Second colour.

Returns

Returns Colour — the channel-wise sum of the two colours.

Colour.Blend.Channel

Linearly interpolates a single channel value.

Parameters

Name	Type	Description
`value1`	`Maths.Real`	The value at factor 0.
`value2`	`Maths.Real`	The value at factor 1.
`factor`	`Maths.Real`	How far between, 0 to 1.

Returns

Returns Maths.Real — value1 and value2 mixed by factor.

Colour.Blend.Linear

Linearly blends two colours by a factor.

Parameters

Name	Type	Description
`colour1`	`Colour`	The colour at factor 0.
`colour2`	`Colour`	The colour at factor 1.
`factor`	`Maths.Real`	How far between, 0 to 1.

Returns

Returns Colour — each channel factor of the way from colour1 to colour2.

Example

LET Colour blended = Colour.Blend.Linear start finish factor

A straight linear blend of two colours.

Colour.Blend.Square

Blends two colours in squared space for a perceptually smoother mix.

Parameters

Name	Type	Description
`colour1`	`Colour`	The colour at factor 0.
`colour2`	`Colour`	The colour at factor 1.
`factor`	`Maths.Real`	How far between, 0 to 1.

Returns

Returns Colour — the blend taken after squaring each colour and rooted back afterwards.

Colour.Blend.SquareRoot

Blends two colours in square-root space.

Parameters

Name	Type	Description
`colour1`	`Colour`	The colour at factor 0.
`colour2`	`Colour`	The colour at factor 1.
`factor`	`Maths.Real`	How far between, 0 to 1.

Returns

Returns Colour — the blend taken after rooting each colour and squared back afterwards.

Colour.ByteValue

Converts a 0.0 to 1.0 channel into a 0-255 byte.

Parameters

Name	Type	Description
`value`	`Maths.Real`	A channel value, 0.0 to 1.0.

Returns

Returns Maths.Integer — value scaled to an integer in the range 0 to 255.

Colour.Clamp

Constrains each channel between a minimum and maximum colour.

Parameters

Name	Type	Description
`colour`	`Colour`	The colour to constrain.
`minColour`	`Colour`	Per-channel lower bound.
`maxColour`	`Colour`	Per-channel upper bound.

Returns

Returns Colour — the colour with each channel pulled into the range of the bound colours.

Colour.Darken

Mixes a colour toward black by a proportion.

Parameters

Name	Type	Description
`colour1`	`Colour`	The colour to darken.
`proportion`	`Maths.Real`	How far toward black, 0 to 1.

Returns

Returns Colour — the colour blended toward black by proportion.

Colour.DataOptionalAlpha

Builds a colour, defaulting alpha to fully opaque when omitted.

Parameters

Name	Type	Description
`red`	`Maths.Real`	Red channel, 0.0 to 1.0.
`green`	`Maths.Real`	Green channel, 0.0 to 1.0.
`blue`	`Maths.Real`	Blue channel, 0.0 to 1.0.
`optionalAlpha`	`Collection.Optional(Maths.Real)`	Alpha channel, or absent for 1.0.

Returns

Returns Colour — the colour, using 1.0 for alpha when optionalAlpha is absent.

Colour.FromBytes

Builds a colour from 0-255 byte channel values.

Parameters

Name	Type	Description
`red`	`Maths.Integer`	Red channel, 0 to 255.
`green`	`Maths.Integer`	Green channel, 0 to 255.
`blue`	`Maths.Integer`	Blue channel, 0 to 255.
`alpha`	`Maths.Integer`	Alpha channel, 0 to 255.

Returns

Returns Colour — the colour with each byte scaled into the 0.0 to 1.0 range.

Example

LET Colour brand = Colour.FromBytes 34 90 200 255

A brand colour given as 8-bit channel values.

Colour.FromJson

Reads a colour from a JSON object of channels.

Parameters

Name	Type	Description
`json`	`Code.Language.Json.Value`	The JSON object to read.

Returns

Returns Colour — the colour parsed from the JSON, using defaults for missing channels.

Colour.FromJsonOptional

Reads a colour from optional JSON, passing absence through.

Parameters

Name	Type	Description
`optionalJson`	`Collection.Optional(Code.Language.Json.Value)`	The JSON object, or absent.

Returns

Returns Collection.Optional(Colour) — the parsed colour, or absent when the input is absent.

Colour.Grey

A grey with every colour channel set to the same value.

Parameters

Name	Type	Description
`value`	`Maths.Real`	The shade for all channels, 0.0 to 1.0.

Returns

Returns Colour — a grey at the given shade.

Colour.Interpolate

Blends two colours channel by channel by a factor.

Parameters

Name	Type	Description
`colour1`	`Colour`	The colour at factor 0.
`colour2`	`Colour`	The colour at factor 1.
`factor`	`Maths.Real`	How far between, 0 to 1.

Returns

Returns Colour — each channel factor of the way from colour1 to colour2.

Example

LET Colour mixed = Colour.Interpolate start finish 0.5

The colour halfway between two others.

Colour.Lighten

Mixes a colour toward white by a proportion.

Parameters

Name	Type	Description
`colour1`	`Colour`	The colour to lighten.
`proportion`	`Maths.Real`	How far toward white, 0 to 1.

Returns

Returns Colour — the colour blended toward white by proportion.

Example

LET Colour tint = Colour.Lighten base 0.3

A lighter tint of the base colour.

Colour.Maximum

Takes the brighter channel from each of two colours.

Parameters

Name	Type	Description
`colour1`	`Colour`	First colour.
`colour2`	`Colour`	Second colour.

Returns

Returns Colour — the channel-wise maximum of the two colours.

Colour.Minimum

Takes the darker channel from each of two colours.

Parameters

Name	Type	Description
`colour1`	`Colour`	First colour.
`colour2`	`Colour`	Second colour.

Returns

Returns Colour — the channel-wise minimum of the two colours.

Colour.Multiply

Multiplies two colours channel by channel.

Parameters

Name	Type	Description
`colour1`	`Colour`	First colour.
`colour2`	`Colour`	Second colour.

Returns

Returns Colour — the channel-wise product of the two colours.

Colour.Square

Squares each channel of a colour.

Parameters

Name	Type	Description
`colour`	`Colour`	The colour to square.

Returns

Returns Colour — the colour with each channel multiplied by itself.

Colour.SquareRoot

Takes the square root of each channel of a colour.

Parameters

Name	Type	Description
`colour`	`Colour`	The colour to take the root of.

Returns

Returns Colour — the colour with each channel replaced by its square root.

Colour.Subtract

Subtracts one colour from another channel by channel.

Parameters

Name	Type	Description
`colour1`	`Colour`	The colour subtracted from.
`colour2`	`Colour`	The colour to subtract.

Returns

Returns Colour — the channel-wise difference of the two colours.

Colour.ToAnsi

Renders a colour as a semicolon-separated ANSI RGB triplet.

Parameters

Name	Type	Description
`colour`	`Colour`	The colour to render.

Returns

Returns Text — the byte channels joined as r;g;b for an ANSI escape.

Colour.ToJson

Encodes a colour as a JSON object of its channels.

Parameters

Name	Type	Description
`data`	`Colour`	The colour to encode.

Returns

Returns Code.Language.Json.Value — a JSON object holding each channel.

Colour

Contents

Types

Constants

Functions

Types

Colour

Fields

Definition

Example

Constants

Colour.Black

Definition

Colour.Blue

Definition

Colour.Brown

Definition

Colour.Cyan

Definition

Colour.Green

Definition

Colour.Grey1

Definition

Colour.Grey2

Definition

Colour.Grey3

Definition

Colour.Grey4

Definition

Colour.Grey5

Definition

Colour.Grey6

Definition

Colour.Grey7

Definition

Colour.Grey8

Definition

Colour.Grey9

Definition

Colour.Magenta

Definition

Colour.Orange

Definition

Colour.Pink

Definition

Colour.Purple

Definition

Colour.Red

Definition

Colour.White

Definition

Colour.Yellow

Definition

Functions

Colour.Add

Parameters

Returns

Colour.Blend.Channel

Parameters

Returns

Colour.Blend.Linear

Parameters

Returns

Example

Colour.Blend.Square

Parameters

Returns

Colour.Blend.SquareRoot

Parameters

Returns

Colour.ByteValue

Parameters

Returns

Colour.Clamp

Parameters

Returns

Colour.Darken

Parameters

Returns

Colour.DataOptionalAlpha