diff --git a/engine/src/core/com/jme3/system/AppSettings.java b/engine/src/core/com/jme3/system/AppSettings.java index a3a89b407..fcb377f7d 100644 --- a/engine/src/core/com/jme3/system/AppSettings.java +++ b/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 { 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:
+ * + * @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:
+ * + * @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 { * 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); diff --git a/engine/src/core/com/jme3/texture/FrameBuffer.java b/engine/src/core/com/jme3/texture/FrameBuffer.java index e8ae1a74c..f642badd5 100644 --- a/engine/src/core/com/jme3/texture/FrameBuffer.java +++ b/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; +/** + *

+ * FrameBuffers 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. + *

+ * A FrameBuffer 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) }. + *

+ * FrameBuffers have several attachment points, there are + * several color attachment points and a single depth + * 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; + /** + * RenderBuffer represents either a texture or a + * buffer that will be rendered to. RenderBuffers + * are attached to an attachment slot on a FrameBuffer. + */ 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 RenderBuffer + * 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 { } } + /** + *

+ * 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. + *

+ * 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 FrameBuffer. + * + * @param format The format to use for the depth buffer. + * @throws IllegalArgumentException If format 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 FrameBuffer. + * + * @param format The format to use for the color buffer. + * @throws IllegalArgumentException If format 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 FrameBuffer + * will be able to write several results into the renderbuffers + * by using the gl_FragData 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. + *

+ * 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 gl_FragData. + * 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; } diff --git a/engine/src/core/com/jme3/texture/Image.java b/engine/src/core/com/jme3/texture/Image.java index e448fee9b..8670118c7 100644 --- a/engine/src/core/com/jme3/texture/Image.java +++ b/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 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. *

- * 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; diff --git a/engine/src/core/com/jme3/ui/Picture.java b/engine/src/core/com/jme3/ui/Picture.java index 13dd821ab..3e8ac2687 100644 --- a/engine/src/core/com/jme3/ui/Picture.java +++ b/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); } diff --git a/engine/src/core/com/jme3/util/BufferUtils.java b/engine/src/core/com/jme3/util/BufferUtils.java index ba187a8d2..d8f3e52f2 100644 --- a/engine/src/core/com/jme3/util/BufferUtils.java +++ b/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 ); diff --git a/engine/src/core/com/jme3/util/IntMap.java b/engine/src/core/com/jme3/util/IntMap.java index 252b000ad..abbaa77b6 100644 --- a/engine/src/core/com/jme3/util/IntMap.java +++ b/engine/src/core/com/jme3/util/IntMap.java @@ -74,6 +74,7 @@ public final class IntMap implements Iterable>, Cloneable { this.mask = capacity - 1; } + @Override public IntMap clone(){ try{ IntMap clone = (IntMap) super.clone();