changeset 5961:35d622e670f1 8.0-b120

[Doc only] RT-26385: Finish javadoc for FX 8 3D API Reviewed-by: kcr, vadim
author Chien Yang <chien.yang@oracle.com>
date Tue, 10 Dec 2013 12:43:30 -0800
parents 8e8958c52331
children c9a2279862ac b7940b612df5
files modules/graphics/src/main/java/javafx/scene/SubScene.java modules/graphics/src/main/java/javafx/scene/paint/PhongMaterial.java
diffstat 2 files changed, 66 insertions(+), 5 deletions(-) [+]
line wrap: on
line diff
--- a/modules/graphics/src/main/java/javafx/scene/SubScene.java	Tue Dec 10 12:07:31 2013 -0800
+++ b/modules/graphics/src/main/java/javafx/scene/SubScene.java	Tue Dec 10 12:43:30 2013 -0800
@@ -61,11 +61,26 @@
 
 /**
  * The {@code SubScene} class is the container for content in a scene graph.
+ * {@code SubScene} provides separation of different parts of a scene, each
+ * of which can be rendered with a different camera, depth buffer, or scene
+ * anti-aliasing. A {@code SubScene} is embedded into the main scene or another
+ * sub-scene.
+ * 
+ * <p>
+ * Possible use cases are:
+ * <ul>
+ * <li> Mixing 2D and 3D content </li>
+ * <li> Overlay for UI controls </li>
+ * <li> Underlay for background </li>
+ * <li> Heads-up display </li>
+ * </ul>
+ * </p>
  *
  * <p>
  * A default headlight will be added to a {@SubScene} that contains one or more
  * {@code Shape3D} nodes, but no light nodes. This light source is a 
  * {@code Color.WHITE} {@code PointLight} placed at the camera position.
+ * </p>
  *
  * @since JavaFX 8.0
  */
--- a/modules/graphics/src/main/java/javafx/scene/paint/PhongMaterial.java	Tue Dec 10 12:07:31 2013 -0800
+++ b/modules/graphics/src/main/java/javafx/scene/paint/PhongMaterial.java	Tue Dec 10 12:43:30 2013 -0800
@@ -33,12 +33,43 @@
 import javafx.beans.property.ObjectProperty;
 import javafx.beans.property.SimpleDoubleProperty;
 import javafx.beans.property.SimpleObjectProperty;
+import javafx.scene.AmbientLight;
+import javafx.scene.PointLight;
 import javafx.scene.image.Image;
 
 /**
  * The {@code PhongMaterial} class provides definitions of properties that 
- * represent a form of Phong shaded material.
+ * represent a Phong shaded material. It describes the interaction of
+ * light with the surface of the {@code Mesh} it is applied to. The {@code PhongMaterial}
+ * reflects light in terms of a diffuse and specular component together with 
+ * an ambient and a self illumination term. The color of a point on a geometric
+ * surface is mathematical function of these four components. 
+ * <p> 
+ * The color is computed by the following equation:
+ * <p>
+ * <ul><pre>
+ * for each ambient light source i {
+ *     ambient += lightColor[i]
+ * }
+ * 
+ * for each point light source i {
+ *     diffuse += (L[i] . N) * lightColor[i]
+ *     specular += ((R[i] . V) ^ (specularPower * intensity(specularMap))) * lightColor[i]
+ * }
  *
+ * color = (ambient + diffuse) * diffuseColor * diffuseMap
+ *             + specular * specularColor * specularMap
+ *             + selfIlluminationMap
+ * </pre></ul>
+ * where
+ * {@code lightColor[i]} is the color of light source i,<br>
+ * {@code L[i]} is the vector from the surface to light source i,<br>
+ * {@code N} is the normal vector (taking into the account the bumpMap if present),<br>
+ * {@code R[i]} is the normalized reflection vector for L[i] about the surface normal,<br>
+ * and {@code V} is the normalized view vector.
+ *
+ * @see AmbientLight
+ * @see PointLight
  * @since JavaFX 8.0
  */
 public class PhongMaterial extends Material {
@@ -52,19 +83,34 @@
     private boolean selfIlluminationMapDirty = true;
 
     /**
-     * Creates a new instance of {@code PhongMaterial} class.
+     * Creates a new instance of {@code PhongMaterial} class with a default
+     * Color.WHITE {@code diffuseColor} property.
      */
     public PhongMaterial() {
-        // TODO: 3D - Need to document this ...
         setDiffuseColor(Color.WHITE);        
     }
 
-    // TODO: 3D - Need to document this ...
+    /**
+     * Creates a new instance of {@code PhongMaterial} class using the specified
+     * color for its {@code diffuseColor} property.
+     *
+     * @param diffuseColor the color of the diffuseColor property 
+     */
     public PhongMaterial(Color diffuseColor) {
         setDiffuseColor(diffuseColor);
     }
 
-    // TODO: 3D - Need to document this ...
+    /**
+     * Creates a new instance of {@code PhongMaterial} class using the specified
+     * colors and images for its {@code diffuseColor} properties.
+     *
+     * @param diffuseColor the color of the diffuseColor property
+     * @param diffuseMap the image of the diffuseMap property
+     * @param specularMap the image of the specularMap property
+     * @param bumpMap the image of the bumpMap property
+     * @param selfIlluminationMap the image of the selfIlluminationMap property
+     * 
+     */
     public PhongMaterial(Color diffuseColor, Image diffuseMap,
             Image specularMap, Image bumpMap, Image selfIlluminationMap) {
         setDiffuseColor(diffuseColor);