From bcef1b1e5cd10217ff9a218724bc56c5518aa701 Mon Sep 17 00:00:00 2001 From: "rem..om" Date: Tue, 14 Jun 2011 20:41:24 +0000 Subject: [PATCH] Documented com.jme3.water and com.jme3.post.ssao git-svn-id: https://jmonkeyengine.googlecode.com/svn/trunk@7630 75d07b2b-3a1a-0410-a2c5-0572b91ccdca --- .../com/jme3/post/ssao/SSAOFilter.java | 82 +++++++++++++++---- .../com/jme3/water/ReflectionProcessor.java | 32 ++++++++ .../com/jme3/water/SimpleWaterProcessor.java | 74 ++++++++++++++++- .../com/jme3/water/WaterFilter.java | 51 +++++++++++- 4 files changed, 217 insertions(+), 22 deletions(-) diff --git a/engine/src/desktop-fx/com/jme3/post/ssao/SSAOFilter.java b/engine/src/desktop-fx/com/jme3/post/ssao/SSAOFilter.java index fc5fdd6e1..f0b0428de 100644 --- a/engine/src/desktop-fx/com/jme3/post/ssao/SSAOFilter.java +++ b/engine/src/desktop-fx/com/jme3/post/ssao/SSAOFilter.java @@ -51,8 +51,12 @@ import java.io.IOException; import java.util.ArrayList; /** - * - * @author nehon + * SSAO stands for screen space ambient occlusion + * It's a technique that fake ambient lighting by computind shadows that near by objects would casts on each others + * under the effect of an ambient light + * more info on this in this blog post http://jmonkeyengine.org/2010/08/16/screen-space-ambient-occlusion-for-jmonkeyengine-3-0/ + * + * @author Rémy Bouquet aka Nehon */ public class SSAOFilter extends Filter { @@ -68,8 +72,8 @@ public class SSAOFilter extends Filter { private boolean useAo = true; private Material ssaoMat; private Pass ssaoPass; - private Material downSampleMat; - private Pass downSamplePass; +// private Material downSampleMat; +// private Pass downSamplePass; private float downSampleFactor = 1f; /** @@ -80,12 +84,11 @@ public class SSAOFilter extends Filter { } /** - * - * @param vp - * @param sampleRadius - * @param intensity - * @param scale - * @param bias + * Create a Screen Space Ambiant Occlusion Filter + * @param sampleRadius The radius of the area where random samples will be picked. default 5.1f + * @param intensity intensity of the resulting AO. default 1.2f + * @param scale distance between occluders and occludee. default 0.2f + * @param bias the width of the occlusion cone considered by the occludee. default 0.1f */ public SSAOFilter(float sampleRadius, float intensity, float scale, float bias) { this(); @@ -123,7 +126,7 @@ public class SSAOFilter extends Filter { postRenderPasses = new ArrayList(); normalPass = new Pass(); - normalPass.init(renderManager.getRenderer(), (int)(screenWidth / downSampleFactor), (int)(screenHeight / downSampleFactor), Format.RGBA8, Format.Depth); + normalPass.init(renderManager.getRenderer(), (int) (screenWidth / downSampleFactor), (int) (screenHeight / downSampleFactor), Format.RGBA8, Format.Depth); frustumNearFar = new Vector2f(); @@ -153,7 +156,7 @@ public class SSAOFilter extends Filter { } }; - ssaoPass.init(renderManager.getRenderer(), (int)(screenWidth / downSampleFactor), (int)(screenHeight / downSampleFactor), Format.RGBA8, Format.Depth, 1, ssaoMat); + ssaoPass.init(renderManager.getRenderer(), (int) (screenWidth / downSampleFactor), (int) (screenHeight / downSampleFactor), Format.RGBA8, Format.Depth, 1, ssaoMat); ssaoPass.getRenderedTexture().setMinFilter(Texture.MinFilter.Trilinear); ssaoPass.getRenderedTexture().setMagFilter(Texture.MagFilter.Bilinear); postRenderPasses.add(ssaoPass); @@ -180,10 +183,19 @@ public class SSAOFilter extends Filter { } + /** + * Return the bias
+ * see {@link setBias(float bias)} + * @return + */ public float getBias() { return bias; } + /** + * Sets the the width of the occlusion cone considered by the occludee default is 0.1f + * @param bias + */ public void setBias(float bias) { this.bias = bias; if (ssaoMat != null) { @@ -191,10 +203,18 @@ public class SSAOFilter extends Filter { } } + /** + * returns the ambient occlusion intensity + * @return + */ public float getIntensity() { return intensity; } + /** + * Sets the Ambient occlusion intensity default is 1.2f + * @param intensity + */ public void setIntensity(float intensity) { this.intensity = intensity; if (ssaoMat != null) { @@ -203,10 +223,19 @@ public class SSAOFilter extends Filter { } + /** + * returns the sample radius
+ * see {link setSampleRadius(float sampleRadius)} + * @return + */ public float getSampleRadius() { return sampleRadius; } + /** + * Sets the radius of the area where random samples will be picked dafault 5.1f + * @param sampleRadius + */ public void setSampleRadius(float sampleRadius) { this.sampleRadius = sampleRadius; if (ssaoMat != null) { @@ -215,22 +244,39 @@ public class SSAOFilter extends Filter { } + /** + * returns the scale
+ * see {@link setScale(float scale)} + * @return + */ public float getScale() { return scale; } + /** + * + * Returns the distance between occluders and occludee. dafault 0.2f + * @param scale + */ public void setScale(float scale) { this.scale = scale; if (ssaoMat != null) { ssaoMat.setFloat("Scale", scale); } - } + /** + * debugging only , will be removed + * @return + */ public boolean isUseAo() { return useAo; } + /** + * debugging only , will be removed + * @return + */ public void setUseAo(boolean useAo) { this.useAo = useAo; if (material != null) { @@ -239,10 +285,18 @@ public class SSAOFilter extends Filter { } + /** + * debugging only , will be removed + * @return + */ public boolean isUseOnlyAo() { return useOnlyAo; } + /** + * debugging only , will be removed + * @return + */ public void setUseOnlyAo(boolean useOnlyAo) { this.useOnlyAo = useOnlyAo; if (material != null) { @@ -269,6 +323,4 @@ public class SSAOFilter extends Filter { scale = ic.readFloat("scale", 0.2f); bias = ic.readFloat("bias", 0.1f); } - - } diff --git a/engine/src/desktop-fx/com/jme3/water/ReflectionProcessor.java b/engine/src/desktop-fx/com/jme3/water/ReflectionProcessor.java index 1267d701f..9a14df82f 100644 --- a/engine/src/desktop-fx/com/jme3/water/ReflectionProcessor.java +++ b/engine/src/desktop-fx/com/jme3/water/ReflectionProcessor.java @@ -24,6 +24,12 @@ public class ReflectionProcessor implements SceneProcessor { private FrameBuffer reflectionBuffer; private Plane reflectionClipPlane; + /** + * Creates a ReflectionProcessor + * @param reflectionCam the cam to use for reflection + * @param reflectionBuffer the FrameBuffer to render to + * @param reflectionClipPlane the clipping plane + */ public ReflectionProcessor(Camera reflectionCam, FrameBuffer reflectionBuffer, Plane reflectionClipPlane) { this.reflectionCam = reflectionCam; this.reflectionBuffer = reflectionBuffer; @@ -67,26 +73,52 @@ public class ReflectionProcessor implements SceneProcessor { public void cleanup() { } + /** + * Internal use only
+ * returns the frame buffer + * @return + */ public FrameBuffer getReflectionBuffer() { return reflectionBuffer; } + /** + * Internal use only
+ * sets the frame buffer + * @param reflectionBuffer + */ public void setReflectionBuffer(FrameBuffer reflectionBuffer) { this.reflectionBuffer = reflectionBuffer; } + /** + * returns the reflection cam + * @return + */ public Camera getReflectionCam() { return reflectionCam; } + /** + * sets the reflection cam + * @param reflectionCam + */ public void setReflectionCam(Camera reflectionCam) { this.reflectionCam = reflectionCam; } + /** + * returns the reflection clip plane + * @return + */ public Plane getReflectionClipPlane() { return reflectionClipPlane; } + /** + * Sets the reflection clip plane + * @param reflectionClipPlane + */ public void setReflectionClipPlane(Plane reflectionClipPlane) { this.reflectionClipPlane = reflectionClipPlane; } diff --git a/engine/src/desktop-fx/com/jme3/water/SimpleWaterProcessor.java b/engine/src/desktop-fx/com/jme3/water/SimpleWaterProcessor.java index 73d6ac730..14e5267d9 100644 --- a/engine/src/desktop-fx/com/jme3/water/SimpleWaterProcessor.java +++ b/engine/src/desktop-fx/com/jme3/water/SimpleWaterProcessor.java @@ -51,16 +51,46 @@ import com.jme3.scene.Spatial; import com.jme3.scene.shape.Quad; import com.jme3.texture.FrameBuffer; import com.jme3.texture.Image.Format; -import com.jme3.texture.Texture.MagFilter; -import com.jme3.texture.Texture.MinFilter; import com.jme3.texture.Texture.WrapMode; import com.jme3.texture.Texture2D; import com.jme3.ui.Picture; -import com.jme3.util.TempVars; /** * - * @author normenhansen + * Simple Water renders a simple plane that use reflection and refraction to look like water. + * It's pretty basic, but much faster than the WaterFilter + * It's useful if you aim low specs hardware and still want a good looking water. + * Usage is : + * + * SimpleWaterProcessor waterProcessor = new SimpleWaterProcessor(assetManager); + * //setting the scene to use for reflection + * waterProcessor.setReflectionScene(mainScene); + * //setting the light position + * waterProcessor.setLightPosition(lightPos); + * + * //setting the water plane + * Vector3f waterLocation=new Vector3f(0,-20,0); + * waterProcessor.setPlane(new Plane(Vector3f.UNIT_Y, waterLocation.dot(Vector3f.UNIT_Y))); + * //setting the water color + * waterProcessor.setWaterColor(ColorRGBA.Brown); + * + * //creating a quad to render water to + * Quad quad = new Quad(400,400); + * + * //the texture coordinates define the general size of the waves + * quad.scaleTextureCoordinates(new Vector2f(6f,6f)); + * + * //creating a geom to attach the water material + * Geometry water=new Geometry("water", quad); + * water.setLocalTranslation(-200, -20, 250); + * water.setLocalRotation(new Quaternion().fromAngleAxis(-FastMath.HALF_PI, Vector3f.UNIT_X)); + * //finally setting the material + * water.setMaterial(waterProcessor.getMaterial()); + * + * //attaching the water to the root node + * rootNode.attachChild(water); + * + * @author Normen Hansen & Rémy Bouquet */ public class SimpleWaterProcessor implements SceneProcessor { @@ -100,6 +130,10 @@ public class SimpleWaterProcessor implements SceneProcessor { private Vector3f vect2 = new Vector3f(); private Vector3f vect3 = new Vector3f(); + /** + * Creates a SimpleWaterProcessor + * @param manager the asset manager + */ public SimpleWaterProcessor(AssetManager manager) { this.manager = manager; material = new Material(manager, "Common/MatDefs/Water/SimpleWater.j3md"); @@ -312,10 +346,18 @@ public class SimpleWaterProcessor implements SceneProcessor { reflectionScene = spat; } + /** + * returns the width of the reflection and refraction textures + * @return + */ public int getRenderWidth() { return renderWidth; } + /** + * returns the height of the reflection and refraction textures + * @return + */ public int getRenderHeight() { return renderHeight; } @@ -331,6 +373,10 @@ public class SimpleWaterProcessor implements SceneProcessor { renderHeight = height; } + /** + * returns the water plane + * @return + */ public Plane getPlane() { return plane; } @@ -390,14 +436,26 @@ public class SimpleWaterProcessor implements SceneProcessor { material.setFloat("waterDepth", depth); } + /** + * return the water depth + * @return + */ public float getWaterDepth() { return waterDepth; } + /** + * returns water transparency + * @return + */ public float getWaterTransparency() { return waterTransparency; } + /** + * sets the water transparency default os 0.1f + * @param waterTransparency + */ public void setWaterTransparency(float waterTransparency) { this.waterTransparency = Math.max(0, waterTransparency); material.setFloat("waterTransparency", waterTransparency / 10); @@ -434,10 +492,18 @@ public class SimpleWaterProcessor implements SceneProcessor { material.setColor("texScale", new ColorRGBA(value, value, value, value)); } + /** + * retruns true if the waterprocessor is in debug mode + * @return + */ public boolean isDebug() { return debug; } + /** + * set to true to display reflection and refraction textures in the GUI for debug purpose + * @param debug + */ public void setDebug(boolean debug) { this.debug = debug; } diff --git a/engine/src/desktop-fx/com/jme3/water/WaterFilter.java b/engine/src/desktop-fx/com/jme3/water/WaterFilter.java index 2f35f6e98..ce2c06cd4 100644 --- a/engine/src/desktop-fx/com/jme3/water/WaterFilter.java +++ b/engine/src/desktop-fx/com/jme3/water/WaterFilter.java @@ -46,7 +46,6 @@ import com.jme3.post.Filter; import com.jme3.post.Filter.Pass; import com.jme3.renderer.Camera; import com.jme3.renderer.RenderManager; -import com.jme3.renderer.Renderer; import com.jme3.renderer.ViewPort; import com.jme3.scene.Node; import com.jme3.scene.Spatial; @@ -57,8 +56,12 @@ import com.jme3.util.TempVars; import java.io.IOException; /** - * - * @author nehon + * The WaterFilter is a 2D post process that simulate water. + * It renders water above and under water. + * See this blog post for more info http://jmonkeyengine.org/2011/01/15/new-advanced-water-effect-for-jmonkeyengine-3/ + * + * + * @author Rémy Bouquet aka Nehon */ public class WaterFilter extends Filter { @@ -805,10 +808,18 @@ public class WaterFilter extends Filter { } + /** + * returns true if the water use the refraction + * @return + */ public boolean isUseRefraction() { return useRefraction; } + /** + * set to true to use refraction (default is true) + * @param useRefraction + */ public void setUseRefraction(boolean useRefraction) { this.useRefraction = useRefraction; if (material != null) { @@ -817,10 +828,19 @@ public class WaterFilter extends Filter { } + /** + * returns true if the ater use ripples + * @return + */ public boolean isUseRipples() { return useRipples; } + /** + * + * Set to true tu use ripples + * @param useRipples + */ public void setUseRipples(boolean useRipples) { this.useRipples = useRipples; if (material != null) { @@ -829,10 +849,18 @@ public class WaterFilter extends Filter { } + /** + * returns true if the water use specular + * @return + */ public boolean isUseSpecular() { return useSpecular; } + /** + * Set to true to use specular lightings on the water + * @param useSpecular + */ public void setUseSpecular(boolean useSpecular) { this.useSpecular = useSpecular; if (material != null) { @@ -840,10 +868,18 @@ public class WaterFilter extends Filter { } } + /** + * returns the foam intensity + * @return + */ public float getFoamIntensity() { return foamIntensity; } + /** + * sets the foam intensity default is 0.5f + * @param foamIntensity + */ public void setFoamIntensity(float foamIntensity) { this.foamIntensity = foamIntensity; if (material != null) { @@ -852,10 +888,19 @@ public class WaterFilter extends Filter { } } + /** + * returns the reflection displace + * see {@link setReflectionDisplace(float reflectionDisplace)} + * @return + */ public float getReflectionDisplace() { return reflectionDisplace; } + /** + * Sets the reflection displace. define how troubled will look the reflection in the water. default is 30 + * @param reflectionDisplace + */ public void setReflectionDisplace(float reflectionDisplace) { this.reflectionDisplace = reflectionDisplace; if (material != null) {