Added proper documentation for camera.getWorldCoordinates

Added a convenience method to compute z in projection space from z in view space

git-svn-id: https://jmonkeyengine.googlecode.com/svn/trunk@9934 75d07b2b-3a1a-0410-a2c5-0572b91ccdca

engine/src/core/com/jme3/renderer/Camera.java

@@ -1296,17 +1296,43 @@ public class Camera implements Savable, Cloneable {
     }
 
     /**
-     * @see Camera#getWorldCoordinates
+     * Computes the z value in projection space from the z value in view space 
+     * Note that the returned value is going non linearly from 0 to 1.
+     * for more explanations on non linear z buffer see
+     * http://www.sjbaker.org/steve/omniv/love_your_z_buffer.html
+     * @param viewZPos the z value in view space.
+     * @return the z value in projection space.
+     */
+    public float getViewToProjectionZ(float viewZPos) {
+        float far = getFrustumFar();
+        float near = getFrustumNear();
+        float a = far / (far - near);
+        float b = far * near / (near - far);
+        return a + b / viewZPos;
+    }
+
+    /**
+     * Computes a position in World space given a screen position in screen space (0,0 to width, height)
+     * and a z position in projection space ( 0 to 1 non linear).
+     * This former value is also known as the Z buffer value or non linear depth buffer.
+     * for more explanations on non linear z buffer see
+     * http://www.sjbaker.org/steve/omniv/love_your_z_buffer.html
+     * 
+     * To compute the projection space z from the view space z (distance from cam to object) @see Camera#getViewToProjectionZ
+     * 
+     * @param screenPos 2d coordinate in screen space
+     * @param projectionZPos non linear z value in projection space
+     * @return the position in world space.
      */
-    public Vector3f getWorldCoordinates(Vector2f screenPos, float zPos) {
-        return getWorldCoordinates(screenPos, zPos, null);
+    public Vector3f getWorldCoordinates(Vector2f screenPos, float projectionZPos) {
+        return getWorldCoordinates(screenPos, projectionZPos, null);
     }
 
     /**
      * @see Camera#getWorldCoordinates
      */
     public Vector3f getWorldCoordinates(Vector2f screenPosition,
-            float zPos, Vector3f store) {
+            float projectionZPos, Vector3f store) {
         if (store == null) {
             store = new Vector3f();
         }
@@ -1317,7 +1343,7 @@ public class Camera implements Savable, Cloneable {
         store.set(
                 (screenPosition.x / getWidth() - viewPortLeft) / (viewPortRight - viewPortLeft) * 2 - 1,
                 (screenPosition.y / getHeight() - viewPortBottom) / (viewPortTop - viewPortBottom) * 2 - 1,
-                zPos * 2 - 1);
+                projectionZPos * 2 - 1);
 
         float w = inverseMat.multProj(store, store);      
         store.multLocal(1f / w);