From c86c692ae9220ab75fef382568f8c34091c23f59 Mon Sep 17 00:00:00 2001 From: "rem..om" Date: Tue, 18 Dec 2012 16:46:21 +0000 Subject: [PATCH] Applied Javadoc patch for ColorRGBA thanks to jonathan.pikalek http://code.google.com/p/jmonkeyengine/issues/detail?id=557&can=6&colspec=ID%20Type%20Status%20Component%20Priority%20Difficulty%20Product%20Milestone%20Owner%20Summary git-svn-id: https://jmonkeyengine.googlecode.com/svn/trunk@10036 75d07b2b-3a1a-0410-a2c5-0572b91ccdca --- engine/src/core/com/jme3/math/ColorRGBA.java | 244 +++++++++++-------- 1 file changed, 145 insertions(+), 99 deletions(-) diff --git a/engine/src/core/com/jme3/math/ColorRGBA.java b/engine/src/core/com/jme3/math/ColorRGBA.java index 7d57624fb..347bec609 100644 --- a/engine/src/core/com/jme3/math/ColorRGBA.java +++ b/engine/src/core/com/jme3/math/ColorRGBA.java @@ -51,86 +51,85 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable static final long serialVersionUID = 1; /** - * the color black (0,0,0). + * The color black (0,0,0). */ public static final ColorRGBA Black = new ColorRGBA(0f, 0f, 0f, 1f); /** - * the color white (1,1,1). + * The color white (1,1,1). */ public static final ColorRGBA White = new ColorRGBA(1f, 1f, 1f, 1f); /** - * the color gray (.2,.2,.2). + * The color gray (.2,.2,.2). */ public static final ColorRGBA DarkGray = new ColorRGBA(0.2f, 0.2f, 0.2f, 1.0f); /** - * the color gray (.5,.5,.5). + * The color gray (.5,.5,.5). */ public static final ColorRGBA Gray = new ColorRGBA(0.5f, 0.5f, 0.5f, 1.0f); /** - * the color gray (.8,.8,.8). + * The color gray (.8,.8,.8). */ public static final ColorRGBA LightGray = new ColorRGBA(0.8f, 0.8f, 0.8f, 1.0f); /** - * the color red (1,0,0). + * The color red (1,0,0). */ public static final ColorRGBA Red = new ColorRGBA(1f, 0f, 0f, 1f); /** - * the color green (0,1,0). + * The color green (0,1,0). */ public static final ColorRGBA Green = new ColorRGBA(0f, 1f, 0f, 1f); /** - * the color blue (0,0,1). + * The color blue (0,0,1). */ public static final ColorRGBA Blue = new ColorRGBA(0f, 0f, 1f, 1f); /** - * the color yellow (1,1,0). + * The color yellow (1,1,0). */ public static final ColorRGBA Yellow = new ColorRGBA(1f, 1f, 0f, 1f); /** - * the color magenta (1,0,1). + * The color magenta (1,0,1). */ public static final ColorRGBA Magenta = new ColorRGBA(1f, 0f, 1f, 1f); /** - * the color cyan (0,1,1). + * The color cyan (0,1,1). */ public static final ColorRGBA Cyan = new ColorRGBA(0f, 1f, 1f, 1f); /** - * the color orange (251/255, 130/255,0). + * The color orange (251/255, 130/255,0). */ public static final ColorRGBA Orange = new ColorRGBA(251f / 255f, 130f / 255f, 0f, 1f); /** - * the color brown (65/255, 40/255, 25/255). + * The color brown (65/255, 40/255, 25/255). */ public static final ColorRGBA Brown = new ColorRGBA(65f / 255f, 40f / 255f, 25f / 255f, 1f); /** - * the color pink (1, 0.68, 0.68). + * The color pink (1, 0.68, 0.68). */ public static final ColorRGBA Pink = new ColorRGBA(1f, 0.68f, 0.68f, 1f); /** - * the black color with no alpha (0, 0, 0, 0); + * The black color with no alpha (0, 0, 0, 0). */ public static final ColorRGBA BlackNoAlpha = new ColorRGBA(0f, 0f, 0f, 0f); /** - * The red component of the color. + * The red component of the color. 0 is none and 1 is maximum red. */ public float r; /** - * The green component of the color. + * The green component of the color. 0 is none and 1 is maximum green. */ public float g; /** - * the blue component of the color. + * The blue component of the color. 0 is none and 1 is maximum blue. */ public float b; /** - * the alpha component of the color. 0 is transparent and 1 is opaque + * The alpha component of the color. 0 is transparent and 1 is opaque. */ public float a; /** * Constructor instantiates a new ColorRGBA object. This * color is the default "white" with all values 1. - * */ public ColorRGBA() { r = g = b = a = 1.0f; @@ -140,10 +139,10 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable * Constructor instantiates a new ColorRGBA object. The * values are defined as passed parameters. These values are then clamped * to insure that they are between 0 and 1. - * @param r the red component of this color. - * @param g the green component of this color. - * @param b the blue component of this color. - * @param a the alpha component of this color. + * @param r The red component of this color. + * @param g The green component of this ColorRGBA. + * @param b The blue component of this ColorRGBA. + * @param a The alpha component of this ColorRGBA. */ public ColorRGBA(float r, float g, float b, float a) { this.r = r; @@ -155,7 +154,7 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable /** * Copy constructor creates a new ColorRGBA object, based on * a provided color. - * @param rgba the ColorRGBA object to copy. + * @param rgba The ColorRGBA object to copy. */ public ColorRGBA(ColorRGBA rgba) { this.a = rgba.a; @@ -165,14 +164,13 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable } /** + * set sets the RGBA values of this ColorRGBA. The + * values are then clamped to insure that they are between 0 and 1. * - * set sets the RGBA values of this color. The values are then - * clamped to insure that they are between 0 and 1. - * - * @param r the red component of this color. - * @param g the green component of this color. - * @param b the blue component of this color. - * @param a the alpha component of this color. + * @param r The red component of this color. + * @param g The green component of this color. + * @param b The blue component of this color. + * @param a The alpha component of this color. * @return this */ public ColorRGBA set(float r, float g, float b, float a) { @@ -184,10 +182,10 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable } /** - * set sets the values of this color to those set by a parameter - * color. + * set sets the values of this ColorRGBA to those + * set by a parameter color. * - * @param rgba ColorRGBA the color to set this color to. + * @param rgba The color to set this ColorRGBA to. * @return this */ public ColorRGBA set(ColorRGBA rgba) { @@ -209,7 +207,6 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable * clamp insures that all values are between 0 and 1. If any * are less than 0 they are set to zero. If any are more than 1 they are * set to one. - * */ public void clamp() { if (r < 0) { @@ -238,20 +235,20 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable } /** - * - * getColorArray retrieves the color values of this object as - * a four element float array. - * @return the float array that contains the color elements. + * getColorArray retrieves the color values of this + * ColorRGBA as a four element float array in the + * order: r,g,b,a. + * @return The float array that contains the color components. */ public float[] getColorArray() { return new float[]{r, g, b, a}; } /** - * Stores the current r/g/b/a values into the tempf array. The tempf array must have a + * Stores the current r,g,b,a values into the given array. The given array must have a * length of 4 or greater, or an array index out of bounds exception will be thrown. - * @param store The array of floats to store the values into. - * @return The float[] after storage. + * @param store The float array to store the values into. + * @return The float array after storage. */ public float[] getColorArray(float[] store) { store[0] = r; @@ -261,28 +258,45 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable return store; } + /** + * Retrieves the alpha component value of this ColorRGBA. + * @return The alpha component value. + */ public float getAlpha() { return a; } + /** + * Retrieves the red component value of this ColorRGBA. + * @return The red component value. + */ public float getRed() { return r; } + /** + * Retrieves the blue component value of this ColorRGBA. + * @return The blue component value. + */ public float getBlue() { return b; } + /** + * Retrieves the green component value of this ColorRGBA. + * @return The green component value. + */ public float getGreen() { return g; } /** - * Sets this color to the interpolation by changeAmnt from this to the finalColor + * Sets this ColorRGBA to the interpolation by changeAmnt from + * this to the finalColor: * this=(1-changeAmnt)*this + changeAmnt * finalColor - * @param finalColor The final color to interpolate towards - * @param changeAmnt An amount between 0.0 - 1.0 representing a precentage - * change from this towards finalColor + * @param finalColor The final color to interpolate towards. + * @param changeAmnt An amount between 0.0 - 1.0 representing a percentage + * change from this towards finalColor. */ public void interpolate(ColorRGBA finalColor, float changeAmnt) { this.r = (1 - changeAmnt) * this.r + changeAmnt * finalColor.r; @@ -292,12 +306,13 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable } /** - * Sets this color to the interpolation by changeAmnt from beginColor to finalColor + * Sets this ColorRGBA to the interpolation by changeAmnt from + * beginColor to finalColor: * this=(1-changeAmnt)*beginColor + changeAmnt * finalColor - * @param beginColor The begining color (changeAmnt=0) - * @param finalColor The final color to interpolate towards (changeAmnt=1) + * @param beginColor The begining color (changeAmnt=0). + * @param finalColor The final color to interpolate towards (changeAmnt=1). * @param changeAmnt An amount between 0.0 - 1.0 representing a precentage - * change from beginColor towards finalColor + * change from beginColor towards finalColor. */ public void interpolate(ColorRGBA beginColor, ColorRGBA finalColor, float changeAmnt) { this.r = (1 - changeAmnt) * beginColor.r + changeAmnt * finalColor.r; @@ -307,11 +322,9 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable } /** - * * randomColor is a utility method that generates a random - * color. - * - * @return a random color. + * opaque color. + * @return a random ColorRGBA with an alpha set to 1. */ public static ColorRGBA randomColor() { ColorRGBA rVal = new ColorRGBA(0, 0, 0, 1); @@ -322,31 +335,33 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable } /** - * Multiplies each r/g/b/a of this color by the r/g/b/a of the given color and - * returns the result as a new ColorRGBA. Used as a way of combining colors and lights. - * @param c The color to multiply. - * @return The new ColorRGBA. this*c + * Multiplies each r,g,b,a of this ColorRGBA by the corresponding + * r,g,b,a of the given color and returns the result as a new ColorRGBA. + * Used as a way of combining colors and lights. + * @param c The color to multiply by. + * @return The new ColorRGBA. this*c */ public ColorRGBA mult(ColorRGBA c) { return new ColorRGBA(c.r * r, c.g * g, c.b * b, c.a * a); } /** - * Multiplies each r/g/b/a of this color by the given scalar and - * returns the result as a new ColorRGBA. Used as a way of making colors dimmer - * or brighter.. - * @param scalar The scalar to multiply. - * @return The new ColorRGBA. this*scalar + * Multiplies each r,g,b,a of this ColorRGBA by the given scalar and + * returns the result as a new ColorRGBA. + * Used as a way of making colors dimmer or brighter. + * @param scalar The scalar to multiply by. + * @return The new ColorRGBA. this*scalar */ public ColorRGBA mult(float scalar) { return new ColorRGBA(scalar * r, scalar * g, scalar * b, scalar * a); } /** - * Multiplies each r/g/b/a of this color by the r/g/b/a of the given color and - * returns the result as a new ColorRGBA. Used as a way of combining colors and lights. - * @param scalar scalar to multiply with - * @return The new ColorRGBA. this*c + * Multiplies each r,g,b,a of this ColorRGBA by the given scalar and + * returns the result (this). + * Used as a way of making colors dimmer or brighter. + * @param scalar The scalar to multiply by. + * @return this*c */ public ColorRGBA multLocal(float scalar) { this.r *= scalar; @@ -357,20 +372,22 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable } /** - * Adds each r/g/b/a of this color by the r/g/b/a of the given color and - * returns the result as a new ColorRGBA. + * Adds each r,g,b,a of this ColorRGBA by the corresponding + * r,g,b,a of the given color and returns the result as a new ColorRGBA. + * Used as a way of combining colors and lights. * @param c The color to add. - * @return The new ColorRGBA. this+c + * @return The new ColorRGBA. this+c */ public ColorRGBA add(ColorRGBA c) { return new ColorRGBA(c.r + r, c.g + g, c.b + b, c.a + a); } /** - * Multiplies each r/g/b/a of this color by the r/g/b/a of the given color and - * returns the result as a new ColorRGBA. Used as a way of combining colors and lights. - * @param c The color to multiply. - * @return The new ColorRGBA. this*c + * Adds each r,g,b,a of this ColorRGBA by the r,g,b,a the given + * color and returns the result (this). + * Used as a way of combining colors and lights. + * @param c The color to add. + * @return this+c */ public ColorRGBA addLocal(ColorRGBA c) { set(c.r + r, c.g + g, c.b + b, c.a + a); @@ -378,11 +395,12 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable } /** - * toString returns the string representation of this color. + * toString returns the string representation of this ColorRGBA. * The format of the string is:
* : [R=RR.RRRR, G=GG.GGGG, B=BB.BBBB, A=AA.AAAA] - * @return the string representation of this color. + * @return The string representation of this ColorRGBA. */ + @Override public String toString() { return "Color[" + r + ", " + g + ", " + b + ", " + a + "]"; } @@ -397,12 +415,10 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable } /** - * Saves this ColorRGBA into the given float[] object. - * - * @param floats - * The float[] to take this ColorRGBA. If null, a new float[4] is - * created. - * @return The array, with R, G, B, A float values in that order + * Saves this ColorRGBA into the given float array. + * @param floats The float array to take this ColorRGBA. + * If null, a new float[4] is created. + * @return The array, with r,g,b,a float values in that order. */ public float[] toArray(float[] floats) { if (floats == null) { @@ -416,12 +432,13 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable } /** - * equals returns true if this color is logically equivalent - * to a given color. That is, if the values of the two colors are the same. + * equals returns true if this ColorRGBA is logically equivalent + * to a given color. That is, if all the components of the two colors are the same. * False is returned otherwise. - * @param o the object to compare againts. + * @param o The object to compare against. * @return true if the colors are equal, false otherwise. */ + @Override public boolean equals(Object o) { if (!(o instanceof ColorRGBA)) { return false; @@ -448,11 +465,12 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable } /** - * hashCode returns a unique code for this color object based - * on it's values. If two colors are logically equivalent, they will return + * hashCode returns a unique code for this ColorRGBA based + * on its values. If two colors are logically equivalent, they will return * the same hash code value. - * @return the hash code value of this color. + * @return The hash code value of this ColorRGBA. */ + @Override public int hashCode() { int hash = 37; hash += 37 * hash + Float.floatToIntBits(r); @@ -477,7 +495,11 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable b = capsule.readFloat("b", 0); a = capsule.readFloat("a", 0); } - + /** + * Retrieves the component values of this ColorRGBA as + * a four element byte array in the order: r,g,b,a. + * @return the byte array that contains the color components. + */ public byte[] asBytesRGBA() { byte[] store = new byte[4]; store[0] = (byte) ((int) (r * 255) & 0xFF); @@ -487,6 +509,12 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable return store; } + /** + * Retrieves the component values of this ColorRGBA as an + * int in a,r,g,b order. + * Bits 24-31 are alpha, 16-23 are red, 8-15 are green, 0-7 are blue. + * @return The integer representation of this ColorRGBA in a,r,g,b order. + */ public int asIntARGB() { int argb = (((int) (a * 255) & 0xFF) << 24) | (((int) (r * 255) & 0xFF) << 16) @@ -495,6 +523,12 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable return argb; } + /** + * Retrieves the component values of this ColorRGBA as an + * int in r,g,b,a order. + * Bits 24-31 are red, 16-23 are green, 8-15 are blue, 0-7 are alpha. + * @return The integer representation of this ColorRGBA in r,g,b,a order. + */ public int asIntRGBA() { int rgba = (((int) (r * 255) & 0xFF) << 24) | (((int) (g * 255) & 0xFF) << 16) @@ -502,7 +536,12 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable | (((int) (a * 255) & 0xFF)); return rgba; } - + /** + * Retrieves the component values of this ColorRGBA as an + * int in a,b,g,r order. + * Bits 24-31 are alpha, 16-23 are blue, 8-15 are green, 0-7 are red. + * @return The integer representation of this ColorRGBA in a,b,g,r order. + */ public int asIntABGR() { int abgr = (((int) (a * 255) & 0xFF) << 24) | (((int) (b * 255) & 0xFF) << 16) @@ -510,14 +549,23 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable | (((int) (r * 255) & 0xFF)); return abgr; } - + /** + * Sets the component values of this ColorRGBA with the given + * combined ARGB int. + * Bits 24-31 are alpha, bits 16-23 are red, bits 8-15 are green, bits 0-7 are blue. + * @param color The integer ARGB value used to set this ColorRGBA. + */ public void fromIntARGB(int color) { a = ((byte) (color >> 24) & 0xFF) / 255f; r = ((byte) (color >> 16) & 0xFF) / 255f; g = ((byte) (color >> 8) & 0xFF) / 255f; b = ((byte) (color) & 0xFF) / 255f; } - + /** + * Sets the RGBA values of this ColorRGBA with the given combined RGBA value + * Bits 24-31 are red, bits 16-23 are green, bits 8-15 are blue, bits 0-7 are alpha. + * @param color The integer RGBA value used to set this object. + */ public void fromIntRGBA(int color) { r = ((byte) (color >> 24) & 0xFF) / 255f; g = ((byte) (color >> 16) & 0xFF) / 255f; @@ -526,22 +574,20 @@ public final class ColorRGBA implements Savable, Cloneable, java.io.Serializable } /** - * Transform the current ColorRGBA to a Vector3f using + * Transform this ColorRGBA to a Vector3f using * x = r, y = g, z = b. The Alpha value is not used. - * * This method is useful to use for shaders assignment. - * @return A Vector3f containing the RGB value of current color definition. + * @return A Vector3f containing the RGB value of this ColorRGBA. */ public Vector3f toVector3f() { return new Vector3f(r, g, b); } /** - * Transform the current ColorRGBA to a Vector4f using + * Transform this ColorRGBA to a Vector4f using * x = r, y = g, z = b, w = a. - * * This method is useful to use for shaders assignment. - * @return A Vector4f containing the RGBA value of current color definition. + * @return A Vector4f containing the RGBA value of this ColorRGBA. */ public Vector4f toVector4f() { return new Vector4f(r, g, b, a);