* Javadocs for com.jme3.renderer.queue

* Javadocs for com.jme3.renderer

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

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

@@ -45,6 +45,9 @@ public class IDList {
     public int newLen = 0;
     public int oldLen = 0;
 
+    /**
+     * Reset all states to zero
+     */
     public void reset(){
         newLen = 0;
         oldLen = 0;
@@ -52,6 +55,16 @@ public class IDList {
         Arrays.fill(oldList, 0);
     }
 
+    /**
+     * Adds an index to the new list.
+     * If the index was not in the old list, false is returned,
+     * if the index was in the old list, it is removed from the old
+     * list and true is returned.
+     * 
+     * @param idx The index to move
+     * @return True if it existed in old list and was removed
+     * from there, false otherwise.
+     */
     public boolean moveToNew(int idx){
         if (newLen == 0 || newList[newLen-1] != idx)
             // add item to newList first
@@ -72,12 +85,18 @@ public class IDList {
         return false;
     }
 
+    /**
+     * Copies the new list to the old list, and clears the new list.
+     */
     public void copyNewToOld(){
         System.arraycopy(newList, 0, oldList, 0, newLen);
         oldLen = newLen;
         newLen = 0;
     }
 
+    /**
+     * Prints the contents of the lists
+     */
     public void print(){
         if (newLen > 0){
             System.out.print("New List: ");

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

@@ -32,8 +32,11 @@
 
 package com.jme3.renderer;
 
+import com.jme3.material.Material;
 import com.jme3.material.RenderState;
+import com.jme3.scene.Mesh;
 import com.jme3.scene.VertexBuffer;
+import com.jme3.texture.FrameBuffer;
 import com.jme3.texture.Image;
 
 /**
@@ -43,58 +46,104 @@ import com.jme3.texture.Image;
 public class RenderContext {
 
     /**
-     * If back-face culling is enabled.
+     * @see RenderState#setFaceCullMode(com.jme3.material.RenderState.FaceCullMode)
      */
     public RenderState.FaceCullMode cullMode = RenderState.FaceCullMode.Off;
 
     /**
-     * If Depth testing is enabled.
+     * @see RenderState#setDepthTest(boolean) 
      */
     public boolean depthTestEnabled = false;
 
+    /**
+     * @see RenderState#setAlphaTest(boolean) 
+     */
     public boolean alphaTestEnabled = false;
 
+    /**
+     * @see RenderState#setDepthWrite(boolean) 
+     */
     public boolean depthWriteEnabled = true;
 
+    /**
+     * @see RenderState#setColorWrite(boolean) 
+     */
     public boolean colorWriteEnabled = true;
 
+    /**
+     * @see Renderer#setClipRect(int, int, int, int) 
+     */
     public boolean clipRectEnabled = false;
 
+    /**
+     * @see RenderState#setPolyOffset(float, float) 
+     */
     public boolean polyOffsetEnabled = false;
+    
+    /**
+     * @see RenderState#setPolyOffset(float, float) 
+     */
     public float polyOffsetFactor = 0;
+    
+    /**
+     * @see RenderState#setPolyOffset(float, float) 
+     */
     public float polyOffsetUnits = 0;
 
+    /**
+     * For normals only. Uses GL_NORMALIZE.
+     * 
+     * @see VertexBuffer#setNormalized(boolean) 
+     */
     public boolean normalizeEnabled = false;
 
+    /**
+     * For glMatrixMode.
+     * 
+     * @see Renderer#setWorldMatrix(com.jme3.math.Matrix4f) 
+     * @see Renderer#setViewProjectionMatrices(com.jme3.math.Matrix4f, com.jme3.math.Matrix4f) 
+     */
     public int matrixMode = -1;
 
+    /**
+     * @see Mesh#setPointSize(float) 
+     */
     public float pointSize = 1;
+    
+    /**
+     * @see Mesh#setLineWidth(float) 
+     */
     public float lineWidth = 1;
 
+    /**
+     * @see RenderState#setBlendMode(com.jme3.material.RenderState.BlendMode) 
+     */
     public RenderState.BlendMode blendMode = RenderState.BlendMode.Off;
 
     /**
-     * If wireframe rendering is enabled. False if fill rendering is enabled.
+     * @see RenderState#setWireframe(boolean) 
      */
     public boolean wireframe = false;
 
     /**
-     * Point sprite mode
+     * @see RenderState#setPointSprite(boolean) 
      */
     public boolean pointSprite = false;
 
     /**
-     * The currently bound shader program.
+     * @see Renderer#setShader(com.jme3.shader.Shader) 
      */
     public int boundShaderProgram;
 
     /**
-     * Currently bound Framebuffer Object.
+     * @see Renderer#setFrameBuffer(com.jme3.texture.FrameBuffer) 
      */
     public int boundFBO = 0;
 
     /**
      * Currently bound Renderbuffer
+     * 
+     * @see Renderer#setFrameBuffer(com.jme3.texture.FrameBuffer) 
      */
     public int boundRB = 0;
 
@@ -105,6 +154,9 @@ public class RenderContext {
      *  0 = GL_COLOR_ATTACHMENT0
      *  n = GL_COLOR_ATTACHMENTn
      *  where n is an integer greater than 1
+     * 
+     * @see Renderer#setFrameBuffer(com.jme3.texture.FrameBuffer) 
+     * @see FrameBuffer#setTargetIndex(int) 
      */
     public int boundDrawBuf = -1;
 
@@ -112,18 +164,27 @@ public class RenderContext {
      * Currently bound read buffer
      *
      * @see RenderContext#boundDrawBuf
+     * @see Renderer#setFrameBuffer(com.jme3.texture.FrameBuffer) 
+     * @see FrameBuffer#setTargetIndex(int) 
      */
     public int boundReadBuf = -1;
 
     /**
      * Currently bound element array vertex buffer.
+     * 
+     * @see Renderer#renderMesh(com.jme3.scene.Mesh, int, int) 
      */
     public int boundElementArrayVBO;
 
+    /**
+     * @see Renderer#renderMesh(com.jme3.scene.Mesh, int, int) 
+     */
     public int boundVertexArray;
 
     /**
      * Currently bound array vertex buffer.
+     * 
+     * @see Renderer#renderMesh(com.jme3.scene.Mesh, int, int) 
      */
     public int boundArrayVBO;
 
@@ -131,11 +192,23 @@ public class RenderContext {
 
     /**
      * Current bound texture IDs for each texture unit.
+     * 
+     * @see Renderer#setTexture(int, com.jme3.texture.Texture) 
      */
     public Image[] boundTextures = new Image[16];
 
+    /**
+     * IDList for texture units
+     * 
+     * @see Renderer#setTexture(int, com.jme3.texture.Texture) 
+     */
     public IDList textureIndexList = new IDList();
 
+    /**
+     * Currently bound texture unit
+     * 
+     * @see Renderer#setTexture(int, com.jme3.texture.Texture) 
+     */
     public int boundTextureUnit = 0;
 
     /**
@@ -157,8 +230,14 @@ public class RenderContext {
      */
     public VertexBuffer[] boundAttribs = new VertexBuffer[16];
 
+    /**
+     * IDList for vertex attributes
+     */
     public IDList attribIndexList = new IDList();
 
+    /**
+     * Reset the RenderContext to default GL state
+     */
     public void reset(){
         cullMode = RenderState.FaceCullMode.Off;
         depthTestEnabled = false;

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

@@ -62,6 +62,9 @@ public interface Renderer {
     /**
      * The statistics allow tracking of how data
      * per frame, such as number of objects rendered, number of triangles, etc.
+     * These are updated when the Renderer's methods are used, make sure
+     * to call {@link Statistics#clearFrame() } at the appropriate time
+     * to get accurate info per frame.
      */
     public Statistics getStatistics();
 
@@ -72,7 +75,7 @@ public interface Renderer {
     public void invalidateState();
 
     /**
-     * Clears certain channels of the current bound framebuffer.
+     * Clears certain channels of the currently bound framebuffer.
      *
      * @param color True if to clear colors (RGBA)
      * @param depth True if to clear depth/z
@@ -83,20 +86,23 @@ public interface Renderer {
 
     /**
      * Sets the background (aka clear) color.
-     * @param color
+     * 
+     * @param color The background color to set
      */
     public void setBackgroundColor(ColorRGBA color);
 
     /**
-     * Applies the given renderstate, making the neccessary
+     * Applies the given {@link RenderState}, making the necessary
      * GL calls so that the state is applied.
      */
     public void applyRenderState(RenderState state);
 
     /**
-     * Set the range of the depth values for objects. 
-     * @param start
-     * @param end
+     * Set the range of the depth values for objects. All rendered
+     * objects will have their depth clamped to this range.
+     * 
+     * @param start The range start
+     * @param end The range end
      */
     public void setDepthRange(float start, float end);
 
@@ -106,47 +112,93 @@ public interface Renderer {
     public void onFrame();
 
     /**
-     * @param worldMatrix The world transform to use. This changes
-     * the world matrix given in the shader.
+     * Set the world matrix to use. Does nothing if the Renderer is 
+     * shader based.
+     * 
+     * @param worldMatrix World matrix to use.
      */
     public void setWorldMatrix(Matrix4f worldMatrix);
 
+    /**
+     * Sets the view and projection matrices to use. Does nothing if the Renderer 
+     * is shader based.
+     * 
+     * @param viewMatrix The view matrix to use.
+     * @param projMatrix The projection matrix to use.
+     */
     public void setViewProjectionMatrices(Matrix4f viewMatrix, Matrix4f projMatrix);
 
+    /**
+     * Set the viewport location and resolution on the screen.
+     * 
+     * @param x The x coordinate of the viewport
+     * @param y The y coordinate of the viewport
+     * @param width Width of the viewport
+     * @param height Height of the viewport
+     */
     public void setViewPort(int x, int y, int width, int height);
 
+    /**
+     * Specifies a clipping rectangle.
+     * For all future rendering commands, no pixels will be allowed
+     * to be rendered outside of the clip rectangle.
+     * 
+     * @param x The x coordinate of the clip rect
+     * @param y The y coordinate of the clip rect
+     * @param width Width of the clip rect
+     * @param height Height of the clip rect
+     */
     public void setClipRect(int x, int y, int width, int height);
 
+    /**
+     * Clears the clipping rectangle set with 
+     * {@link #setClipRect(int, int, int, int) }.
+     */
     public void clearClipRect();
 
+    /**
+     * Set lighting state.
+     * Does nothing if the renderer is shader based.
+     * The lights should be provided in world space. 
+     * Specify <code>null</code> to disable lighting.
+     * 
+     * @param lights The light list to set.
+     */
     public void setLighting(LightList lights);
 
     /**
-     * @param shader Sets the shader to use for rendering, uploading it
-     * if neccessary.
+     * Sets the shader to use for rendering.
+     * If the shader has not been uploaded yet, it is compiled
+     * and linked. If it has been uploaded, then the 
+     * uniform data is updated and the shader is set.
+     * 
+     * @param shader The shader to use for rendering.
      */
     public void setShader(Shader shader);
 
     /**
-     * @param shader The shader to delete. This method also deletes
+     * Deletes a shader. This method also deletes
      * the attached shader sources.
+     * 
+     * @param shader Shader to delete.
      */
     public void deleteShader(Shader shader);
 
     /**
      * Deletes the provided shader source.
-     * @param source
+     * 
+     * @param source The ShaderSource to delete.
      */
     public void deleteShaderSource(ShaderSource source);
 
     /**
-     * Copies contents from src to dst, scaling if neccessary.
+     * Copies contents from src to dst, scaling if necessary.
      */
     public void copyFrameBuffer(FrameBuffer src, FrameBuffer dst);
 
     /**
-     * Copies contents from src to dst, scaling if neccessary.
-     * set copyDepth to false ton ly copy the color
+     * Copies contents from src to dst, scaling if necessary.
+     * set copyDepth to false to only copy the color buffers.
      */
     public void copyFrameBuffer(FrameBuffer src, FrameBuffer dst, boolean copyDepth);
 
@@ -161,8 +213,9 @@ public interface Renderer {
      * Only color pixels are transferred, the format is BGRA with 8 bits 
      * per component. The given byte buffer should have at least
      * fb.getWidth() * fb.getHeight() * 4 bytes remaining.
-     * @param fb
-     * @param byteBuf
+     * 
+     * @param fb The framebuffer to read from
+     * @param byteBuf The bytebuffer to transfer color data to
      */
     public void readFrameBuffer(FrameBuffer fb, ByteBuffer byteBuf);
 
@@ -202,25 +255,43 @@ public interface Renderer {
      * The int variable gl_InstanceID can be used to access the current
      * instance of the mesh being rendered inside the vertex shader.
      *
-     * @param mesh
-     * @param count
+     * @param mesh The mesh to render
+     * @param lod The LOD level to use, see {@link Mesh#setLodLevels(com.jme3.scene.VertexBuffer[]) }.
+     * @param count Number of mesh instances to render
      */
     public void renderMesh(Mesh mesh, int lod, int count);
 
     /**
-     * Called on restart() to reset all GL objects
+     * Resets all previously used {@link GLObject}s on this Renderer.
+     * The state of the GLObjects is reset in such way, that using
+     * them again will cause the renderer to reupload them.
+     * Call this method when you know the GL context is going to shutdown.
+     * 
+     * @see GLObject#resetObject() 
      */
     public void resetGLObjects();
 
     /**
-     * Called when the display is restarted to delete
-     * all created GL objects.
+     * Deletes all previously used {@link GLObject}s on this Renderer, and
+     * then resets the GLObjects.
+     * 
+     * @see #resetGLObjects() 
+     * @see GLObject#deleteObject(com.jme3.renderer.Renderer) 
      */
     public void cleanup();
 
     /**
-     * sets alpha to coverage
-     * @param value
+     * Sets the alpha to coverage state.
+     * <p>
+     * When alpha coverage and multi-sampling is enabled, 
+     * each pixel will contain alpha coverage in all
+     * of its subsamples, which is then combined when
+     * other future alpha-blended objects are rendered.
+     * </p>
+     * <p>
+     * Alpha-to-coverage is useful for rendering transparent objects
+     * without having to worry about sorting them.
+     * </p>
      */
     public void setAlphaToCoverage(boolean value);
 }

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

@@ -41,7 +41,7 @@ package com.jme3.renderer;
 public class RendererException extends RuntimeException {
     
     /**
-     * Creates a new isntance of <code>RendererException</code>
+     * Creates a new instance of <code>RendererException</code>
      */
     public RendererException(String message){
         super(message);

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

@@ -91,6 +91,13 @@ public class Statistics {
 
     }
 
+    /**
+     * Retrieves the statistics data into the given array.
+     * The array should be as large as the array given in 
+     * {@link #getLabels() }.
+     * 
+     * @param data The data array to write to
+     */
     public void getData(int[] data){
         data[0] = numVertices;
         data[1] = numTriangles;
@@ -110,12 +117,22 @@ public class Statistics {
         data[12] = memoryFrameBuffers;
     }
 
+    /**
+     * Called by the Renderer when a mesh has been drawn.
+     * 
+     */
     public void onMeshDrawn(Mesh mesh, int lod){
         numObjects ++;
         numTriangles += mesh.getTriangleCount(lod);
         numVertices += mesh.getVertexCount();
     }
 
+    /**
+     * Called by the Renderer when a shader has been utilized.
+     * 
+     * @param shader The shader that was used
+     * @param wasSwitched If true, the shader has required a state switch
+     */
     public void onShaderUse(Shader shader, boolean wasSwitched){
         assert shader.id >= 1;
 
@@ -126,10 +143,19 @@ public class Statistics {
             numShaderSwitches++;
     }
 
+    /**
+     * Called by the Renderer when a uniform was set.
+     */
     public void onUniformSet(){
         numUniformsSet ++;
     }
 
+    /**
+     * Called by the Renderer when a texture has been set.
+     * 
+     * @param image The image that was set
+     * @param wasSwitched If true, the texture has required a state switch
+     */
     public void onTextureUse(Image image, boolean wasSwitched){
         assert image.id >= 1;
 
@@ -140,6 +166,12 @@ public class Statistics {
             numTextureBinds ++;
     }
 
+    /**
+     * Called by the Renderer when a framebuffer has been set.
+     * 
+     * @param fb The framebuffer that was set
+     * @param wasSwitched If true, the framebuffer required a state switch
+     */
     public void onFrameBufferUse(FrameBuffer fb, boolean wasSwitched){
         if (fb != null){
             assert fb.id >= 1;
@@ -152,6 +184,9 @@ public class Statistics {
             numFboSwitches ++;
     }
     
+    /**
+     * Clears all frame-specific statistics such as objects used per frame.
+     */
     public void clearFrame(){
         shadersUsed.clear();
         texturesUsed.clear();
@@ -166,26 +201,44 @@ public class Statistics {
         numUniformsSet = 0;
     }
 
+    /**
+     * Called by the Renderer when it creates a new shader
+     */
     public void onNewShader(){
         memoryShaders ++;
     }
 
+    /**
+     * Called by the Renderer when it creates a new texture
+     */
     public void onNewTexture(){
         memoryTextures ++;
     }
 
+    /**
+     * Called by the Renderer when it creates a new framebuffer
+     */
     public void onNewFrameBuffer(){
         memoryFrameBuffers ++;
     }
 
+    /**
+     * Called by the Renderer when it deletes a shader
+     */
     public void onDeleteShader(){
         memoryShaders --;
     }
 
+    /**
+     * Called by the Renderer when it deletes a texture
+     */
     public void onDeleteTexture(){
         memoryTextures --;
     }
 
+    /**
+     * Called by the Renderer when it deletes a framebuffer
+     */
     public void onDeleteFrameBuffer(){
         memoryFrameBuffers --;
     }

engine/src/core/com/jme3/renderer/queue/GeometryComparator.java

@@ -36,6 +36,18 @@ import com.jme3.renderer.Camera;
 import com.jme3.scene.Geometry;
 import java.util.Comparator;
 
+/**
+ * <code>GeometryComparator</code> is a special version of {@link Comparator}
+ * that is used to sort geometries for rendering in the {@link RenderQueue}.
+ * 
+ * @author Kirill Vainer
+ */
 public interface GeometryComparator extends Comparator<Geometry> {
+    
+    /**
+     * Set the camera to use for sorting.
+     * 
+     * @param cam The camera to use for sorting
+     */
     public void setCamera(Camera cam);
 }

engine/src/core/com/jme3/renderer/queue/GeometryList.java

@@ -35,14 +35,14 @@ package com.jme3.renderer.queue;
 import com.jme3.renderer.Camera;
 import com.jme3.scene.Geometry;
 import com.jme3.util.SortUtil;
-import java.util.Arrays;
 
 /**
- * This class is a special function list of Spatial objects for render
+ * This class is a special purpose list of {@link Geometry} objects for render
  * queuing.
  *
  * @author Jack Lindamood
  * @author Three Rings - better sorting alg.
+ * @author Kirill Vainer
  */
 public class GeometryList {
 
@@ -53,6 +53,12 @@ public class GeometryList {
     private int size;
     private GeometryComparator comparator;
 
+    /**
+     * Initializes the GeometryList to use the given {@link GeometryComparator}
+     * to use for comparing geometries.
+     * 
+     * @param comparator The comparator to use.
+     */
     public GeometryList(GeometryComparator comparator) {
         size = 0;
         geometries = new Geometry[DEFAULT_SIZE];
@@ -60,20 +66,38 @@ public class GeometryList {
         this.comparator = comparator;
     }
 
+    /**
+     * Set the camera that will be set on the geometry comparators 
+     * via {@link GeometryComparator#setCamera(com.jme3.renderer.Camera)}.
+     * 
+     * @param cam Camera to use for sorting.
+     */
     public void setCamera(Camera cam){
         this.comparator.setCamera(cam);
     }
 
+    /**
+     * Returns the number of elements in this GeometryList.
+     * 
+     * @return Number of elements in the list
+     */
     public int size(){
         return size;
     }
 
+    /**
+     * Returns the element at the given index.
+     * 
+     * @param index The index to lookup
+     * @return Geometry at the index
+     */
     public Geometry get(int index){
         return geometries[index];
     }
 
     /**
-     * Adds a geometry to the list. List size is doubled if there is no room.
+     * Adds a geometry to the list. 
+     * List size is doubled if there is no room.
      *
      * @param g
      *            The geometry to add.

engine/src/core/com/jme3/renderer/queue/OpaqueComparator.java

@@ -71,9 +71,6 @@ public class OpaqueComparator implements GeometryComparator {
     }
 
     public int compare(Geometry o1, Geometry o2) {
-        if (o1 == null || o2 == null)
-            return -1;
-
         Material m1 = o1.getMaterial();
         Material m2 = o2.getMaterial();
 

engine/src/core/com/jme3/renderer/queue/RenderQueue.java

@@ -37,6 +37,12 @@ import com.jme3.renderer.RenderManager;
 import com.jme3.scene.Geometry;
 import com.jme3.scene.Spatial;
 
+/**
+ * <code>RenderQueue</code> is used to queue up and sort 
+ * {@link Geometry geometries} for rendering.
+ * 
+ * @author Kirill Vainer
+ */
 public class RenderQueue {
 
     private GeometryList opaqueList;
@@ -47,6 +53,10 @@ public class RenderQueue {
     private GeometryList shadowRecv;
     private GeometryList shadowCast;
 
+    /**
+     * Creates a new RenderQueue, the default {@link GeometryComparator comparators}
+     * are used for all {@link GeometryList geometry lists}.
+     */
     public RenderQueue() {
         this.opaqueList = new GeometryList(new OpaqueComparator());
         this.guiList = new GeometryList(new GuiComparator());