Merge pull request #2420 from capdevon/capdevon-emitter-shape

EmitterShape: javadoc improvements

jme3-core/src/main/java/com/jme3/effect/shapes/EmitterBoxShape.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2012 jMonkeyEngine
+ * Copyright (c) 2009-2025 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -40,13 +40,35 @@ import com.jme3.math.Vector3f;
 import com.jme3.util.clone.Cloner;
 import java.io.IOException;
 
+/**
+ * An {@link EmitterShape} that emits particles randomly within the bounds of an axis-aligned box.
+ * The box is defined by a minimum corner and a length vector.
+ */
 public class EmitterBoxShape implements EmitterShape {
 
-    private Vector3f min, len;
+    /**
+     * The minimum corner of the box.
+     */
+    private Vector3f min;
+    /**
+     * The length of the box along each axis.  The x, y, and z components of this
+     * vector represent the width, height, and depth of the box, respectively.
+     */
+    private Vector3f len;
 
+    /**
+     * For serialization only. Do not use.
+     */
     public EmitterBoxShape() {
     }
 
+    /**
+     * Constructs an {@code EmitterBoxShape} defined by a minimum and maximum corner.
+     *
+     * @param min The minimum corner of the box.
+     * @param max The maximum corner of the box.
+     * @throws IllegalArgumentException If either {@code min} or {@code max} is null.
+     */
     public EmitterBoxShape(Vector3f min, Vector3f max) {
         if (min == null || max == null) {
             throw new IllegalArgumentException("min or max cannot be null");
@@ -57,6 +79,11 @@ public class EmitterBoxShape implements EmitterShape {
         this.len.set(max).subtractLocal(min);
     }
 
+    /**
+     * Generates a random point within the bounds of the box.
+     *
+     * @param store The {@link Vector3f} to store the generated point in.
+     */
     @Override
     public void getRandomPoint(Vector3f store) {
         store.x = min.x + len.x * FastMath.nextRandomFloat();
@@ -65,10 +92,11 @@ public class EmitterBoxShape implements EmitterShape {
     }
 
     /**
-     * This method fills the point with data.
-     * It does not fill the normal.
-     * @param store the variable to store the point data
-     * @param normal not used in this class
+     * For a box shape, the normal is not well-defined for points within the volume.
+     * This implementation simply calls {@link #getRandomPoint(Vector3f)} and does not modify the provided normal.
+     *
+     * @param store  The {@link Vector3f} to store the generated point in.
+     * @param normal The {@link Vector3f} to store the generated normal in (unused).
      */
     @Override
     public void getRandomPointAndNormal(Vector3f store, Vector3f normal) {
@@ -108,18 +136,40 @@ public class EmitterBoxShape implements EmitterShape {
         this.len = cloner.clone(len);
     }
 
+    /**
+     * Returns the minimum corner of the emitting box.
+     *
+     * @return The minimum corner.
+     */
     public Vector3f getMin() {
         return min;
     }
 
+    /**
+     * Sets the minimum corner of the emitting box.
+     *
+     * @param min The new minimum corner.
+     */
     public void setMin(Vector3f min) {
         this.min = min;
     }
 
+    /**
+     * Returns the length vector of the emitting box. This vector represents the
+     * extent of the box along each axis (length = max - min).
+     *
+     * @return The length vector.
+     */
     public Vector3f getLen() {
         return len;
     }
 
+    /**
+     * Sets the length vector of the emitting box. This vector should represent
+     * the extent of the box along each axis (length = max - min).
+     *
+     * @param len The new length vector.
+     */
     public void setLen(Vector3f len) {
         this.len = len;
     }

jme3-core/src/main/java/com/jme3/effect/shapes/EmitterPointShape.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2012 jMonkeyEngine
+ * Copyright (c) 2009-2025 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -31,6 +31,7 @@
  */
 package com.jme3.effect.shapes;
 
+import com.jme3.export.InputCapsule;
 import com.jme3.export.JmeExporter;
 import com.jme3.export.JmeImporter;
 import com.jme3.export.OutputCapsule;
@@ -38,13 +39,27 @@ import com.jme3.math.Vector3f;
 import com.jme3.util.clone.Cloner;
 import java.io.IOException;
 
+/**
+ * An {@link EmitterShape} that emits particles from a single point in space.
+ */
 public class EmitterPointShape implements EmitterShape {
 
+    /**
+     * The point in space from which particles are emitted.
+     */
     private Vector3f point;
 
+    /**
+     * For serialization only. Do not use.
+     */
     public EmitterPointShape() {
     }
 
+    /**
+     * Constructs an {@code EmitterPointShape} with the given point.
+     *
+     * @param point The point from which particles are emitted.
+     */
     public EmitterPointShape(Vector3f point) {
         this.point = point;
     }
@@ -80,26 +95,43 @@ public class EmitterPointShape implements EmitterShape {
         this.point = cloner.clone(point);
     }
 
+    /**
+     * For a point shape, the generated point is
+     * always the shape's defined point.
+     *
+     * @param store The {@link Vector3f} to store the generated point in.
+     */
     @Override
     public void getRandomPoint(Vector3f store) {
         store.set(point);
     }
 
     /**
-     * This method fills the point with data.
-     * It does not fill the normal.
-     * @param store the variable to store the point data
-     * @param normal not used in this class
+     * For a point shape, the generated point is always the shape's defined point.
+     * The normal is not defined for a point shape, so this method does not modify the normal parameter.
+     *
+     * @param store  The {@link Vector3f} to store the generated point in.
+     * @param normal The {@link Vector3f} to store the generated normal in (unused).
      */
     @Override
     public void getRandomPointAndNormal(Vector3f store, Vector3f normal) {
         store.set(point);
     }
 
+    /**
+     * Returns the point from which particles are emitted.
+     *
+     * @return The point.
+     */
     public Vector3f getPoint() {
         return point;
     }
 
+    /**
+     * Sets the point from which particles are emitted.
+     *
+     * @param point The new point.
+     */
     public void setPoint(Vector3f point) {
         this.point = point;
     }
@@ -112,6 +144,7 @@ public class EmitterPointShape implements EmitterShape {
 
     @Override
     public void read(JmeImporter im) throws IOException {
-        this.point = (Vector3f) im.getCapsule(this).readSavable("point", null);
+        InputCapsule ic = im.getCapsule(this);
+        this.point = (Vector3f) ic.readSavable("point", null);
     }
 }

jme3-core/src/main/java/com/jme3/effect/shapes/EmitterShape.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2012 jMonkeyEngine
+ * Copyright (c) 2009-2025 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -39,14 +39,14 @@ import com.jme3.util.clone.JmeCloneable;
  * This interface declares methods used by all shapes that represent particle emitters.
  * @author Kirill
  */
-public interface EmitterShape extends Savable, Cloneable, JmeCloneable {
+public interface EmitterShape extends Savable, JmeCloneable {
 
     /**
      * This method fills in the initial position of the particle.
      * @param store
      *        store variable for initial position
      */
-    public void getRandomPoint(Vector3f store);
+    void getRandomPoint(Vector3f store);
 
     /**
      * This method fills in the initial position of the particle and its normal vector.
@@ -55,11 +55,11 @@ public interface EmitterShape extends Savable, Cloneable, JmeCloneable {
      * @param normal
      *        store variable for initial normal
      */
-    public void getRandomPointAndNormal(Vector3f store, Vector3f normal);
+    void getRandomPointAndNormal(Vector3f store, Vector3f normal);
 
     /**
      * This method creates a deep clone of the current instance of the emitter shape.
      * @return deep clone of the current instance of the emitter shape
      */
-    public EmitterShape deepClone();
+    EmitterShape deepClone();
 }

jme3-core/src/main/java/com/jme3/effect/shapes/EmitterSphereShape.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2012 jMonkeyEngine
+ * Copyright (c) 2009-2025 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -40,19 +40,38 @@ import com.jme3.math.Vector3f;
 import com.jme3.util.clone.Cloner;
 import java.io.IOException;
 
+/**
+ * An {@link EmitterShape} that emits particles randomly from within the volume of a sphere.
+ * The sphere is defined by a center point and a radius.
+ */
 public class EmitterSphereShape implements EmitterShape {
 
+    /**
+     * The center point of the sphere.
+     */
     private Vector3f center;
+    /**
+     * The radius of the sphere.
+     */
     private float radius;
 
+    /**
+     * For serialization only. Do not use.
+     */
     public EmitterSphereShape() {
     }
 
+    /**
+     * Constructs an {@code EmitterSphereShape} with the given center and radius.
+     *
+     * @param center The center point of the sphere.
+     * @param radius The radius of the sphere.
+     * @throws IllegalArgumentException If {@code center} is null, or if {@code radius} is not greater than 0.
+     */
     public EmitterSphereShape(Vector3f center, float radius) {
         if (center == null) {
             throw new IllegalArgumentException("center cannot be null");
         }
-
         if (radius <= 0) {
             throw new IllegalArgumentException("Radius must be greater than 0");
         }
@@ -92,6 +111,11 @@ public class EmitterSphereShape implements EmitterShape {
         this.center = cloner.clone(center);
     }
 
+    /**
+     * Generates a random point within the volume of the sphere.
+     *
+     * @param store The {@link Vector3f} to store the generated point in.
+     */
     @Override
     public void getRandomPoint(Vector3f store) {
         do {
@@ -103,23 +127,50 @@ public class EmitterSphereShape implements EmitterShape {
         store.addLocal(center);
     }
 
+    /**
+     * For a sphere shape, the normal is not well-defined for points within the volume.
+     * This implementation simply calls {@link #getRandomPoint(Vector3f)} and does not modify the provided normal.
+     *
+     * @param store  The {@link Vector3f} to store the generated point in.
+     * @param normal The {@link Vector3f} to store the generated normal in (unused).
+     */
     @Override
     public void getRandomPointAndNormal(Vector3f store, Vector3f normal) {
         this.getRandomPoint(store);
     }
 
+    /**
+     * Returns the center point of the sphere.
+     *
+     * @return The center point.
+     */
     public Vector3f getCenter() {
         return center;
     }
 
+    /**
+     * Sets the center point of the sphere.
+     *
+     * @param center The new center point.
+     */
     public void setCenter(Vector3f center) {
         this.center = center;
     }
 
+    /**
+     * Returns the radius of the sphere.
+     *
+     * @return The radius.
+     */
     public float getRadius() {
         return radius;
     }
 
+    /**
+     * Sets the radius of the sphere.
+     *
+     * @param radius The new radius.
+     */
     public void setRadius(float radius) {
         this.radius = radius;
     }