ezEngine  Milestone 7
ezColor Class Reference

ezColor represents and RGBA color in linear color space. Values are stored as float, allowing HDR values and full precision color modifications. More...

#include <Color.h>

Public Member Functions

 EZ_DECLARE_POD_TYPE ()
 
 ezColor ()
 default-constructed color is uninitialized (for speed)
 
 ezColor (float fLinearRed, float fLinearGreen, float fLinearBlue, float fLinearAlpha=1.0f)
 Initializes the color with r, g, b, a. The color values must be given in a linear color space. More...
 
 ezColor (const ezColorLinearUB &cc)
 Initializes this color from a ezColorLinearUB object. More...
 
 ezColor (const ezColorGammaUB &cc)
 Initializes this color from a ezColorGammaUB object. More...
 
void SetRGB (float fLinearRed, float fLinearGreen, float fLinearBlue)
 Sets the RGB components, ignores alpha.
 
void SetRGBA (float fLinearRed, float fLinearGreen, float fLinearBlue, float fLinearAlpha=1.0f)
 Sets all four RGBA components.
 
void FromLinearHSV (float hue, float sat, float val)
 Sets this color from a color that is in linear color space and given in HSV format. More...
 
void ToLinearHSV (float &hue, float &sat, float &val) const
 Converts the color part to HSV format. The HSV color will be in linear space. More...
 
void FromGammaHSV (float hue, float sat, float val)
 Sets this color from a color that is in gamma space and given in HSV format. More...
 
void ToGammaHSV (float &hue, float &sat, float &val) const
 Converts the color part to HSV format. The HSV color will be in gamma space. More...
 
const float * GetData () const
 Conversion to const float*.
 
float * GetData ()
 Conversion to float*.
 
bool IsNormalized () const
 Returns if the color is in the Range [0; 1] on all 4 channels.
 
float GetSaturation () const
 Computes saturation.
 
float GetLuminance () const
 Computes the perceived luminance. Assumes linear color space (http://en.wikipedia.org/wiki/Luminance_%28relative%29).
 
ezColor GetInvertedColor () const
 [tested] More...
 
ezColor GetComplementaryColor () const
 Calculates the complementary color for this color (hue shifted by 180 degrees). The complementary color will have the same alpha.
 
bool IsNaN () const
 Returns true, if any of r, g, b or a is NaN.
 
bool IsValid () const
 Checks that all components are finite numbers.
 
void operator= (const ezColorLinearUB &cc)
 Converts the color from ezColorLinearUB to linear float values.
 
void operator= (const ezColorGammaUB &cc)
 Converts the color from ezColorGammaUB to linear float values. Gamma is correctly converted to linear space.
 
void operator+= (const ezColor &rhs)
 Adds rhs component-wise to this color.
 
void operator-= (const ezColor &rhs)
 Subtracts rhs component-wise from this vector.
 
void operator*= (const ezColor &rhs)
 Multiplies rhs component-wise with this color.
 
void operator*= (float f)
 Multiplies all components of this color with f.
 
void operator/= (float f)
 Divides all components of this color by f.
 
void operator*= (const ezMat4 &rhs)
 Transforms the RGB components by the matrix. Alpha has no influence on the computation and will stay unmodified. The fourth row of the matrix is ignored. More...
 
bool IsIdenticalRGB (const ezColor &rhs) const
 Equality Check (bitwise). Only compares RGB, ignores Alpha.
 
bool IsIdenticalRGBA (const ezColor &rhs) const
 Equality Check (bitwise). Compares all four components.
 
bool IsEqualRGB (const ezColor &rhs, float fEpsilon) const
 Equality Check with epsilon. Only compares RGB, ignores Alpha.
 
bool IsEqualRGBA (const ezColor &rhs, float fEpsilon) const
 Equality Check with epsilon. Compares all four components.
 

Static Public Member Functions

static ezVec3 GammaToLinear (const ezVec3 &gamma)
 Helper function to convert a float RGB color value from gamma space to linear color space.
 
static ezVec3 LinearToGamma (const ezVec3 &gamma)
 Helper function to convert a float RGB color value from linear space to gamma color space.
 

Public Attributes

float r
 
float g
 
float b
 
float a
 

Static Public Attributes

static const ezColor AliceBlue
 #F0F8FF
 
static const ezColor AntiqueWhite
 #FAEBD7
 
static const ezColor Aqua
 #00FFFF
 
static const ezColor Aquamarine
 #7FFFD4
 
static const ezColor Azure
 #F0FFFF
 
static const ezColor Beige
 #F5F5DC
 
static const ezColor Bisque
 #FFE4C4
 
static const ezColor Black
 #000000
 
static const ezColor BlanchedAlmond
 #FFEBCD
 
static const ezColor Blue
 #0000FF
 
static const ezColor BlueViolet
 #8A2BE2
 
static const ezColor Brown
 #A52A2A
 
static const ezColor BurlyWood
 #DEB887
 
static const ezColor CadetBlue
 #5F9EA0
 
static const ezColor Chartreuse
 #7FFF00
 
static const ezColor Chocolate
 #D2691E
 
static const ezColor Coral
 #FF7F50
 
static const ezColor CornflowerBlue
 #6495ED The original!
 
static const ezColor Cornsilk
 #FFF8DC
 
static const ezColor Crimson
 #DC143C
 
static const ezColor Cyan
 #00FFFF
 
static const ezColor DarkBlue
 #00008B
 
static const ezColor DarkCyan
 #008B8B
 
static const ezColor DarkGoldenRod
 #B8860B
 
static const ezColor DarkGray
 #A9A9A9
 
static const ezColor DarkGreen
 #006400
 
static const ezColor DarkKhaki
 #BDB76B
 
static const ezColor DarkMagenta
 #8B008B
 
static const ezColor DarkOliveGreen
 #556B2F
 
static const ezColor DarkOrange
 #FF8C00
 
static const ezColor DarkOrchid
 #9932CC
 
static const ezColor DarkRed
 #8B0000
 
static const ezColor DarkSalmon
 #E9967A
 
static const ezColor DarkSeaGreen
 #8FBC8F
 
static const ezColor DarkSlateBlue
 #483D8B
 
static const ezColor DarkSlateGray
 #2F4F4F
 
static const ezColor DarkTurquoise
 #00CED1
 
static const ezColor DarkViolet
 #9400D3
 
static const ezColor DeepPink
 #FF1493
 
static const ezColor DeepSkyBlue
 #00BFFF
 
static const ezColor DimGray
 #696969
 
static const ezColor DodgerBlue
 #1E90FF
 
static const ezColor FireBrick
 #B22222
 
static const ezColor FloralWhite
 #FFFAF0
 
static const ezColor ForestGreen
 #228B22
 
static const ezColor Fuchsia
 #FF00FF
 
static const ezColor Gainsboro
 #DCDCDC
 
static const ezColor GhostWhite
 #F8F8FF
 
static const ezColor Gold
 #FFD700
 
static const ezColor GoldenRod
 #DAA520
 
static const ezColor Gray
 #808080
 
static const ezColor Green
 #008000
 
static const ezColor GreenYellow
 #ADFF2F
 
static const ezColor HoneyDew
 #F0FFF0
 
static const ezColor HotPink
 #FF69B4
 
static const ezColor IndianRed
 #CD5C5C
 
static const ezColor Indigo
 #4B0082
 
static const ezColor Ivory
 #FFFFF0
 
static const ezColor Khaki
 #F0E68C
 
static const ezColor Lavender
 #E6E6FA
 
static const ezColor LavenderBlush
 #FFF0F5
 
static const ezColor LawnGreen
 #7CFC00
 
static const ezColor LemonChiffon
 #FFFACD
 
static const ezColor LightBlue
 #ADD8E6
 
static const ezColor LightCoral
 #F08080
 
static const ezColor LightCyan
 #E0FFFF
 
static const ezColor LightGoldenRodYellow
 #FAFAD2
 
static const ezColor LightGray
 #D3D3D3
 
static const ezColor LightGreen
 #90EE90
 
static const ezColor LightPink
 #FFB6C1
 
static const ezColor LightSalmon
 #FFA07A
 
static const ezColor LightSeaGreen
 #20B2AA
 
static const ezColor LightSkyBlue
 #87CEFA
 
static const ezColor LightSlateGray
 #778899
 
static const ezColor LightSteelBlue
 #B0C4DE
 
static const ezColor LightYellow
 #FFFFE0
 
static const ezColor Lime
 #00FF00
 
static const ezColor LimeGreen
 #32CD32
 
static const ezColor Linen
 #FAF0E6
 
static const ezColor Magenta
 #FF00FF
 
static const ezColor Maroon
 #800000
 
static const ezColor MediumAquaMarine
 #66CDAA
 
static const ezColor MediumBlue
 #0000CD
 
static const ezColor MediumOrchid
 #BA55D3
 
static const ezColor MediumPurple
 #9370DB
 
static const ezColor MediumSeaGreen
 #3CB371
 
static const ezColor MediumSlateBlue
 #7B68EE
 
static const ezColor MediumSpringGreen
 #00FA9A
 
static const ezColor MediumTurquoise
 #48D1CC
 
static const ezColor MediumVioletRed
 #C71585
 
static const ezColor MidnightBlue
 #191970
 
static const ezColor MintCream
 #F5FFFA
 
static const ezColor MistyRose
 #FFE4E1
 
static const ezColor Moccasin
 #FFE4B5
 
static const ezColor NavajoWhite
 #FFDEAD
 
static const ezColor Navy
 #000080
 
static const ezColor OldLace
 #FDF5E6
 
static const ezColor Olive
 #808000
 
static const ezColor OliveDrab
 #6B8E23
 
static const ezColor Orange
 #FFA500
 
static const ezColor OrangeRed
 #FF4500
 
static const ezColor Orchid
 #DA70D6
 
static const ezColor PaleGoldenRod
 #EEE8AA
 
static const ezColor PaleGreen
 #98FB98
 
static const ezColor PaleTurquoise
 #AFEEEE
 
static const ezColor PaleVioletRed
 #DB7093
 
static const ezColor PapayaWhip
 #FFEFD5
 
static const ezColor PeachPuff
 #FFDAB9
 
static const ezColor Peru
 #CD853F
 
static const ezColor Pink
 #FFC0CB
 
static const ezColor Plum
 #DDA0DD
 
static const ezColor PowderBlue
 #B0E0E6
 
static const ezColor Purple
 #800080
 
static const ezColor RebeccaPurple
 #663399
 
static const ezColor Red
 #FF0000
 
static const ezColor RosyBrown
 #BC8F8F
 
static const ezColor RoyalBlue
 #4169E1
 
static const ezColor SaddleBrown
 #8B4513
 
static const ezColor Salmon
 #FA8072
 
static const ezColor SandyBrown
 #F4A460
 
static const ezColor SeaGreen
 #2E8B57
 
static const ezColor SeaShell
 #FFF5EE
 
static const ezColor Sienna
 #A0522D
 
static const ezColor Silver
 #C0C0C0
 
static const ezColor SkyBlue
 #87CEEB
 
static const ezColor SlateBlue
 #6A5ACD
 
static const ezColor SlateGray
 #708090
 
static const ezColor Snow
 #FFFAFA
 
static const ezColor SpringGreen
 #00FF7F
 
static const ezColor SteelBlue
 #4682B4
 
static const ezColor Tan
 #D2B48C
 
static const ezColor Teal
 #008080
 
static const ezColor Thistle
 #D8BFD8
 
static const ezColor Tomato
 #FF6347
 
static const ezColor Turquoise
 #40E0D0
 
static const ezColor Violet
 #EE82EE
 
static const ezColor Wheat
 #F5DEB3
 
static const ezColor White
 #FFFFFF
 
static const ezColor WhiteSmoke
 #F5F5F5
 
static const ezColor Yellow
 #FFFF00
 
static const ezColor YellowGreen
 #9ACD32
 

Detailed Description

ezColor represents and RGBA color in linear color space. Values are stored as float, allowing HDR values and full precision color modifications.

ezColor is the central class to handle colors throughout the engine. With floating point precision it can handle any value, including HDR colors. Since it is stored in linear space, doing color transformations (e.g. adding colors or multiplying them) work as expected.

When you need to pass colors to the GPU you have multiple options.

  • If you can spare the bandwidth, you should prefer to use floating point formats, e.g. the same as ezColor on the CPU.
  • If you need higher precision and HDR values, you can use ezColorLinear16f as a storage format with only half the memory footprint.
  • If you need to use preserve memory and LDR values are sufficient, you should use ezColorGammaUB. This format uses 8 Bit per pixel but stores colors in Gamma space, resulting in higher precision in the range that the human eye can distinguish better. However, when you store a color in Gamma space, you need to make sure to convert it back to linear space before doing ANY computations with it. E.g. your shader needs to convert the color.
  • You can also use 8 Bit per pixel with a linear color space by using ezColorLinearUB, however this may give very noticeable precision loss.

When working with color in your code, be aware to always use the correct class to handle color conversions properly. E.g. when you hardcode a color in source code, you might go to a Paint program, pick a nice color and then type that value into the source code. Note that ALL colors that you see on screen are implicitly in sRGB / Gamma space. That means you should do the following cast:

ezColor linear = ezColorGammaUB(100, 149, 237);

This will automatically convert the color from Gamma to linear space. From there on all mathematical operations are possible.

The inverse has to be done when you want to present the value of a color in a UI:

ezColorGammaUB gamma = ezColor(0.39f, 0.58f, 0.93f);

Now the integer values in gamma can be used to e.g. populate a color picker and the color displayed on screen will show up the same, as in a gamma correct 3D rendering.

The predefined colors can be seen at http://www.w3schools.com/cssref/css_colornames.asp

Constructor & Destructor Documentation

ezColor::ezColor ( float  fLinearRed,
float  fLinearGreen,
float  fLinearBlue,
float  fLinearAlpha = 1.0f 
)
inline

Initializes the color with r, g, b, a. The color values must be given in a linear color space.

To initialize the color from a Gamma color space, e.g. when using a color value that was determined with a color picker, use the constructor that takes a ezColorGammaUB object for initialization.

ezColor::ezColor ( const ezColorLinearUB cc)
inline

Initializes this color from a ezColorLinearUB object.

Prefer to either use linear colors with floating point precision, or to use ezColorGammaUB for 8 bit per pixel colors in gamma space.

ezColor::ezColor ( const ezColorGammaUB cc)
inline

Initializes this color from a ezColorGammaUB object.

This should be the preferred method when hardcoding colors in source code.

Member Function Documentation

void ezColor::FromGammaHSV ( float  hue,
float  sat,
float  val 
)

Sets this color from a color that is in gamma space and given in HSV format.

This method should be used when a color was determined through a color picker.

void ezColor::FromLinearHSV ( float  hue,
float  sat,
float  val 
)

Sets this color from a color that is in linear color space and given in HSV format.

You should typically NOT use this functions, as most colors in HSV format are taken from some color picker, which will return a color in Gamma space.

ezColor ezColor::GetInvertedColor ( ) const
inline

[tested]

Performs a simple (1.0 - color) inversion on all four channels.

Using this function on non-normalized colors will lead to negative results.

See Also
ezColor IsNormalized
void ezColor::operator*= ( const ezMat4 rhs)

Transforms the RGB components by the matrix. Alpha has no influence on the computation and will stay unmodified. The fourth row of the matrix is ignored.

This operation can be used to do basic color correction.

void ezColor::ToGammaHSV ( float &  hue,
float &  sat,
float &  val 
) const

Converts the color part to HSV format. The HSV color will be in gamma space.

This should be used when you want to display the color as HSV in a color picker.

void ezColor::ToLinearHSV ( float &  hue,
float &  sat,
float &  val 
) const

Converts the color part to HSV format. The HSV color will be in linear space.

You should NOT use this functions when you want to display the HSV value in a UI element, as those should display colors in Gamma space. You can use this function for procedural color modifications. E.g. GetComplementaryColor() is computed by rotating the hue value 180 degree. In this case you also need to use FromLinearHSV() to convert the color back to RGB format.


The documentation for this class was generated from the following files: