Fixed issue 379: Needs NPOT support documented in Texture, Texture3D and TextureCubeMap

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

4 files changed, 110 insertions, 46 deletions

diff --git a/src/classes/share/javax/media/j3d/Texture.java b/src/classes/share/javax/media/j3d/Texture.java
index 2ac1fce..effc1c0 100644
--- a/src/classes/share/javax/media/j3d/Texture.java
+++ b/src/classes/share/javax/media/j3d/Texture.java
@@ -216,6 +216,13 @@ import java.util.Hashtable;
  * greater than or equal to 4. </LI><P>
  * </UL>
  *
+ * <p>
+ * Note that as of Java 3D 1.5, the texture width and height are no longer
+ * required to be an exact power of two. However, not all graphics devices
+ * supports non-power-of-two textures. If non-power-of-two texture mapping is
+ * unsupported on a particular Canvas3D, textures with a width or height that
+ * are not an exact power of two are ignored for that canvas.
+ *
  * @see Canvas3D#queryProperties
  */
 public abstract class Texture extends NodeComponent {
@@ -596,15 +603,18 @@ public abstract class Texture extends NodeComponent {
      * <code>setImages</code> method). If <code>mipMapMode</code> is
      * set to <code>MULTI_LEVEL_MIPMAP</code>, then images for levels
      * Base Level through Maximum Level must be set. 
+     * Note that a texture with a non-power-of-two width or height will
+     * only be rendered on a graphics device that supports non-power-of-two
+     * textures.
      *
      * @param mipMapMode type of mipmap for this Texture: one of
      * BASE_LEVEL, MULTI_LEVEL_MIPMAP
      * @param format data format of Textures saved in this object.
      * One of INTENSITY, LUMINANCE, ALPHA, LUMINANCE_ALPHA, RGB, RGBA
-     * @param width width of image at level 0. Must be power of 2.
-     * @param height height of image at level 0. Must be power of 2.
-     * @exception IllegalArgumentException if width or height are not a
-     * power of 2, or if an invalid format or mipMapMode is specified.
+     * @param width width of image at level 0.
+     * @param height height of image at level 0.
+     * @exception IllegalArgumentException if width or height are not greater
+     * than 0, or if an invalid format or mipMapMode is specified.
      */
     public Texture(int		mipMapMode,
 		   int		format,
@@ -661,18 +671,21 @@ public abstract class Texture extends NodeComponent {
      * <code>setImages</code> method). If <code>mipMapMode</code> is
      * set to <code>MULTI_LEVEL_MIPMAP</code>, then images for levels
      * Base Level through Maximum Level must be set. 
+     * Note that a texture with a non-power-of-two width or height will
+     * only be rendered on a graphics device that supports non-power-of-two
+     * textures.
      *
      * @param mipMapMode type of mipmap for this Texture: one of
      * BASE_LEVEL, MULTI_LEVEL_MIPMAP
      * @param format data format of Textures saved in this object.
      * One of INTENSITY, LUMINANCE, ALPHA, LUMINANCE_ALPHA, RGB, RGBA
-     * @param width width of image at level 0. Must be power of 2. This
+     * @param width width of image at level 0. This
      * does not include the width of the boundary.
-     * @param height height of image at level 0. Must be power of 2. This
+     * @param height height of image at level 0. This
      * does not include the width of the boundary.
      * @param boundaryWidth width of the boundary, which must be 0 or 1.
-     * @exception IllegalArgumentException if width or height are not a
-     * power of 2, if an invalid format or mipMapMode is specified, or
+     * @exception IllegalArgumentException if width or height are not greater
+     * than 0, if an invalid format or mipMapMode is specified, or
      * if the boundaryWidth is &lt; 0 or &gt; 1
      *
      * @since Java 3D 1.3
diff --git a/src/classes/share/javax/media/j3d/Texture2D.java b/src/classes/share/javax/media/j3d/Texture2D.java
index ca20be6..f2e4450 100644
--- a/src/classes/share/javax/media/j3d/Texture2D.java
+++ b/src/classes/share/javax/media/j3d/Texture2D.java
@@ -19,6 +19,14 @@ import javax.vecmath.*;
  * Texture2D is a subclass of Texture class. It extends Texture
  * class by adding a constructor and a mutator method for
  * setting a 2D texture image.
+ * <p>
+ * Note that as of Java 3D 1.5, the texture width and height are no longer
+ * required to be an exact power of two. However, not all graphics devices
+ * supports non-power-of-two textures. If non-power-of-two texture mapping is
+ * unsupported on a particular Canvas3D, textures with a width or height that
+ * are not an exact power of two are ignored for that canvas.
+ *
+ * @see Canvas3D#queryProperties
  */
 public class Texture2D extends Texture {
 
@@ -119,26 +127,30 @@ public class Texture2D extends Texture {
 
     }
 
-  /**
-   * Constructs an empty Texture2D object with specified mipmapMode
-   * format, width and height. Image at base level must be set by 
-   * the application using 'setImage' method. If mipmapMode is
-   * set to MULTI_LEVEL_MIPMAP, images for base level through maximum level
-   * must be set.
-   * @param mipMapMode type of mipmap for this Texture: One of
-   * BASE_LEVEL, MULTI_LEVEL_MIPMAP.
-   * @param format data format of Textures saved in this object.
-   * One of INTENSITY, LUMINANCE, ALPHA, LUMINANCE_ALPHA, RGB, RGBA.
-   * @param width width of image at level 0. Must be greater than 0
-   * @param height height of image at level 0. Must be greater than 0
-   * @exception IllegalArgumentException if width or height are NOT
-   * greater than 0 OR invalid format/mipmapMode is specified.
-   */
+    /**
+     * Constructs an empty Texture2D object with specified mipmapMode
+     * format, width and height. Image at base level must be set by
+     * the application using 'setImage' method. If mipmapMode is
+     * set to MULTI_LEVEL_MIPMAP, images for base level through maximum level
+     * must be set.
+     * Note that a texture with a non-power-of-two width or height will
+     * only be rendered on a graphics device that supports non-power-of-two
+     * textures.
+     *
+     * @param mipMapMode type of mipmap for this Texture: One of
+     * BASE_LEVEL, MULTI_LEVEL_MIPMAP.
+     * @param format data format of Textures saved in this object.
+     * One of INTENSITY, LUMINANCE, ALPHA, LUMINANCE_ALPHA, RGB, RGBA.
+     * @param width width of image at level 0.
+     * @param height height of image at level 0.
+     * @exception IllegalArgumentException if width or height are NOT
+     * greater than 0 OR invalid format/mipmapMode is specified.
+     */
     public Texture2D(
-	    int		mipMapMode,
-	    int		format,
-	    int		width,
-	    int		height){
+            int		mipMapMode,
+            int		format,
+            int		width,
+            int		height) {
 
 	super(mipMapMode, format, width, height);
 
@@ -157,14 +169,17 @@ public class Texture2D extends Texture {
      * <code>setImages</code> method). If <code>mipMapMode</code> is
      * set to <code>MULTI_LEVEL_MIPMAP</code>, then images for levels
      * Base Level through Maximum Level must be set.
+     * Note that a texture with a non-power-of-two width or height will
+     * only be rendered on a graphics device that supports non-power-of-two
+     * textures.
      *
      * @param mipMapMode type of mipmap for this Texture: one of
      * BASE_LEVEL, MULTI_LEVEL_MIPMAP
      * @param format data format of Textures saved in this object.
      * One of INTENSITY, LUMINANCE, ALPHA, LUMINANCE_ALPHA, RGB, RGBA
-     * @param width width of image at level 0. Must be greater than 0. This
+     * @param width width of image at level 0. This
      * does not include the width of the boundary.
-     * @param height height of image at level 0. Must be greater than 0. This
+     * @param height height of image at level 0. This
      * does not include the width of the boundary.
      * @param boundaryWidth width of the boundary, which must be 0 or 1.
      * @exception IllegalArgumentException if width or height are not greater
diff --git a/src/classes/share/javax/media/j3d/Texture3D.java b/src/classes/share/javax/media/j3d/Texture3D.java
index 024a2d8..b9ea1ff 100644
--- a/src/classes/share/javax/media/j3d/Texture3D.java
+++ b/src/classes/share/javax/media/j3d/Texture3D.java
@@ -19,6 +19,14 @@ package javax.media.j3d;
  * If 3D texture mapping is not supported on a particular Canvas3D,
  * 3D texture mapping is ignored for that canvas.
  *
+ * <p>
+ * Note that as of Java 3D 1.5, the texture width, height, and depth
+ * are no longer
+ * required to be an exact power of two. However, not all graphics devices
+ * supports non-power-of-two textures. If non-power-of-two texture mapping is
+ * unsupported on a particular Canvas3D, textures with a width, height,
+ * or depth that are not an exact power of two are ignored for that canvas.
+ *
  * @see Canvas3D#queryProperties
  */
 
@@ -47,15 +55,19 @@ public class Texture3D extends Texture {
      * the application using 'setImage' method. If mipmapMode is
      * set to MULTI_LEVEL_MIPMAP, images for base level through
      * maximum level must be set.
+     * Note that a texture with a non-power-of-two width, height, or depth will
+     * only be rendered on a graphics device that supports non-power-of-two
+     * textures.
+     *
      * @param mipmapMode type of mipmap for this Texture: One of
      * BASE_LEVEL, MULTI_LEVEL_MIPMAP.
      * @param format data format of Textures saved in this object.
      * One of INTENSITY, LUMINANCE, ALPHA, LUMINANCE_ALPHA, RGB, RGBA.
-     * @param width width of image at level 0. Must be power of 2.
-     * @param height height of image at level 0. Must be power of 2.
-     * @param depth depth of image at level 0. Must be power of 2.
-     * @exception IllegalArgumentException if width or height are NOT
-     * power of 2 OR invalid format/mipmapMode is specified.
+     * @param width width of image at level 0.
+     * @param height height of image at level 0.
+     * @param depth depth of image at level 0.
+     * @exception IllegalArgumentException if width, height, or depth are not
+     * greater than 0 OR invalid format/mipmapMode is specified.
      */
     public Texture3D(int	mipmapMode,
 		     int	format,
@@ -88,16 +100,23 @@ public class Texture3D extends Texture {
      * the application using 'setImage' method. If mipmapMode is
      * set to MULTI_LEVEL_MIPMAP, images for base level through
      * maximum level must be set.
+     * Note that a texture with a non-power-of-two width, height, or depth will
+     * only be rendered on a graphics device that supports non-power-of-two
+     * textures.
+     *
      * @param mipmapMode type of mipmap for this Texture: One of
      * BASE_LEVEL, MULTI_LEVEL_MIPMAP.
      * @param format data format of Textures saved in this object.
      * One of INTENSITY, LUMINANCE, ALPHA, LUMINANCE_ALPHA, RGB, RGBA.
-     * @param width width of image at level 0. Must be power of 2.
-     * @param height height of image at level 0. Must be power of 2.
-     * @param depth depth of image at level 0. Must be power of 2.
+     * @param width width of image at level 0. This
+     * does not include the width of the boundary.
+     * @param height height of image at level 0. This
+     * does not include the width of the boundary.
+     * @param depth depth of image at level 0. This
+     * does not include the width of the boundary.
      * @param boundaryWidth width of the boundary, which must be 0 or 1.
-     * @exception IllegalArgumentException if width or height are NOT
-     * power of 2 OR invalid format/mipmapMode is specified, or
+     * @exception IllegalArgumentException if width, height, or depth are not
+     * greater than 0 OR invalid format/mipmapMode is specified, or
      * if the boundaryWidth is &lt; 0 or &gt; 1
      *
      * @since Java 3D 1.3
diff --git a/src/classes/share/javax/media/j3d/TextureCubeMap.java b/src/classes/share/javax/media/j3d/TextureCubeMap.java
index f3facec..97b6548 100644
--- a/src/classes/share/javax/media/j3d/TextureCubeMap.java
+++ b/src/classes/share/javax/media/j3d/TextureCubeMap.java
@@ -39,8 +39,16 @@ import javax.vecmath.*;
  * <LI>NEGATIVE_Z</LI>
  * </UL> 
  *
- * @since Java 3D 1.3
+ * <p>
+ * Note that as of Java 3D 1.5, the texture width and height are no longer
+ * required to be an exact power of two. However, not all graphics devices
+ * supports non-power-of-two textures. If non-power-of-two texture mapping is
+ * unsupported on a particular Canvas3D, textures with a width or height that
+ * are not an exact power of two are ignored for that canvas.
+ *
  * @see Canvas3D#queryProperties
+ *
+ * @since Java 3D 1.3
  */
 public class TextureCubeMap extends Texture {
 
@@ -95,13 +103,17 @@ public class TextureCubeMap extends Texture {
      * must be set.
      * Note that cube map is square in dimensions, hence specifying width 
      * is sufficient.
+     * Note also that a texture with a non-power-of-two width will
+     * only be rendered on a graphics device that supports non-power-of-two
+     * textures.
+     *
      * @param mipmapMode type of mipmap for this Texture: One of
      * BASE_LEVEL, MULTI_LEVEL_MIPMAP.
      * @param format data format of Textures saved in this object.
      * One of INTENSITY, LUMINANCE, ALPHA, LUMINANCE_ALPHA, RGB, RGBA.
-     * @param width width of image at level 0. Must be power of 2.
-     * @exception IllegalArgumentException if width is NOT
-     * power of 2 OR invalid format/mipmapMode is specified.
+     * @param width width (and height) of image at level 0.
+     * @exception IllegalArgumentException if width is not greater
+     * than 0 OR invalid format/mipmapMode is specified.
      */
     public TextureCubeMap(
         int     mipmapMode,
@@ -120,15 +132,20 @@ public class TextureCubeMap extends Texture {
      * must be set.
      * Note that cube map is square in dimensions, hence specifying width 
      * is sufficient.
+     * Note also that a texture with a non-power-of-two width will
+     * only be rendered on a graphics device that supports non-power-of-two
+     * textures.
+     *
      * @param mipmapMode type of mipmap for this Texture: One of
      * BASE_LEVEL, MULTI_LEVEL_MIPMAP.
      * @param format data format of Textures saved in this object.
      * One of INTENSITY, LUMINANCE, ALPHA, LUMINANCE_ALPHA, RGB, RGBA.
-     * @param width width of image at level 0. Must be power of 2.
+     * @param width width (and height) of image at level 0. This
+     * does not include the width of the boundary.
      * @param boundaryWidth width of the boundary, which must be 0 or 1.
      *
-     * @exception IllegalArgumentException if width is NOT
-     * power of 2 OR invalid format/mipmapMode is specified.
+     * @exception IllegalArgumentException if width is not
+     * greater than 0 OR invalid format/mipmapMode is specified.
      */
     public TextureCubeMap(
         int     mipmapMode,