* Javadocs for com.jme3.light

git-svn-id: https://jmonkeyengine.googlecode.com/svn/trunk@7585 75d07b2b-3a1a-0410-a2c5-0572b91ccdca

engine/src/core/com/jme3/light/AmbientLight.java

@@ -2,6 +2,16 @@ package com.jme3.light;
 
 import com.jme3.scene.Spatial;
 
+/**
+ * An ambient light adds a constant color to the scene.
+ * <p>
+ * 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

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.
+ * <code>DirectionalLight</code> is a light coming from a certain direction in world space. 
+ * E.g sun or moon light.
+ * <p>
+ * 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.
+     * <p>
-     * (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);

engine/src/core/com/jme3/light/Light.java

@@ -43,14 +43,42 @@ import java.io.IOException;
 
 /**
  * Abstract class for representing a light source.
+ * <p>
+ * 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.
+         * <p>
+         * 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.
+     * This method sets the light name.
-     * @param name the light's name
+     * 
+     * @param name the light name
      */
     public void setName(String name) {
         this.name = name;
     }
 
     /**
-     * This method returns the light's name.
+     * Return the light name.
-     * @return the light's 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();
 
 }

engine/src/core/com/jme3/light/LightList.java

@@ -47,6 +47,12 @@ import java.util.Iterator;
 import java.util.List;
 import java.util.NoSuchElementException;
 
+/**
+ * <code>LightList</code> is used internally by {@link Spatial}s to manage
+ * lights that are attached to them.
+ * 
+ * @author Kirill Vainer
+ */
 public final class LightList implements Iterable<Light>, Savable, Cloneable {
 
     private Light[] list, tlist;
@@ -76,6 +82,11 @@ public final class LightList implements Iterable<Light>, Savable, Cloneable {
     public LightList(){
     }
 
+    /**
+     * Creates a <code>LightList</code> 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 Iterable<Light>, Savable, Cloneable {
         this.owner = owner;
     }
 
+    /**
+     * Set the owner of the LightList. Only used for cloning.
+     * @param owner 
+     */
     public void setOwner(Spatial owner){
         this.owner = owner;
     }
@@ -132,6 +147,11 @@ public final class LightList implements Iterable<Light>, Savable, Cloneable {
         list[listSize] = null;
     }
 
+    /**
+     * Removes the given light from the LightList.
+     * 
+     * @param l the light to remove
+     */
     public void remove(Light l){
         for (int i = 0; i < listSize; i++){
             if (list[i] == l){
@@ -249,6 +269,11 @@ public final class LightList implements Iterable<Light>, Savable, Cloneable {
         }
     }
 
+    /**
+     * Returns an iterator that can be used to iterate over this LightList.
+     * 
+     * @return an iterator that can be used to iterate over this LightList.
+     */
     public Iterator<Light> iterator() {
         return new Iterator<Light>(){
 

engine/src/core/com/jme3/light/PointLight.java

@@ -37,7 +37,6 @@ import com.jme3.export.JmeExporter;
 import com.jme3.export.JmeImporter;
 import com.jme3.export.InputCapsule;
 import com.jme3.export.OutputCapsule;
-import com.jme3.math.ColorRGBA;
 import com.jme3.math.Vector3f;
 import com.jme3.scene.Spatial;
 import java.io.IOException;
@@ -45,7 +44,12 @@ import java.io.IOException;
 /**
  * Represents a point light.
  * A point light emits light from a given position into all directions in space.
- * E.g a lamp or a bright effect.
+ * E.g a lamp or a bright effect. Point light positions are in world space.
+ * <p>
+ * 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.
+     * <p>
+     * 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;
     }
 

engine/src/core/com/jme3/light/package.html

@@ -0,0 +1,23 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+
+<head>
+<title></title>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+</head>
+<body>
+
+The <code>com.jme3.light</code> package contains various lights that can be placed
+in a scene.
+<p>
+There are 3 types of lights currently supported in jMonkeyEngine:
+<ul>
+    <li>Point Light - Point lights emit from a certain location and have a certain influence radius (optional)</li>
+    <li>Directional Light - Directional lights will always appear to emit from a certain direction
+    regardless of an object's position</li>
+    <li>Ambient Light - Ambient lights have no location or direction; 
+        they simply emit a constant color that is applied to the entire scene</li>
+</ul>
+
+</body>
+</html>