From 6b96a6f282ff434ca7e1e0656d7c8542ff5b4484 Mon Sep 17 00:00:00 2001 From: "sha..rd" Date: Sat, 11 Jun 2011 22:26:58 +0000 Subject: [PATCH] * Javadocs for com.jme3.light git-svn-id: https://jmonkeyengine.googlecode.com/svn/trunk@7585 75d07b2b-3a1a-0410-a2c5-0572b91ccdca --- .../src/core/com/jme3/light/AmbientLight.java | 10 +++ .../core/com/jme3/light/DirectionalLight.java | 17 +++- engine/src/core/com/jme3/light/Light.java | 81 +++++++++++++++++-- engine/src/core/com/jme3/light/LightList.java | 25 ++++++ .../src/core/com/jme3/light/PointLight.java | 42 +++++++++- engine/src/core/com/jme3/light/package.html | 23 ++++++ 6 files changed, 185 insertions(+), 13 deletions(-) create mode 100644 engine/src/core/com/jme3/light/package.html diff --git a/engine/src/core/com/jme3/light/AmbientLight.java b/engine/src/core/com/jme3/light/AmbientLight.java index 3fc9be061..cb7a8827d 100644 --- a/engine/src/core/com/jme3/light/AmbientLight.java +++ b/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. + *

+ * 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; +/** + * LightList is used internally by {@link Spatial}s to manage + * lights that are attached to them. + * + * @author Kirill Vainer + */ public final class LightList implements Iterable, Savable, Cloneable { private Light[] list, tlist; @@ -76,6 +82,11 @@ public final class LightList implements Iterable, Savable, Cloneable { public LightList(){ } + /** + * Creates a LightList 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, 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, 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, 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 iterator() { return new Iterator(){ diff --git a/engine/src/core/com/jme3/light/PointLight.java b/engine/src/core/com/jme3/light/PointLight.java index b38523e4d..93bc9fa7d 100644 --- a/engine/src/core/com/jme3/light/PointLight.java +++ b/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. + *

+ * 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 @@ + + + + + + + + + +The com.jme3.light package contains various lights that can be placed +in a scene. +

+There are 3 types of lights currently supported in jMonkeyEngine: +

+ + +