Updated web pages.

git-svn-id: https://svn.java.net/svn/j3d-core~svn/trunk@144 ba19aa83-45c5-6ac9-afd3-db810772062c

2 files changed, 100 insertions, 54 deletions

diff --git a/www/j3d1_4/proposed-changes.html b/www/j3d1_4/proposed-changes.html
index d8a23a3..c4ef970 100644
--- a/www/j3d1_4/proposed-changes.html
+++ b/www/j3d1_4/proposed-changes.html
@@ -27,17 +27,52 @@ into the 1.4 API.
 for the 1.4. For more information see the <a href="shaders.html">Programmable
 Shaders in Java&nbsp;3D 1.4</a> page.
 </p>
-<h4>2. Another feature...</h4>
-<p>This is another feature...</p>
+<h4>2. Scene graph structure change listeners<br>
+</h4>
+<p>We propose to add a notification mechansim for scene graph structure
+changes: additions, deletions, and
+moves of branch graphs to/from a live scene graph. We propose adding <code>add/removeGraphChangeListener(</code><code>GraphChangeListener</code><code>)</code>
+methods to <code>VirtualUniverse</code> and a new <code>GraphChangeListener</code>
+interface with <code>graphAdded</code>, <code>graphRemoved</code>,
+and <code>graphMoved</code> methods that get called when any branch
+graph is added (attached),
+removed (detached), or moved, respectively.<br>
+</p>
 <h4>3. Miscellaneous features</h4>
 <p>This is a list of miscellaneous features that we propose to add to
 the API.
 </p>
 <ul>
-  <li>Name string added to all scene graph objects. Need public
-get/setName(String) in SceneGraphObject</li>
-  <li>What else...</li>
+  <li>Name string for all scene graph objects: add public <code>get/setName(String)</code>
+to <code>SceneGraphObject</code> class</li>
+  <li><span style="font-style: italic; color: rgb(64, 192, 64);">Anything
+else???</span></li>
 </ul>
+<h4>4. List of features to deprecate</h4>
+<p>This is a list of miscellaneous features that we propose to
+deprecate in
+the API.<br>
+</p>
+<ul>
+  <li>Collision: <code>WakeupOnCollision{Entry,Exit,Movement}</code>
+(misnamed, not useful for most applications)<br>
+  </li>
+  <li><code>CompressedGeometry</code> (no HW support, lack of industry
+acceptance)</li>
+  <li><code>WakeupOnAWTBehavior</code> (listeners + <code>WakeupOnBehaviorPost</code>
+is more robust)</li>
+  <li><code>Sensor</code> prediction (has never been implemented)<br>
+  </li>
+</ul>
+<p>Note that none of these features will actually be removed. It
+instead
+reflects a decrease of emphasis on these features. While they should
+continue
+to function normally, no additional effort is likely to be put into
+them (for example, compressed geometry will not be supported with
+programmable shaders). This action paves the way to remove them from a
+future major release (e.g., a 2.0 release).<br>
+</p>
 <h3>II. Medium Priority Features</h3>
 <p>This list of medium priority features is under discussion for
 possible inclusion
@@ -45,7 +80,8 @@ into the 1.4 API.
 </p>
 <h4>1. Something...<br>
 </h4>
-<p>Something...<br>
+<p><span style="font-style: italic; color: rgb(64, 192, 64);">Something
+goes here (maybe)...</span><br>
 </p>
 <h4>2. Miscellaneous features</h4>
 <p>This is a list of miscellaneous features that are being considered
@@ -53,9 +89,26 @@ for addition to
 the API.<br>
 </p>
 <ul>
-  <li>a</li>
-  <li>b</li>
+  <li>API support for&nbsp; retained alpha buffers</li>
+  <li>Ability to query properties from a GraphicsConfiguration</li>
+  <li><span style="font-style: italic; color: rgb(64, 192, 64);">Anything
+else???</span></li>
 </ul>
+<h4>3. List of features to deprecate</h4>
+<p>This is a list of miscellaneous features that are being considered
+for deprecation in
+the API.<br>
+</p>
+<ul>
+  <li><code>Billboard</code> (use <code>OrientedShape3D</code> instead)<br>
+  </li>
+  <li><code>SharedGroup</code> (many bugs, <em>very</em> difficult to
+implement
+efficiently)</li>
+</ul>
+<p>This is in addition to the API being proposed for deprecation in
+section I.<br>
+</p>
 <h3>III. Future Features</h3>
 <p>Here is an unprioritized list of possible features under
 consideration for a future (e.g., 1.5/2.0)
@@ -64,6 +117,9 @@ version of the Java&nbsp;3D API.
 <ul>
   <li>Extensibility</li>
   <li>Pluggable renderers</li>
+  <li>Retained alpha buffers</li>
+  <li><span style="font-style: italic; color: rgb(64, 192, 64);">Anything
+else???</span></li>
 </ul>
 <p><font color="gray">Page last updated &#8212;
 $Date$
diff --git a/www/j3d1_4/shaders.html b/www/j3d1_4/shaders.html
index cf6c91e..fadfde0 100644
--- a/www/j3d1_4/shaders.html
+++ b/www/j3d1_4/shaders.html
@@ -72,30 +72,21 @@ public abstract class CgShader extends Shader
 <ul>
 <pre>public class ShaderAppearance extends Appearance
     method: set/getShaderProgram(ShaderProgram)
-    method: set/getShaderAttributes(ShaderAttributes)
+    method: set/getShaderAttributeSet(ShaderAttributeSet)
 </pre>
 </ul>
 
-<li>New SystemAttributes class:</li>
+<li>New ShaderAttributeSet class:</li>
 <ul>
-<pre>public class SystemAttributes extends NodeComponent
-    method: put/getAttribute(String,Object)
-    method: putAllAttributes(Map)
-    method: removeAttribute(String)
-    method: clearAttributes()
-    method: getAttributesMap()
-
-    method: put/getSystemAttribute(String,String)
-    method: putAllSystemAttributes(Map)
-    method: removeSystemAttribute(String)
-    method: clearSystemAttributes()
-    method: getSystemAttributesMap()
+<pre>public class ShaderAttributeSet extends NodeComponent
+    method: put/get(ShaderAttribute)
+    ...
 </pre>
 </ul>
 
 </ul>
 
-<p>Click on the following link for a preliminary look at the <a
+<p>Click on the following link for a current look at the <a
 href="http://javadesktop.org/java3d/javadoc/1.4.0-latest/index.html">javadoc-generated
 API definitions</a> for the proposed 1.4 API.
 </p>
@@ -111,8 +102,8 @@ String vertexShaderSource;
 String fragmentShaderSource;
 
 // Read GLSL vertex and fragment shader source code from text files
-vertexShaderSource = TextFileUtils.readFully(vertexShaderFile);
-fragmentShaderSource = TextFileUtils.readFully(fragmentShaderSource);
+vertexShaderSource = StringIO.readFully(vertexShaderFile);
+fragmentShaderSource = StringIO.readFully(fragmentShaderSource);
 
 // Create GLSL vertex and fragment shader objects using the given source code
 GLSLVertexShader vertexShader = new GLSLVertexShader(vertexShaderSource);
@@ -131,12 +122,6 @@ shaderAppearance.setShaderProgram(shaderProgram);
 </ul>
 <h4>Shader Parameters</h4>
 
-<p>NOTE: This section is under construction. For the most up to date
-API definition, please see the javadoc for the new <a
-href="http://javadesktop.org/java3d/javadoc/1.4.0-latest/javax/media/j3d/ShaderAttributes.html">ShaderAttributes</a>
-class.
-</p>
-
 <p>Programmable shaders define two types of parameters: uniform and
 varying. As the names imply, uniform parameters are constant (within a
 primitive), while varying parameters can vary on per-vertex or
@@ -152,29 +137,31 @@ vertex (for vertex shaders) or fragment (for fragment shaders) of a
 single primitive. Examples of uniform parameters include a
 transformation matrix, a texture map, lights, lookup tables,
 etc.<br>
-
-
 <br>
-We have created a new ShaderAttributes object with following new attributes:
-
-<ul>
-    <li>Attributes Map, expressed as (attrName,value) pairs, for
-    explicitly defined attributes</li>
 
-    <li>SystemAttributes Map, expressed as (attrName,j3dAttrName) pairs,
-    for implicitly defined attributes</li>
-</ul>
-
-See the javadoc for the new <a
-href="http://javadesktop.org/java3d/javadoc/1.4.0-latest/javax/media/j3d/ShaderAttributes.html">ShaderAttributes</a>
-class for more details.
+We have created a new ShaderAttributeSet for allowing applications to
+specify uniform shader attributes. There are two ways in which values
+can be specified for uniform attributes: explicitly, by providing a
+value; and implicitly, by defining a binding between a Java 3D system
+attribute and a uniform attribute. This functionality is provided by
+two subclasses of ShaderAttribute: ShaderAttributeObject, which is
+used to specify explicitly defined attributes; and
+ShaderAttributeBinding, which is used to specify implicitly defined,
+automatically tracked attributes. See the javadoc for the new <a
+href="http://javadesktop.org/java3d/javadoc/1.4.0-latest/javax/media/j3d/ShaderAttributeSet.html">ShaderAttributeSet</a>
+and <a
+href="http://javadesktop.org/java3d/javadoc/1.4.0-latest/javax/media/j3d/ShaderAttribute.html">ShaderAttribute</a>
+classes for more details.<br>
+<br>
 
 <b>Issues</b><br>
 
 <ul>
 
 <li>Should j3dAttrName be specified as a type-safe enum or object
-instead of a String?</li>
+instead of a String?
+    <ul><font color="gray"><li>No; we will use a String</li></font>
+</ul></li>
 
 <li>How do we handle passing arrays to the shader, especially for
 system parameters such as lights? One possibility is:
@@ -185,23 +172,26 @@ system parameters such as lights? One possibility is:
    "arr[1,3]"  - subarray composed of elements 1 through 3 of "arr"<br>
    "arr[]"     - entire array "arr"<br>
 </ul>
-
 Alternatively, an object with a string or type-safe enum, a state
 (scalar, array element, subarray, or entire array), and indices (as
 needed).
-</li>
+    <ul><font color="gray"><li>TBD, but since they will be String objects, we will probably
+do something like the first suggestion</li></font>
+</ul></li>
 </ul>
 
 <br>
 <b>Automatic variables</b><br>
-Several Java&nbsp;3D state attributes are automatically available
-to the shader program as pre-defined uniform parameters. The
-application doesn't need to do anything to pass these parameters in to
-the shader program. The implementation of each shader language (e.g.,
-Cg, GLSL) defines its own mapping from Java&nbsp;3D attribute to uniform
-variable name.<br>
 
+Depending on the shading language (and profile) being used, several
+Java&nbsp;3D state attributes are automatically made available to the
+shader program as pre-defined uniform attributes. The application
+doesn't need to do anything to pass these attributes in to the shader
+program. The implementation of each shader language (e.g., Cg, GLSL)
+defines its own mapping from Java&nbsp;3D attribute to uniform
+variable name.<br>
 <br>
+
 A partial list of Java&nbsp;3D attributes that are mapped to shader
 attributes follows:
 </li>