cesium 0.23.0 → 0.24.0

data/app/assets/javascripts/Shaders/Builtin/Functions/ellipsoidWgs84TextureCoordinates.js

@@ -2,9 +2,15 @@
     /*global define*/
     define(function() {
     "use strict";
-    return "vec2 czm_ellipsoidWgs84TextureCoordinates(vec3 normal)\n\
+    return "/**\n\
+ * DOC_TBA\n\
+ *\n\
+ * @name czm_ellipsoidWgs84TextureCoordinates\n\
+ * @glslFunction\n\
+ */\n\
+vec2 czm_ellipsoidWgs84TextureCoordinates(vec3 normal)\n\
 {\n\
-return vec2(atan(normal.y, normal.x) * czm_oneOverTwoPi + 0.5, asin(normal.z) * czm_oneOverPi + 0.5);\n\
+    return vec2(atan(normal.y, normal.x) * czm_oneOverTwoPi + 0.5, asin(normal.z) * czm_oneOverPi + 0.5);\n\
 }\n\
 ";
 });

data/app/assets/javascripts/Shaders/Builtin/Functions/equalsEpsilon.js

@@ -2,17 +2,41 @@
     /*global define*/
     define(function() {
     "use strict";
-    return "bool czm_equalsEpsilon(vec4 left, vec4 right, float epsilon) {\n\
-return all(lessThanEqual(abs(left - right), vec4(epsilon)));\n\
+    return "/**\n\
+ * Compares <code>left</code> and <code>right</code> componentwise. Returns <code>true</code>\n\
+ * if they are within <code>epsilon</code> and <code>false</code> otherwise. The inputs\n\
+ * <code>left</code> and <code>right</code> can be <code>float</code>s, <code>vec2</code>s,\n\
+ * <code>vec3</code>s, or <code>vec4</code>s.\n\
+ *\n\
+ * @name czm_equalsEpsilon\n\
+ * @glslFunction\n\
+ *\n\
+ * @param {} left The first vector.\n\
+ * @param {} right The second vector.\n\
+ * @param {float} epsilon The epsilon to use for equality testing.\n\
+ * @returns {bool} <code>true</code> if the components are within <code>epsilon</code> and <code>false</code> otherwise.\n\
+ *\n\
+ * @example\n\
+ * // GLSL declarations\n\
+ * bool czm_equalsEpsilon(float left, float right, float epsilon);\n\
+ * bool czm_equalsEpsilon(vec2 left, vec2 right, float epsilon);\n\
+ * bool czm_equalsEpsilon(vec3 left, vec3 right, float epsilon);\n\
+ * bool czm_equalsEpsilon(vec4 left, vec4 right, float epsilon);\n\
+ */\n\
+bool czm_equalsEpsilon(vec4 left, vec4 right, float epsilon) {\n\
+    return all(lessThanEqual(abs(left - right), vec4(epsilon)));\n\
 }\n\
+\n\
 bool czm_equalsEpsilon(vec3 left, vec3 right, float epsilon) {\n\
-return all(lessThanEqual(abs(left - right), vec3(epsilon)));\n\
+    return all(lessThanEqual(abs(left - right), vec3(epsilon)));\n\
 }\n\
+\n\
 bool czm_equalsEpsilon(vec2 left, vec2 right, float epsilon) {\n\
-return all(lessThanEqual(abs(left - right), vec2(epsilon)));\n\
+    return all(lessThanEqual(abs(left - right), vec2(epsilon)));\n\
 }\n\
+\n\
 bool czm_equalsEpsilon(float left, float right, float epsilon) {\n\
-return (abs(left - right) <= epsilon);\n\
+    return (abs(left - right) <= epsilon);\n\
 }\n\
 ";
 });

data/app/assets/javascripts/Shaders/Builtin/Functions/eyeOffset.js

@@ -2,13 +2,25 @@
     /*global define*/
     define(function() {
     "use strict";
-    return "vec4 czm_eyeOffset(vec4 positionEC, vec3 eyeOffset)\n\
+    return "/**\n\
+ * DOC_TBA\n\
+ *\n\
+ * @name czm_eyeOffset\n\
+ * @glslFunction\n\
+ *\n\
+ * @param {vec4} positionEC DOC_TBA.\n\
+ * @param {vec3} eyeOffset DOC_TBA.\n\
+ *\n\
+ * @returns {vec4} DOC_TBA.\n\
+ */\n\
+vec4 czm_eyeOffset(vec4 positionEC, vec3 eyeOffset)\n\
 {\n\
-vec4 p = positionEC;\n\
-vec4 zEyeOffset = normalize(p) * eyeOffset.z;\n\
-p.xy += eyeOffset.xy + zEyeOffset.xy;\n\
-p.z += zEyeOffset.z;\n\
-return p;\n\
+    // This equation is approximate in x and y.\n\
+    vec4 p = positionEC;\n\
+    vec4 zEyeOffset = normalize(p) * eyeOffset.z;\n\
+    p.xy += eyeOffset.xy + zEyeOffset.xy;\n\
+    p.z += zEyeOffset.z;\n\
+    return p;\n\
 }\n\
 ";
 });

data/app/assets/javascripts/Shaders/Builtin/Functions/eyeToWindowCoordinates.js

@@ -2,12 +2,37 @@
     /*global define*/
     define(function() {
     "use strict";
-    return "vec4 czm_eyeToWindowCoordinates(vec4 positionEC)\n\
+    return "/**\n\
+ * Transforms a position from eye to window coordinates.  The transformation\n\
+ * from eye to clip coordinates is done using {@link czm_projection}.\n\
+ * The transform from normalized device coordinates to window coordinates is\n\
+ * done using {@link czm_viewportTransformation}, which assumes a depth range\n\
+ * of <code>near = 0</code> and <code>far = 1</code>.\n\
+ * <br /><br />\n\
+ * This transform is useful when there is a need to manipulate window coordinates\n\
+ * in a vertex shader as done by {@link BillboardCollection}.\n\
+ *\n\
+ * @name czm_eyeToWindowCoordinates\n\
+ * @glslFunction\n\
+ *\n\
+ * @param {vec4} position The position in eye coordinates to transform.\n\
+ *\n\
+ * @returns {vec4} The transformed position in window coordinates.\n\
+ *\n\
+ * @see czm_modelToWindowCoordinates\n\
+ * @see czm_projection\n\
+ * @see czm_viewportTransformation\n\
+ * @see BillboardCollection\n\
+ *\n\
+ * @example\n\
+ * vec4 positionWC = czm_eyeToWindowCoordinates(positionEC);\n\
+ */\n\
+vec4 czm_eyeToWindowCoordinates(vec4 positionEC)\n\
 {\n\
-vec4 q = czm_projection * positionEC;\n\
-q.xyz /= q.w;\n\
-q.xyz = (czm_viewportTransformation * vec4(q.xyz, 1.0)).xyz;\n\
-return q;\n\
+    vec4 q = czm_projection * positionEC;                        // clip coordinates\n\
+    q.xyz /= q.w;                                                // normalized device coordinates\n\
+    q.xyz = (czm_viewportTransformation * vec4(q.xyz, 1.0)).xyz; // window coordinates\n\
+    return q;\n\
 }\n\
 ";
 });

data/app/assets/javascripts/Shaders/Builtin/Functions/geodeticSurfaceNormal.js

@@ -2,9 +2,21 @@
     /*global define*/
     define(function() {
     "use strict";
-    return "vec3 czm_geodeticSurfaceNormal(vec3 positionOnEllipsoid, vec3 ellipsoidCenter, vec3 oneOverEllipsoidRadiiSquared)\n\
+    return "/**\n\
+ * DOC_TBA\n\
+ *\n\
+ * @name czm_geodeticSurfaceNormal\n\
+ * @glslFunction\n\
+ *\n\
+ * @param {vec3} positionOnEllipsoid DOC_TBA\n\
+ * @param {vec3} ellipsoidCenter DOC_TBA\n\
+ * @param {vec3} oneOverEllipsoidRadiiSquared DOC_TBA\n\
+ * \n\
+ * @returns {vec3} DOC_TBA.\n\
+ */\n\
+vec3 czm_geodeticSurfaceNormal(vec3 positionOnEllipsoid, vec3 ellipsoidCenter, vec3 oneOverEllipsoidRadiiSquared)\n\
 {\n\
-return normalize((positionOnEllipsoid - ellipsoidCenter) * oneOverEllipsoidRadiiSquared);\n\
+    return normalize((positionOnEllipsoid - ellipsoidCenter) * oneOverEllipsoidRadiiSquared);\n\
 }\n\
 ";
 });

data/app/assets/javascripts/Shaders/Builtin/Functions/getDefaultMaterial.js

@@ -2,16 +2,32 @@
     /*global define*/
     define(function() {
     "use strict";
-    return "czm_material czm_getDefaultMaterial(czm_materialInput materialInput)\n\
+    return "/**\n\
+ * An czm_material with default values. Every material's czm_getMaterial\n\
+ * should use this default material as a base for the material it returns.\n\
+ * The default normal value is given by materialInput.normalEC.\n\
+ *\n\
+ * @name czm_getDefaultMaterial\n\
+ * @glslFunction \n\
+ *\n\
+ * @param {czm_materialInput} input The input used to construct the default material.\n\
+ * \n\
+ * @returns {czm_material} The default material.\n\
+ *\n\
+ * @see czm_materialInput\n\
+ * @see czm_material\n\
+ * @see czm_getMaterial\n\
+ */\n\
+czm_material czm_getDefaultMaterial(czm_materialInput materialInput)\n\
 {\n\
-czm_material material;\n\
-material.diffuse = vec3(0.0);\n\
-material.specular = 0.0;\n\
-material.shininess = 1.0;\n\
-material.normal = materialInput.normalEC;\n\
-material.emission = vec3(0.0);\n\
-material.alpha = 1.0;\n\
-return material;\n\
+    czm_material material;\n\
+    material.diffuse = vec3(0.0);\n\
+    material.specular = 0.0;\n\
+    material.shininess = 1.0;\n\
+    material.normal = materialInput.normalEC;\n\
+    material.emission = vec3(0.0);\n\
+    material.alpha = 1.0;\n\
+    return material;\n\
 }\n\
 ";
 });

data/app/assets/javascripts/Shaders/Builtin/Functions/getLambertDiffuse.js

@@ -2,9 +2,26 @@
     /*global define*/
     define(function() {
     "use strict";
-    return "float czm_getLambertDiffuse(vec3 lightDirectionEC, vec3 normalEC)\n\
+    return "/**\n\
+ * Calculates the intensity of diffusely reflected light.\n\
+ *\n\
+ * @name czm_getLambertDiffuse\n\
+ * @glslFunction\n\
+ *\n\
+ * @param {vec3} lightDirectionEC Unit vector pointing to the light source in eye coordinates.\n\
+ * @param {vec3} normalEC The surface normal in eye coordinates.\n\
+ *\n\
+ * @returns {float} The intensity of the diffuse reflection.\n\
+ *\n\
+ * @see czm_phong\n\
+ *\n\
+ * @example\n\
+ * float diffuseIntensity = czm_getLambertDiffuse(lightDirectionEC, normalEC);\n\
+ * float specularIntensity = czm_getSpecular(lightDirectionEC, toEyeEC, normalEC, 200);\n\
+ * vec3 color = (diffuseColor * diffuseIntensity) + (specularColor * specularIntensity);\n\
+ */\n\
+float czm_getLambertDiffuse(vec3 lightDirectionEC, vec3 normalEC)\n\
 {\n\
-return max(dot(lightDirectionEC, normalEC), 0.0);\n\
-}\n\
-";
+    return max(dot(lightDirectionEC, normalEC), 0.0);\n\
+}";
 });

data/app/assets/javascripts/Shaders/Builtin/Functions/getSpecular.js

@@ -2,11 +2,30 @@
     /*global define*/
     define(function() {
     "use strict";
-    return "float czm_getSpecular(vec3 lightDirectionEC, vec3 toEyeEC, vec3 normalEC, float shininess)\n\
+    return "/**\n\
+ * Calculates the specular intensity of reflected light.\n\
+ *\n\
+ * @name czm_getSpecular\n\
+ * @glslFunction\n\
+ *\n\
+ * @param {vec3} lightDirectionEC Unit vector pointing to the light source in eye coordinates.\n\
+ * @param {vec3} toEyeEC Unit vector pointing to the eye position in eye coordinates.\n\
+ * @param {vec3} normalEC The surface normal in eye coordinates.\n\
+ * @param {float} shininess The sharpness of the specular reflection.  Higher values create a smaller, more focused specular highlight.\n\
+ *\n\
+ * @returns {float} The intensity of the specular highlight.\n\
+ *\n\
+ * @see czm_phong\n\
+ *\n\
+ * @example\n\
+ * float diffuseIntensity = czm_getLambertDiffuse(lightDirectionEC, normalEC);\n\
+ * float specularIntensity = czm_getSpecular(lightDirectionEC, toEyeEC, normalEC, 200);\n\
+ * vec3 color = (diffuseColor * diffuseIntensity) + (specularColor * specularIntensity);\n\
+ */\n\
+float czm_getSpecular(vec3 lightDirectionEC, vec3 toEyeEC, vec3 normalEC, float shininess)\n\
 {\n\
-vec3 toReflectedLight = reflect(-lightDirectionEC, normalEC);\n\
-float specular = max(dot(toReflectedLight, toEyeEC), 0.0);\n\
-return pow(specular, shininess);\n\
-}\n\
-";
+    vec3 toReflectedLight = reflect(-lightDirectionEC, normalEC);\n\
+    float specular = max(dot(toReflectedLight, toEyeEC), 0.0);\n\
+    return pow(specular, shininess);\n\
+}";
 });

data/app/assets/javascripts/Shaders/Builtin/Functions/getWaterNoise.js

@@ -2,31 +2,42 @@
     /*global define*/
     define(function() {
     "use strict";
-    return "vec4 czm_getWaterNoise(sampler2D normalMap, vec2 uv, float time, float angleInRadians)\n\
+    return "/**\n\
+ * @private\n\
+ */\n\
+vec4 czm_getWaterNoise(sampler2D normalMap, vec2 uv, float time, float angleInRadians)\n\
 {\n\
-float cosAngle = cos(angleInRadians);\n\
-float sinAngle = sin(angleInRadians);\n\
-vec2 s0 = vec2(1.0/17.0, 0.0);\n\
-vec2 s1 = vec2(-1.0/29.0, 0.0);\n\
-vec2 s2 = vec2(1.0/101.0, 1.0/59.0);\n\
-vec2 s3 = vec2(-1.0/109.0, -1.0/57.0);\n\
-s0 = vec2((cosAngle * s0.x) - (sinAngle * s0.y), (sinAngle * s0.x) + (cosAngle * s0.y));\n\
-s1 = vec2((cosAngle * s1.x) - (sinAngle * s1.y), (sinAngle * s1.x) + (cosAngle * s1.y));\n\
-s2 = vec2((cosAngle * s2.x) - (sinAngle * s2.y), (sinAngle * s2.x) + (cosAngle * s2.y));\n\
-s3 = vec2((cosAngle * s3.x) - (sinAngle * s3.y), (sinAngle * s3.x) + (cosAngle * s3.y));\n\
-vec2 uv0 = (uv/103.0) + (time * s0);\n\
-vec2 uv1 = uv/107.0 + (time * s1) + vec2(0.23);\n\
-vec2 uv2 = uv/vec2(897.0, 983.0) + (time * s2) + vec2(0.51);\n\
-vec2 uv3 = uv/vec2(991.0, 877.0) + (time * s3) + vec2(0.71);\n\
-uv0 = fract(uv0);\n\
-uv1 = fract(uv1);\n\
-uv2 = fract(uv2);\n\
-uv3 = fract(uv3);\n\
-vec4 noise = (texture2D(normalMap, uv0)) +\n\
-(texture2D(normalMap, uv1)) +\n\
-(texture2D(normalMap, uv2)) +\n\
-(texture2D(normalMap, uv3));\n\
-return ((noise / 4.0) - 0.5) * 2.0;\n\
+    float cosAngle = cos(angleInRadians);\n\
+    float sinAngle = sin(angleInRadians);\n\
+\n\
+    // time dependent sampling directions\n\
+    vec2 s0 = vec2(1.0/17.0, 0.0);\n\
+    vec2 s1 = vec2(-1.0/29.0, 0.0);\n\
+    vec2 s2 = vec2(1.0/101.0, 1.0/59.0);\n\
+    vec2 s3 = vec2(-1.0/109.0, -1.0/57.0);\n\
+\n\
+    // rotate sampling direction by specified angle\n\
+    s0 = vec2((cosAngle * s0.x) - (sinAngle * s0.y), (sinAngle * s0.x) + (cosAngle * s0.y));\n\
+    s1 = vec2((cosAngle * s1.x) - (sinAngle * s1.y), (sinAngle * s1.x) + (cosAngle * s1.y));\n\
+    s2 = vec2((cosAngle * s2.x) - (sinAngle * s2.y), (sinAngle * s2.x) + (cosAngle * s2.y));\n\
+    s3 = vec2((cosAngle * s3.x) - (sinAngle * s3.y), (sinAngle * s3.x) + (cosAngle * s3.y));\n\
+\n\
+    vec2 uv0 = (uv/103.0) + (time * s0);\n\
+    vec2 uv1 = uv/107.0 + (time * s1) + vec2(0.23);\n\
+    vec2 uv2 = uv/vec2(897.0, 983.0) + (time * s2) + vec2(0.51);\n\
+    vec2 uv3 = uv/vec2(991.0, 877.0) + (time * s3) + vec2(0.71);\n\
+\n\
+    uv0 = fract(uv0);\n\
+    uv1 = fract(uv1);\n\
+    uv2 = fract(uv2);\n\
+    uv3 = fract(uv3);\n\
+    vec4 noise = (texture2D(normalMap, uv0)) +\n\
+                 (texture2D(normalMap, uv1)) +\n\
+                 (texture2D(normalMap, uv2)) +\n\
+                 (texture2D(normalMap, uv3));\n\
+\n\
+    // average and scale to between -1 and 1\n\
+    return ((noise / 4.0) - 0.5) * 2.0;\n\
 }\n\
 ";
 });

data/app/assets/javascripts/Shaders/Builtin/Functions/getWgs84EllipsoidEC.js

@@ -2,13 +2,26 @@
     /*global define*/
     define(function() {
     "use strict";
-    return "czm_ellipsoid czm_getWgs84EllipsoidEC()\n\
+    return "/**\n\
+ * Returns the WGS84 ellipsoid, with its center at the origin of world coordinates, in eye coordinates.\n\
+ *\n\
+ * @name czm_getWgs84EllipsoidEC\n\
+ * @glslFunction\n\
+ *\n\
+ * @returns {czm_ellipsoid} The WGS84 ellipsoid, with its center at the origin of world coordinates, in eye coordinates.\n\
+ *\n\
+ * @see Ellipsoid.getWgs84\n\
+ *\n\
+ * @example\n\
+ * czm_ellipsoid ellipsoid = czm_getWgs84EllipsoidEC();\n\
+ */\n\
+czm_ellipsoid czm_getWgs84EllipsoidEC()\n\
 {\n\
-vec3 radii = vec3(6378137.0, 6378137.0, 6356752.314245);\n\
-vec3 inverseRadii = vec3(1.0 / radii.x, 1.0 / radii.y, 1.0 / radii.z);\n\
-vec3 inverseRadiiSquared = inverseRadii * inverseRadii;\n\
-czm_ellipsoid temp = czm_ellipsoid(czm_view[3].xyz, radii, inverseRadii, inverseRadiiSquared);\n\
-return temp;\n\
+    vec3 radii = vec3(6378137.0, 6378137.0, 6356752.314245);\n\
+    vec3 inverseRadii = vec3(1.0 / radii.x, 1.0 / radii.y, 1.0 / radii.z);\n\
+    vec3 inverseRadiiSquared = inverseRadii * inverseRadii;\n\
+    czm_ellipsoid temp = czm_ellipsoid(czm_view[3].xyz, radii, inverseRadii, inverseRadiiSquared);\n\
+    return temp;\n\
 }\n\
 ";
 });

data/app/assets/javascripts/Shaders/Builtin/Functions/hue.js

@@ -2,19 +2,35 @@
     /*global define*/
     define(function() {
     "use strict";
-    return "vec3 czm_hue(vec3 rgb, float adjustment)\n\
+    return "/**\n\
+ * Adjusts the hue of a color.\n\
+ * \n\
+ * @name czm_hue\n\
+ * @glslFunction\n\
+ * \n\
+ * @param {vec3} rgb The color.\n\
+ * @param {float} adjustment The amount to adjust the hue of the color in radians.\n\
+ *\n\
+ * @returns {float} The color with the hue adjusted.\n\
+ *\n\
+ * @example\n\
+ * vec3 adjustHue = czm_hue(color, czm_pi); // The same as czm_hue(color, -czm_pi)\n\
+ */\n\
+vec3 czm_hue(vec3 rgb, float adjustment)\n\
 {\n\
-const mat3 toYIQ = mat3(0.299,     0.587,     0.114,\n\
-0.595716, -0.274453, -0.321263,\n\
-0.211456, -0.522591,  0.311135);\n\
-const mat3 toRGB = mat3(1.0,  0.9563,  0.6210,\n\
-1.0, -0.2721, -0.6474,\n\
-1.0, -1.107,   1.7046);\n\
-vec3 yiq = toYIQ * rgb;\n\
-float hue = atan(yiq.z, yiq.y) + adjustment;\n\
-float chroma = sqrt(yiq.z * yiq.z + yiq.y * yiq.y);\n\
-vec3 color = vec3(yiq.x, chroma * cos(hue), chroma * sin(hue));\n\
-return toRGB * color;\n\
+    const mat3 toYIQ = mat3(0.299,     0.587,     0.114,\n\
+                            0.595716, -0.274453, -0.321263,\n\
+                            0.211456, -0.522591,  0.311135);\n\
+    const mat3 toRGB = mat3(1.0,  0.9563,  0.6210,\n\
+                            1.0, -0.2721, -0.6474,\n\
+                            1.0, -1.107,   1.7046);\n\
+    \n\
+    vec3 yiq = toYIQ * rgb;\n\
+    float hue = atan(yiq.z, yiq.y) + adjustment;\n\
+    float chroma = sqrt(yiq.z * yiq.z + yiq.y * yiq.y);\n\
+    \n\
+    vec3 color = vec3(yiq.x, chroma * cos(hue), chroma * sin(hue));\n\
+    return toRGB * color;\n\
 }\n\
 ";
 });

data/app/assets/javascripts/Shaders/Builtin/Functions/isEmpty.js

@@ -2,9 +2,24 @@
     /*global define*/
     define(function() {
     "use strict";
-    return "bool czm_isEmpty(czm_raySegment interval)\n\
+    return "/**\n\
+ * Determines if a time interval is empty.\n\
+ *\n\
+ * @name czm_isEmpty\n\
+ * @glslFunction \n\
+ * \n\
+ * @param {czm_raySegment} interval The interval to test.\n\
+ * \n\
+ * @returns {bool} <code>true</code> if the time interval is empty; otherwise, <code>false</code>.\n\
+ *\n\
+ * @example\n\
+ * bool b0 = czm_isEmpty(czm_emptyRaySegment);      // true\n\
+ * bool b1 = czm_isEmpty(czm_raySegment(0.0, 1.0)); // false\n\
+ * bool b2 = czm_isEmpty(czm_raySegment(1.0, 1.0)); // false, contains 1.0.\n\
+ */\n\
+bool czm_isEmpty(czm_raySegment interval)\n\
 {\n\
-return (interval.stop < 0.0);\n\
+    return (interval.stop < 0.0);\n\
 }\n\
 ";
 });