Package com.ardor3d.math

Class ColorRGBA

java.lang.Object
com.ardor3d.math.ColorRGBA
All Implemented Interfaces:
Poolable, ReadOnlyColorRGBA, Savable, Externalizable, Serializable, Cloneable
public class ColorRGBA extends Object implements Cloneable, Savable, Externalizable, ReadOnlyColorRGBA, Poolable
ColorRGBA is a 4 component color value (red, green, blue, alpha). The standard range for each individual component is [0f, 1f]. Non-standard use of color (for example HDR rendering) may need to use values outside of this range however, so the value is not clipped or enforced.
See Also:

  • Field Details

    • BLACK

      public static final ReadOnlyColorRGBA BLACK
      the color black (0, 0, 0, 1).

    • BLACK_NO_ALPHA

      public static final ReadOnlyColorRGBA BLACK_NO_ALPHA
      the color black with a zero alpha value (0, 0, 0, 0).

    • WHITE

      public static final ReadOnlyColorRGBA WHITE
      the color white (1, 1, 1, 1).

    • DARK_GRAY

      public static final ReadOnlyColorRGBA DARK_GRAY
      the color gray (.2f, .2f, .2f, 1).

    • GRAY

      public static final ReadOnlyColorRGBA GRAY
      the color gray (.5f, .5f, .5f, 1).

    • LIGHT_GRAY

      public static final ReadOnlyColorRGBA LIGHT_GRAY
      the color gray (.8f, .8f, .8f, 1).

    • RED

      public static final ReadOnlyColorRGBA RED
      the color red (1, 0, 0, 1).

    • GREEN

      public static final ReadOnlyColorRGBA GREEN
      the color green (0, 1, 0, 1).

    • BLUE

      public static final ReadOnlyColorRGBA BLUE
      the color blue (0, 0, 1, 1).

    • YELLOW

      public static final ReadOnlyColorRGBA YELLOW
      the color yellow (1, 1, 0, 1).

    • MAGENTA

      public static final ReadOnlyColorRGBA MAGENTA
      the color magenta (1, 0, 1, 1).

    • CYAN

      public static final ReadOnlyColorRGBA CYAN
      the color cyan (0, 1, 1, 1).

    • ORANGE

      public static final ReadOnlyColorRGBA ORANGE
      the color orange (251/255f, 130/255f, 0, 1).

    • BROWN

      public static final ReadOnlyColorRGBA BROWN
      the color brown (65/255f, 40/255f, 25/255f, 1).

    • PINK

      public static final ReadOnlyColorRGBA PINK
      the color pink (1, 0.68f, 0.68f, 1).

    • _r

      protected float _r

    • _g

      protected float _g

    • _b

      protected float _b

    • _a

      protected float _a

  • Constructor Details

    • ColorRGBA

      public ColorRGBA()
      Constructs a new, mutable color set to (1, 1, 1, 1).

    • ColorRGBA

      public ColorRGBA(ReadOnlyColorRGBA src)
      Constructs a new, mutable color set to the (r, g, b, a) values of the provided source color.
      Parameters:
      src - the source color

    • ColorRGBA

      public ColorRGBA(float r, float g, float b, float a)
      Constructs a new color set to (r, g, b, a).
      Parameters:
      r - the red component
      g - the green component
      b - the blue component
      a - the alpha component

  • Method Details

    • getRed

      public float getRed()
      Specified by:
      getRed in interface ReadOnlyColorRGBA

    • getGreen

      public float getGreen()
      Specified by:
      getGreen in interface ReadOnlyColorRGBA

    • getBlue

      public float getBlue()
      Specified by:
      getBlue in interface ReadOnlyColorRGBA

    • getAlpha

      public float getAlpha()
      Specified by:
      getAlpha in interface ReadOnlyColorRGBA

    • getValue

      public float getValue(int index)
      Specified by:
      getValue in interface ReadOnlyColorRGBA
      Parameters:
      index - the field index in this color, must be either 0, 1, 2 or 3
      Returns:
      r value if index == 0, g value if index == 1, b value if index == 2 or a value if index == 3
      Throws:
      IllegalArgumentException - if index is not one of 0, 1, 2, 3.

    • setValue

      public void setValue(int index, float value)
      Parameters:
      index - which field index in this color to set.
      value - to set to one of r, g, b or a.
      Throws:
      IllegalArgumentException - if index is not one of 0, 1, 2, 3.

    • toArray

      public float[] toArray(float[] store)
      Stores the float values of this color in the given float array.
      Specified by:
      toArray in interface ReadOnlyColorRGBA
      Parameters:
      store - if null, a new float[4] array is created.
      Returns:
      the float array
      Throws:
      NullPointerException - if store is null.
      ArrayIndexOutOfBoundsException - if store is not at least length 4.

    • setRed

      public void setRed(float r)
      Sets the red component of this color to the given float value.
      Parameters:
      r - new red value, generally should be in the range [0.0f, 1.0f]

    • setGreen

      public void setGreen(float g)
      Sets the green component of this color to the given float value.
      Parameters:
      g - new green value, generally should be in the range [0.0f, 1.0f]

    • setBlue

      public void setBlue(float b)
      Sets the blue component of this color to the given float value.
      Parameters:
      b - new blue value, generally should be in the range [0.0f, 1.0f]

    • setAlpha

      public void setAlpha(float a)
      Sets the alpha component of this color to the given float value. Consider that an alpha of 1.0f means opaque (can not see through) and 0.0f means transparent.
      Parameters:
      a - new alpha value, generally should be in the range [0.0f, 1.0f]

    • set

      public ColorRGBA set(float r, float g, float b, float a)
      Sets the value of this color to (r, g, b, a)
      Parameters:
      r - new red value, generally should be in the range [0.0f, 1.0f]
      g - new green value, generally should be in the range [0.0f, 1.0f]
      b - new blue value, generally should be in the range [0.0f, 1.0f]
      a - new alpha value, generally should be in the range [0.0f, 1.0f]
      Returns:
      this color for chaining

    • set

      public ColorRGBA set(ReadOnlyColorRGBA source)
      Sets the value of this color to the (r, g, b, a) values of the provided source color.
      Parameters:
      source - the source color
      Returns:
      this color for chaining
      Throws:
      NullPointerException - if source is null.

    • zero

      public ColorRGBA zero()
      Sets the value of this color to (0, 0, 0, 0)
      Returns:
      this color for chaining

    • clamp

      public ColorRGBA clamp(ColorRGBA store)
      Brings all values (r,g,b,a) into the range [0.0f, 1.0f]. If a value is above or below this range it is replaced with the appropriate end of the range.
      Specified by:
      clamp in interface ReadOnlyColorRGBA
      Parameters:
      store - the color to store the result in for return. If null, a new color object is created and returned.
      Returns:
      the clamped color

    • clampLocal

      public ColorRGBA clampLocal()
      Brings all values (r,g,b,a) into the range [0.0f, 1.0f]. If a value is above or below this range it is replaced with the appropriate end of the range.
      Returns:
      this color for chaining

    • randomColor

      public static ColorRGBA randomColor(ColorRGBA store)
      Parameters:
      store - the color to store the result in for return. If null, a new color object is created and returned.
      Returns:
      a random, mutable opaque color.

    • asIntARGB

      public int asIntARGB()
      Specified by:
      asIntARGB in interface ReadOnlyColorRGBA
      Returns:
      this color, stored as an integer by converting the values to the range [0, 255] and combining them as single byte values into a 4 byte int in the order ARGB. Note that this method expects color values in the [0.0f, 1.0f] range.

    • asIntRGBA

      public int asIntRGBA()
      Specified by:
      asIntRGBA in interface ReadOnlyColorRGBA
      Returns:
      this color, stored as an integer by converting the values to the range [0, 255] and combining them as single byte values into a 4 byte int in the order RGBA. Note that this method expects color values in the [0.0f, 1.0f] range.

    • fromIntARGB

      public ColorRGBA fromIntARGB(int color)
      Reads a color, packed into a 4 byte int as 1 byte values in the order ARGB. These byte values are normalized to the range [0.0f, 1.0f]
      Parameters:
      color - the 4 byte int as 1 byte values in the order ARGB
      Returns:
      this color for chaining

    • fromIntRGBA

      public ColorRGBA fromIntRGBA(int color)
      Reads a color, packed into a 4 byte int as 1 byte values in the order RGBA. These byte values are normalized to the range [0.0f, 1.0f]
      Parameters:
      color - the 4 byte int as 1 byte values in the order RGBA
      Returns:
      this color for chaining

    • asHexRRGGBBAA

      public String asHexRRGGBBAA()
      Specified by:
      asHexRRGGBBAA in interface ReadOnlyColorRGBA
      Returns:
      this string as a hex value (#RRGGBBAA). e.g. opaque blue is #0000ffff

    • add

      public ColorRGBA add(float r, float g, float b, float a, ColorRGBA store)
      Adds the given values to those of this color and returns them in store.
      Specified by:
      add in interface ReadOnlyColorRGBA
      Parameters:
      r - the red component
      g - the green component
      b - the blue component
      a - the alpha component
      store - the color to store the result in for return. If null, a new color object is created and returned.
      Returns:
      (this.r + r, this.g + g, this.b + b, this.a + a)

    • addLocal

      public ColorRGBA addLocal(float r, float g, float b, float a)
      Increments the values of this color with the given r, g, b and a values.
      Parameters:
      r - the red component
      g - the green component
      b - the blue component
      a - the alpha component
      Returns:
      this color for chaining

    • add

      public ColorRGBA add(ReadOnlyColorRGBA source, ColorRGBA store)
      Adds the values of the given source color to those of this color and returns them in store.
      Specified by:
      add in interface ReadOnlyColorRGBA
      Parameters:
      source - the source color
      store - the color to store the result in for return. If null, a new color object is created and returned.
      Returns:
      (this.r + source.r, this.g + source.g, this.b + source.b, this.a + source.a)
      Throws:
      NullPointerException - if source is null.

    • addLocal

      public ColorRGBA addLocal(ReadOnlyColorRGBA source)
      Increments the values of this color with the r, g, b and a values of the given color.
      Parameters:
      source - the source color
      Returns:
      this color for chaining
      Throws:
      NullPointerException - if source is null.

    • subtract

      public ColorRGBA subtract(float r, float g, float b, float a, ColorRGBA store)
      Subtracts the given values from those of this color and returns them in store.
      Specified by:
      subtract in interface ReadOnlyColorRGBA
      Parameters:
      r - the red component
      g - the green component
      b - the blue component
      a - the alpha component
      store - the color to store the result in for return. If null, a new color object is created and returned.
      Returns:
      (this.r - r, this.g - g, this.b - b, this.a - a)

    • subtractLocal

      public ColorRGBA subtractLocal(float r, float g, float b, float a)
      Decrements the values of this color by the given r, g, b and a values.
      Parameters:
      r - the red component
      g - the green component
      b - the blue component
      a - the alpha component
      Returns:
      this color for chaining

    • subtract

      public ColorRGBA subtract(ReadOnlyColorRGBA source, ColorRGBA store)
      Subtracts the values of the given source color from those of this color and returns them in store.
      Specified by:
      subtract in interface ReadOnlyColorRGBA
      Parameters:
      source - the source color
      store - the color to store the result in for return. If null, a new color object is created and returned.
      Returns:
      (this.r - source.r, this.g - source.g, this.b - source.b, this.a - source.a)
      Throws:
      NullPointerException - if source is null.

    • subtractLocal

      public ColorRGBA subtractLocal(ReadOnlyColorRGBA source)
      Decrements the values of this color by the r, g, b and a values from the given source color.
      Parameters:
      source - the source color
      Returns:
      this color for chaining
      Throws:
      NullPointerException - if source is null.

    • multiply

      public ColorRGBA multiply(float scalar, ColorRGBA store)
      Multiplies the values of this color by the given scalar value and returns the result in store.
      Specified by:
      multiply in interface ReadOnlyColorRGBA
      Parameters:
      scalar - the scalar value
      store - the color to store the result in for return. If null, a new color object is created and returned.
      Returns:
      a new color (this.r * scalar, this.g * scalar, this.b * scalar, this.a * scalar)

    • multiplyLocal

      public ColorRGBA multiplyLocal(float scalar)
      Internally modifies the values of this color by multiplying them each by the given scalar value.
      Parameters:
      scalar - the scalar value
      Returns:
      this color for chaining

    • multiply

      public ColorRGBA multiply(ReadOnlyColorRGBA scale, ColorRGBA store)
      Multiplies the values of this color by the given scalar value and returns the result in store.
      Specified by:
      multiply in interface ReadOnlyColorRGBA
      Parameters:
      scale - the scale values
      store - the color to store the result in for return. If null, a new color object is created and returned.
      Returns:
      a new color (this.r * scale.r, this.g * scale.g, this.b * scale.b, this.a * scale.a)

    • multiplyLocal

      public ColorRGBA multiplyLocal(ReadOnlyColorRGBA scale)
      Internally modifies the values of this color by multiplying them each by the given scale values.
      Parameters:
      scale - the scale values
      Returns:
      this color for chaining

    • divide

      public ColorRGBA divide(float scalar, ColorRGBA store)
      Divides the values of this color by the given scalar value and returns the result in store.
      Specified by:
      divide in interface ReadOnlyColorRGBA
      Parameters:
      scalar - the scalar value
      store - the color to store the result in for return. If null, a new color object is created and returned.
      Returns:
      a new color (this.r / scalar, this.g / scalar, this.b / scalar, this.a / scalar)

    • divideLocal

      public ColorRGBA divideLocal(float scalar)
      Internally modifies the values of this color by dividing them each by the given scalar value.
      Parameters:
      scalar - the scalar value
      Returns:
      this color for chaining
      Throws:
      ArithmeticException - if scalar is 0

    • divide

      public ColorRGBA divide(ReadOnlyColorRGBA scale, ColorRGBA store)
      Divides the values of this color by the given scale values and returns the result in store.
      Specified by:
      divide in interface ReadOnlyColorRGBA
      Parameters:
      scale - the scale values
      store - the color to store the result in for return. If null, a new color object is created and returned.
      Returns:
      a new color (this.r / scale.r, this.g / scale.g, this.b / scale.b, this.a / scale.a)

    • divideLocal

      public ColorRGBA divideLocal(ReadOnlyColorRGBA scale)
      Internally modifies the values of this color by dividing them each by the given scale values.
      Parameters:
      scale - the scale values
      Returns:
      this color for chaining

    • lerp

      public ColorRGBA lerp(ReadOnlyColorRGBA endColor, float scalar, ColorRGBA store)
      Performs a linear interpolation between this color and the given end color, using the given scalar as a percent. iow, if changeAmnt is closer to 0, the result will be closer to the current value of this color and if it is closer to 1, the result will be closer to the end value.
      Specified by:
      lerp in interface ReadOnlyColorRGBA
      Parameters:
      endColor - the end color
      scalar - the scalar value
      store - the color to store the result in for return. If null, a new color object is created and returned.
      Returns:
      a new mutable color as described above.
      Throws:
      NullPointerException - if endVec is null.

    • lerpLocal

      public ColorRGBA lerpLocal(ReadOnlyColorRGBA endColor, float scalar)
      Performs a linear interpolation between this color and the given end color, using the given scalar as a percent. iow, if changeAmnt is closer to 0, the result will be closer to the current value of this color and if it is closer to 1, the result will be closer to the end value. The result is stored back in this color.
      Parameters:
      endColor - the end color
      scalar - the scalar value
      Returns:
      this color for chaining
      Throws:
      NullPointerException - if endVec is null.

    • lerp

      public static ColorRGBA lerp(ReadOnlyColorRGBA beginColor, ReadOnlyColorRGBA endColor, float scalar, ColorRGBA store)
      Performs a linear interpolation between the given begin and end colors, using the given scalar as a percent. iow, if changeAmnt is closer to 0, the result will be closer to the begin value and if it is closer to 1, the result will be closer to the end value.
      Parameters:
      beginColor - the begin color
      endColor - the end color
      scalar - the scalar as a percent.
      store - the color to store the result in for return. If null, a new color object is created and returned.
      Returns:
      a new mutable color as described above.
      Throws:
      NullPointerException - if beginVec or endVec are null.

    • lerpLocal

      public ColorRGBA lerpLocal(ReadOnlyColorRGBA beginColor, ReadOnlyColorRGBA endColor, float scalar)
      Performs a linear interpolation between the given begin and end colors, using the given scalar as a percent. iow, if scalar is closer to 0, the result will be closer to the begin value and if it is closer to 1, the result will be closer to the end value. The result is stored back in this color.
      Parameters:
      beginColor - the begin color
      endColor - the end color
      scalar - the scalar as a percent.
      Returns:
      this color for chaining
      Throws:
      NullPointerException - if beginVec or endVec are null.

    • isValid

      public static boolean isValid(ReadOnlyColorRGBA color)
      Check a color... if it is null or its values are NaN or infinite, return false. Else return true.
      Parameters:
      color - the color to check
      Returns:
      true or false as stated above.

    • toString

      public String toString()
      Overrides:
      toString in class Object
      Returns:
      the string representation of this color.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
      Returns:
      returns a unique code for this color object based on its values. If two colors are numerically equal, they will return the same hash code value.

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object
      Parameters:
      o - the object to compare for equality
      Returns:
      true if this color and the provided color have the same r, g, b and a values.

    • clone

      public ColorRGBA clone()
      Specified by:
      clone in interface ReadOnlyColorRGBA
      Overrides:
      clone in class Object

    • getClassTag

      public Class<? extends ColorRGBA> getClassTag()
      Specified by:
      getClassTag in interface Savable

    • write

      public void write(OutputCapsule capsule) throws IOException
      Specified by:
      write in interface Savable
      Throws:
      IOException

    • read

      public void read(InputCapsule capsule) throws IOException
      Specified by:
      read in interface Savable
      Throws:
      IOException

    • readExternal

      public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException
      Used with serialization. Not to be called manually.
      Specified by:
      readExternal in interface Externalizable
      Parameters:
      in - ObjectInput
      Throws:
      IOException - if something wrong happens while reading the float values
      ClassNotFoundException - if a class is not found

    • writeExternal

      public void writeExternal(ObjectOutput out) throws IOException
      Used with serialization. Not to be called manually.
      Specified by:
      writeExternal in interface Externalizable
      Parameters:
      out - ObjectOutput
      Throws:
      IOException - exception

    • fetchTempInstance

      public static final ColorRGBA fetchTempInstance()
      Returns:
      An instance of ColorRGBA that is intended for temporary use in calculations and so forth. Multiple calls to the method should return instances of this class that are not currently in use.

    • releaseTempInstance

      public static final void releaseTempInstance(ColorRGBA color)
      Releases a ColorRGBA back to be used by a future call to fetchTempInstance. TAKE CARE: this ColorRGBA object should no longer have other classes referencing it or "Bad Things" will happen.
      Parameters:
      color - the ColorRGBA to release.

    • parseColor

      public static ColorRGBA parseColor(String colorString, ColorRGBA store)
      Parses the given string for a color value. Currently we support hex notation - # followed by 1, 2, 3, 4, 6, or 8 chars 0-9A-F.
      • chars: pattern - notes
      • 1: V - RGB is parsed as val/15, A=1
      • 2: VA - RGB is parsed as V/15, A as A/15
      • 3: RGB - RGB is parsed as R/15, G/15, B/15, A=1
      • 4: RGB - RGBA are parsed as R/15, G/15, B/15, A/15
      • 6: RRGGBB - RGB is parsed as RR/255, GG/255, BB/255, A=1
      • 8: RRGGBBAA - RGBA is parsed as RR/255, GG/255, BB/255, AA/255
      Parameters:
      colorString - the color string
      store - the object used to store the result if not null
      Returns:
      the parsed color