* Added Javadoc for Picture, FrameBuffer, Image.Format, and AppSettings

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

engine/src/core/com/jme3/system/AppSettings.java

@@ -31,6 +31,7 @@
  */
 package com.jme3.system;
 
+import com.jme3.renderer.Renderer;
 import java.awt.image.BufferedImage;
 import java.io.IOException;
 import java.io.InputStream;
@@ -207,63 +208,156 @@ public class AppSettings extends HashMap<String, Object> {
         put(key, value);
     }
 
+    /**
+     * @param frameRate The frame-rate is the upper limit on how high
+     * the application's frames-per-second can go.
+     * (Default: -1 no frame rate limit imposed)
+     */
     public void setFrameRate(int frameRate) {
         putInteger("FrameRate", frameRate);
     }
 
+    /**
+     * @param use If true, the application will initialize and use input.
+     * Set to false for headless applications that do not require keyboard
+     * or mouse input.
+     * (Default: true)
+     */
     public void setUseInput(boolean use) {
         putBoolean("UseInput", use);
     }
 
+    /**
+     * @param use If true, the application will initialize and use joystick
+     * input. Set to false if no joystick input is desired.
+     * (Default: false)
+     */
     public void setUseJoysticks(boolean use) {
         putBoolean("DisableJoysticks", !use);
     }
 
+    /**
+     * Set the graphics renderer to use, one of:<br>
+     * <ul>
+     * <li>AppSettings.LWJGL_OPENGL1 - Force OpenGL1.1 compatability</li>
+     * <li>AppSettings.LWJGL_OPENGL2 - Force OpenGL2 compatability</li>
+     * <li>AppSettings.LWJGL_OPENGL3 - Force OpenGL3.3 compatability</li>
+     * <li>AppSettings.LWJGL_OPENGL_ANY - Choose an appropriate 
+     * OpenGL version based on system capabilities</li>
+     * <li>null - Disable graphics rendering</li>
+     * </ul>
+     * @param renderer The renderer to set
+     * (Default: AppSettings.LWJGL_OPENGL2)
+     */
     public void setRenderer(String renderer) {
         putString("Renderer", renderer);
     }
 
+    /**
+     * Set a custom graphics renderer to use. The class should implement 
+     * the {@link Renderer} interface.
+     * @param clazz The custom graphics renderer class.
+     * (Default: not set)
+     */
     public void setCustomRenderer(Class clazz){
         put("Renderer", "CUSTOM" + clazz.getName());
     }
 
+    /**
+     * Set the audio renderer to use. One of:<br>
+     * <ul>
+     * <li>AppSettings.LWJGL_OPENAL - Default for LWJGL</li>
+     * <li>null - Disable audio</li>
+     * </ul>
+     * @param audioRenderer 
+     * (Default: LWJGL)
+     */
     public void setAudioRenderer(String audioRenderer) {
         putString("AudioRenderer", audioRenderer);
     }
 
+    /**
+     * @param value the width for the rendering display.
+     * (Default: 640)
+     */
     public void setWidth(int value) {
         putInteger("Width", value);
     }
 
+    /**
+     * @param value the height for the rendering display.
+     * (Default: 480)
+     */
     public void setHeight(int value) {
         putInteger("Height", value);
     }
 
+    /**
+     * Set the resolution for the rendering display
+     * @param width The width
+     * @param height The height
+     * (Default: 640x480)
+     */
     public void setResolution(int width, int height) {
         setWidth(width);
         setHeight(height);
     }
 
+    /**
+     * Set the frequency, also known as refresh rate, for the 
+     * rendering display.
+     * @param value The frequency
+     * (Default: 60)
+     */
     public void setFrequency(int value) {
         putInteger("Frequency", value);
     }
 
+    /**
+     * Set the bits per pixel for the display. Appropriate
+     * values are 16 for RGB565 color format, or 24 for RGB8 color format.
+     * 
+     * @param value The bits per pixel to set
+     * (Default: 24)
+     */
     public void setBitsPerPixel(int value) {
         putInteger("BitsPerPixel", value);
     }
 
+    /**
+     * Set the number of samples per pixel. A value of 1 indicates
+     * each pixel should be single-sampled, higher values indicate
+     * a pixel should be multi-sampled.
+     * 
+     * @param value The number of samples
+     * (Default: 1)
+     */
     public void setSamples(int value) {
         putInteger("Samples", value);
     }
 
+    /**
+     * @param title The title of the rendering display
+     * (Default: jMonkeyEngine 3.0)
+     */
     public void setTitle(String title) {
         putString("Title", title);
     }
 
+    /**
+     * @param value true to enable full-screen rendering, false to render in a window
+     * (Default: false)
+     */
     public void setFullscreen(boolean value) {
         putBoolean("Fullscreen", value);
     }
 
+    /**
+     * Set to true to enable vertical-synchronization, limiting and synchronizing
+     * every frame rendered to the monitor's refresh rate.
+     * @param value 
+     * (Default: false)
+     */
     public void setVSync(boolean value) {
         putBoolean("VSync", value);
     }
@@ -280,6 +374,7 @@ public class AppSettings extends HashMap<String, Object> {
      * the icon working for alt-tab on the settings dialog in Windows.
      *
      * @param value An array of BufferedImages to use as icons.
+     * (Default: not set)
      */
     public void setIcons(BufferedImage[] value) {
         put("Icons", value);

engine/src/core/com/jme3/texture/FrameBuffer.java

@@ -32,11 +32,46 @@
 
 package com.jme3.texture;
 
+import com.jme3.renderer.Caps;
 import com.jme3.renderer.GLObject;
 import com.jme3.renderer.Renderer;
 import com.jme3.texture.Image.Format;
 import java.util.ArrayList;
 
+/**
+ * <p>
+ * <code>FrameBuffer</code>s are rendering surfaces allowing
+ * off-screen rendering and render-to-texture functionality.
+ * Instead of the scene rendering to the screen, it is rendered into the 
+ * FrameBuffer, the result can be either a texture or a buffer.
+ * <p>
+ * A <code>FrameBuffer</code> supports two methods of rendering, 
+ * using a {@link Texture} or using a buffer. 
+ * When using a texture, the result of the rendering will be rendered
+ * onto the texture, after which the texture can be placed on an object
+ * and rendered as if the texture was uploaded from disk.
+ * When using a buffer, the result is rendered onto 
+ * a buffer located on the GPU, the data of this buffer is not accessible
+ * to the user. buffers are useful if one
+ * wishes to retrieve only the color content of the scene, but still desires
+ * depth testing (which requires a depth buffer). 
+ * Buffers can be copied to other framebuffers
+ * including the main screen, by using 
+ * {@link Renderer#copyFrameBuffer(com.jme3.texture.FrameBuffer, com.jme3.texture.FrameBuffer) }.
+ * The content of a {@link RenderBuffer} can be retrieved by using 
+ * {@link Renderer#readFrameBuffer(com.jme3.texture.FrameBuffer, java.nio.ByteBuffer) }.
+ * <p>
+ * <code>FrameBuffer</code>s have several attachment points, there are 
+ * several <em>color</em> attachment points and a single <em>depth</em> 
+ * attachment point.
+ * The color attachment points support image formats such as
+ * {@link Format#RGBA8}, allowing rendering the color content of the scene.
+ * The depth attachment point requires a depth image format. 
+ * 
+ * @see Renderer#setFrameBuffer(com.jme3.texture.FrameBuffer) 
+ * 
+ * @author Kirill Vainer
+ */
 public class FrameBuffer extends GLObject {
 
     private int width = 0;
@@ -46,6 +81,11 @@ public class FrameBuffer extends GLObject {
     private RenderBuffer depthBuf = null;
     private int colorBufIndex = 0;
 
+    /**
+     * <code>RenderBuffer</code> represents either a texture or a 
+     * buffer that will be rendered to. <code>RenderBuffer</code>s
+     * are attached to an attachment slot on a <code>FrameBuffer</code>.
+     */
     public class RenderBuffer {
 
         Texture tex;
@@ -53,30 +93,42 @@ public class FrameBuffer extends GLObject {
         int id = -1;
         int slot = -1;
 
+        /**
+         * @return The image format of the render buffer.
+         */
         public Format getFormat() {
             return format;
         }
 
+        /**
+         * @return The texture to render to for this <code>RenderBuffer</code>
+         * or null if content should be rendered into a buffer.
+         */
         public Texture getTexture(){
             return tex;
         }
 
+        /**
+         * Do not use.
+         */
         public int getId() {
             return id;
         }
 
+        /**
+         * Do not use.
+         */
         public void setId(int id){
             this.id = id;
         }
 
+        /**
+         * Do not use.
+         */
         public int getSlot() {
             return slot;
         }
 
-        public void setSlot(int slot) {
-            this.slot = slot;
-        }
-
         public void resetObject(){
             id = -1;
         }
@@ -101,6 +153,23 @@ public class FrameBuffer extends GLObject {
         }
     }
 
+    /**
+     * <p>
+     * Creates a new FrameBuffer with the given width, height, and number
+     * of samples. If any textures are attached to this FrameBuffer, then
+     * they must have the same number of samples as given in this constructor.
+     * <p>
+     * Note that if the {@link Renderer} does not expose the 
+     * {@link Caps#NonPowerOfTwoTextures}, then an exception will be thrown
+     * if the width and height arguments are not power of two.
+     * 
+     * @param width The width to use
+     * @param height The height to use
+     * @param samples The number of samples to use for a multisampled
+     * framebuffer, or 1 if the framebuffer should be singlesampled.
+     * 
+     * @throws IllegalArgumentException If width or height are not positive.
+     */
     public FrameBuffer(int width, int height, int samples){
         super(Type.FrameBuffer);
         if (width <= 0 || height <= 0)
@@ -124,6 +193,12 @@ public class FrameBuffer extends GLObject {
          */
     }
 
+    /**
+     * Enables the use of a depth buffer for this <code>FrameBuffer</code>.
+     * 
+     * @param format The format to use for the depth buffer.
+     * @throws IllegalArgumentException If <code>format</code> is not a depth format.
+     */
     public void setDepthBuffer(Image.Format format){
         if (id != -1)
             throw new UnsupportedOperationException("FrameBuffer already initialized.");
@@ -136,6 +211,12 @@ public class FrameBuffer extends GLObject {
         depthBuf.format = format;
     }
 
+    /**
+     * Enables the use of a color buffer for this <code>FrameBuffer</code>.
+     * 
+     * @param format The format to use for the color buffer.
+     * @throws IllegalArgumentException If <code>format</code> is not a color format.
+     */
     public void setColorBuffer(Image.Format format){
         if (id != -1)
             throw new UnsupportedOperationException("FrameBuffer already initialized.");
@@ -170,38 +251,85 @@ public class FrameBuffer extends GLObject {
             throw new IllegalStateException("Texture samples must match framebuffer samples");
     }
 
+    /**
+     * If enabled, any shaders rendering into this <code>FrameBuffer</code>
+     * will be able to write several results into the renderbuffers
+     * by using the <code>gl_FragData</code> array. Every slot in that
+     * array maps into a color buffer attached to this framebuffer.
+     * 
+     * @param enabled True to enable MRT (multiple rendering targets).
+     */
     public void setMultiTarget(boolean enabled){
         if (enabled) colorBufIndex = -1;
         else colorBufIndex = 0;
     }
 
+    /**
+     * @return True if MRT (multiple rendering targets) is enabled.
+     * @see FrameBuffer#setMultiTarget(boolean)
+     */
+    public boolean isMultiTarget(){
+        return colorBufIndex == -1;
+    }
+    
+    /**
+     * If MRT is not enabled ({@link FrameBuffer#setMultiTarget(boolean) } is false)
+     * then this specifies the color target to which the scene should be rendered.
+     * <p>
+     * By default the value is 0.
+     * 
+     * @param index The color attachment index.
+     * @throws IllegalArgumentException If index is negative or doesn't map
+     * to any attachment on this framebuffer.
+     */
     public void setTargetIndex(int index){
         if (index < 0 || index >= 16)
             throw new IllegalArgumentException();
 
         if (colorBufs.size() >= index)
-            throw new IndexOutOfBoundsException("The target at " + index + " is not set!");
+            throw new IllegalArgumentException("The target at " + index + " is not set!");
 
         colorBufIndex = index;
     }
 
-    public boolean isMultiTarget(){
-        return colorBufIndex == -1;
-    }
-
+    /**
+     * @return The color target to which the scene should be rendered.
+     * 
+     * @see FrameBuffer#setTargetIndex(int) 
+     */
     public int getTargetIndex(){
         return colorBufIndex;
     }
 
+    /**
+     * Set the color texture to use for this framebuffer.
+     * This automatically clears all existing textures added previously
+     * with {@link FrameBuffer#addColorTexture(com.jme3.texture.Texture2D) }
+     * and adds this texture as the only target.
+     * 
+     * @param tex The color texture to set.
+     */
     public void setColorTexture(Texture2D tex){
         clearColorTargets();
         addColorTexture(tex);
     }
 
+    /**
+     * Clears all color targets that were set or added previously.
+     */
     public void clearColorTargets(){
         colorBufs.clear();
     }
 
+    /**
+     * Add a color texture to use for this framebuffer.
+     * If MRT is enabled, then each subsequently added texture can be
+     * rendered to through a shader that writes to the array <code>gl_FragData</code>.
+     * If MRT is not enabled, then the index set with {@link FrameBuffer#setTargetIndex(int) }
+     * is rendered to by the shader.
+     * 
+     * @param tex The texture to add.
+     */
     public void addColorTexture(Texture2D tex) {
         if (id != -1)
             throw new UnsupportedOperationException("FrameBuffer already initialized.");
@@ -217,6 +345,11 @@ public class FrameBuffer extends GLObject {
         colorBufs.add(colorBuf);
     }
 
+    /**
+     * Set the depth texture to use for this framebuffer.
+     * 
+     * @param tex The color texture to set.
+     */
     public void setDepthTexture(Texture2D tex){
         if (id != -1)
             throw new UnsupportedOperationException("FrameBuffer already initialized.");
@@ -230,33 +363,58 @@ public class FrameBuffer extends GLObject {
         depthBuf.format = img.getFormat();
     }
 
+    /**
+     * @return The number of color buffers attached to this texture. 
+     */
     public int getNumColorBuffers(){
         return colorBufs.size();
     }
 
+    /**
+     * @param index
+     * @return The color buffer at the given index.
+     */
     public RenderBuffer getColorBuffer(int index){
         return colorBufs.get(index);
     }
 
+    /**
+     * @return The first color buffer attached to this FrameBuffer, or null
+     * if no color buffers are attached.
+     */
     public RenderBuffer getColorBuffer() {
-        if (colorBufs.size() == 0)
+        if (colorBufs.isEmpty())
             return null;
         
         return colorBufs.get(0);
     }
 
+    /**
+     * @return The depth buffer attached to this FrameBuffer, or null
+     * if no depth buffer is attached
+     */
     public RenderBuffer getDepthBuffer() {
         return depthBuf;
     }
 
+    /**
+     * @return The height in pixels of this framebuffer.
+     */
     public int getHeight() {
         return height;
     }
 
+    /**
+     * @return The width in pixels of this framebuffer.
+     */
     public int getWidth() {
         return width;
     }
 
+    /**
+     * @return The number of samples when using a multisample framebuffer, or
+     * 1 if this is a singlesampled framebuffer.
+     */
     public int getSamples() {
         return samples;
     }

engine/src/core/com/jme3/texture/Image.java

@@ -58,55 +58,207 @@ import com.jme3.renderer.GLObject;
 public class Image extends GLObject implements Savable /*, Cloneable*/ {
 
     public enum Format {
+        /**
+         * 8-bit alpha
+         */
         Alpha8(8),
+        
+        /**
+         * 16-bit alpha
+         */
         Alpha16(16),
 
+        /**
+         * 8-bit grayscale/luminance.
+         */
         Luminance8(8),
+        
+        /**
+         * 16-bit grayscale/luminance.
+         */
         Luminance16(16),
+        
+        /**
+         * half-precision floating-point grayscale/luminance.
+         */
         Luminance16F(16,true),
+        
+        /**
+         * single-precision floating-point grayscale/luminance.
+         */
         Luminance32F(32,true),
         
+        /**
+         * 8-bit luminance/grayscale and 8-bit alpha.
+         */
         Luminance8Alpha8(16),
+        
+        /**
+         * 16-bit luminance/grayscale and 16-bit alpha.
+         */
         Luminance16Alpha16(32),
+        
+        /**
+         * half-precision floating-point grayscale/luminance and alpha.
+         */
         Luminance16FAlpha16F(32,true),
 
         Intensity8(8),
         Intensity16(16),
 
+        /**
+         * 8-bit blue, green, and red.
+         */
         BGR8(24), // BGR and ABGR formats are often used on windows systems
+        
+        /**
+         * 8-bit red, green, and blue.
+         */
         RGB8(24),
+        
+        /**
+         * 10-bit red, green, and blue.
+         */
         RGB10(30),
+        
+        /**
+         * 16-bit red, green, and blue.
+         */
         RGB16(48),
 
+        /**
+         * 5-bit red, 6-bit green, and 5-bit blue.
+         */
         RGB565(16),
+        
+        /**
+         * 4-bit alpha, red, green, and blue. Used on Android only.
+         */
         ARGB4444(16),
+        
+        /**
+         * 5-bit red, green, and blue with 1-bit alpha.
+         */
         RGB5A1(16),
+        
+        /**
+         * 8-bit red, green, blue, and alpha.
+         */
         RGBA8(32),
+        
+        /**
+         * 8-bit alpha, blue, green, and red.
+         */
         ABGR8(32),
+        
+        /**
+         * 16-bit red, green, blue and alpha
+         */
         RGBA16(64),
 
+        /**
+         * S3TC compression DXT1. 
+         * Called BC1 in DirectX10.
+         */
         DXT1(4,false,true, false),
+        
+        /**
+         * S3TC compression DXT1 with 1-bit alpha.
+         */
         DXT1A(4,false,true, false),
+        
+        /**
+         * S3TC compression DXT3 with 4-bit alpha.
+         * Called BC2 in DirectX10.
+         */
         DXT3(8,false,true, false),
+        
+        /**
+         * S3TC compression DXT5 with interpolated 8-bit alpha.
+         * Called BC3 in DirectX10.
+         */
         DXT5(8,false,true, false),
+        
+        /**
+         * Luminance-Alpha Texture Compression. 
+         * Called BC5 in DirectX10.
+         */
         LATC(8, false, true, false),
 
+        /**
+         * Arbitrary depth format. The precision is chosen by the video
+         * hardware.
+         */
         Depth(0,true,false,false),
+        
+        /**
+         * 16-bit depth.
+         */
         Depth16(16,true,false,false),
+        
+        /**
+         * 24-bit depth.
+         */
         Depth24(24,true,false,false),
+        
+        /**
+         * 32-bit depth.
+         */
         Depth32(32,true,false,false),
+        
+        /**
+         * single-precision floating point depth.
+         */
         Depth32F(32,true,false,true),
 
+        /**
+         * Texture data is stored as {@link Format#RGB16F} in system memory,
+         * but will be converted to {@link Format#RGB111110F} when sent
+         * to the video hardware.
+         */
         RGB16F_to_RGB111110F(48,true),
+        
+        /**
+         * unsigned floating-point red, green and blue that uses 32 bits.
+         */
         RGB111110F(32,true),
+        
+        /**
+         * Texture data is stored as {@link Format#RGB16F} in system memory,
+         * but will be converted to {@link Format#RGB9E5} when sent
+         * to the video hardware.
+         */
         RGB16F_to_RGB9E5(48,true),
+        
+        /**
+         * 9-bit red, green and blue with 5-bit exponent.
+         */
         RGB9E5(32,true),
         
+        /**
+         * half-precision floating point red, green, and blue.
+         */
         RGB16F(48,true),
+        
+        /**
+         * half-precision floating point red, green, blue, and alpha.
+         */
         RGBA16F(64,true),
+        
+        /**
+         * single-precision floating point red, green, and blue.
+         */
         RGB32F(96,true),
+        
+        /**
+         * single-precision floating point red, green, blue and alpha.
+         */
         RGBA32F(128,true),
 
+        /**
+         * Luminance/grayscale texture compression. 
+         * Called BC4 in DirectX10.
+         */
         LTC(4, false, true, false);
 
         private int bpp;
@@ -129,18 +281,32 @@ public class Image extends GLObject implements Savable /*, Cloneable*/ {
             this.isCompressed = isCompressed;
         }
 
+        /**
+         * @return bits per pixel.
+         */
         public int getBitsPerPixel(){
             return bpp;
         }
 
+        /**
+         * @return True if this format is a depth format, false otherwise.
+         */
         public boolean isDepthFormat(){
             return isDepth;
         }
 
+        /**
+         * @return True if this is a compressed image format, false if
+         * uncompressed.
+         */
         public boolean isCompressed() {
             return isCompressed;
         }
 
+        /**
+         * @return True if this image format is in floating point, 
+         * false if it is an integer format.
+         */
         public boolean isFloatingPont(){
             return isFloatingPoint;
         }
@@ -152,7 +318,7 @@ public class Image extends GLObject implements Savable /*, Cloneable*/ {
     protected int width, height, depth;
     protected int[] mipMapSizes;
     protected ArrayList<ByteBuffer> data;
-    protected transient Object efficentData;
+    protected transient Object efficientData;
     protected int multiSamples = 1;
 //    protected int mipOffset = 0;
 
@@ -172,6 +338,9 @@ public class Image extends GLObject implements Savable /*, Cloneable*/ {
         return new Image(id);
     }
 
+    /**
+     * @return A shallow clone of this image. The data is not cloned.
+     */
     @Override
     public Image clone(){
         Image clone = (Image) super.clone();
@@ -365,24 +534,24 @@ public class Image extends GLObject implements Savable /*, Cloneable*/ {
     }
 
     /**
-     * Set the efficent data representation of this image.
+     * Set the efficient data representation of this image.
      * <p>
-     * Some system implementations are more efficent at operating
+     * Some system implementations are more efficient at operating
      * on data other than ByteBuffers, in that case, this method can be used.
      *
      * @param efficentData
      */
-    public void setEfficentData(Object efficentData){
-        this.efficentData = efficentData;
+    public void setEfficentData(Object efficientData){
+        this.efficientData = efficientData;
         setUpdateNeeded();
     }
 
     /**
-     * @return The efficent data representation of this image.
+     * @return The efficient data representation of this image.
      * @see Image#setEfficentData(java.lang.Object)
      */
     public Object getEfficentData(){
-        return efficentData;
+        return efficientData;
     }
 
     /**
@@ -557,6 +726,7 @@ public class Image extends GLObject implements Savable /*, Cloneable*/ {
         return sb.toString();
     }
 
+    @Override
     public boolean equals(Object other) {
         if (other == this) {
             return true;

engine/src/core/com/jme3/ui/Picture.java

@@ -51,46 +51,104 @@ import com.jme3.texture.Texture2D;
  */
 public class Picture extends Geometry {
 
-    private float width;
-    private float height;
+    private float width  = 1f;
+    private float height = 1f;
 
+    /**
+     * Create a named picture. 
+     * By default a picture's width and height are 1
+     * and its position is 0, 0.
+     * 
+     * @param name the name of the picture in the scene graph
+     * @param flipY If true, the Y coordinates of the texture will be flipped.
+     */
     public Picture(String name, boolean flipY){
         super(name, new Quad(1, 1, flipY));
         setQueueBucket(Bucket.Gui);
         setCullHint(CullHint.Never);
     }
 
+    /**
+     * Creates a named picture.
+     * By default a picture's width and height are 1
+     * and its position is 0, 0.
+     * The image texture coordinates will not be flipped.
+     * 
+     * @param name the name of the picture in the scene graph 
+     */
     public Picture(String name){
         this(name, false);
     }
 
+    /*
+     * Serialization only. Do not use.
+     */
     public Picture(){
     }
 
+    /**
+     * Set the width in pixels of the picture, if the width
+     * does not match the texture's width, then the texture will
+     * be scaled to fit the picture.
+     * 
+     * @param width the width to set.
+     */
     public void setWidth(float width){
         this.width = width;
         setLocalScale(new Vector3f(width, height, 1f));
     }
 
+    /**
+     * Set the height in pixels of the picture, if the height
+     * does not match the texture's height, then the texture will
+     * be scaled to fit the picture.
+     * 
+     * @param height the height to set.
+     */
     public void setHeight(float height){
         this.height = height;
         setLocalScale(new Vector3f(width, height, 1f));
     }
 
+    /**
+     * Set the position of the picture in pixels.
+     * The origin (0, 0) is at the bottom-left of the screen.
+     * 
+     * @param x The x coordinate
+     * @param y The y coordinate
+     */
     public void setPosition(float x, float y){
         float z = getLocalTranslation().getZ();
         setLocalTranslation(x, y, z);
     }
 
-    public void setImage(AssetManager manager, String imgName, boolean useAlpha){
+    /**
+     * Set the image to put on the picture.
+     * 
+     * @param assetManager The {@link AssetManager} to use to load the image.
+     * @param imgName The image name.
+     * @param useAlpha If true, the picture will appear transparent and allow
+     * objects behind it to appear through. If false, the transparent
+     * portions will be black.
+     */
+    public void setImage(AssetManager assetManager, String imgName, boolean useAlpha){
         TextureKey key = new TextureKey(imgName, true);
-        Texture2D tex = (Texture2D) manager.loadTexture(key);
-        setTexture(manager, tex, useAlpha);
+        Texture2D tex = (Texture2D) assetManager.loadTexture(key);
+        setTexture(assetManager, tex, useAlpha);
     }
 
-    public void setTexture(AssetManager manager, Texture2D tex, boolean useAlpha){
+    /**
+     * Set the texture to put on the picture.
+     * 
+     * @param assetManager The {@link AssetManager} to use to load the material.
+     * @param tex The texture
+     * @param useAlpha If true, the picture will appear transparent and allow
+     * objects behind it to appear through. If false, the transparent
+     * portions will be black.
+     */
+    public void setTexture(AssetManager assetManager, Texture2D tex, boolean useAlpha){
         if (getMaterial() == null){
-            Material mat = new Material(manager, "Common/MatDefs/Gui/Gui.j3md");
+            Material mat = new Material(assetManager, "Common/MatDefs/Gui/Gui.j3md");
             mat.setColor("Color", ColorRGBA.White);
             setMaterial(mat);
         }

engine/src/core/com/jme3/util/BufferUtils.java

@@ -70,6 +70,13 @@ public final class BufferUtils {
 
     ////  -- GENERIC CLONE -- ////
 
+    /**
+     * Creates a clone of the given buffer. The clone's capacity is
+     * equal to the given buffer's limit.
+     * 
+     * @param buf The buffer to clone
+     * @return The cloned buffer
+     */
     public static Buffer clone(Buffer buf){
         if (buf instanceof FloatBuffer){
             return clone( (FloatBuffer) buf );

engine/src/core/com/jme3/util/IntMap.java

@@ -74,6 +74,7 @@ public final class IntMap<T> implements Iterable<Entry<T>>, Cloneable {
         this.mask = capacity - 1;
     }
 
+    @Override
     public IntMap<T> clone(){
         try{
             IntMap<T> clone = (IntMap<T>) super.clone();