* Javadocs for com.jme3.renderer

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

engine/src/core/com/jme3/renderer/Camera.java

@@ -75,6 +75,11 @@ public class Camera implements Savable, Cloneable {
 
     private static final Logger logger = Logger.getLogger(Camera.class.getName());
 
+    /**
+     * The <code>FrustumIntersect</code> enum is returned as a result
+     * of a culling check operation, 
+     * see {@link #contains(com.jme3.bounding.BoundingVolume) }
+     */
     public enum FrustumIntersect {
 
         /**
@@ -93,40 +98,40 @@ public class Camera implements Savable, Cloneable {
          */
         Intersects;
     }
-    //planes of the frustum
+    
     /**
      * LEFT_PLANE represents the left plane of the camera frustum.
      */
-    public static final int LEFT_PLANE = 0;
+    private static final int LEFT_PLANE = 0;
     /**
      * RIGHT_PLANE represents the right plane of the camera frustum.
      */
-    public static final int RIGHT_PLANE = 1;
+    private static final int RIGHT_PLANE = 1;
     /**
      * BOTTOM_PLANE represents the bottom plane of the camera frustum.
      */
-    public static final int BOTTOM_PLANE = 2;
+    private static final int BOTTOM_PLANE = 2;
     /**
      * TOP_PLANE represents the top plane of the camera frustum.
      */
-    public static final int TOP_PLANE = 3;
+    private static final int TOP_PLANE = 3;
     /**
      * FAR_PLANE represents the far plane of the camera frustum.
      */
-    public static final int FAR_PLANE = 4;
+    private static final int FAR_PLANE = 4;
     /**
      * NEAR_PLANE represents the near plane of the camera frustum.
      */
-    public static final int NEAR_PLANE = 5;
+    private static final int NEAR_PLANE = 5;
     /**
      * FRUSTUM_PLANES represents the number of planes of the camera frustum.
      */
-    public static final int FRUSTUM_PLANES = 6;
+    private static final int FRUSTUM_PLANES = 6;
     /**
      * MAX_WORLD_PLANES holds the maximum planes allowed by the system.
      */
-    public static final int MAX_WORLD_PLANES = 6;
-    //the location and orientation of the camera.
+    private static final int MAX_WORLD_PLANES = 6;
+    
     /**
      * Camera's location
      */
@@ -159,12 +164,14 @@ public class Camera implements Savable, Cloneable {
      * Distance from camera to bottom frustum plane.
      */
     protected float frustumBottom;
+    
     //Temporary values computed in onFrustumChange that are needed if a
     //call is made to onFrameChange.
     protected float[] coeffLeft;
     protected float[] coeffRight;
     protected float[] coeffBottom;
     protected float[] coeffTop;
+    
     //view port coordinates
     /**
      * Percent value on display where horizontal viewing starts for this camera.
@@ -190,11 +197,13 @@ public class Camera implements Savable, Cloneable {
      * Array holding the planes that this camera will check for culling.
      */
     protected Plane[] worldPlane;
+    
     /**
      * A mask value set during contains() that allows fast culling of a Node's
      * children.
      */
     private int planeState;
+    
     protected int width;
     protected int height;
     protected boolean viewportChanged = true;
@@ -211,8 +220,7 @@ public class Camera implements Savable, Cloneable {
     protected String name;
 
     /**
-     * Don't use this constructor, use Camera(int width, int height)
-     * This constructor is for serialization only
+     * Serialization only. Do not use.
      */
     public Camera() {
         worldPlane = new Plane[MAX_WORLD_PLANES];
@@ -378,13 +386,13 @@ public class Camera implements Savable, Cloneable {
     /**
      * Resizes this camera's view with the given width and height. This is
      * similar to constructing a new camera, but reusing the same Object. This
-     * method is called by an associated renderer to notify the camera of
+     * method is called by an associated {@link RenderManager} to notify the camera of
      * changes in the display dimensions.
      *
-     * @param width
-     *            the view width
-     * @param height
-     *            the view height
+     * @param width the view width
+     * @param height the view height
+     * @param fixAspect If true, the camera's aspect ratio will be recomputed.
+     * Recomputing the aspect ratio requires changing the frustum values.
      */
     public void resize(int width, int height, boolean fixAspect) {
         this.width = width;
@@ -621,26 +629,6 @@ public class Camera implements Savable, Cloneable {
         onFrameChange();
     }
 
-    /**
-     * <code>setDirection</code> sets the direction vector of the camera.
-     * This operation doesn't change the left and up vectors of the camera,
-     * which must change if the camera is to actually face the given
-     * direction. In most cases the method {@link Camera#lookAtDirection(com.jme3.math.Vector3f, com.jme3.math.Vector3f) }
-     * should be used instead.
-     *
-     * @param direction the direction this camera is facing.
-     * @deprecated Manipulate the quaternion rotation instead: 
-     * {@link Camera#setRotation(com.jme3.math.Quaternion) }.
-     */
-    @Deprecated
-    public void setDirection(Vector3f direction) {
-        //this.rotation.lookAt(direction, getUp());
-        Vector3f left = getLeft();
-        Vector3f up = getUp();
-        this.rotation.fromAxes(left, up, direction);
-        onFrameChange();
-    }
-
     /**
      * <code>lookAtDirection</code> sets the direction the camera is facing
      * given a direction and an up vector.
@@ -682,7 +670,7 @@ public class Camera implements Savable, Cloneable {
      * normalize normalizes the camera vectors.
      */
     public void normalize() {
-        this.rotation.normalize();
+        this.rotation.normalizeLocal();
         onFrameChange();
     }
 
@@ -794,7 +782,7 @@ public class Camera implements Savable, Cloneable {
         newUp.set(newDirection).crossLocal(newLeft).normalizeLocal();
 
         this.rotation.fromAxes(newLeft, newUp, newDirection);
-        this.rotation.normalize();
+        this.rotation.normalizeLocal();
         assert vars.unlock();
 
         onFrameChange();
@@ -1279,6 +1267,8 @@ public class Camera implements Savable, Cloneable {
     }
 
     /**
+     * Converts the given position from world space to screen space.
+     * 
      * @see Camera#getScreenCoordinates
      */
     public Vector3f getScreenCoordinates(Vector3f worldPos) {
@@ -1286,7 +1276,7 @@ public class Camera implements Savable, Cloneable {
     }
 
     /**
-     * Implementation contributed by Zbyl.
+     * Converts the given position from world space to screen space.
      *
      * @see Camera#getScreenCoordinates(Vector3f, Vector3f)
      */

engine/src/core/com/jme3/renderer/Caps.java

@@ -40,44 +40,113 @@ import com.jme3.texture.Image.Format;
 import com.jme3.texture.Texture;
 import java.util.Collection;
 
+/**
+ * <code>Caps</code> is an enum specifying a capability that the {@link Renderer}
+ * supports.
+ * 
+ * @author Kirill Vainer
+ */
 public enum Caps {
 
-    /// Framebuffer features
     /**
-     * Supports FrameBuffer Objects (FBO)
+     * Supports {@link FrameBuffer FrameBuffers}.
+     * <p>
+     * OpenGL: Renderer exposes the GL_EXT_framebuffer_object extension.<br>
+     * OpenGL ES: Renderer supports OpenGL ES 2.0.
      */
     FrameBuffer,
 
     /**
      * Supports framebuffer Multiple Render Targets (MRT)
+     * <p>
+     * OpenGL: Renderer exposes the GL_ARB_draw_buffers extension
      */
     FrameBufferMRT,
 
     /**
      * Supports framebuffer multi-sampling
+     * <p>
+     * OpenGL: Renderer exposes the GL EXT framebuffer multisample extension<br>
+     * OpenGL ES: Renderer exposes GL_APPLE_framebuffer_multisample or
+     * GL_ANGLE_framebuffer_multisample.
      */
     FrameBufferMultisample,
 
     /**
      * Supports texture multi-sampling
+     * <p>
+     * OpenGL: Renderer exposes the GL_ARB_texture_multisample extension<br>
+     * OpenGL ES: Renderer exposes the GL_IMG_multisampled_render_to_texture
+     * extension.
      */
     TextureMultisample,
 
-    /// API Version
+    /**
+     * Supports OpenGL 2.0 or OpenGL ES 2.0.
+     */
     OpenGL20,
+    
+    /**
+     * Supports OpenGL 2.1
+     */
     OpenGL21,
+    
+    /**
+     * Supports OpenGL 3.0
+     */
     OpenGL30,
+    
+    /**
+     * Supports OpenGL 3.1
+     */
     OpenGL31,
+    
+    /**
+     * Supports OpenGL 3.2
+     */
     OpenGL32,
 
-    /// Shader language version
+    /**
+     * Supports OpenGL ARB program.
+     * <p>
+     * OpenGL: Renderer exposes ARB_vertex_program and ARB_fragment_program
+     * extensions.
+     */
     ARBprogram,
+    
+    /**
+     * Supports GLSL 1.0
+     */
     GLSL100,
+    
+    /**
+     * Supports GLSL 1.1
+     */
     GLSL110,
+    
+    /**
+     * Supports GLSL 1.2
+     */
     GLSL120,
+    
+    /**
+     * Supports GLSL 1.3
+     */
     GLSL130,
+    
+    /**
+     * Supports GLSL 1.4
+     */
     GLSL140,
+    
+    /**
+     * Supports GLSL 1.5
+     */
     GLSL150,
+    
+    /**
+     * Supports GLSL 3.3
+     */
     GLSL330,
 
     /**
@@ -159,6 +228,18 @@ public enum Caps {
      */
     Multisample;
 
+    /**
+     * Returns true if given the renderer capabilities, the texture
+     * can be supported by the renderer.
+     * <p>
+     * This only checks the format of the texture, non-power-of-2
+     * textures are scaled automatically inside the renderer 
+     * if are not supported natively.
+     * 
+     * @param caps The collection of renderer capabilities {@link Renderer#getCaps() }.
+     * @param tex The texture to check
+     * @return True if it is supported, false otherwise.
+     */
     public static boolean supports(Collection<Caps> caps, Texture tex){
         if (tex.getType() == Texture.Type.TwoDimensionalArray
          && !caps.contains(Caps.TextureArray))
@@ -188,6 +269,14 @@ public enum Caps {
         }
     }
 
+    /**
+     * Returns true if given the renderer capabilities, the framebuffer
+     * can be supported by the renderer.
+     * 
+     * @param caps The collection of renderer capabilities {@link Renderer#getCaps() }.
+     * @param fb The framebuffer to check
+     * @return True if it is supported, false otherwise.
+     */
     public static boolean supports(Collection<Caps> caps, FrameBuffer fb){
         if (!caps.contains(Caps.FrameBuffer))
             return false;
@@ -234,6 +323,14 @@ public enum Caps {
         return true;
     }
 
+    /**
+     * Returns true if given the renderer capabilities, the shader
+     * can be supported by the renderer.
+     * 
+     * @param caps The collection of renderer capabilities {@link Renderer#getCaps() }.
+     * @param fb The shader to check
+     * @return True if it is supported, false otherwise.
+     */
     public static boolean supports(Collection<Caps> caps, Shader shader){
         String lang = shader.getLanguage();
         if (lang.startsWith("GLSL")){
@@ -251,6 +348,8 @@ public enum Caps {
                     return caps.contains(Caps.GLSL140);
                 case 150:
                     return caps.contains(Caps.GLSL150);
+                case 330:
+                    return caps.contains(Caps.GLSL330);
                 default:
                     return false;
             }

engine/src/core/com/jme3/renderer/GL1Renderer.java

@@ -2,6 +2,25 @@ package com.jme3.renderer;
 
 import com.jme3.material.FixedFuncBinding;
 
+/**
+ * Renderer sub-interface that is used for non-shader based renderers.
+ * <p>
+ * The <code>GL1Renderer</code> provides a single call, 
+ * {@link #setFixedFuncBinding(com.jme3.material.FixedFuncBinding, java.lang.Object) }
+ * which allows to set fixed functionality state.
+ * 
+ * @author Kirill Vainer
+ */
 public interface GL1Renderer extends Renderer {
+    
+    /**
+     * Set the fixed functionality state.
+     * <p>
+     * See {@link FixedFuncBinding} for various values that
+     * can be set.
+     * 
+     * @param ffBinding The binding to set
+     * @param val The value
+     */
     public void setFixedFuncBinding(FixedFuncBinding ffBinding, Object val);
 }

engine/src/core/com/jme3/renderer/GLObject.java

@@ -32,13 +32,12 @@
 
 package com.jme3.renderer;
 
-import java.util.logging.Level;
-import java.util.logging.Logger;
-
 /**
  * Describes a GL object. An encapsulation of a certain object 
  * on the native side of the graphics library.
- * This class is used to track
+ * This class is used to track when OpenGL native objects are collected
+ * by the garbage collector, and then invoke the proper destructor
+ * on the OpenGL library to delete it from memory.
  */
 public abstract class GLObject implements Cloneable {
 
@@ -66,6 +65,9 @@ public abstract class GLObject implements Cloneable {
      */
     protected final Type type;
 
+    /**
+     * The type of the GLObject, usually specified by a subclass.
+     */
     public static enum Type {
         /**
          * A texture is an image that is applied to geometry.
@@ -97,6 +99,12 @@ public abstract class GLObject implements Cloneable {
         FrameBuffer,
     }
 
+    /**
+     * Creates a new GLObject with the given type. Should be
+     * called by the subclasses.
+     * 
+     * @param type The type that the subclass represents.
+     */
     public GLObject(Type type){
         this.type = type;
         this.handleRef = new Object();
@@ -131,17 +139,24 @@ public abstract class GLObject implements Cloneable {
         return id;
     }
 
+    /**
+     * Internal use only. Indicates that the object has changed
+     * and its state needs to be updated.
+     */
     public void setUpdateNeeded(){
         updateNeeded = true;
     }
 
     /**
-     * 
+     * Internal use only. Indicates that the state changes were applied.
      */
     public void clearUpdateNeeded(){
         updateNeeded = false;
     }
 
+    /**
+     * Internal use only. Check if {@link #setUpdateNeeded()} was called before.
+     */
     public boolean isUpdateNeeded(){
         return updateNeeded;
     }
@@ -168,17 +183,6 @@ public abstract class GLObject implements Cloneable {
         }
     }
 
-//    @Override
-//    public boolean equals(Object other){
-//        if (this == other)
-//            return true;
-//        if (!(other instanceof GLObject))
-//            return false;
-//
-//    }
-
-    // Specialized calls to be used by object manager only.
-
     /**
      * Called when the GL context is restarted to reset all IDs. Prevents
      * "white textures" on display restart.
@@ -188,7 +192,8 @@ public abstract class GLObject implements Cloneable {
     /**
      * Deletes the GL object from the GPU when it is no longer used. Called
      * automatically by the GL object manager.
-     * @param r
+     * 
+     * @param r The renderer to be used to delete the object
      */
     public abstract void deleteObject(Renderer r);
 

engine/src/core/com/jme3/renderer/RenderManager.java

@@ -32,7 +32,9 @@
 package com.jme3.renderer;
 
 import com.jme3.material.Material;
+import com.jme3.material.MaterialDef;
 import com.jme3.material.RenderState;
+import com.jme3.material.Technique;
 import com.jme3.math.Matrix3f;
 import com.jme3.math.Matrix4f;
 import com.jme3.math.Quaternion;
@@ -42,12 +44,14 @@ import com.jme3.post.SceneProcessor;
 import com.jme3.renderer.queue.GeometryList;
 import com.jme3.renderer.queue.RenderQueue;
 import com.jme3.renderer.queue.RenderQueue.Bucket;
+import com.jme3.renderer.queue.RenderQueue.ShadowMode;
 import com.jme3.scene.Geometry;
 import com.jme3.scene.Mesh;
 import com.jme3.scene.Node;
 import com.jme3.scene.Spatial;
 import com.jme3.scene.VertexBuffer;
 import com.jme3.shader.Uniform;
+import com.jme3.shader.UniformBinding;
 import com.jme3.shader.VarType;
 import com.jme3.system.NullRenderer;
 import com.jme3.system.Timer;
@@ -71,6 +75,7 @@ import java.util.logging.Logger;
 public class RenderManager {
 
     private static final Logger logger = Logger.getLogger(RenderManager.class.getName());
+    
     private Renderer renderer;
     private Timer timer;
     private ArrayList<ViewPort> preViewPorts = new ArrayList<ViewPort>();
@@ -106,6 +111,14 @@ public class RenderManager {
         //this.shader = renderer.getCaps().contains(Caps.GLSL100);
     }
 
+    /**
+     * Returns the pre ViewPort with the given name.
+     * 
+     * @param viewName The name of the pre ViewPort to look up
+     * @return The ViewPort, or null if not found.
+     * 
+     * @see #createPreView(java.lang.String, com.jme3.renderer.Camera) 
+     */
     public ViewPort getPreView(String viewName) {
         for (int i = 0; i < preViewPorts.size(); i++) {
             if (preViewPorts.get(i).getName().equals(viewName)) {
@@ -115,10 +128,26 @@ public class RenderManager {
         return null;
     }
 
+    /**
+     * Removes the specified pre ViewPort.
+     * 
+     * @param view The pre ViewPort to remove
+     * @return True if the ViewPort was removed successfully.
+     * 
+     * @see #createPreView(java.lang.String, com.jme3.renderer.Camera) 
+     */
     public boolean removePreView(ViewPort view) {
         return preViewPorts.remove(view);
     }
 
+    /**
+     * Returns the main ViewPort with the given name.
+     * 
+     * @param viewName The name of the main ViewPort to look up
+     * @return The ViewPort, or null if not found.
+     * 
+     * @see #createMainView(java.lang.String, com.jme3.renderer.Camera) 
+     */
     public ViewPort getMainView(String viewName) {
         for (int i = 0; i < viewPorts.size(); i++) {
             if (viewPorts.get(i).getName().equals(viewName)) {
@@ -128,6 +157,14 @@ public class RenderManager {
         return null;
     }
 
+    /**
+     * Removes the main ViewPort with the specified name.
+     * 
+     * @param view The main ViewPort name to remove
+     * @return True if the ViewPort was removed successfully.
+     * 
+     * @see #createMainView(java.lang.String, com.jme3.renderer.Camera) 
+     */
     public boolean removeMainView(String viewName) {
         for (int i = 0; i < viewPorts.size(); i++) {
             if (viewPorts.get(i).getName().equals(viewName)) {
@@ -138,10 +175,26 @@ public class RenderManager {
         return false;
     }
 
+    /**
+     * Removes the specified main ViewPort.
+     * 
+     * @param view The main ViewPort to remove
+     * @return True if the ViewPort was removed successfully.
+     * 
+     * @see #createMainView(java.lang.String, com.jme3.renderer.Camera) 
+     */
     public boolean removeMainView(ViewPort view) {
         return viewPorts.remove(view);
     }
 
+    /**
+     * Returns the post ViewPort with the given name.
+     * 
+     * @param viewName The name of the post ViewPort to look up
+     * @return The ViewPort, or null if not found.
+     * 
+     * @see #createPostView(java.lang.String, com.jme3.renderer.Camera) 
+     */
     public ViewPort getPostView(String viewName) {
         for (int i = 0; i < postViewPorts.size(); i++) {
             if (postViewPorts.get(i).getName().equals(viewName)) {
@@ -151,6 +204,14 @@ public class RenderManager {
         return null;
     }
 
+    /**
+     * Removes the post ViewPort with the specified name.
+     * 
+     * @param view The post ViewPort name to remove
+     * @return True if the ViewPort was removed successfully.
+     * 
+     * @see #createPostView(java.lang.String, com.jme3.renderer.Camera) 
+     */
     public boolean removePostView(String viewName) {
         for (int i = 0; i < postViewPorts.size(); i++) {
             if (postViewPorts.get(i).getName().equals(viewName)) {
@@ -162,25 +223,49 @@ public class RenderManager {
         return false;
     }
 
+    /**
+     * Removes the specified post ViewPort.
+     * 
+     * @param view The post ViewPort to remove
+     * @return True if the ViewPort was removed successfully.
+     * 
+     * @see #createPostView(java.lang.String, com.jme3.renderer.Camera) 
+     */
     public boolean removePostView(ViewPort view) {
         return postViewPorts.remove(view);
     }
 
+    /**
+     * Returns a read-only list of all pre ViewPorts
+     * @return a read-only list of all pre ViewPorts
+     * @see #createPreView(java.lang.String, com.jme3.renderer.Camera) 
+     */
     public List<ViewPort> getPreViews() {
         return Collections.unmodifiableList(preViewPorts);
     }
 
+    /**
+     * Returns a read-only list of all main ViewPorts
+     * @return a read-only list of all main ViewPorts
+     * @see #createMainView(java.lang.String, com.jme3.renderer.Camera) 
+     */
     public List<ViewPort> getMainViews() {
         return Collections.unmodifiableList(viewPorts);
     }
 
+    /**
+     * Returns a read-only list of all post ViewPorts
+     * @return a read-only list of all post ViewPorts
+     * @see #createPostView(java.lang.String, com.jme3.renderer.Camera) 
+     */
     public List<ViewPort> getPostViews() {
         return Collections.unmodifiableList(postViewPorts);
     }
 
     /**
-     * Creates a new viewport, to display the given camera's content.
-     * The view will be processed before the primary viewport.
+     * Creates a new pre ViewPort, to display the given camera's content.
+     * <p>
+     * The view will be processed before the main and post viewports.
      */
     public ViewPort createPreView(String viewName, Camera cam) {
         ViewPort vp = new ViewPort(viewName, cam);
@@ -188,12 +273,23 @@ public class RenderManager {
         return vp;
     }
 
+    /**
+     * Creates a new main ViewPort, to display the given camera's content.
+     * <p>
+     * The view will be processed before the post viewports but after
+     * the pre viewports.
+     */
     public ViewPort createMainView(String viewName, Camera cam) {
         ViewPort vp = new ViewPort(viewName, cam);
         viewPorts.add(vp);
         return vp;
     }
 
+    /**
+     * Creates a new post ViewPort, to display the given camera's content.
+     * <p>
+     * The view will be processed after the pre and main viewports.
+     */
     public ViewPort createPostView(String viewName, Camera cam) {
         ViewPort vp = new ViewPort(viewName, cam);
         postViewPorts.add(vp);
@@ -212,8 +308,9 @@ public class RenderManager {
     }
 
     /**
-     * @param w
-     * @param h
+     * Internal use only.
+     * Updates the resolution of all on-screen cameras to match
+     * the given width and height.
      */
     public void notifyReshape(int w, int h) {
         for (ViewPort vp : preViewPorts) {
@@ -239,6 +336,11 @@ public class RenderManager {
         }
     }
 
+    /**
+     * Internal use only.
+     * Updates the given list of uniforms with {@link UniformBinding uniform bindings}
+     * based on the current world state.
+     */
     public void updateUniformBindings(List<Uniform> params) {
         // assums worldMatrix is properly set.
         TempVars vars = TempVars.get();
@@ -372,20 +474,121 @@ public class RenderManager {
      * with the provided material instead.
      * Use null to clear the material and return renderer to normal
      * functionality.
-     * @param mat
+     * @param mat The forced material to set, or null to return to normal
      */
     public void setForcedMaterial(Material mat) {
         forcedMaterial = mat;
     }
 
+    /**
+     * Returns the forced render state previously set with 
+     * {@link #setForcedRenderState(com.jme3.material.RenderState) }.
+     * @return the forced render state
+     */
     public RenderState getForcedRenderState() {
         return forcedRenderState;
     }
 
+    /**
+     * Set the render state to use for all future objects.
+     * This overrides the render state set on the material and instead
+     * forces this render state to be applied for all future materials
+     * rendered. Set to null to return to normal functionality.
+     * 
+     * @param forcedRenderState The forced render state to set, or null
+     * to return to normal
+     */
     public void setForcedRenderState(RenderState forcedRenderState) {
         this.forcedRenderState = forcedRenderState;
     }
 
+    /**
+     * Set the timer that should be used to query the time based
+     * {@link UniformBinding}s for material world parameters.
+     * 
+     * @param timer The timer to query time world parameters
+     */
+    public void setTimer(Timer timer) {
+        this.timer = timer;
+    }
+
+    /**
+     * Returns the forced technique name set.
+     * 
+     * @return the forced technique name set.
+     * 
+     * @see #setForcedTechnique(java.lang.String) 
+     */
+    public String getForcedTechnique() {
+        return forcedTechnique;
+    }
+
+    /**
+     * Sets the forced technique to use when rendering geometries.
+     * <p>
+     * If the specified technique name is available on the geometry's
+     * material, then it is used, otherwise, the 
+     * {@link #setForcedMaterial(com.jme3.material.Material) forced material} is used.
+     * If a forced material is not set and the forced technique name cannot
+     * be found on the material, the geometry will <em>not</em> be rendered.
+     * 
+     * @param forcedTechnique The forced technique name to use, set to null
+     * to return to normal functionality.
+     * 
+     * @see #renderGeometry(com.jme3.scene.Geometry) 
+     */
+    public void setForcedTechnique(String forcedTechnique) {
+        this.forcedTechnique = forcedTechnique;
+    }
+
+    /**
+     * Enable or disable alpha-to-coverage. 
+     * <p>
+     * When alpha to coverage is enabled and the renderer implementation
+     * supports it, then alpha blending will be replaced with alpha dissolve
+     * if multi-sampling is also set on the renderer.
+     * This feature allows avoiding of alpha blending artifacts due to
+     * lack of triangle-level back-to-front sorting.
+     * 
+     * @param value True to enable alpha-to-coverage, false otherwise.
+     */
+    public void setAlphaToCoverage(boolean value) {
+        renderer.setAlphaToCoverage(value);
+    }
+
+    /**
+     * True if the translucent bucket should automatically be rendered
+     * by the RenderManager.
+     * 
+     * @return Whether or not the translucent bucket is rendered.
+     * 
+     * @see #setHandleTranslucentBucket(boolean) 
+     */
+    public boolean isHandleTranslucentBucket() {
+        return handleTranlucentBucket;
+    }
+
+    /**
+     * Enable or disable rendering of the 
+     * {@link Bucket#Translucent translucent bucket}
+     * by the RenderManager. The default is enabled.
+     * 
+     * @param handleTranslucentBucket Whether or not the translucent bucket should
+     * be rendered.
+     */
+    public void setHandleTranslucentBucket(boolean handleTranslucentBucket) {
+        this.handleTranlucentBucket = handleTranslucentBucket;
+    }
+    
+    /**
+     * Internal use only. Sets the world matrix to use for future
+     * rendering. This has no effect unless objects are rendered manually
+     * using {@link Material#render(com.jme3.scene.Geometry, com.jme3.renderer.RenderManager) }.
+     * Using {@link #renderGeometry(com.jme3.scene.Geometry) } will 
+     * override this value.
+     * 
+     * @param mat The world matrix to set
+     */
     public void setWorldMatrix(Matrix4f mat) {
         if (shader) {
             worldMatrix.set(mat);
@@ -394,6 +597,37 @@ public class RenderManager {
         }
     }
 
+    /**
+     * Renders the given geometry.
+     * <p>
+     * First the proper world matrix is set, if 
+     * the geometry's {@link Geometry#setIgnoreTransform(boolean) ignore transform}
+     * feature is enabled, the identity world matrix is used, otherwise, the 
+     * geometry's {@link Geometry#getWorldMatrix() world transform matrix} is used. 
+     * <p>
+     * Once the world matrix is applied, the proper material is chosen for rendering.
+     * If a {@link #setForcedMaterial(com.jme3.material.Material) forced material} is
+     * set on this RenderManager, then it is used for rendering the geometry,
+     * otherwise, the {@link Geometry#getMaterial() geometry's material} is used.
+     * <p>
+     * If a {@link #setForcedTechnique(java.lang.String) forced technique} is
+     * set on this RenderManager, then it is selected automatically
+     * on the geometry's material and is used for rendering. Otherwise, one
+     * of the {@link MaterialDef#getDefaultTechniques() default techniques} is
+     * used.
+     * <p>
+     * If a {@link #setForcedRenderState(com.jme3.material.RenderState) forced
+     * render state} is set on this RenderManager, then it is used
+     * for rendering the material, and the material's own render state is ignored.
+     * Otherwise, the material's render state is used as intended.
+     * 
+     * @param g The geometry to render
+     * 
+     * @see Technique
+     * @see RenderState
+     * @see Material#selectTechnique(java.lang.String, com.jme3.renderer.RenderManager) 
+     * @see Material#render(com.jme3.scene.Geometry, com.jme3.renderer.RenderManager) 
+     */
     public void renderGeometry(Geometry g) {
         if (g.isIgnoreTransform()) {
             setWorldMatrix(Matrix4f.IDENTITY);
@@ -425,6 +659,17 @@ public class RenderManager {
         }
     }
 
+    /**
+     * Renders the given GeometryList.
+     * <p>
+     * For every geometry in the list, the 
+     * {@link #renderGeometry(com.jme3.scene.Geometry) } method is called.
+     * 
+     * @param gl The geometry list to render.
+     * 
+     * @see GeometryList
+     * @see #renderGeometry(com.jme3.scene.Geometry) 
+     */
     public void renderGeometryList(GeometryList gl) {
         for (int i = 0; i < gl.size(); i++) {
             renderGeometry(gl.get(i));
@@ -433,10 +678,8 @@ public class RenderManager {
 
     /**
      * If a spatial is not inside the eye frustum, it
-     * is still rendered in the shadow frustum through this
-     * recursive method.
-     * @param s
-     * @param r
+     * is still rendered in the shadow frustum (shadow casting queue)
+     * through this recursive method.
      */
     private void renderShadow(Spatial s, RenderQueue rq) {
         if (s instanceof Node) {
@@ -456,6 +699,19 @@ public class RenderManager {
         }
     }
 
+    /**
+     * Preloads a scene for rendering.
+     * <p>
+     * After invocation of this method, the underlying
+     * renderer would have uploaded any textures, shaders and meshes
+     * used by the given scene to the video driver. 
+     * Using this method is useful when wishing to avoid the initial pause
+     * when rendering a scene for the first time. Note that it is not 
+     * guaranteed that the underlying renderer will actually choose to upload
+     * the data to the GPU so some pause is still to be expected.
+     * 
+     * @param scene The scene to preload
+     */
     public void preloadScene(Spatial scene) {
         if (scene instanceof Node) {
             // recurse for all children
@@ -485,7 +741,33 @@ public class RenderManager {
     }
 
     /**
-     * Render scene graph
+     * Flattens the given scene graph into the ViewPort's RenderQueue,
+     * checking for culling as the call goes down the graph recursively.
+     * <p>
+     * First, the scene is checked for culling based on the <code>Spatial</code>s
+     * {@link Spatial#setCullHint(com.jme3.scene.Spatial.CullHint) cull hint},
+     * if the camera frustum contains the scene, then this method is recursively
+     * called on its children.
+     * <p>
+     * When the scene's leaves or {@link Geometry geometries} are reached,
+     * they are each enqueued into the 
+     * {@link ViewPort#getQueue() ViewPort's render queue}.
+     * <p>
+     * In addition to enqueuing the visible geometries, this method
+     * also scenes which cast or receive shadows, by putting them into the
+     * RenderQueue's 
+     * {@link RenderQueue#addToShadowQueue(com.jme3.scene.Geometry, com.jme3.renderer.queue.RenderQueue.ShadowMode) 
+     * shadow queue}. Each Spatial which has its 
+     * {@link Spatial#setShadowMode(com.jme3.renderer.queue.RenderQueue.ShadowMode) shadow mode}
+     * set to not off, will be put into the appropriate shadow queue, note that
+     * this process does not check for frustum culling on any 
+     * {@link ShadowMode#Cast shadow casters}, as they don't have to be
+     * in the eye camera frustum to cast shadows on objects that are inside it.
+     * 
+     * @param scene The scene to flatten into the queue
+     * @param vp The ViewPort provides the {@link ViewPort#getCamera() camera}
+     * used for culling and the {@link ViewPort#getQueue() queue} used to 
+     * contain the flattened scene graph.
      */
     public void renderScene(Spatial scene, ViewPort vp) {
         if (scene.getParent() == null) {
@@ -531,31 +813,77 @@ public class RenderManager {
         }
     }
 
+    /**
+     * Returns the camera currently used for rendering.
+     * <p>
+     * The camera can be set with {@link #setCamera(com.jme3.renderer.Camera, boolean) }.
+     * 
+     * @return the camera currently used for rendering.
+     */
     public Camera getCurrentCamera() {
         return prevCam;
     }
 
+    /**
+     * The renderer implementation used for rendering operations.
+     * 
+     * @return The renderer implementation
+     * 
+     * @see #RenderManager(com.jme3.renderer.Renderer) 
+     * @see Renderer
+     */
     public Renderer getRenderer() {
         return renderer;
     }
 
     /**
-     * Render the given viewport queues, flushing the geometryList
-     * @param vp the viewport
+     * Flushes the ViewPort's {@link ViewPort#getQueue() render queue}
+     * by rendering each of its visible buckets.
+     * By default the queues will automatically be cleared after rendering,
+     * so there's no need to clear them manually.
+     * 
+     * @param vp The ViewPort of which the queue will be flushed
+     * 
+     * @see RenderQueue#renderQueue(com.jme3.renderer.queue.RenderQueue.Bucket, com.jme3.renderer.RenderManager, com.jme3.renderer.Camera) 
+     * @see #renderGeometryList(com.jme3.renderer.queue.GeometryList) 
      */
     public void flushQueue(ViewPort vp) {
         renderViewPortQueues(vp, true);
     }
 
+    /**
+     * Clears the queue of the given ViewPort.
+     * Simply calls {@link RenderQueue#clear() } on the ViewPort's 
+     * {@link ViewPort#getQueue() render queue}.
+     * 
+     * @param vp The ViewPort of which the queue will be cleared.
+     * 
+     * @see RenderQueue#clear()
+     * @see ViewPort#getQueue()
+     */
     public void clearQueue(ViewPort vp) {
         vp.getQueue().clear();
     }
 
-    //Nehon 08/18/2010 changed flushQueue to renderViewPortQueues with a flush boolean param
     /**
-     * Render the given viewport queues
-     * @param vp the viewport
-     * @param flush true to flush geometryList
+     * Render the given viewport queues.
+     * <p>
+     * Changes the {@link Renderer#setDepthRange(float, float) depth range}
+     * appropriately as expected by each queue and then calls 
+     * {@link RenderQueue#renderQueue(com.jme3.renderer.queue.RenderQueue.Bucket, com.jme3.renderer.RenderManager, com.jme3.renderer.Camera, boolean) }
+     * on the queue. Makes sure to restore the depth range to [0, 1] 
+     * at the end of the call.
+     * Note that the {@link Bucket#Translucent translucent bucket} is NOT
+     * rendered by this method. Instead the user should call 
+     * {@link #renderTranslucentQueue(com.jme3.renderer.ViewPort) }
+     * after this call.
+     * 
+     * @param vp the viewport of which queue should be rendered
+     * @param flush If true, the queues will be cleared after
+     * rendering.
+     * 
+     * @see RenderQueue
+     * @see #renderTranslucentQueue(com.jme3.renderer.ViewPort) 
      */
     public void renderViewPortQueues(ViewPort vp, boolean flush) {
         RenderQueue rq = vp.getQueue();
@@ -600,6 +928,18 @@ public class RenderManager {
         }
     }
 
+    /**
+     * Renders the {@link Bucket#Translucent translucent queue} on the viewPort.
+     * <p>
+     * This call does nothing unless {@link #setHandleTranslucentBucket(boolean) }
+     * is set to true. This method clears the translucent queue after rendering
+     * it.
+     * 
+     * @param vp The viewport of which the translucent queue should be rendered.
+     * 
+     * @see #renderViewPortQueues(com.jme3.renderer.ViewPort, boolean) 
+     * @see #setHandleTranslucentBucket(boolean) 
+     */
     public void renderTranslucentQueue(ViewPort vp) {
         RenderQueue rq = vp.getQueue();
         if (!rq.isQueueEmpty(Bucket.Translucent) && handleTranlucentBucket) {
@@ -664,14 +1004,35 @@ public class RenderManager {
         }
     }
 
+    /**
+     * Set the camera to use for rendering.
+     * <p>
+     * First, the camera's 
+     * {@link Camera#setViewPort(float, float, float, float) view port parameters}
+     * are applied. Then, the camera's {@link Camera#getViewMatrix() view} and 
+     * {@link Camera#getProjectionMatrix() projection} matrices are set
+     * on the renderer. If <code>ortho</code> is <code>true</code>, then
+     * instead of using the camera's view and projection matrices, an ortho
+     * matrix is computed and used instead of the view projection matrix. 
+     * The ortho matrix converts from the range (0 ~ Width, 0 ~ Height, -1 ~ +1)
+     * to the clip range (-1 ~ +1, -1 ~ +1, -1 ~ +1).
+     * 
+     * @param cam The camera to set
+     * @param ortho True if to use orthographic projection (for GUI rendering),
+     * false if to use the camera's view and projection matrices.
+     */
     public void setCamera(Camera cam, boolean ortho) {
         setViewPort(cam);
         setViewProjection(cam, ortho);
     }
 
     /**
-     * Draws the viewport but doesn't invoke processors.
-     * @param vp
+     * Draws the viewport but without notifying {@link SceneProcessor scene
+     * processors} of any rendering events.
+     * 
+     * @param vp The ViewPort to render
+     * 
+     * @see #renderViewPort(com.jme3.renderer.ViewPort, float) 
      */
     public void renderViewPortRaw(ViewPort vp) {
         setCamera(vp.getCamera(), false);
@@ -682,12 +1043,53 @@ public class RenderManager {
         flushQueue(vp);
     }
 
+    /**
+     * Renders the {@link ViewPort}.
+     * <p>
+     * If the ViewPort is {@link ViewPort#isEnabled() disabled}, this method
+     * returns immediately. Otherwise, the ViewPort is rendered by 
+     * the following process:<br>
+     * <ul>
+     * <li>All {@link SceneProcessor scene processors} that are attached
+     * to the ViewPort are {@link SceneProcessor#initialize(com.jme3.renderer.RenderManager, com.jme3.renderer.ViewPort) initialized}.
+     * </li>
+     * <li>The SceneProcessors' {@link SceneProcessor#preFrame(float) } method 
+     * is called.</li>
+     * <li>The ViewPort's {@link ViewPort#getOutputFrameBuffer() output framebuffer}
+     * is set on the Renderer</li>
+     * <li>The camera is set on the renderer, including its view port parameters.
+     * (see {@link #setCamera(com.jme3.renderer.Camera, boolean) })</li>
+     * <li>Any buffers that the ViewPort requests to be cleared are cleared
+     * and the {@link ViewPort#getBackgroundColor() background color} is set</li>
+     * <li>Every scene that is attached to the ViewPort is flattened into 
+     * the ViewPort's render queue 
+     * (see {@link #renderViewPortQueues(com.jme3.renderer.ViewPort, boolean) })
+     * </li>
+     * <li>The SceneProcessors' {@link SceneProcessor#postQueue(com.jme3.renderer.queue.RenderQueue) }
+     * method is called.</li>
+     * <li>The render queue is sorted and then flushed, sending
+     * rendering commands to the underlying Renderer implementation. 
+     * (see {@link #flushQueue(com.jme3.renderer.ViewPort) })</li>
+     * <li>The SceneProcessors' {@link SceneProcessor#postFrame(com.jme3.texture.FrameBuffer) }
+     * method is called.</li>
+     * <li>The translucent queue of the ViewPort is sorted and then flushed
+     * (see {@link #renderTranslucentQueue(com.jme3.renderer.ViewPort) })</li>
+     * <li>If any objects remained in the render queue, they are removed
+     * from the queue. This is generally objects added to the 
+     * {@link RenderQueue#renderShadowQueue(com.jme3.renderer.queue.RenderQueue.ShadowMode, com.jme3.renderer.RenderManager, com.jme3.renderer.Camera, boolean) 
+     * shadow queue}
+     * which were not rendered because of a missing shadow renderer.</li>
+     * </ul>
+     * 
+     * @param vp
+     * @param tpf 
+     */
     public void renderViewPort(ViewPort vp, float tpf) {
         if (!vp.isEnabled()) {
             return;
         }
         List<SceneProcessor> processors = vp.getProcessors();
-        if (processors.size() == 0) {
+        if (processors.isEmpty()) {
             processors = null;
         }
 
@@ -735,6 +1137,19 @@ public class RenderManager {
         clearQueue(vp);
     }
 
+    /**
+     * Called by the application to render any ViewPorts
+     * added to this RenderManager.
+     * <p>
+     * Renders any viewports that were added using the following methods:
+     * <ul>
+     * <li>{@link #createPreView(java.lang.String, com.jme3.renderer.Camera) }</li>
+     * <li>{@link #createMainView(java.lang.String, com.jme3.renderer.Camera) }</li>
+     * <li>{@link #createPostView(java.lang.String, com.jme3.renderer.Camera) }</li>
+     * </ul>
+     * 
+     * @param tpf Time per frame value
+     */
     public void render(float tpf) {
         if (renderer instanceof NullRenderer) {
             return;
@@ -753,28 +1168,4 @@ public class RenderManager {
         }
     }
 
-    //Remy - 09/14/2010 - added a setter for the timer in order to correctly populate g_Time and g_Tpf in the shaders
-    public void setTimer(Timer timer) {
-        this.timer = timer;
-    }
-
-    public String getForcedTechnique() {
-        return forcedTechnique;
-    }
-
-    public void setForcedTechnique(String forcedTechnique) {
-        this.forcedTechnique = forcedTechnique;
-    }
-
-    public void setAlphaToCoverage(boolean value) {
-        renderer.setAlphaToCoverage(value);
-    }
-
-    public boolean isHandleTranslucentBucket() {
-        return handleTranlucentBucket;
-    }
-
-    public void setHandleTranslucentBucket(boolean handleTranslucentBucket) {
-        this.handleTranlucentBucket = handleTranslucentBucket;
-    }
 }

engine/src/core/com/jme3/renderer/ViewPort.java

@@ -40,6 +40,29 @@ import com.jme3.texture.FrameBuffer;
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * A <code>ViewPort</code> represents a view inside the display
+ * window or a {@link FrameBuffer} to which scenes will be rendered. 
+ * <p>
+ * A viewport has a {@link #ViewPort(java.lang.String, com.jme3.renderer.Camera) camera}
+ * which is used to render a set of {@link #attachScene(com.jme3.scene.Spatial) scenes}.
+ * A view port has a location on the screen as set by the 
+ * {@link Camera#setViewPort(float, float, float, float) } method.
+ * By default, a view port does not clear the framebuffer, but it can be
+ * set to {@link #setClearFlags(boolean, boolean, boolean) clear the framebuffer}.
+ * The background color which the color buffer is cleared to can be specified 
+ * via the {@link #setBackgroundColor(com.jme3.math.ColorRGBA)} method.
+ * <p>
+ * A ViewPort has a list of {@link SceneProcessor}s which can
+ * control how the ViewPort is rendered by the {@link RenderManager}.
+ * 
+ * @author Kirill Vainer
+ * 
+ * @see RenderManager
+ * @see SceneProcessor
+ * @see Spatial
+ * @see Camera
+ */
 public class ViewPort {
 
     protected final String name;
@@ -53,122 +76,286 @@ public class ViewPort {
     protected boolean clearDepth = false, clearColor = false, clearStencil = false;
     private boolean enabled = true;
 
+    /**
+     * Create a new viewport. User code should generally use these methods instead:<br>
+     * <ul>
+     * <li>{@link RenderManager#createPreView(java.lang.String, com.jme3.renderer.Camera) }</li>
+     * <li>{@link RenderManager#createMainView(java.lang.String, com.jme3.renderer.Camera)  }</li>
+     * <li>{@link RenderManager#createPostView(java.lang.String, com.jme3.renderer.Camera)  }</li>
+     * </ul>
+     * 
+     * @param name The name of the viewport. Used for debugging only.
+     * @param cam The camera through which the viewport is rendered. The camera
+     * cannot be swapped to a different one after creating the viewport.
+     */
     public ViewPort(String name, Camera cam) {
         this.name = name;
         this.cam = cam;
     }
 
+    /**
+     * Returns the name of the viewport as set in the constructor.
+     * 
+     * @return the name of the viewport
+     * 
+     * @see #ViewPort(java.lang.String, com.jme3.renderer.Camera) 
+     */
     public String getName() {
         return name;
     }
 
+    /**
+     * Get the list of {@link SceneProcessor scene processors} that were
+     * added to this <code>ViewPort</code>
+     * 
+     * @return the list of processors attached to this ViewPort
+     * 
+     * @see #addProcessor(com.jme3.post.SceneProcessor) 
+     */
     public List<SceneProcessor> getProcessors(){
         return processors;
     }
 
+    /**
+     * Adds a {@link SceneProcessor} to this ViewPort.
+     * <p>
+     * SceneProcessors that are added to the ViewPort will be notified
+     * of events as the ViewPort is being rendered by the {@link RenderManager}.
+     * 
+     * @param processor The processor to add
+     * 
+     * @see SceneProcessor
+     */
     public void addProcessor(SceneProcessor processor){
         processors.add(processor);
     }
 
+    /**
+     * Removes a {@link SceneProcessor} from this ViewPort.
+     * <p>
+     * The processor will no longer receive events occurring to this ViewPort.
+     * 
+     * @param processor The processor to remove
+     * 
+     * @see SceneProcessor
+     */
     public void removeProcessor(SceneProcessor processor){
         processors.remove(processor);
         processor.cleanup();
     }
 
     /**
-     * Does nothing.
-     * @deprecated Use {@link ViewPort#setClearColor(boolean) } and similar
-     * methods.
+     * Check if depth buffer clearing is enabled.
+     * 
+     * @return true if depth buffer clearing is enabled.
+     * 
+     * @see #setClearDepth(boolean) 
      */
-    @Deprecated
-    public boolean isClearEnabled() {
-        return clearDepth && clearColor && clearStencil;
-    }
-    
-    /**
-     * Does nothing.
-     * @deprecated Use {@link ViewPort#setClearColor(boolean) } and similar
-     * methods.
-     */
-    @Deprecated
-    public void setClearEnabled(boolean clearEnabled) {
-        clearDepth = clearColor = clearStencil = clearEnabled;
-    }
-
     public boolean isClearDepth() {
         return clearDepth;
     }
 
+    /**
+     * Enable or disable clearing of the depth buffer for this ViewPort.
+     * <p>
+     * By default depth clearing is disabled.
+     * 
+     * @param clearDepth Enable/disable depth buffer clearing.
+     */
     public void setClearDepth(boolean clearDepth) {
         this.clearDepth = clearDepth;
     }
 
+    /**
+     * Check if color buffer clearing is enabled.
+     * 
+     * @return true if color buffer clearing is enabled.
+     * 
+     * @see #setClearColor(boolean) 
+     */
     public boolean isClearColor() {
         return clearColor;
     }
 
+    /**
+     * Enable or disable clearing of the color buffer for this ViewPort.
+     * <p>
+     * By default color clearing is disabled.
+     * 
+     * @param clearDepth Enable/disable color buffer clearing.
+     */
     public void setClearColor(boolean clearColor) {
         this.clearColor = clearColor;
     }
 
+    /**
+     * Check if stencil buffer clearing is enabled.
+     * 
+     * @return true if stencil buffer clearing is enabled.
+     * 
+     * @see #setClearStencil(boolean) 
+     */
     public boolean isClearStencil() {
         return clearStencil;
     }
 
+    /**
+     * Enable or disable clearing of the stencil buffer for this ViewPort.
+     * <p>
+     * By default stencil clearing is disabled.
+     * 
+     * @param clearDepth Enable/disable stencil buffer clearing.
+     */
     public void setClearStencil(boolean clearStencil) {
         this.clearStencil = clearStencil;
     }
 
+    /**
+     * Set the clear flags (color, depth, stencil) in one call.
+     * 
+     * @param color If color buffer clearing should be enabled.
+     * @param depth If depth buffer clearing should be enabled.
+     * @param stencil If stencil buffer clearing should be enabled.
+     * 
+     * @see #setClearColor(boolean) 
+     * @see #setClearDepth(boolean) 
+     * @see #setClearStencil(boolean) 
+     */
     public void setClearFlags(boolean color, boolean depth, boolean stencil){
         this.clearColor = color;
         this.clearDepth = depth;
         this.clearStencil = stencil;
     }
 
+    /**
+     * Returns the framebuffer where this ViewPort's scenes are
+     * rendered to.
+     * 
+     * @return the framebuffer where this ViewPort's scenes are
+     * rendered to.
+     * 
+     * @see #setOutputFrameBuffer(com.jme3.texture.FrameBuffer) 
+     */
     public FrameBuffer getOutputFrameBuffer() {
         return out;
     }
 
+    /**
+     * Sets the output framebuffer for the ViewPort.
+     * <p>
+     * The output framebuffer specifies where the scenes attached
+     * to this ViewPort are rendered to. By default this is <code>null</code>
+     * which indicates the scenes are rendered to the display window.
+     * 
+     * @param out The framebuffer to render scenes to, or null if to render
+     * to the screen.
+     */
     public void setOutputFrameBuffer(FrameBuffer out) {
         this.out = out;
     }
 
+    /**
+     * Returns the camera which renders the attached scenes.
+     * 
+     * @return the camera which renders the attached scenes.
+     * 
+     * @see Camera
+     */
     public Camera getCamera() {
         return cam;
     }
 
+    /**
+     * Internal use only.
+     */
     public RenderQueue getQueue() {
         return queue;
     }
 
+    /**
+     * Attaches a new scene to render in this ViewPort.
+     * 
+     * @param scene The scene to attach
+     * 
+     * @see Spatial
+     */
     public void attachScene(Spatial scene){
         sceneList.add(scene);
     }
 
+    /**
+     * Detaches a scene from rendering.
+     * 
+     * @param scene The scene to detach
+     * 
+     * @see #attachScene(com.jme3.scene.Spatial) 
+     */
     public void detachScene(Spatial scene){
         sceneList.remove(scene);
     }
 
+    /**
+     * Removes all attached scenes.
+     * 
+     * @see #attachScene(com.jme3.scene.Spatial) 
+     */
     public void clearScenes() {
         sceneList.clear();
     }
 
+    /**
+     * Returns a list of all attached scenes.
+     * 
+     * @return a list of all attached scenes.
+     * 
+     * @see #attachScene(com.jme3.scene.Spatial) 
+     */
     public List<Spatial> getScenes(){
         return sceneList;
     }
 
+    /**
+     * Sets the background color.
+     * <p>
+     * When the ViewPort's color buffer is cleared 
+     * (if {@link #setClearColor(boolean) color clearing} is enabled), 
+     * this specifies the color to which the color buffer is set to.
+     * By default the background color is black without alpha.
+     * 
+     * @param background the background color.
+     */
     public void setBackgroundColor(ColorRGBA background){
         backColor.set(background);
     }
 
+    /**
+     * Returns the background color of this ViewPort
+     * 
+     * @return the background color of this ViewPort
+     * 
+     * @see #setBackgroundColor(com.jme3.math.ColorRGBA) 
+     */
     public ColorRGBA getBackgroundColor(){
         return backColor;
     }
     
+    /**
+     * Enable or disable this ViewPort.
+     * <p>
+     * Disabled ViewPorts are skipped by the {@link RenderManager} when
+     * rendering. By default all ViewPorts are enabled.
+     * 
+     * @param enable If the viewport should be disabled or enabled.
+     */
     public void setEnabled(boolean enable) {
         this.enabled = enable;
     }
     
+    /**
+     * Returns true if the viewport is enabled, false otherwise.
+     * @return true if the viewport is enabled, false otherwise.
+     * @see #setEnabled(boolean) 
+     */
     public boolean isEnabled() {
         return enabled;
     }