From f182b5d91b91248bfed80b3250e15ba66d35f6b6 Mon Sep 17 00:00:00 2001 From: "sha..rd" Date: Sun, 24 Jul 2011 23:47:18 +0000 Subject: [PATCH] * Javadoc for some classes git-svn-id: https://jmonkeyengine.googlecode.com/svn/trunk@7912 75d07b2b-3a1a-0410-a2c5-0572b91ccdca --- .../src/core/com/jme3/system/AppSettings.java | 300 ++++++++++++++++-- engine/src/core/com/jme3/ui/Picture.java | 4 +- engine/src/core/com/jme3/util/IntMap.java | 6 + .../src/core/com/jme3/util/xml/SAXUtil.java | 9 + 4 files changed, 296 insertions(+), 23 deletions(-) diff --git a/engine/src/core/com/jme3/system/AppSettings.java b/engine/src/core/com/jme3/system/AppSettings.java index 0cbc9bf2c..80656bf5e 100644 --- a/engine/src/core/com/jme3/system/AppSettings.java +++ b/engine/src/core/com/jme3/system/AppSettings.java @@ -42,17 +42,87 @@ import java.util.Properties; import java.util.prefs.BackingStoreException; import java.util.prefs.Preferences; +/** + * AppSettings provides a store of configuration + * to be used by the application. + *

+ * By default only the {@link JmeContext context} uses the configuration, + * however the user may set and retrieve the settings as well. + * + * @author Kirill Vainer + */ public class AppSettings extends HashMap { private static final AppSettings defaults = new AppSettings(false); - public static final String LWJGL_OPENGL1 = "LWJGL-OPENGL1", - LWJGL_OPENGL2 = "LWJGL-OpenGL2", - LWJGL_OPENGL3 = "LWJGL-OpenGL3", - LWJGL_OPENGL_ANY = "LWJGL-OpenGL-Any", - JOGL = "JOGL", - NULL = "NULL"; + + /** + * Use LWJGL as the display system and force using the OpenGL1.1 renderer. + * + * @see AppSettings#setRenderer(java.lang.String) + */ + public static final String LWJGL_OPENGL1 = "LWJGL-OPENGL1"; + + /** + * Use LWJGL as the display system and force using the OpenGL2.0 renderer. + *

+ * If the underlying system does not support OpenGL2.0, then the context + * initialization will throw an exception. + * + * @see AppSettings#setRenderer(java.lang.String) + */ + public static final String LWJGL_OPENGL2 = "LWJGL-OpenGL2"; + + /** + * Use LWJGL as the display system and force using the core OpenGL3.3 renderer. + *

+ * If the underlying system does not support OpenGL3.3, then the context + * initialization will throw an exception. Note that currently jMonkeyEngine + * does not have any shaders that support OpenGL3.3 therefore this + * option is not useful. + * + * + * @see AppSettings#setRenderer(java.lang.String) + */ + public static final String LWJGL_OPENGL3 = "LWJGL-OpenGL3"; + + /** + * Use LWJGL as the display system and allow the context + * to choose an appropriate renderer based on system capabilities. + *

+ * If the GPU supports OpenGL2 or later, then the OpenGL2.0 renderer will + * be used, otherwise, the OpenGL1.1 renderer is used. + * + * @see AppSettings#setRenderer(java.lang.String) + */ + public static final String LWJGL_OPENGL_ANY = "LWJGL-OpenGL-Any"; + + /** + * The JOGL renderer is no longer supported by jME. + * + * @deprecated Use the LWJGL renderer instead. + * + * @see AppSettings#setRenderer(java.lang.String) + */ + @Deprecated + public static final String JOGL = "JOGL"; + + /** + * The "NULL" option is no longer supported + * + * @deprecated Specify the "null" value instead + * + * @see AppSettings#setRenderer(java.lang.String) + * @see AppSettings#setAudioRenderer(java.lang.String) + */ + @Deprecated + public static final String NULL = "NULL"; + + /** + * Use the LWJGL OpenAL based renderer for audio capabilities. + * + * @see AppSettings#setAudioRenderer(java.lang.String) + */ public static final String LWJGL_OPENAL = "LWJGL"; - private String settingsDialogImage = "/com/jme3/app/Monkey.png"; static { defaults.put("Width", 640); @@ -70,18 +140,19 @@ public class AppSettings extends HashMap { defaults.put("UseInput", true); defaults.put("VSync", false); defaults.put("FrameRate", -1); + defaults.put("SettingsDialogImage", "/com/jme3/app/Monkey.png"); // defaults.put("Icons", null); - - // disable these settings to benchmark speed -// defaults.put("VSync", true); -// defaults.put("FrameRate", 60); } /** - * Create Application settings - * use loadDefault=true, to load jME default values. - * use false if you want to change some settings but you would like the application to remind other settings from previous launches - * @param loadDefaults + * Create a new instance of AppSettings. + *

+ * If loadDefaults is true, then the default settings + * will be set on the AppSettings. + * Use false if you want to change some settings but you would like the + * application to load settings from previous launches. + * + * @param loadDefaults If default settings are to be loaded. */ public AppSettings(boolean loadDefaults) { if (loadDefaults) { @@ -89,10 +160,25 @@ public class AppSettings extends HashMap { } } + /** + * Copies all settings from other to this + * AppSettings. + *

+ * Any settings that are specified in other will overwrite settings + * set on this AppSettings. + * + * @param other The AppSettings to copy the settings from + */ public void copyFrom(AppSettings other) { this.putAll(other); } + /** + * Same as {@link #copyFrom(com.jme3.system.AppSettings) }, except + * doesn't overwrite settings that are already set. + * + * @param other The AppSettings to merge the settings from + */ public void mergeFrom(AppSettings other) { for (String key : other.keySet()) { if (get(key) == null) { @@ -101,6 +187,14 @@ public class AppSettings extends HashMap { } } + /** + * Loads the settings from the given properties input stream. + * + * @param in The InputStream to load from + * @throws IOException If an IOException occurs + * + * @see #save(java.io.OutputStream) + */ public void load(InputStream in) throws IOException { Properties props = new Properties(); props.load(in); @@ -125,6 +219,14 @@ public class AppSettings extends HashMap { } } + /** + * Saves all settings to the given properties output stream. + * + * @param out The OutputStream to write to + * @throws IOException If an IOException occurs + * + * @see #load(java.io.InputStream) + */ public void save(OutputStream out) throws IOException { Properties props = new Properties(); for (Map.Entry entry : entrySet()) { @@ -144,6 +246,14 @@ public class AppSettings extends HashMap { props.store(out, "jME3 AppSettings"); } + /** + * Loads settings previously saved in the Java preferences. + * + * @param preferencesKey The preferencesKey previously used to save the settings. + * @throws BackingStoreException If an exception occurs with the preferences + * + * @see #save(java.lang.String) + */ public void load(String preferencesKey) throws BackingStoreException { Preferences prefs = Preferences.userRoot().node(preferencesKey); String[] keys = prefs.keys(); @@ -161,6 +271,18 @@ public class AppSettings extends HashMap { } } + /** + * Saves settings into the Java preferences. + *

+ * On the Windows operating system, the preferences are saved in the registry + * at the following key:
+ * HKEY_CURRENT_USER\Software\JavaSoft\Prefs\[preferencesKey] + * + * @param preferencesKey The preferences key to save at. Generally the + * application's unique name. + * + * @throws BackingStoreException If an exception occurs with the preferences + */ public void save(String preferencesKey) throws BackingStoreException { Preferences prefs = Preferences.userRoot().node(preferencesKey); for (String key : keySet()) { @@ -168,6 +290,11 @@ public class AppSettings extends HashMap { } } + /** + * Get an integer from the settings. + *

+ * If the key is not set, then 0 is returned. + */ public int getInteger(String key) { Integer i = (Integer) get(key); if (i == null) { @@ -177,6 +304,11 @@ public class AppSettings extends HashMap { return i.intValue(); } + /** + * Get a boolean from the settings. + *

+ * If the key is not set, then false is returned. + */ public boolean getBoolean(String key) { Boolean b = (Boolean) get(key); if (b == null) { @@ -186,6 +318,11 @@ public class AppSettings extends HashMap { return b.booleanValue(); } + /** + * Get a string from the settings. + *

+ * If the key is not set, then null is returned. + */ public String getString(String key) { String s = (String) get(key); if (s == null) { @@ -195,14 +332,23 @@ public class AppSettings extends HashMap { return s; } + /** + * Set an integer on the settings. + */ public void putInteger(String key, int value) { put(key, Integer.valueOf(value)); } + /** + * Set a boolean on the settings. + */ public void putBoolean(String key, boolean value) { put(key, Boolean.valueOf(value)); } + /** + * Set a string on the settings. + */ public void putString(String key, String value) { put(key, value); } @@ -312,6 +458,36 @@ public class AppSettings extends HashMap { putInteger("Frequency", value); } + /** + * Sets the number of depth bits to use. + *

+ * The number of depth bits specifies the precision of the depth buffer. + * To increase precision, specify 32 bits. To decrease precision, specify + * 16 bits. On some platforms 24 bits might not be supported, in that case, + * specify 16 bits.

+ * (Default: 24) + * + * @param value The depth bits + */ + public void setDepthBits(int value){ + putInteger("DepthBits", value); + } + + /** + * Set the number of stencil bits. + *

+ * This value is only relevant when the stencil buffer is being used. + * Specify 8 to indicate an 8-bit stencil buffer, specify 0 to disable + * the stencil buffer. + *

+ * (Default: 0) + * + * @param value Number of stencil bits + */ + public void setStencilBits(int value){ + putInteger("StencilBits", value); + } + /** * Set the bits per pixel for the display. Appropriate * values are 16 for RGB565 color format, or 24 for RGB8 color format. @@ -390,80 +566,162 @@ public class AppSettings extends HashMap { public void setIcons(Object[] value) { put("Icons", value); } + + /** + * Sets the path of the settings dialog image to use. + *

+ * The image will be displayed in the settings dialog when the + * application is started. + *

+ * (Default: /com/jme3/app/Monkey.png) + * + * @param path The path to the image in the classpath. + */ + public void setSettingsDialogImage(String path) { + putString("SettingsDialogImage", path); + } + /** + * Get the framerate. + * @see #setFrameRate(int) + */ public int getFrameRate() { return getInteger("FrameRate"); } + /** + * Get the use input state. + * @see #setUseInput(boolean) + */ public boolean useInput() { return getBoolean("UseInput"); } + /** + * Get the renderer + * @see #setRenderer(java.lang.String) + */ public String getRenderer() { return getString("Renderer"); } + /** + * Get the width + * @see #setWidth(int) + */ public int getWidth() { return getInteger("Width"); } + /** + * Get the height + * @see #setHeight(int) + */ public int getHeight() { return getInteger("Height"); } + /** + * Get the bits per pixel + * @see #setBitsPerPixel(int) + */ public int getBitsPerPixel() { return getInteger("BitsPerPixel"); } + /** + * Get the frequency + * @see #setFrequency(int) + */ public int getFrequency() { return getInteger("Frequency"); } + /** + * Get the number of depth bits + * @see #setDepthBits(int) + */ public int getDepthBits() { return getInteger("DepthBits"); } + /** + * Get the number of stencil bits + * @see #setStencilBits(int) + */ public int getStencilBits() { return getInteger("StencilBits"); } + /** + * Get the number of samples + * @see #setSamples(int) + */ public int getSamples() { return getInteger("Samples"); } + /** + * Get the application title + * @see #setTitle(java.lang.String) + */ public String getTitle() { return getString("Title"); } + /** + * Get the vsync state + * @see #setVSync(boolean) + */ public boolean isVSync() { return getBoolean("VSync"); } + /** + * Get the fullscreen state + * @see #setFullscreen(boolean) + */ public boolean isFullscreen() { return getBoolean("Fullscreen"); } + /** + * Get the use joysticks state + * @see #setUseJoysticks(boolean) + */ public boolean useJoysticks() { return !getBoolean("DisableJoysticks"); } + /** + * Get the audio renderer + * @see #setAudioRenderer(java.lang.String) + */ public String getAudioRenderer() { return getString("AudioRenderer"); } + /** + * Get the stereo 3D state + * @see #setStereo3D(boolean) + */ public boolean useStereo3D(){ return getBoolean("Stereo3D"); } + /** + * Get the icon array + * @see #setIcons(java.lang.Object[]) + */ public Object[] getIcons() { return (Object[]) get("Icons"); } - - public void setSettingsDialogImage(String path) { - settingsDialogImage = path; - } - + + /** + * Get the settings dialog image + * @see #setSettingsDialogImage(java.lang.String) + */ public String getSettingsDialogImage() { - return settingsDialogImage; + return getString("SettingsDialogImage"); } } diff --git a/engine/src/core/com/jme3/ui/Picture.java b/engine/src/core/com/jme3/ui/Picture.java index 3e8ac2687..2b92b41e5 100644 --- a/engine/src/core/com/jme3/ui/Picture.java +++ b/engine/src/core/com/jme3/ui/Picture.java @@ -129,7 +129,7 @@ public class Picture extends Geometry { * @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. + * portions will be the image's color at that pixel. */ public void setImage(AssetManager assetManager, String imgName, boolean useAlpha){ TextureKey key = new TextureKey(imgName, true); @@ -144,7 +144,7 @@ public class Picture extends Geometry { * @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. + * portions will be the image's color at that pixel. */ public void setTexture(AssetManager assetManager, Texture2D tex, boolean useAlpha){ if (getMaterial() == null){ diff --git a/engine/src/core/com/jme3/util/IntMap.java b/engine/src/core/com/jme3/util/IntMap.java index abbaa77b6..307a91111 100644 --- a/engine/src/core/com/jme3/util/IntMap.java +++ b/engine/src/core/com/jme3/util/IntMap.java @@ -34,8 +34,12 @@ package com.jme3.util; import com.jme3.util.IntMap.Entry; import java.util.Iterator; +import java.util.Map; /** + * Similar to a {@link Map} except that ints are used as keys. + * @see Map + * * Taken from http://code.google.com/p/skorpios/ * * @author Nate @@ -276,10 +280,12 @@ public final class IntMap implements Iterable>, Cloneable { return value; } + @Override public String toString(){ return key + " => " + value; } + @Override public Entry clone(){ try{ Entry clone = (Entry) super.clone(); diff --git a/engine/src/core/com/jme3/util/xml/SAXUtil.java b/engine/src/core/com/jme3/util/xml/SAXUtil.java index 51a618284..33b6f4288 100644 --- a/engine/src/core/com/jme3/util/xml/SAXUtil.java +++ b/engine/src/core/com/jme3/util/xml/SAXUtil.java @@ -42,6 +42,15 @@ import org.xml.sax.SAXException; */ public final class SAXUtil { + /** + * Parses an integer from a string, if the string is null returns + * def. + * + * @param i + * @param def + * @return + * @throws SAXException + */ public static int parseInt(String i, int def) throws SAXException{ if (i == null) return def;