xxxLightShadowFilter: format code + javadoc (#2204)

DirectionalLightShadowFilter, DirectionalLightShadowFilter, SpotLightShadowFilter, PointLightShadowFilter : format code + javadoc

jme3-core/src/main/java/com/jme3/shadow/DirectionalLightShadowFilter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2021 jMonkeyEngine
+ * Copyright (c) 2009-2024 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -40,49 +40,43 @@ import com.jme3.light.DirectionalLight;
 import java.io.IOException;
 
 /**
- *
  * This Filter does basically the same as a DirectionalLightShadowRenderer
  * except it renders the post shadow pass as a fullscreen quad pass instead of a
  * geometry pass. It's mostly faster than PssmShadowRenderer as long as you have
  * more than about ten shadow receiving objects. The expense is the drawback
  * that the shadow Receive mode set on spatial is ignored. So basically all and
- * only objects that render depth in the scene receive shadows. See this post
- * for more details
- * http://jmonkeyengine.org/groups/general-2/forum/topic/silly-question-about-shadow-rendering/#post-191599
+ * only objects that render depth in the scene receive shadows.
  *
- * API is basically the same as the PssmShadowRenderer;
+ * API is basically the same as the PssmShadowRenderer.
  *
  * @author Rémy Bouquet aka Nehon
  */
 public class DirectionalLightShadowFilter extends AbstractShadowFilter<DirectionalLightShadowRenderer> {
 
     /**
-     * Used for serialization.
-     * Use DirectionalLightShadowFilter#DirectionalLightShadowFilter
-     * (AssetManager assetManager, int shadowMapSize, int nbSplits)
-     * instead.
+     * For serialization only. Do not use.
+     * 
+     * @see #DirectionalLightShadowFilter(AssetManager assetManager, int shadowMapSize, int nbSplits)
      */
     public DirectionalLightShadowFilter() {
         super();
     }
     
     /**
-     * Creates a DirectionalLight shadow filter. More info on the
-     * technique at <a
-     * href="http://http.developer.nvidia.com/GPUGems3/gpugems3_ch10.html">http://http.developer.nvidia.com/GPUGems3/gpugems3_ch10.html</a>
-     *
-     * @param assetManager the application's asset manager
-     * @param shadowMapSize the size of the rendered shadowmaps (512, 1024, 2048,
-     *     etcetera)
-     * @param nbSplits the number of shadow maps rendered (More shadow maps mean
-     *     better quality, fewer frames per second.)
+     * Creates a DirectionalLightShadowFilter.
+     * 
+     * @param assetManager  the application's asset manager
+     * @param shadowMapSize the size of the rendered shadow maps (512, 1024, 2048, etc...)
+     * @param nbSplits      the number of shadow maps rendered (more shadow maps = better quality, but slower)
+     * 
+     * @throws IllegalArgumentException if the provided 'nbSplits' is not within the valid range of 1 to 4.
      */
     public DirectionalLightShadowFilter(AssetManager assetManager, int shadowMapSize, int nbSplits) {
         super(assetManager, shadowMapSize, new DirectionalLightShadowRenderer(assetManager, shadowMapSize, nbSplits));
     }
 
     /**
-     * return the light used to cast shadows
+     * Returns the light used to cast shadows.
      *
      * @return the DirectionalLight
      */
@@ -91,7 +85,7 @@ public class DirectionalLightShadowFilter extends AbstractShadowFilter<Direction
     }
 
     /**
-     * Sets the light to use to cast shadows
+     * Sets the light to use to cast shadows.
      *
      * @param light a DirectionalLight
      */
@@ -100,7 +94,7 @@ public class DirectionalLightShadowFilter extends AbstractShadowFilter<Direction
     }
 
     /**
-     * returns the lambda parameter
+     * Returns the lambda parameter.
      *
      * @see #setLambda(float lambda)
      * @return lambda
@@ -110,24 +104,25 @@ public class DirectionalLightShadowFilter extends AbstractShadowFilter<Direction
     }
 
     /**
-     * Adjusts the partition of the shadow extend into shadow maps.
-     * Lambda is usually between 0 and 1.
-     * A low value gives a more linear partition,
-     * resulting in consistent shadow quality over the extend,
-     * but near shadows could look very jagged.
-     * A high value gives a more logarithmic partition,
-     * resulting in high quality for near shadows,
-     * but quality decreases rapidly with distance.
+     * Adjusts the partition of the shadow extend into shadow maps. Lambda is
+     * usually between 0 and 1.
+     * <p>
+     * A low value gives a more linear partition, resulting in consistent shadow
+     * quality over the extend, but near shadows could look very jagged. A high
+     * value gives a more logarithmic partition, resulting in high quality for near
+     * shadows, but quality decreases rapidly with distance.
+     * <p>
      * The default value is 0.65 (the theoretical optimum).
      *
-     * @param lambda the lambda value.
+     * @param lambda the lambda value
      */
     public void setLambda(float lambda) {
         shadowRenderer.setLambda(lambda);
     }
 
     /**
-     * returns true if stabilization is enabled
+     * Returns true if stabilization is enabled.
+     * 
      * @return true if stabilization is enabled
      */
     public boolean isEnabledStabilization() {
@@ -150,7 +145,6 @@ public class DirectionalLightShadowFilter extends AbstractShadowFilter<Direction
         super.write(ex);
         OutputCapsule oc = ex.getCapsule(this);
         oc.write(shadowRenderer, "shadowRenderer", null);
-
     }
 
     @Override
@@ -159,4 +153,5 @@ public class DirectionalLightShadowFilter extends AbstractShadowFilter<Direction
         InputCapsule ic = im.getCapsule(this);
         shadowRenderer = (DirectionalLightShadowRenderer) ic.readSavable("shadowRenderer", null);
     }
+    
 }

jme3-core/src/main/java/com/jme3/shadow/PointLightShadowFilter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2021 jMonkeyEngine
+ * Copyright (c) 2009-2024 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -40,56 +40,51 @@ import com.jme3.light.PointLight;
 import java.io.IOException;
 
 /**
- *
  * This Filter does basically the same as a PointLightShadowRenderer except it
  * renders the post shadow pass as a fullscreen quad pass instead of a geometry
  * pass. It's mostly faster than PointLightShadowRenderer as long as you have
  * more than about ten shadow receiving objects. The expense is the drawback
  * that the shadow Receive mode set on spatial is ignored. So basically all and
- * only objects that render depth in the scene receive shadows. See this post
- * for more details
- * http://jmonkeyengine.org/groups/general-2/forum/topic/silly-question-about-shadow-rendering/#post-191599
+ * only objects that render depth in the scene receive shadows.
  *
- * API is basically the same as the PssmShadowRenderer;
+ * API is basically the same as the PssmShadowRenderer.
  *
  * @author Rémy Bouquet aka Nehon
  */
 public class PointLightShadowFilter extends AbstractShadowFilter<PointLightShadowRenderer> {
 
     /**
-     * Used for serialization.
-     * Use PointLightShadowFilter#PointLightShadowFilter(AssetManager
-     * assetManager, int shadowMapSize)
-     * instead.
+     * For serialization only. Do not use.
+     * 
+     * @see #PointLightShadowFilter(AssetManager assetManager, int shadowMapSize)
      */
     protected PointLightShadowFilter() {
         super();
     }
 
     /**
-     * Creates a PointLightShadowFilter
+     * Creates a PointLightShadowFilter.
      *
-     * @param assetManager the application asset manager
-     * @param shadowMapSize the size of the rendered shadowmaps (512,1024,2048,
-     * etc...)
+     * @param assetManager  the application's asset manager
+     * @param shadowMapSize the size of the rendered shadow maps (512, 1024, 2048, etc...)
      */
     public PointLightShadowFilter(AssetManager assetManager, int shadowMapSize) {
         super(assetManager, shadowMapSize, new PointLightShadowRenderer(assetManager, shadowMapSize));
     }
 
     /**
-     * gets the point light used to cast shadows with this processor
+     * Returns the light used to cast shadows.
      *
-     * @return the point light
+     * @return the PointLight
      */
     public PointLight getLight() {
         return shadowRenderer.getLight();
     }
 
     /**
-     * sets the light to use for casting shadows with this processor
+     * Sets the light to use to cast shadows.
      *
-     * @param light the point light
+     * @param light the PointLight
      */
     public void setLight(PointLight light) {
         shadowRenderer.setLight(light);
@@ -100,7 +95,6 @@ public class PointLightShadowFilter extends AbstractShadowFilter<PointLightShado
         super.write(ex);
         OutputCapsule oc = ex.getCapsule(this);
         oc.write(shadowRenderer, "shadowRenderer", null);
-
     }
 
     @Override
@@ -109,4 +103,5 @@ public class PointLightShadowFilter extends AbstractShadowFilter<PointLightShado
         InputCapsule ic = im.getCapsule(this);
         shadowRenderer = (PointLightShadowRenderer) ic.readSavable("shadowRenderer", null);
     }
+    
 }

jme3-core/src/main/java/com/jme3/shadow/SpotLightShadowFilter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2021 jMonkeyEngine
+ * Copyright (c) 2009-2024 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -40,45 +40,40 @@ import com.jme3.light.SpotLight;
 import java.io.IOException;
 
 /**
- *
  * This Filter does basically the same as a SpotLightShadowRenderer except it
  * renders the post shadow pass as a fullscreen quad pass instead of a geometry
  * pass. It's mostly faster than PssmShadowRenderer as long as you have more
  * than about ten shadow receiving objects. The expense is the drawback that
  * the shadow Receive mode set on spatial is ignored. So basically all and only
- * objects that render depth in the scene receive shadows. See this post for
- * more details
- * http://jmonkeyengine.org/groups/general-2/forum/topic/silly-question-about-shadow-rendering/#post-191599
+ * objects that render depth in the scene receive shadows.
  *
- * API is basically the same as the PssmShadowRenderer;
+ * API is basically the same as the PssmShadowRenderer.
  *
  * @author Rémy Bouquet aka Nehon
  */
 public class SpotLightShadowFilter extends AbstractShadowFilter<SpotLightShadowRenderer> {
 
     /**
-     * Used for serialization.
-     * Use SpotLightShadowFilter#SpotLightShadowFilter(AssetManager assetManager,
-     * int shadowMapSize)
-     * instead.
+     * For serialization only. Do not use.
+     * 
+     * @see #SpotLightShadowFilter(AssetManager assetManager, int shadowMapSize)
      */
     protected SpotLightShadowFilter() {
         super();
     }
     
     /**
-     * Creates a SpotLight Shadow Filter
+     * Creates a SpotLightShadowFilter.
      *
-     * @param assetManager the application asset manager
-     * @param shadowMapSize the size of the rendered shadowmaps (512,1024,2048,
-     * etc...) The more quality, the fewer fps.
+     * @param assetManager  the application's asset manager
+     * @param shadowMapSize the size of the rendered shadow maps (512, 1024, 2048, etc...)
      */
     public SpotLightShadowFilter(AssetManager assetManager, int shadowMapSize) {
         super(assetManager, shadowMapSize, new SpotLightShadowRenderer(assetManager, shadowMapSize));
     }
 
     /**
-     * return the light used to cast shadows
+     * Returns the light used to cast shadows.
      *
      * @return the SpotLight
      */
@@ -87,20 +82,19 @@ public class SpotLightShadowFilter extends AbstractShadowFilter<SpotLightShadowR
     }
 
     /**
-     * Sets the light to use to cast shadows
+     * Sets the light to use to cast shadows.
      *
-     * @param light a SpotLight
+     * @param light the SpotLight
      */
     public void setLight(SpotLight light) {
         shadowRenderer.setLight(light);
     }
-   
+
     @Override
     public void write(JmeExporter ex) throws IOException {
         super.write(ex);
         OutputCapsule oc = ex.getCapsule(this);
         oc.write(shadowRenderer, "shadowRenderer", null);
-
     }
 
     @Override
@@ -109,4 +103,5 @@ public class SpotLightShadowFilter extends AbstractShadowFilter<SpotLightShadowR
         InputCapsule ic = im.getCapsule(this);
         shadowRenderer = (SpotLightShadowRenderer) ic.readSavable("shadowRenderer", null);
     }
+    
 }