From c6d887cf5ae1bb9f9448cc7836f92b8274c6a488 Mon Sep 17 00:00:00 2001 From: "sha..rd" Date: Sat, 18 Jun 2011 19:01:30 +0000 Subject: [PATCH] * Javadocs for com.jme3.scene git-svn-id: https://jmonkeyengine.googlecode.com/svn/trunk@7663 75d07b2b-3a1a-0410-a2c5-0572b91ccdca --- .../com/jme3/renderer/queue/RenderQueue.java | 84 ++++++++- .../core/com/jme3/scene/AssetLinkNode.java | 1 + .../src/core/com/jme3/scene/CameraNode.java | 1 - .../core/com/jme3/scene/CollisionData.java | 2 +- engine/src/core/com/jme3/scene/Geometry.java | 88 ++++++++- engine/src/core/com/jme3/scene/LightNode.java | 11 +- engine/src/core/com/jme3/scene/Mesh.java | 10 +- engine/src/core/com/jme3/scene/Node.java | 42 +++-- .../com/jme3/scene/SceneGraphVisitor.java | 11 +- .../jme3/scene/SceneGraphVisitorAdapter.java | 19 +- engine/src/core/com/jme3/scene/Spatial.java | 115 ++++++------ engine/src/core/com/jme3/scene/UserData.java | 14 ++ .../src/core/com/jme3/scene/VertexBuffer.java | 170 +++++++++++++++--- .../core/com/jme3/scene/control/Control.java | 3 + .../com/jme3/scene/control/LodControl.java | 31 +++- 15 files changed, 473 insertions(+), 129 deletions(-) diff --git a/engine/src/core/com/jme3/renderer/queue/RenderQueue.java b/engine/src/core/com/jme3/renderer/queue/RenderQueue.java index 7f8f209d9..0daa113f5 100644 --- a/engine/src/core/com/jme3/renderer/queue/RenderQueue.java +++ b/engine/src/core/com/jme3/renderer/queue/RenderQueue.java @@ -31,6 +31,7 @@ */ package com.jme3.renderer.queue; +import com.jme3.post.SceneProcessor; import com.jme3.renderer.Camera; import com.jme3.renderer.RenderManager; import com.jme3.scene.Geometry; @@ -56,22 +57,97 @@ public class RenderQueue { this.shadowCast = new GeometryList(new OpaqueComparator()); } + /** + * The render queue Bucket specifies the bucket + * to which the spatial will be placed when rendered. + *

+ * The behavior of the rendering will differ depending on which + * bucket the spatial is placed. A spatial's queue bucket can be set + * via {@link Spatial#setQueueBucket(com.jme3.renderer.queue.RenderQueue.Bucket) }. + */ public enum Bucket { - - Gui, + /** + * The renderer will try to find the optimal order for rendering all + * objects using this mode. + * You should use this mode for most normal objects, except transparent + * ones, as it could give a nice performance boost to your application. + */ Opaque, - Sky, + + /** + * This is the mode you should use for object with + * transparency in them. It will ensure the objects furthest away are + * rendered first. That ensures when another transparent object is drawn on + * top of previously drawn objects, you can see those (and the object drawn + * using Opaque) through the transparent parts of the newly drawn + * object. + */ Transparent, + + /** + * A special mode used for rendering really far away, flat objects - + * e.g. skies. In this mode, the depth is set to infinity so + * spatials in this bucket will appear behind everything, the downside + * to this bucket is that 3D objects will not be rendered correctly + * due to lack of depth testing. + */ + Sky, + + /** + * A special mode used for rendering transparent objects that + * should not be effected by {@link SceneProcessor}. + * Generally this would contain translucent objects, and + * also objects that do not write to the depth buffer such as + * particle emitters. + */ Translucent, + + /** + * This is a special mode, for drawing 2D object + * without perspective (such as GUI or HUD parts). + * The spatial's world coordinate system has the range + * of [0, 0, -1] to [Width, Height, 1] where Width/Height is + * the resolution of the screen rendered to. Any spatials + * outside of that range are culled. + */ + Gui, + + /** + * A special mode, that will ensure that this spatial uses the same + * mode as the parent Node does. + */ Inherit, } + /** + * ShadowMode is a marker used to specify how shadow + * effects should treat the spatial. + */ public enum ShadowMode { - + /** + * Disable both shadow casting and shadow receiving for this spatial. + * Generally used for special effects like particle emitters. + */ Off, + + /** + * Enable casting of shadows but not receiving them. + */ Cast, + + /** + * Enable receiving of shadows but not casting them. + */ Receive, + + /** + * Enable both receiving and casting of shadows. + */ CastAndReceive, + + /** + * Inherit the ShadowMode from the parent node. + */ Inherit } diff --git a/engine/src/core/com/jme3/scene/AssetLinkNode.java b/engine/src/core/com/jme3/scene/AssetLinkNode.java index 7ea393e9b..99764eeaa 100644 --- a/engine/src/core/com/jme3/scene/AssetLinkNode.java +++ b/engine/src/core/com/jme3/scene/AssetLinkNode.java @@ -54,6 +54,7 @@ import java.util.logging.Logger; * The AssetLinkNode does not store its children when exported to file. * Instead, you can add a list of AssetKeys that will be loaded and attached * when the AssetLinkNode is restored. + * * @author normenhansen */ public class AssetLinkNode extends Node { diff --git a/engine/src/core/com/jme3/scene/CameraNode.java b/engine/src/core/com/jme3/scene/CameraNode.java index a52ee3b4e..c78f6c35c 100644 --- a/engine/src/core/com/jme3/scene/CameraNode.java +++ b/engine/src/core/com/jme3/scene/CameraNode.java @@ -31,7 +31,6 @@ */ package com.jme3.scene; -import com.jme3.math.Vector3f; import com.jme3.renderer.Camera; import com.jme3.scene.control.CameraControl; import com.jme3.scene.control.CameraControl.ControlDirection; diff --git a/engine/src/core/com/jme3/scene/CollisionData.java b/engine/src/core/com/jme3/scene/CollisionData.java index 6bbc177e1..914bf248a 100644 --- a/engine/src/core/com/jme3/scene/CollisionData.java +++ b/engine/src/core/com/jme3/scene/CollisionData.java @@ -40,7 +40,7 @@ import com.jme3.math.Matrix4f; /** * CollisionData is an interface that can be used to - * do triangle-accurate collision between bounding volumes and rays. + * do triangle-accurate collision with bounding volumes and rays. * * @author Kirill Vainer */ diff --git a/engine/src/core/com/jme3/scene/Geometry.java b/engine/src/core/com/jme3/scene/Geometry.java index a9635f594..c7fb669b5 100644 --- a/engine/src/core/com/jme3/scene/Geometry.java +++ b/engine/src/core/com/jme3/scene/Geometry.java @@ -49,13 +49,18 @@ import java.util.Queue; import java.util.logging.Level; import java.util.logging.Logger; +/** + * Geometry defines a leaf node of the scene graph. The leaf node + * contains the geometric data for rendering objects. It manages all rendering + * information such as a {@link Material} object to define how the surface + * should be shaded and the {@link Mesh} data to contain the actual geometry. + * + * @author Kirill Vainer + */ public class Geometry extends Spatial { private static final Logger logger = Logger.getLogger(Geometry.class.getName()); - /** - * The mesh contained herein - */ protected Mesh mesh; protected transient int lodLevel = 0; @@ -70,13 +75,16 @@ public class Geometry extends Spatial { protected transient Matrix4f cachedWorldMat = new Matrix4f(); /** - * Do not use this constructor. Serialization purposes only. + * Serialization only. Do not use. */ public Geometry(){ } /** * Create a geometry node without any mesh data. + * Both the mesh and the material are null, the geometry + * cannot be rendered until those are set. + * * @param name The name of this geometry */ public Geometry(String name){ @@ -85,7 +93,9 @@ public class Geometry extends Spatial { /** * Create a geometry node with mesh data. - * + * The material of the geometry is null, it cannot + * be rendered until it is set. + * * @param name The name of this geometry * @param mesh The mesh data for this geometry */ @@ -99,6 +109,7 @@ public class Geometry extends Spatial { /** * @return If ignoreTransform mode is set. + * * @see Geometry#setIgnoreTransform(boolean) */ public boolean isIgnoreTransform() { @@ -112,6 +123,14 @@ public class Geometry extends Spatial { this.ignoreTransform = ignoreTransform; } + /** + * Sets the LOD level to use when rendering the mesh of this geometry. + * Level 0 indicates that the default index buffer should be used, + * levels [1, LodLevels + 1] represent the levels set on the mesh + * with {@link Mesh#setLodLevels(com.jme3.scene.VertexBuffer[]) }. + * + * @param lod The lod level to set + */ @Override public void setLodLevel(int lod){ if (mesh.getNumLodLevels() == 0) @@ -123,35 +142,80 @@ public class Geometry extends Spatial { lodLevel = lod; } + /** + * Returns the LOD level set with {@link #setLodLevel(int) }. + * + * @return the LOD level set + */ public int getLodLevel(){ return lodLevel; } + /** + * Returns this geometry's mesh vertex count. + * + * @return this geometry's mesh vertex count. + * + * @see Mesh#getVertexCount() + */ public int getVertexCount(){ return mesh.getVertexCount(); } + /** + * Returns this geometry's mesh triangle count. + * + * @return this geometry's mesh triangle count. + * + * @see Mesh#getTriangleCount() + */ public int getTriangleCount(){ return mesh.getTriangleCount(); } + /** + * Sets the mesh to use for this geometry when rendering. + * + * @param mesh the mesh to use for this geometry + * + * @throws IllegalArgumentException If mesh is null + */ public void setMesh(Mesh mesh){ if (mesh == null) - throw new NullPointerException(); + throw new IllegalArgumentException(); this.mesh = mesh; setBoundRefresh(); } + /** + * Returns the mseh to use for this geometry + * + * @return the mseh to use for this geometry + * + * @see #setMesh(com.jme3.scene.Mesh) + */ public Mesh getMesh(){ return mesh; } + /** + * Sets the material to use for this geometry. + * + * @param material the material to use for this geometry + */ @Override public void setMaterial(Material material){ this.material = material; } + /** + * Returns the material that is used for this geometry. + * + * @return the material that is used for this geometry + * + * @see #setMaterial(com.jme3.material.Material) + */ public Material getMaterial(){ return material; } @@ -228,16 +292,26 @@ public class Geometry extends Spatial { } /** - * @return A {@link Matrix4f matrix} that transforms the {@link Geometry#getMesh() mesh} + * A {@link Matrix4f matrix} that transforms the {@link Geometry#getMesh() mesh} * from model space to world space. This matrix is computed based on the * {@link Geometry#getWorldTransform() world transform} of this geometry. * In order to receive updated values, you must call {@link Geometry#computeWorldMatrix() } * before using this method. + * + * @return Matrix to transform from local space to world space */ public Matrix4f getWorldMatrix(){ return cachedWorldMat; } + /** + * Sets the model bound to use for this geometry. + * This alters the bound used on the mesh as well via + * {@link Mesh#setBound(com.jme3.bounding.BoundingVolume) } and + * forces the world bounding volume to be recomputed. + * + * @param modelBound The model bound to set + */ @Override public void setModelBound(BoundingVolume modelBound) { this.worldBound = null; diff --git a/engine/src/core/com/jme3/scene/LightNode.java b/engine/src/core/com/jme3/scene/LightNode.java index fe4cea262..fde61667f 100644 --- a/engine/src/core/com/jme3/scene/LightNode.java +++ b/engine/src/core/com/jme3/scene/LightNode.java @@ -36,7 +36,8 @@ import com.jme3.scene.control.LightControl; import com.jme3.scene.control.LightControl.ControlDirection; /** - * This Node is a shorthand for using a CameraControl. + * LightNode is used to link together a {@link Light} object + * with a {@link Node} object. * * @author Tim8Dev */ @@ -45,7 +46,7 @@ public class LightNode extends Node { private LightControl lightControl; /** - * for IO purpose + * Serialization only. Do not use. */ public LightNode() { } @@ -60,6 +61,12 @@ public class LightNode extends Node { lightControl = control; } + /** + * Enable or disable the LightNode functionality. + * + * @param enabled If false, the functionality of LightNode will + * be disabled. + */ public void setEnabled(boolean enabled) { lightControl.setEnabled(enabled); } diff --git a/engine/src/core/com/jme3/scene/Mesh.java b/engine/src/core/com/jme3/scene/Mesh.java index 0563a6cd9..f5b3e0f29 100644 --- a/engine/src/core/com/jme3/scene/Mesh.java +++ b/engine/src/core/com/jme3/scene/Mesh.java @@ -72,9 +72,13 @@ import java.util.ArrayList; * All visible elements in a scene are represented by meshes. * Meshes may contain three types of geometric primitives: *

* * @author Kirill Vainer diff --git a/engine/src/core/com/jme3/scene/Node.java b/engine/src/core/com/jme3/scene/Node.java index 46142ed49..d9a7dd531 100644 --- a/engine/src/core/com/jme3/scene/Node.java +++ b/engine/src/core/com/jme3/scene/Node.java @@ -68,7 +68,7 @@ public class Node extends Spatial implements Savable { protected ArrayList children = new ArrayList(1); /** - * Default constructor. + * Serialization only. Do not use. */ public Node() { } @@ -141,11 +141,6 @@ public class Node extends Spatial implements Savable { this.worldBound = resultBound; } - /** - * updateLogicalState updates logic state. Should - * be overriden by subclasses desiring this functionality. - * @param tpf Time per frame - */ @Override public void updateLogicalState(float tpf){ super.updateLogicalState(tpf); @@ -159,15 +154,6 @@ public class Node extends Spatial implements Savable { } } - /** - * updateGeometricState updates all the geometry information - * for the node. - * - * @param time - * the frame time. - * @param initiator - * true if this node started the update process. - */ @Override public void updateGeometricState(){ if ((refreshFlags & RF_LIGHTLIST) != 0){ @@ -200,6 +186,7 @@ public class Node extends Spatial implements Savable { /** * getTriangleCount returns the number of triangles contained * in all sub-branches of this node that contain geometry. + * * @return the triangle count of this branch. */ @Override @@ -217,6 +204,7 @@ public class Node extends Spatial implements Savable { /** * getVertexCount returns the number of vertices contained * in all sub-branches of this node that contain geometry. + * * @return the vertex count of this branch. */ @Override @@ -232,7 +220,6 @@ public class Node extends Spatial implements Savable { } /** - * * attachChild attaches a child to this node. This node * becomes the child's parent. The current number of children maintained is * returned. @@ -305,7 +292,7 @@ public class Node extends Spatial implements Savable { /** * detachChild removes a given child from the node's list. - * This child will no longe be maintained. + * This child will no longer be maintained. * * @param child * the child to remove. @@ -362,7 +349,7 @@ public class Node extends Spatial implements Savable { Spatial child = children.remove(index); if ( child != null ) { child.setParent( null ); - logger.info("Child removed."); + logger.log(Level.INFO, "{0}: Child removed.", this.toString()); // since a child with a bound was detached; // our own bound will probably change. @@ -387,17 +374,27 @@ public class Node extends Spatial implements Savable { for ( int i = children.size() - 1; i >= 0; i-- ) { detachChildAt(i); } - logger.info("All children removed."); + logger.log(Level.INFO, "{0}: All children removed.", this.toString()); } + /** + * getChildIndex returns the index of the given spatial + * in this node's list of children. + * @param sp + * The spatial to look up + * @return + * The index of the spatial in the node's children, or -1 + * if the spatial is not attached to this node + */ public int getChildIndex(Spatial sp) { return children.indexOf(sp); } /** * More efficient than e.g detaching and attaching as no updates are needed. - * @param index1 - * @param index2 + * + * @param index1 The index of the first child to swap + * @param index2 The index of the second child to swap */ public void swapChildren(int index1, int index2) { Spatial c2 = children.get(index2); @@ -467,7 +464,8 @@ public class Node extends Spatial implements Savable { } /** - * Returns all children to this node. + * Returns all children to this node. Note that modifying that given + * list is not allowed. * * @return a list containing all children to this node */ diff --git a/engine/src/core/com/jme3/scene/SceneGraphVisitor.java b/engine/src/core/com/jme3/scene/SceneGraphVisitor.java index e9099ce65..35cc1157c 100644 --- a/engine/src/core/com/jme3/scene/SceneGraphVisitor.java +++ b/engine/src/core/com/jme3/scene/SceneGraphVisitor.java @@ -1,9 +1,16 @@ package com.jme3.scene; /** - * Interface to traverse and visit scene graph - * by calling Spatial.depthFirstTraversal() or Spatial.breadthFirstTraversal(). + * SceneGraphVisitorAdapter is used to traverse the scene + * graph tree. + * Use by calling {@link Spatial#depthFirstTraversal(com.jme3.scene.SceneGraphVisitor) } + * or {@link Spatial#breadthFirstTraversal(com.jme3.scene.SceneGraphVisitor)}. */ public interface SceneGraphVisitor { + /** + * Called when a spatial is visited in the scene graph. + * + * @param spatial The visited spatial + */ public void visit(Spatial spatial); } diff --git a/engine/src/core/com/jme3/scene/SceneGraphVisitorAdapter.java b/engine/src/core/com/jme3/scene/SceneGraphVisitorAdapter.java index 3644973e0..b91a8fbab 100644 --- a/engine/src/core/com/jme3/scene/SceneGraphVisitorAdapter.java +++ b/engine/src/core/com/jme3/scene/SceneGraphVisitorAdapter.java @@ -1,14 +1,27 @@ package com.jme3.scene; /** - * Traverse and visit Geometry/Node - * by calling Spatial.depthFirstTraversal() or Spatial.breadthFirstTraversal(). - * + * SceneGraphVisitorAdapter is used to traverse the scene + * graph tree. The adapter version of the interface simply separates + * between the {@link Geometry geometries} and the {@link Node nodes} by + * supplying visit methods that take them. + * Use by calling {@link Spatial#depthFirstTraversal(com.jme3.scene.SceneGraphVisitor) } + * or {@link Spatial#breadthFirstTraversal(com.jme3.scene.SceneGraphVisitor)}. */ public class SceneGraphVisitorAdapter implements SceneGraphVisitor { + /** + * Called when a {@link Geometry} is visited. + * + * @param geom The visited geometry + */ public void visit(Geometry geom) {} + /** + * Called when a {@link visit} is visited. + * + * @param geom The visited node + */ public void visit(Node geom) {} @Override diff --git a/engine/src/core/com/jme3/scene/Spatial.java b/engine/src/core/com/jme3/scene/Spatial.java index b78e0bf35..217dc27c5 100644 --- a/engine/src/core/com/jme3/scene/Spatial.java +++ b/engine/src/core/com/jme3/scene/Spatial.java @@ -66,8 +66,8 @@ import java.util.logging.Logger; /** * Spatial defines the base class for scene graph nodes. It * maintains a link to a parent, it's local transforms and the world's - * transforms. All other nodes, such as Node and - * Geometry are subclasses of Spatial. + * transforms. All other scene graph elements, such as {@link Node} and + * {@link Geometry} are subclasses of Spatial. * * @author Mark Powell * @author Joshua Slack @@ -77,24 +77,30 @@ public abstract class Spatial implements Savable, Cloneable, Collidable { private static final Logger logger = Logger.getLogger(Spatial.class.getName()); + /** + * Specifies how frustum culling should be handled by + * this spatial. + */ public enum CullHint { - + /** - * Do whatever our parent does. If no parent, we'll default to dynamic. + * Do whatever our parent does. If no parent, default to {@link #Dynamic}. */ Inherit, /** * Do not draw if we are not at least partially within the view frustum - * of the renderer's camera. + * of the camera. This is determined via the defined + * Camera planes whether or not this Spatial should be culled. */ Dynamic, /** - * Always cull this from view. + * Always cull this from the view, throwing away this object + * and any children from rendering commands. */ Always, /** - * Never cull this from view. Note that we will still get culled if our - * parent is culled. + * Never cull this from view, always draw it. + * Note that we will still get culled if our parent is culled. */ Never; } @@ -138,7 +144,7 @@ public abstract class Spatial implements Savable, Cloneable, Collidable { protected transient int refreshFlags = 0; /** - * Default Constructor. + * Serialization only. Do not use. */ public Spatial() { localTransform = new Transform(); @@ -156,7 +162,7 @@ public abstract class Spatial implements Savable, Cloneable, Collidable { * * @param name * the name of the scene element. This is required for - * identification and comparision purposes. + * identification and comparison purposes. */ public Spatial(String name) { this(); @@ -232,12 +238,7 @@ public abstract class Spatial implements Savable, Cloneable, Collidable { if (getQueueBucket() == Bucket.Gui) { return cam.containsGui(getWorldBound()); } else { - -// int state = cam.getPlaneState(); - frustrumIntersects = cam.contains(getWorldBound()); - -// cam.setPlaneState(state); } } @@ -263,10 +264,25 @@ public abstract class Spatial implements Savable, Cloneable, Collidable { return name; } + /** + * Returns the local {@link LightList}, which are the lights + * that were directly attached to this Spatial through the + * {@link #addLight(com.jme3.light.Light) } and + * {@link #removeLight(com.jme3.light.Light) } methods. + * + * @return The local light list + */ public LightList getLocalLightList() { return localLights; } + /** + * Returns the world {@link LightList}, containing the lights + * combined from all this Spatial's parents up to and including + * this Spatial's lights. + * + * @return The combined world light list + */ public LightList getWorldLightList() { return worldLights; } @@ -275,7 +291,7 @@ public abstract class Spatial implements Savable, Cloneable, Collidable { * getWorldRotation retrieves the absolute rotation of the * Spatial. * - * @return the Spatial's world rotation matrix. + * @return the Spatial's world rotation quaternion. */ public Quaternion getWorldRotation() { checkDoTransformUpdate(); @@ -286,7 +302,7 @@ public abstract class Spatial implements Savable, Cloneable, Collidable { * getWorldTranslation retrieves the absolute translation of * the spatial. * - * @return the world's tranlsation vector. + * @return the Spatial's world tranlsation vector. */ public Vector3f getWorldTranslation() { checkDoTransformUpdate(); @@ -297,7 +313,7 @@ public abstract class Spatial implements Savable, Cloneable, Collidable { * getWorldScale retrieves the absolute scale factor of the * spatial. * - * @return the world's scale factor. + * @return the Spatial's world scale factor. */ public Vector3f getWorldScale() { checkDoTransformUpdate(); @@ -316,8 +332,8 @@ public abstract class Spatial implements Savable, Cloneable, Collidable { } /** - * rotateUpTo is a util function that alters the - * localrotation to point the Y axis in the direction given by newUp. + * rotateUpTo is a utility function that alters the + * local rotation to point the Y axis in the direction given by newUp. * * @param newUp * the up vector to use - assumed to be a unit vector. @@ -350,11 +366,11 @@ public abstract class Spatial implements Savable, Cloneable, Collidable { } /** - * lookAt is a convienence method for auto-setting the local + * lookAt is a convenience method for auto-setting the local * rotation based on a position and an up vector. It computes the rotation * to transform the z-axis to point onto 'position' and the y-axis to 'up'. - * Unlike {@link Quaternion#lookAt} this method takes a world position to - * look at not a relative direction. + * Unlike {@link Quaternion#lookAt(com.jme3.math.Vector3f, com.jme3.math.Vector3f) } + * this method takes a world position to look at and not a relative direction. * * @param position * where to look at in terms of world coordinates @@ -377,7 +393,7 @@ public abstract class Spatial implements Savable, Cloneable, Collidable { } /** - * Should be overriden by Node and Geometry. + * Should be overridden by Node and Geometry. */ protected void updateWorldBound() { // the world bound of a leaf is the same as it's model bound @@ -418,6 +434,10 @@ public abstract class Spatial implements Savable, Cloneable, Collidable { } } + /** + * Computes the world transform of this Spatial in the most + * efficient manner possible. + */ void checkDoTransformUpdate() { if ((refreshFlags & RF_TRANSFORM) == 0) { return; @@ -464,6 +484,10 @@ public abstract class Spatial implements Savable, Cloneable, Collidable { } } + /** + * Computes this Spatial's world bounding volume in the most efficient + * manner possible. + */ void checkDoBoundUpdate() { if ((refreshFlags & RF_BOUND) == 0) { return; @@ -675,7 +699,7 @@ public abstract class Spatial implements Savable, Cloneable, Collidable { } /** - * getParent retrieve's this node's parent. If the parent is + * getParent retrieves this node's parent. If the parent is * null this is the root node. * * @return the parent of this node. @@ -737,7 +761,8 @@ public abstract class Spatial implements Savable, Cloneable, Collidable { } /** - * setLocalRotation sets the local rotation of this node. + * setLocalRotation sets the local rotation of this node + * by using a {@link Matrix3f}. * * @param rotation * the new local rotation. @@ -749,11 +774,10 @@ public abstract class Spatial implements Savable, Cloneable, Collidable { } /** - * setLocalRotation sets the local rotation of this node, - * using a quaterion to build the matrix. + * setLocalRotation sets the local rotation of this node. * * @param quaternion - * the quaternion that defines the matrix. + * the new local rotation. */ public void setLocalRotation(Quaternion quaternion) { localTransform.setRotation(quaternion); @@ -1261,13 +1285,8 @@ public abstract class Spatial implements Savable, Cloneable, Collidable { /** * setCullHint sets how scene culling should work on this - * spatial during drawing. CullHint.Dynamic: Determine via the defined - * Camera planes whether or not this Spatial should be culled. - * CullHint.Always: Always throw away this object and any children during - * draw commands. CullHint.Never: Never throw away this object (always draw - * it) CullHint.Inherit: Look for a non-inherit parent and use its cull - * mode. NOTE: You must set this AFTER attaching to a parent or it will be - * reset with the parent's cullMode value. + * spatial during drawing. NOTE: You must set this AFTER attaching to a + * parent or it will be reset with the parent's cullMode value. * * @param hint * one of CullHint.Dynamic, CullHint.Always, CullHint.Inherit or @@ -1286,21 +1305,10 @@ public abstract class Spatial implements Savable, Cloneable, Collidable { /** * setQueueBucket determines at what phase of the - * rendering proces this Spatial will rendered. There are 4 different - * phases: Bucket.Opaque - The renderer will - * try to find the optimal order for rendering all objects using this mode. - * You should use this mode for most normal objects, except transparant - * ones, as it could give a nice performance boost to your application. - * Bucket.Transparent - This is the mode you should use for object with - * transparancy in them. It will ensure the objects furthest away are - * rendered first. That ensures when another transparent object is drawn on - * top of previously drawn objects, you can see those (and the object drawn - * using Opaque) through the tranparant parts of the newly drawn - * object. Bucket.Gui - This is a special mode, for drawing 2D object - * without prespective (such as GUI or HUD parts) Lastly, there is a special - * mode, Bucket.Inherit, that will ensure that this spatial uses the same - * mode as the parent Node does. - * + * rendering process this Spatial will rendered. See the + * {@link Bucket} enum for an explanation of the various + * render queue buckets. + * * @param queueBucket * The bucket to use for this Spatial. */ @@ -1312,7 +1320,7 @@ public abstract class Spatial implements Savable, Cloneable, Collidable { * Sets the shadow mode of the spatial * The shadow mode determines how the spatial should be shadowed, * when a shadowing technique is used. See the - * documentation for the class ShadowMode for more information. + * documentation for the class {@link ShadowMode} for more information. * * @see ShadowMode * @@ -1355,8 +1363,7 @@ public abstract class Spatial implements Savable, Cloneable, Collidable { /** * Overrides the last intersection result. This is useful for operations * that want to start rendering at the middle of a scene tree and don't want - * the parent of that node to influence culling. (See texture renderer code - * for example.) + * the parent of that node to influence culling. * * @param intersects * the new value diff --git a/engine/src/core/com/jme3/scene/UserData.java b/engine/src/core/com/jme3/scene/UserData.java index 9d37212ec..542faee07 100644 --- a/engine/src/core/com/jme3/scene/UserData.java +++ b/engine/src/core/com/jme3/scene/UserData.java @@ -38,6 +38,13 @@ import com.jme3.export.OutputCapsule; import com.jme3.export.Savable; import java.io.IOException; +/** + * UserData is used to contain user data objects + * set on spatials (primarily primitives) that do not implement + * the {@link Savable} interface. Note that attempting + * to export any models which have non-savable objects + * attached to them will fail. + */ public final class UserData implements Savable { protected byte type; @@ -46,6 +53,13 @@ public final class UserData implements Savable { public UserData() { } + /** + * Creates a new UserData with the given + * type and value. + * + * @param type Type of data, should be between 0 and 4. + * @param value Value of the data + */ public UserData(byte type, Object value) { assert type >= 0 && type <= 4; this.type = type; diff --git a/engine/src/core/com/jme3/scene/VertexBuffer.java b/engine/src/core/com/jme3/scene/VertexBuffer.java index 858b05d19..e507d7f3a 100644 --- a/engine/src/core/com/jme3/scene/VertexBuffer.java +++ b/engine/src/core/com/jme3/scene/VertexBuffer.java @@ -52,6 +52,15 @@ import java.nio.ShortBuffer; * A VertexBuffer contains a particular type of geometry * data used by {@link Mesh}es. Every VertexBuffer set on a Mesh * is sent as an attribute to the vertex shader to be processed. + *

+ * Several terms are used throughout the javadoc for this class, explanation: + *

    + *
  • Element - A single element is the largest individual object + * inside a VertexBuffer. E.g. if the VertexBuffer is used to store 3D position + * data, then an element will be a single 3D vector.
    • + *
  • Component - A component represents the parts inside an element. + * For a 3D vector, a single component is one of the dimensions, X, Y or Z.
    • + *
*/ public class VertexBuffer extends GLObject implements Savable, Cloneable { @@ -65,17 +74,17 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable { Position, /** - * The size of the point when using point buffers. + * The size of the point when using point buffers (float). */ Size, /** - * Normal vector, normalized. + * Normal vector, normalized (3 floats). */ Normal, /** - * Texture coordinate + * Texture coordinate (2 float) */ TexCoord, @@ -85,18 +94,19 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable { Color, /** - * Tangent vector, normalized. + * Tangent vector, normalized (3 floats) */ Tangent, /** - * Binormal vector, normalized. + * Binormal vector, normalized (3 floats, optional) */ Binormal, /** * Specifies the source data for various vertex buffers - * when interleaving is used. + * when interleaving is used. By default the format is + * byte. */ InterleavedData, @@ -107,27 +117,42 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable { MiscAttrib, /** - * Specifies the index buffer, must contain integer data. + * Specifies the index buffer, must contain integer data + * (ubyte, ushort, or uint). */ Index, /** - * Inital vertex position, used with animation + * Initial vertex position, used with animation. + * Should have the same format and size as {@link Type#Position}. + * If used with software skinning, the usage should be + * {@link Usage#CpuOnly}, and the buffer should be allocated + * on the heap. */ BindPosePosition, /** - * Inital vertex normals, used with animation + * Initial vertex normals, used with animation. + * Should have the same format and size as {@link Type#Normal}. + * If used with software skinning, the usage should be + * {@link Usage#CpuOnly}, and the buffer should be allocated + * on the heap. */ BindPoseNormal, /** - * Bone weights, used with animation + * Bone weights, used with animation (4 floats). + * If used with software skinning, the usage should be + * {@link Usage#CpuOnly}, and the buffer should be allocated + * on the heap. */ BoneWeight, /** - * Bone indices, used with animation + * Bone indices, used with animation (4 ubytes). + * If used with software skinning, the usage should be + * {@link Usage#CpuOnly}, and the buffer should be allocated + * on the heap. */ BoneIndex, @@ -190,24 +215,68 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable { Stream, /** - * Mesh data is not sent to GPU at all. It is only + * Mesh data is not sent to GPU at all. It is only * used by the CPU. */ CpuOnly; } + /** + * Specifies format of the data stored in the buffer. + * This should directly correspond to the buffer's class, for example, + * an {@link Format#UnsignedShort} formatted buffer should use the + * class {@link ShortBuffer} (e.g. the closest resembling type). + * For the {@link Format#Half} type, {@link ByteBuffer}s should + * be used. + */ public static enum Format { - // Floating point formats + /** + * Half precision floating point. + * 2 bytes, signed. + */ Half(2), + + /** + * Single precision floating point. + * 4 bytes, signed + */ Float(4), + + /** + * Double precision floating point. + * 8 bytes, signed. May not + * be supported by all GPUs. + */ Double(8), - // Integer formats + /** + * 1 byte integer, signed. + */ Byte(1), + + /** + * 1 byte integer, unsigned. + */ UnsignedByte(1), + + /** + * 2 byte integer, signed. + */ Short(2), + + /** + * 2 byte integer, unsigned. + */ UnsignedShort(2), + + /** + * 4 byte integer, signed. + */ Int(4), + + /** + * 4 byte integer, unsigned. + */ UnsignedInt(4); private int componentSize = 0; @@ -217,6 +286,8 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable { } /** + * Returns the size in bytes of this data type. + * * @return Size in bytes of this data type. */ public int getComponentSize(){ @@ -250,7 +321,7 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable { } /** - * Do not use this constructor. Serialization purposes only. + * Serialization only. Do not use. */ public VertexBuffer(){ super(GLObject.Type.VertexBuffer); @@ -261,8 +332,9 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable { } /** - * @return The offset (in bytes) from the start of the buffer - * after which the data is sent to the GPU. + * @return The offset after which the data is sent to the GPU. + * + * @see #setOffset(int) */ public int getOffset() { return offset; @@ -277,20 +349,22 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable { } /** - * @return The stride (in bytes) for the data. If the data is packed - * in the buffer, then stride is 0, if there's other data that is between - * the current component and the next component in the buffer, then this - * specifies the size in bytes of that additional data. + * @return The stride (in bytes) for the data. + * + * @see #setStride(int) */ public int getStride() { return stride; } /** - * @param stride The stride (in bytes) for the data. If the data is packed - * in the buffer, then stride is 0, if there's other data that is between - * the current component and the next component in the buffer, then this - * specifies the size in bytes of that additional data. + * Set the stride (in bytes) for the data. + *

+ * If the data is packed in the buffer, then stride is 0, if there's other + * data that is between the current component and the next component in the + * buffer, then this specifies the size in bytes of that additional data. + * + * @param stride the stride (in bytes) for the data */ public void setStride(int stride) { this.stride = stride; @@ -432,6 +506,11 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable { setUpdateNeeded(); } + /** + * Returns true if the data size of the VertexBuffer has changed. + * Internal use only. + * @return true if the data size has changed + */ public boolean hasDataSizeChanged() { return dataSizeChanged; } @@ -477,7 +556,7 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable { * of elements, any elements at the end of the buffer are truncated * as necessary. * - * @param numElements + * @param numElements The number of elements to reduce to. */ public void compact(int numElements){ int total = components * numElements; @@ -523,6 +602,16 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable { dataSizeChanged = true; } + /** + * Modify a component inside an element. + * The val parameter must be in the buffer's format: + * {@link Format}. + * + * @param elementIndex The element index to modify + * @param componentIndex The component index to modify + * @param val The value to set, either byte, short, int or float depending + * on the {@link Format}. + */ public void setElementComponent(int elementIndex, int componentIndex, Object val){ int inPos = elementIndex * components; int elementPos = componentIndex; @@ -560,6 +649,14 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable { } } + /** + * Get the component inside an element. + * + * @param elementIndex The element index + * @param componentIndex The component index + * @return The component, as one of the primitive types, byte, short, + * int or float. + */ public Object getElementComponent(int elementIndex, int componentIndex){ int inPos = elementIndex * components; int elementPos = componentIndex; @@ -597,9 +694,12 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable { * Copies a single element of data from this VertexBuffer * to the given output VertexBuffer. * - * @param inIndex - * @param outVb - * @param outIndex + * @param inIndex The input element index + * @param outVb The buffer to copy to + * @param outIndex The output element index + * + * @throws IllegalArgumentException If the formats of the buffers do not + * match. */ public void copyElement(int inIndex, VertexBuffer outVb, int outIndex){ if (outVb.format != format || outVb.components != components) @@ -692,6 +792,11 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable { } } + /** + * Creates a deep clone of the {@link VertexBuffer}. + * + * @return Deep clone of this buffer + */ @Override public VertexBuffer clone(){ // NOTE: Superclass GLObject automatically creates shallow clone @@ -705,6 +810,13 @@ public class VertexBuffer extends GLObject implements Savable, Cloneable { return vb; } + /** + * Creates a deep clone of this VertexBuffer but overrides the + * {@link Type}. + * + * @param overrideType The type of the cloned VertexBuffer + * @return A deep clone of the buffer + */ public VertexBuffer clone(Type overrideType){ VertexBuffer vb = new VertexBuffer(overrideType); vb.components = components; diff --git a/engine/src/core/com/jme3/scene/control/Control.java b/engine/src/core/com/jme3/scene/control/Control.java index 6be46a322..b5b00572b 100644 --- a/engine/src/core/com/jme3/scene/control/Control.java +++ b/engine/src/core/com/jme3/scene/control/Control.java @@ -39,6 +39,9 @@ import com.jme3.scene.Spatial; /** * An interface for scene-graph controls. + *

+ * Controls are used to specify certain update and render logic + * for a {@link Spatial}. * * @author Kirill Vainer */ diff --git a/engine/src/core/com/jme3/scene/control/LodControl.java b/engine/src/core/com/jme3/scene/control/LodControl.java index 85191e41d..23aaed016 100644 --- a/engine/src/core/com/jme3/scene/control/LodControl.java +++ b/engine/src/core/com/jme3/scene/control/LodControl.java @@ -67,23 +67,52 @@ public class LodControl extends AbstractControl implements Cloneable { private int[] numTris; /** - * Serialization only. Do not use. + * Creates a new LodControl. */ public LodControl(){ } + /** + * Returns the distance tolerance for changing LOD. + * + * @return the distance tolerance for changing LOD. + * + * @see #setDistTolerance(float) + */ public float getDistTolerance() { return distTolerance; } + /** + * Specifies the distance tolerance for changing the LOD level on the geometry. + * The LOD level will only get changed if the geometry has moved this + * distance beyond the current LOD level. + * + * @param distTolerance distance tolerance for changing LOD + */ public void setDistTolerance(float distTolerance) { this.distTolerance = distTolerance; } + /** + * Returns the triangles per pixel value. + * + * @return the triangles per pixel value. + * + * @see #setTrisPerPixel(float) + */ public float getTrisPerPixel() { return trisPerPixel; } + /** + * Sets the triangles per pixel value. + * The LodControl will use this value as an error metric + * to determine which LOD level to use based on the geometry's + * area on the screen. + * + * @param trisPerPixel triangles per pixel + */ public void setTrisPerPixel(float trisPerPixel) { this.trisPerPixel = trisPerPixel; }