j3dcore: flatten the directory structure a bit

Signed-off-by: Harvey Harrison <[email protected]>

1 files changed, 434 insertions, 0 deletions

diff --git a/src/javax/media/j3d/ImageComponent.java b/src/javax/media/j3d/ImageComponent.java
new file mode 100644
index 0000000..85d7aa4
--- /dev/null
+++ b/src/javax/media/j3d/ImageComponent.java
@@ -0,0 +1,434 @@
+/*
+ * Copyright 1996-2008 Sun Microsystems, Inc.  All Rights Reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Sun designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Sun in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+ * CA 95054 USA or visit www.sun.com if you need additional information or
+ * have any questions.
+ *
+ */
+
+package javax.media.j3d;
+
+/**
+ * Abstract class that is used to define 2D or 3D ImageComponent
+ * classes used in a Java 3D scene graph.  This is used for texture
+ * images, background images and raster components of Shape3D nodes.
+ *
+ * <p>
+ * Image data may be passed to this ImageComponent object in
+ * one of two ways: by copying the image data into this object or by
+ * accessing the image data by reference.
+ *
+ * <p>
+ * <ul>
+ * <li>
+ * <b>By Copying:</b>
+ * By default, the set and get image methods copy the image
+ * data into or out of this ImageComponent object.  This is
+ * appropriate for many applications, since the application may reuse
+ * the RenderedImage object after copying it to the ImageComponent.
+ * </li>
+ * <li><b>By Reference:</b>
+ * A new feature in Java 3D version 1.2 allows image data to
+ * be accessed by reference, directly from the RenderedImage object.
+ * To use this feature, you need to construct an ImageComponent object
+ * with the <code>byReference</code> flag set to <code>true</code>.
+ * In this mode, a reference to the input data is saved, but the data
+ * itself is not necessarily copied (although it may be, depending on
+ * the value of the <code>yUp</code> flag, the format of the
+ * ImageComponent, and the format of the RenderedImage).  Image data
+ * referenced by an ImageComponent object can only be modified via
+ * the updateData method.
+ * Applications must exercise care not to violate this rule.  If any
+ * referenced RenderedImage is modified outside the updateData method
+ * after it has been passed
+ * to an ImageComponent object, the results are undefined.
+ * Another restriction in by-reference mode is that if the specified
+ * RenderedImage is not an instance of BufferedImage, then
+ * this ImageComponent cannot be used for readRaster or
+ * off-screen rendering operations, since these operations modify
+ * the ImageComponent data.
+ * </li>
+ * </ul>
+ *
+ * <p>
+ * An image component object also specifies whether the orientation of
+ * its image data is "y-up" or "y-down" (the default).  Y-up mode
+ * causes images to be interpreted as having their origin at the lower
+ * left (rather than the default upper left) of a texture or raster
+ * image with successive scan lines moving up.  This is more
+ * consistent with texture mapping data onto a surface, and maps
+ * directly into the the way textures are used in OpenGL and other 3D
+ * APIs.  Setting the <code>yUp</code> flag to true in conjunction
+ * with setting the <code>byReference</code> flag to true makes it
+ * possible for Java 3D to avoid copying the texture map in some
+ * cases.
+ *
+ * <p>
+ * Note that all color fields are treated as unsigned values, even though
+ * Java does not directly support unsigned variables.  This means, for
+ * example, that an ImageComponent using a format of FORMAT_RGB5 can
+ * represent red, green, and blue values between 0 and 31, while an
+ * ImageComponent using a format of FORMAT_RGB8 can represent color
+ * values between 0 and 255.  Even when byte values are used to create a
+ * RenderedImage with 8-bit color components, the resulting colors
+ * (bytes) are interpreted as if they were unsigned.
+ * Values greater than 127 can be assigned to a byte variable using a
+ * type cast.  For example:
+ * <ul>byteVariable = (byte) intValue; // intValue can be > 127</ul>
+ * If intValue is greater than 127, then byteVariable will be negative.  The
+ * correct value will be extracted when it is used (by masking off the upper
+ * bits).
+ */
+
+public abstract class ImageComponent extends NodeComponent {
+    //
+    // Pixel format values
+    //
+
+  /**
+   * Specifies that each pixel contains 3 8-bit channels: one each
+   * for red, green, blue. Same as FORMAT_RGB8.
+   */
+    public static final int FORMAT_RGB = 1;
+
+  /**
+   * Specifies that each pixel contains 4 8-bit channels: one each
+   * for red, green, blue, alpha. Same as FORMAT_RGBA8.
+   */
+    public static final int FORMAT_RGBA = 2;
+
+  /**
+   * Specifies that each pixel contains 3 8-bit channels: one each
+   * for red, green, blue. Same as FORMAT_RGB.
+   */
+    public static final int FORMAT_RGB8 = FORMAT_RGB;
+
+  /**
+   * Specifies that each pixel contains 4 8-bit channels: one each
+   * for red, green, blue, alpha. Same as FORMAT_RGBA.
+   */
+    public static final int FORMAT_RGBA8 = FORMAT_RGBA;
+
+  /**
+   * Specifies that each pixel contains 3 5-bit channels: one each
+   * for red, green, blue.
+   */
+    public static final int FORMAT_RGB5 = 3;
+
+  /**
+   * Specifies that each pixel contains 3 5-bit channels: one each
+   * for red, green, blue and 1 1-bit channel for alpha.
+   */
+    public static final int FORMAT_RGB5_A1 = 4;
+
+  /**
+   * Specifies that each pixel contains 3 4-bit channels: one each
+   * for red, green, blue.
+   */
+    public static final int FORMAT_RGB4 = 5;
+
+  /**
+   * Specifies that each pixel contains 4 4-bit channels: one each
+   * for red, green, blue, alpha.
+   */
+    public static final int FORMAT_RGBA4 = 6;
+
+  /**
+   * Specifies that each pixel contains 2 4-bit channels: one each
+   * for luminance and alpha.
+   */
+    public static final int FORMAT_LUM4_ALPHA4 = 7;
+
+  /**
+   * Specifies that each pixel contains 2 8-bit channels: one each
+   * for luminance and alpha.
+   */
+    public static final int FORMAT_LUM8_ALPHA8 = 8;
+
+  /**
+   * Specifies that each pixel contains 2 3-bit channels: one each
+   * for red, green, and 1 2-bit channel for blue.
+   */
+    public static final int FORMAT_R3_G3_B2 = 9;
+
+  /**
+   * Specifies that each pixel contains 1 8-bit channel: it can be
+   * used for only luminance or only alpha or only intensity.
+   */
+    public static final int FORMAT_CHANNEL8 = 10;
+
+    // Internal variable for checking validity of formats
+    // Change this if any more formats are added or removed
+    static final int FORMAT_TOTAL = 10;
+
+
+    /**
+     * Used to specify the class of the image being wrapped.
+     *
+     * @since Java 3D 1.5
+     */
+    public enum ImageClass {
+        /**
+         * Indicates that this ImageComponent object wraps a BufferedImage
+         * object. This is the default state. Note that the image class will
+         * be BUFFERED_IMAGE following a call to set(RenderedImage image)
+         * if we are in by-copy mode, or if the image is an instance of
+         * BufferedImage.
+         */
+        BUFFERED_IMAGE,
+
+        /**
+         * Indicates that this ImageComponent object wraps a RenderedImage
+         * object that is <i>not</i> a BufferedImage. Note that the image class
+         * of an ImageComponent following a call to set(RenderedImage image)
+         * will be RENDERED_IMAGE, if and only if the image is not an instance
+         * of BufferedImage and the ImageComponent is in by-reference mode.
+         */
+        RENDERED_IMAGE,
+
+        /**
+         * Indicates that this ImageComponent object wraps an NioImageBuffer
+         * object. Note that an ImageComponent in this state must not be used
+         * as the off-screen buffer of a Canvas3D nor as the target of a
+         * readRaster operation.
+         */
+        NIO_IMAGE_BUFFER,
+    }
+
+
+    /**
+     * Specifies that this ImageComponent object allows reading its
+     * size component information (width, height, and depth).
+     */
+    public static final int
+    ALLOW_SIZE_READ = CapabilityBits.IMAGE_COMPONENT_ALLOW_SIZE_READ;
+
+    /**
+     * Specifies that this ImageComponent object allows reading its
+     * format component information.
+     */
+    public static final int
+    ALLOW_FORMAT_READ = CapabilityBits.IMAGE_COMPONENT_ALLOW_FORMAT_READ;
+
+    /**
+     * Specifies that this ImageComponent object allows reading its
+     * image component information.
+     */
+    public static final int
+    ALLOW_IMAGE_READ = CapabilityBits.IMAGE_COMPONENT_ALLOW_IMAGE_READ;
+
+    /**
+     * Specifies that this ImageComponent object allows writing its
+     * image component information.
+     *
+     * @since Java 3D 1.3
+     */
+    public static final int
+    ALLOW_IMAGE_WRITE = CapabilityBits.IMAGE_COMPONENT_ALLOW_IMAGE_WRITE;
+
+   // Array for setting default read capabilities
+    private static final int[] readCapabilities = {
+        ALLOW_SIZE_READ,
+        ALLOW_IMAGE_READ,
+        ALLOW_FORMAT_READ
+    };
+
+    /**
+     * Not a public constructor, for internal use
+     */
+    ImageComponent() {
+        // set default read capabilities
+        setDefaultReadCapabilities(readCapabilities);
+    }
+
+    /**
+     * Constructs an image component object using the specified format, width,
+     * and height.  Default values are used for all other parameters.  The
+     * default values are as follows:
+     * <ul>
+     * byReference : false<br>
+     * yUp : false<br>
+     * </ul>
+     *
+     * @param format the image component format, one of: FORMAT_RGB,
+     * FORMAT_RGBA etc.
+     * @param width the number of columns of pixels in this image component
+     * object
+     * @param height the number of rows of pixels in this image component
+     * object
+     * @exception IllegalArgumentException if format is invalid, or if
+     * width or height are not positive.
+     */
+    public ImageComponent(int format, int width, int height) {
+        // set default read capabilities
+        setDefaultReadCapabilities(readCapabilities);
+
+        ((ImageComponentRetained)this.retained).processParams(format, width, height, 1);
+    }
+
+    /**
+     * Constructs an image component object using the specified format, width,
+     * height, byReference flag, and yUp flag.
+     *
+     * @param format the image component format, one of: FORMAT_RGB,
+     * FORMAT_RGBA etc.
+     * @param width the number of columns of pixels in this image component
+     * object
+     * @param height the number of rows of pixels in this image component
+     * object
+     * @param byReference a flag that indicates whether the data is copied
+     * into this image component object or is accessed by reference.
+     * @param yUp a flag that indicates the y-orientation of this image
+     * component.  If yUp is set to true, the origin of the image is
+     * the lower left; otherwise, the origin of the image is the upper
+     * left.
+     * @exception IllegalArgumentException if format is invalid, or if
+     * width or height are not positive.
+     *
+     * @since Java 3D 1.2
+     */
+    public ImageComponent(int format,
+			  int width,
+			  int height,
+			  boolean byReference,
+			  boolean yUp) {
+        // set default read capabilities
+        setDefaultReadCapabilities(readCapabilities);
+
+ 	((ImageComponentRetained)this.retained).setYUp(yUp);
+ 	((ImageComponentRetained)this.retained).setByReference(byReference);
+ 	((ImageComponentRetained)this.retained).processParams(format, width, height, 1);
+    }
+
+    /**
+     * Retrieves the width of this image component object.
+     * @return the width of this image component object
+     * @exception CapabilityNotSetException if appropriate capability is
+     * not set and this object is part of live or compiled scene graph
+     */
+    public int getWidth() {
+        if (isLiveOrCompiled())
+            if(!this.getCapability(ALLOW_SIZE_READ))
+              throw new CapabilityNotSetException(J3dI18N.getString("ImageComponent0"));
+        return ((ImageComponentRetained)this.retained).getWidth();
+    }
+
+    /**
+     * Retrieves the height of this image component object.
+     * @return the height of this image component object
+     * @exception CapabilityNotSetException if appropriate capability is
+     * not set and this object is part of live or compiled scene graph
+     */
+    public int getHeight() {
+        if (isLiveOrCompiled())
+            if(!this.getCapability(ALLOW_SIZE_READ))
+              throw new CapabilityNotSetException(J3dI18N.getString("ImageComponent1"));
+        return ((ImageComponentRetained)this.retained).getHeight();
+    }
+
+    /**
+     * Retrieves the format of this image component object.
+     * @return the format of this image component object
+     * @exception CapabilityNotSetException if appropriate capability is
+     * not set and this object is part of live or compiled scene graph
+     */
+    public int getFormat() {
+        if (isLiveOrCompiled())
+            if(!this.getCapability(ALLOW_FORMAT_READ))
+              throw new CapabilityNotSetException(J3dI18N.getString("ImageComponent2"));
+        return ((ImageComponentRetained)this.retained).getFormat();
+    }
+
+
+    /**
+     * Retrieves the data access mode for this ImageComponent object.
+     *
+     * @return <code>true</code> if the data access mode for this
+     * ImageComponent object is by-reference;
+     * <code>false</code> if the data access mode is by-copying.
+     *
+     * @since Java 3D 1.2
+     */
+    public boolean isByReference() {
+        return ((ImageComponentRetained)this.retained).isByReference();
+    }
+
+
+    /**
+     * Sets the y-orientation of this ImageComponent object to
+     * y-up or y-down.
+     *
+     * @param yUp a flag that indicates the y-orientation of this image
+     * component.  If yUp is set to true, the origin of the image is
+     * the lower left; otherwise, the origin of the image is the upper
+     * left.
+     *
+     * @exception RestrictedAccessException if the method is called
+     * when this object is part of live or compiled scene graph.
+     *
+     * @exception IllegalStateException if the image class of this object
+     * is ImageClass.NIO_IMAGE_BUFFER.
+     *
+     * @deprecated as of Java 3D 1.5, the yUp flag should only be set at object
+     * construction time.
+     *
+     * @since Java 3D 1.2
+     */
+    public void setYUp(boolean yUp) {
+	checkForLiveOrCompiled();
+
+        // check for illegal image class
+        if (((ImageComponentRetained)this.retained).getImageClass() == ImageClass.NIO_IMAGE_BUFFER) {
+            throw new IllegalStateException("ImageComponent4");
+        }
+
+        ((ImageComponentRetained)this.retained).setYUp(yUp);
+    }
+
+
+    /**
+     * Retrieves the y-orientation for this ImageComponent object.
+     *
+     * @return <code>true</code> if the y-orientation of this
+     * ImageComponent object is y-up; <code>false</code> if the
+     * y-orientation of this ImageComponent object is y-down.
+     *
+     * @since Java 3D 1.2
+     */
+    public boolean isYUp() {
+        return ((ImageComponentRetained)this.retained).isYUp();
+    }
+
+
+    /**
+     * Retrieves the image class of this ImageComponent object.
+     *
+     * @return the image class of this ImageComponent,
+     * one of: ImageClass.BUFFERED_IMAGE,
+     * ImageClass.RENDERED_IMAGE, or ImageClass.NIO_IMAGE_BUFFER.
+     *
+     * @since Java 3D 1.5
+     */
+    public ImageClass getImageClass() {
+        return ((ImageComponentRetained)this.retained).getImageClass();
+    }
+
+}