+ * Ambient lights are uneffected by the surface normal, and are constant
+ * regardless of the model's location. The material's ambient color is
+ * multiplied by the ambient light color to get the final ambient color of
+ * an object.
+ *
+ * @author Kirill Vainer
+ */
public class AmbientLight extends Light {
@Override
diff --git a/engine/src/core/com/jme3/light/DirectionalLight.java b/engine/src/core/com/jme3/light/DirectionalLight.java
index 6b59f79a1..306d804f7 100644
--- a/engine/src/core/com/jme3/light/DirectionalLight.java
+++ b/engine/src/core/com/jme3/light/DirectionalLight.java
@@ -41,7 +41,11 @@ import com.jme3.scene.Spatial;
import java.io.IOException;
/**
- * A light coming from a certain direction in world space. E.g sun or moon light.
+ * DirectionalLight is a light coming from a certain direction in world space.
+ * E.g sun or moon light.
+ *
+ * Directional lights have no specific position in the scene, they always + * come from their direction regardless of where an object is placed. */ public class DirectionalLight extends Light { @@ -53,7 +57,11 @@ public class DirectionalLight extends Light { } /** + * Returns the direction vector of the light. + * * @return The direction vector of the light. + * + * @see DirectionalLight#setDirection(com.jme3.math.Vector3f) */ public Vector3f getDirection() { return direction; @@ -61,8 +69,11 @@ public class DirectionalLight extends Light { /** * Sets the direction of the light. - * @param dir Represents the vector direction the light is coming from. - * (1f, 0, 0) would represent a directional light coming from the X axis. + *
+ * Represents the vector direction the light is coming from. + * (1, 0, 0) would represent a directional light coming from the X axis. + * + * @param dir the direction of the light. */ public void setDirection(Vector3f dir){ direction.set(dir); diff --git a/engine/src/core/com/jme3/light/Light.java b/engine/src/core/com/jme3/light/Light.java index d724c97e1..712c45ab1 100644 --- a/engine/src/core/com/jme3/light/Light.java +++ b/engine/src/core/com/jme3/light/Light.java @@ -43,14 +43,42 @@ import java.io.IOException; /** * Abstract class for representing a light source. + *
+ * All light source types have a color. */ public abstract class Light implements Savable, Cloneable { - public static enum Type { + /** + * Describes the light type. + */ + public enum Type { + /** + * Directional light + * + * @see DirectionalLight + */ Directional(0), + + /** + * Point light + * + * @see PointLight + */ Point(1), + + /** + * Spot light. + *
+ * Not supported by jMonkeyEngine
+ */
Spot(2),
+
+ /**
+ * Ambient light
+ *
+ * @see AmbientLight
+ */
Ambient(3);
private int typeId;
@@ -59,6 +87,10 @@ public abstract class Light implements Savable, Cloneable {
this.typeId = type;
}
+ /**
+ * Returns an index for the light type
+ * @return an index for the light type
+ */
public int getId(){
return typeId;
}
@@ -73,14 +105,18 @@ public abstract class Light implements Savable, Cloneable {
protected transient float lastDistance = -1;
/**
- * If light is disabled, it will not take effect.
+ * If light is disabled, it will not have any
*/
protected boolean enabled = true;
- /** The light's name. */
+ /**
+ * The light name.
+ */
protected String name;
/**
+ * Returns the color of the light.
+ *
* @return The color of the light.
*/
public ColorRGBA getColor() {
@@ -88,21 +124,24 @@ public abstract class Light implements Savable, Cloneable {
}
/**
- * This method sets the light's name.
- * @param name the light's name
+ * This method sets the light name.
+ *
+ * @param name the light name
*/
public void setName(String name) {
this.name = name;
}
/**
- * This method returns the light's name.
- * @return the light's name
+ * Return the light name.
+ *
+ * @return the light name
*/
public String getName() {
return name;
}
+ /*
public void setLastDistance(float lastDistance){
this.lastDistance = lastDistance;
}
@@ -110,14 +149,29 @@ public abstract class Light implements Savable, Cloneable {
public float getLastDistance(){
return lastDistance;
}
+ */
+ /**
+ * Sets the light color.
+ *
+ * @param color the light color.
+ */
public void setColor(ColorRGBA color){
this.color.set(color);
}
+ /**
+ * Returns true if the light is enabled
+ *
+ * @return true if the light is enabled
+ *
+ * @see Light#setEnabled(boolean)
+ */
+ /*
public boolean isEnabled() {
return enabled;
}
+ */
@Override
public Light clone(){
@@ -142,7 +196,18 @@ public abstract class Light implements Savable, Cloneable {
name = ic.readString("name", null);
}
- public abstract void computeLastDistance(Spatial owner);
+ /**
+ * Used internally to compute the last distance value.
+ */
+ protected abstract void computeLastDistance(Spatial owner);
+
+ /**
+ * Returns the light type
+ *
+ * @return the light type
+ *
+ * @see Type
+ */
public abstract Type getType();
}
diff --git a/engine/src/core/com/jme3/light/LightList.java b/engine/src/core/com/jme3/light/LightList.java
index 394e22cbc..5c311fae9 100644
--- a/engine/src/core/com/jme3/light/LightList.java
+++ b/engine/src/core/com/jme3/light/LightList.java
@@ -47,6 +47,12 @@ import java.util.Iterator;
import java.util.List;
import java.util.NoSuchElementException;
+/**
+ *
+ * In addition to a position, point lights also have a radius which
+ * can be used to attenuate the influence of the light depending on the
+ * distance between the light and the effected object.
+ *
*/
public class PointLight extends Light {
@@ -62,19 +66,53 @@ public class PointLight extends Light {
}
}
+ /**
+ * Returns the world space position of the light.
+ *
+ * @return the world space position of the light.
+ *
+ * @see PointLight#setPosition(com.jme3.math.Vector3f)
+ */
public Vector3f getPosition() {
return position;
}
+ /**
+ * Set the world space position of the light.
+ *
+ * @param position the world space position of the light.
+ */
public void setPosition(Vector3f position){
this.position.set(position);
}
+ /**
+ * Returns the radius of the light influence. A radius of 0 means
+ * the light has no attenuation.
+ *
+ * @return the radius of the light
+ */
public float getRadius(){
return radius;
}
+ /**
+ * Set the radius of the light influence.
+ *
+ * Setting a non-zero radius indicates the light should use attenuation.
+ * If a pixel's distance to this light's position
+ * is greater than the light's radius, then the pixel will not be
+ * effected by this light, if the distance is less than the radius, then
+ * the magnitude of the influence is equal to distance / radius.
+ *
+ * @param radius the radius of the light influence.
+ *
+ * @throws IllegalArgumentException If radius is negative
+ */
public void setRadius(float radius){
+ if (radius < 0) {
+ throw new IllegalArgumentException("Light radius cannot be negative");
+ }
this.radius = radius;
}
diff --git a/engine/src/core/com/jme3/light/package.html b/engine/src/core/com/jme3/light/package.html
new file mode 100644
index 000000000..ac6581609
--- /dev/null
+++ b/engine/src/core/com/jme3/light/package.html
@@ -0,0 +1,23 @@
+
+
+
+
+There are 3 types of lights currently supported in jMonkeyEngine:
+LightList is used internally by {@link Spatial}s to manage
+ * lights that are attached to them.
+ *
+ * @author Kirill Vainer
+ */
public final class LightList implements IterableLightList for the given {@link Spatial}.
+ *
+ * @param owner The spatial owner
+ */
public LightList(Spatial owner) {
listSize = 0;
list = new Light[DEFAULT_SIZE];
@@ -84,6 +95,10 @@ public final class LightList implements Iterablecom.jme3.light package contains various lights that can be placed
+in a scene.
+
+
+
+
+