Skip to content

API Reference

Jump to bottom
MusNik edited this page Apr 20, 2024 · 30 revisions

Constructor

new OKColor() ➞ Struct.OKColor

This constructor returns a new instance of the OKColor struct to hold a color data.

Check out How to use section for basics.

Setters

setColor(color) ➞ Struct.OKColor

With this method, you can set a color for OKColor struct in GameMaker format.

Parameters:

Name Type Description
color Constant.Color The color definition in GameMaker supported format, can be c_color constant, #rrggbb, $bbggrr or a decimal number.

Returns: Struct.OKColor The same OKColor instance that the method was called on, for method chaining.

setHex(hex) ➞ Struct.OKColor

With this method, you can set a color for OKColor struct in a string format.

Parameters:

Name Type Description
hex String The color definition in hex format as a string "#rrggbb".

Returns: Struct.OKColor The same OKColor instance that the method was called on, for method chaining.

setRGB([red], [green], [blue]) ➞ Struct.OKColor

With this method, you can set a color in sRGB format. Arguments are optional so you can set components separately.

Parameters:

Name Type Description
[red] Real The red component definition of RGB color (in 0-255 range).
[green] Real The green component definition of RGB color (in 0-255 range).
[blue] Real The blue component definition of RGB color (in 0-255 range).

Returns: Struct.OKColor The same OKColor instance that the method was called on, for method chaining.

setLinearRGB([red], [green], [blue]) ➞ Struct.OKColor

With this method, you can set a color in non-gamma corrected Linear RGB format. Arguments are optional so you can set components separately.

Parameters:

Name Type Description
[red] Real The red component definition of Linear RGB color (in 0-1 range).
[green] Real The green component definition of Linear RGB color (in 0-1 range).
[blue] Real The blue component definition of Linear RGB color (in 0-1 range).

Returns: Struct.OKColor The same OKColor instance that the method was called on, for method chaining.

setHSV([hue], [saturation], [value]) ➞ Struct.OKColor

With this method, you can set a color in HSV format. Arguments are optional so you can set components separately.

Parameters:

Name Type Description
[hue] Real The hue component definition of HSV color (in 0-360 range).
[saturation] Real The saturation component definition of HSV color (in 0-1 range).
[value] Real The value component definition of HSV color (in 0-1 range).

Returns: Struct.OKColor The same OKColor instance that the method was called on, for method chaining.

setHSL([hue], [saturation], [lightness]) ➞ Struct.OKColor

With this method, you can set a color in HSL format. Arguments are optional so you can set components separately.

Parameters:

Name Type Description
[hue] Real The hue component definition of HSL color (in 0-360 range).
[saturation] Real The saturation component definition of HSL color (in 0-1 range).
[lightness] Real The lightness component definition of HSL color (in 0-1 range).

Returns: Struct.OKColor The same OKColor instance that the method was called on, for method chaining.

setLab([lightness], [a], [b]) ➞ Struct.OKColor

With this method, you can set a color in CIELab format. Arguments are optional so you can set components separately.

Parameters:

Name Type Description
[lightness] Real The lightness component definition of CIELab color (in 0-100 range).
[a] Real The a component definition of CIELab color (in -125 to 125 range).
[b] Real The b component definition of CIELab color (in -125 to 125 range).

Returns: Struct.OKColor The same OKColor instance that the method was called on, for method chaining.

setLCH([lightness], [chroma], [hue]) ➞ Struct.OKColor

With this method, you can set a color in CIELCH format. Arguments are optional so you can set components separately.

Parameters:

Name Type Description
[lightness] Real The lightness component definition of CIELCH color (in 0-100 range).
[chroma] Real The chroma component definition of CIELCH color (in 0-150 range).
[hue] Real The hue component definition of CIELCH color (in 0-360 range).

Returns: Struct.OKColor The same OKColor instance that the method was called on, for method chaining.

setOKLab([lightness], [a], [b]) ➞ Struct.OKColor

With this method, you can set a color in OKLab format. Arguments are optional so you can set components separately.

Parameters:

Name Type Description
[lightness] Real The lightness component definition of OKLab color (in 0-1 range).
[a] Real The a component definition of OKLab color (in -0.4 to 0.4 range).
[b] Real The b component definition of OKLab color (in -0.4 to 0.4 range).

Returns: Struct.OKColor The same OKColor instance that the method was called on, for method chaining.

setOKLCH([lightness], [chroma], [hue]) ➞ Struct.OKColor

With this method, you can set a color in OKLCH format. Arguments are optional so you can set components separately.

Parameters:

Name Type Description
[lightness] Real The lightness component definition of OKLCH color (in 0-1 range).
[chroma] Real The chroma component definition of OKLCH color (in 0 to 0.4 range).
[hue] Real The hue component definition of OKLCH color (in 0-360 range).

Returns: Struct.OKColor The same OKColor instance that the method was called on, for method chaining.

setLMS([long], [medium], [short]) ➞ Struct.OKColor

With this method, you can set a color in LMS format that is mostly used for technical needs. Arguments are optional so you can set components separately.

Parameters:

Name Type Description
[long] Real The long wavelength definition of LMS color.
[medium] Real The medium wavelength definition of LMS color.
[short] Real The short wavelength definition of LMS color.

Returns: Struct.OKColor The same OKColor instance that the method was called on, for method chaining.

setXYZ([x], [y], [z]) ➞ Struct.OKColor

With this method, you can set a color in CIE XYZ format that is mostly used for technical needs. Arguments are optional so you can set components separately.

Parameters:

Name Type Description
[x] Real The X component definition of CIE XYZ color.
[y] Real The Y component definition of CIE XYZ color.
[z] Real The Z component definition of CIE XYZ color.

Returns: Struct.OKColor The same OKColor instance that the method was called on, for method chaining.

Getters

Important

Values generated by these functions will contain the raw components of the chosen color model and can lay outside of sRGB gamut! To get color values ready for rendering use Color Getters.

getRGB() ➞ Struct { r : Real, g : Real, b : Real }

With this method, you can get a color in raw RGB format. Rendering-safe version: colorRGB().

Returns: Struct { r : Real, g : Real, b : Real }

getLinearRGB() ➞ Struct { r : Real, g : Real, b : Real }

With this method, you can get a color in raw non-gamma corrected Linear RGB format.

Returns: Struct { r : Real, g : Real, b : Real }

getHSV() ➞ Struct { h : Real, s : Real, v : Real }

With this method, you can get a color in raw HSV format. Rendering-safe versions: colorHSV() and colorGMHSV().

Warning

Hue in the resulting struct can be NaN, if the saturation is 0, for example. NaN hue can be safely treated as 0 in outside use.

Returns: Struct { h : Real, s : Real, v : Real }

getHSL() ➞ Struct { h : Real, s : Real, l : Real }

With this method, you can get a color in raw HSL format. Rendering-safe version: colorHSL().

Warning

Hue in the resulting struct can be NaN, if the saturation is 0, for example. NaN hue can be safely treated as 0 in outside use.

Returns: Struct { h : Real, s : Real, l : Real }

getLab() ➞ Struct { l : Real, a : Real, b : Real }

With this method, you can get a color in raw CIELab format.

Returns: Struct { l : Real, a : Real, b : Real }

getLCH() ➞ Struct { l : Real, c : Real, h : Real }

With this method, you can get a color in raw CIELCH format.

Returns: Struct { l : Real, c : Real, h : Real }

getOKLab() ➞ Struct { l : Real, a : Real, b : Real }

With this method, you can get a color in raw OKLab format.

Returns: Struct { l : Real, a : Real, b : Real }

getOKLCH() ➞ Struct { l : Real, c : Real, h : Real }

With this method, you can get a color in raw OKLCH format.

Returns: Struct { l : Real, c : Real, h : Real }

getLMS() ➞ Struct { l : Real, m : Real, s : Real }

With this method, you can get a color in raw LMS format that is mostly used for technical needs.

Returns: Struct { l : Real, m : Real, s : Real }

getXYZ() ➞ Struct { x : Real, y : Real, z : Real }

With this method, you can get a color in raw CIE XYZ format that is mostly used for technical needs.

Returns: Struct { x : Real, y : Real, z : Real }

Gamut Mapping

When dealing with different color models you can retrieve a color that lies outside of the renderable range called "gamut". Gamut mapping is the process of taking a color that is out of gamut and adjusting it such that it fits within it. Currently, OKColor only supports 24-bit sRGB color gamut that GameMaker can render on screen.

OKColorMapping enum sets the type of gamut mapping method in Color Getters, Mixing and other functions.

OKColorMapping.None

Won't do any gamut mapping and pass the color values unchanged. It may produce colors outside of gamut that will render incorrectly.

OKColorMapping.Clip

The naive version of gamut mapping clamping RGB values to 0-255 range. The fastest to compute (aside from no mapping at all) but gives mostly poor results.

gamut_clip

Here in the example is a number of colors generated outside of gamut, in the form of gradients from lowest to maximum lightness. Clip method doesn't reflect the lightness, distributes colors non-linearly and performs hue shifts so generally it's not recommended to use. Clipping is still very important and can be used to trim minor channel noise after certain color operations.

OKColorMapping.Geometric

The method is based on the geometric representation of gamut triangle finding the intersection of the outside color with the gamut and moving it inside. Self-invented by me for this library. Works faster than chroma reduction algorithms shown below and produces results similar to Chroma method but worse than OKChroma.

gamut_geometric

Here in the example is a number of colors generated outside of gamut, in the form of gradients from lowest to maximum lightness. Geometric method copes better with preserving lightness and color distribution, but with hue shifts to purple on reds and blues and some artefacts on darker colors.

OKColorMapping.Chroma

It's a chroma reduction algorithm in CIELCH color space with deltaEOK distance function. Along with the OKChroma method it is the slowest to compute but provides more consistent results.

gamut_lch

Here in the example is a number of colors generated outside of gamut, in the form of gradients from lowest to maximum lightness. Chroma handles lighting better with little to no artefacts on the dark but with a hue shift to yellow on reds and less to purple on blues. Worse than OKChroma in terms of lightness linearity but someone may want to use this instead as CIELCH is a more well-understood color space.

OKColorMapping.OKChroma

It's a chroma reduction algorithm in OKLCH color space with deltaEOK distance function. Along with the Chroma method it is the slowest to compute but provides the most consistent results. Currently the default gamut mapping method.

gamut_oklch

Here in the example is a number of colors generated outside of gamut, in the form of gradients from lowest to maximum lightness. OKChroma provides the best results on color distributions, no hue shifts and constant linear lightness. OKLCH is a relatively new color model and may have certain quirks, but generally it is a preferable option. Also recommended as a default method in CSS.

Color Getters

color([gamutMapping]) ➞ Constant.Color

With this method you can get a color value valid for rendering in GameMaker format usable for any system function like draw_set_color.

Parameters:

Name Type Description
[gamutMapping] Enum.OKColorMapping Gamut mapping type, default is OKColorMapping.OKChroma.

Returns: Constant.Color

colorHex([gamutMapping]) ➞ String

With this method you can get a color value valid for rendering in hex format as a string "#rrggbb".

Parameters:

Name Type Description
[gamutMapping] Enum.OKColorMapping Gamut mapping type, default is OKColorMapping.OKChroma.

Returns: String

colorRGB([gamutMapping]) ➞ Struct { r : Real, g : Real, b : Real }

With this method you can get color values valid for rendering in RGB format.

Parameters:

Name Type Description
[gamutMapping] Enum.OKColorMapping Gamut mapping type, default is OKColorMapping.OKChroma.

Returns: Struct { r : Real, g : Real, b : Real }

colorHSV([gamutMapping]) ➞ Struct { h : Real, s : Real, v : Real }

With this method you can get color values valid for rendering in HSV format.

Parameters:

Name Type Description
[gamutMapping] Enum.OKColorMapping Gamut mapping type, default is OKColorMapping.OKChroma.

Returns: Struct { h : Real, s : Real, v : Real }

colorGMHSV([gamutMapping]) ➞ Struct { h : Real, s : Real, v : Real }

With this method you can get color values valid for rendering in GameMaker HSV format with 0-255 range.

Parameters:

Name Type Description
[gamutMapping] Enum.OKColorMapping Gamut mapping type, default is OKColorMapping.OKChroma

Returns: Struct { h : Real, s : Real, v : Real }

colorHSL([gamutMapping]) ➞ Struct { h : Real, s : Real, l : Real }

With this method you can get color values valid for rendering in HSL format.

Parameters:

Name Type Description
[gamutMapping] Enum.OKColorMapping Gamut mapping type, default is OKColorMapping.OKChroma.

Returns: Struct { h : Real, s : Real, l : Real }

Mixing

Mixing is a process of merging two colors to produce a new color. OKColor have several mixing algorithms that interpolate colors with different color models. You can learn more about the specifics of different mixing methods here. Here is a quick example:

figure_1_9_blue_yellow_gradient figure_1_7_aqua_gred_gradient

OKColorMixing enum sets the mixing colors method.

OKColorMixing.RGB

Performs the mixing in RGB color space. Basically the same as the GameMaker's system merge_color.

OKColorMixing.Lab

Performs the mixing in Lab color space.

OKColorMixing.OKLab

Performs the mixing in OKLab color space. Currently is the default method of color mixing.

mix(mixColor, amount, [colorMixing], [gamutMapping]) ➞ Struct.OKColor

With this method you can mix additional color to the current one with a specified amount. Pure version is also available that returns new color instead of mutating current one.

Parameters:

Name Type Description
mixColor Struct.OKColor Additional color to mix with.
amount Real How much to mix a color in 0-1 range.
[colorMixing] Enum.OKColorMixing Color mixing type, default is OKColorMixing.OKLab.
[gamutMapping] Enum.OKColorMapping Gamut mapping type, default is OKColorMapping.OKChroma.

Returns: Struct.OKColor The same OKColor instance that the method was called on, for method chaining.

Cloning

clone() ➞ Struct.OKColor

With this method you can get a new copy of OKColor struct with the same color.

Returns: Struct.OKColor New OKColor instance.

cloneMapped([gamutMapping]) ➞ Struct.OKColor

With this method you can get a new copy of OKColor struct with the same color mapped for rendering.

Parameters:

Name Type Description
[gamutMapping] Enum.OKColorMapping Gamut mapping type, default is OKColorMapping.OKChroma.

Returns: Struct.OKColor New OKColor instance.

cloneMixed(mixColor, amount, [colorMixing], [gamutMapping]) ➞ Struct.OKColor

With this method you can get a new copy of OKColor struct with the additional color mixed.

Parameters:

Name Type Description
mixColor Struct.OKColor Additional color to mix with.
amount Real How much to mix a color in 0-1 range.
[colorMixing] Enum.OKColorMixing Color mixing type, default is OKColorMixing.OKLab.
[gamutMapping] Enum.OKColorMapping Gamut mapping type, default is OKColorMapping.OKChroma.

Returns: Struct.OKColor New OKColor instance.

Why to use?

How to use?

API Reference

Architecture

How to contribute

Clone this wiki locally