001: /*
002: * $RCSfile: ShaderAttributeObject.java,v $
003: *
004: * Copyright 2005-2008 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
006: *
007: * This code is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU General Public License version 2 only, as
009: * published by the Free Software Foundation. Sun designates this
010: * particular file as subject to the "Classpath" exception as provided
011: * by Sun in the LICENSE file that accompanied this code.
012: *
013: * This code is distributed in the hope that it will be useful, but WITHOUT
014: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
015: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
016: * version 2 for more details (a copy is included in the LICENSE file that
017: * accompanied this code).
018: *
019: * You should have received a copy of the GNU General Public License version
020: * 2 along with this work; if not, write to the Free Software Foundation,
021: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
022: *
023: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
024: * CA 95054 USA or visit www.sun.com if you need additional information or
025: * have any questions.
026: *
027: * $Revision: 1.5 $
028: * $Date: 2008/02/28 20:17:29 $
029: * $State: Exp $
030: */
031:
032: package javax.media.j3d;
033:
034: import javax.vecmath.*;
035:
036: /**
037: * The ShaderAttributeObject class is an abstract class that
038: * encapsulates a uniform shader attribute whose value is specified
039: * explicitly. This class has concrete subclasses for single-value
040: * attributes (ShaderAttributeValue) and array attributes
041: * (ShaderAttributeArray). The shader variable <code>attrName</code>
042: * is explicitly set to the specified <code>value</code> during
043: * rendering. <code>attrName</code> must be the name of a valid
044: * uniform attribute in the shader in which it is used. Otherwise, the
045: * attribute name will be ignored and a runtime error may be
046: * generated. The <code>value</code> must be an instance of one of the
047: * allowed classes or an array of one the allowed classes. The allowed
048: * classes are: <code>Integer</code>, <code>Float</code>,
049: * <code>Tuple{2,3,4}{i,f}</code>,
050: * <code>Matrix{3,4}f</code>. A ClassCastException will be thrown
051: * if a specified <code>value</code> object is not one of the allowed
052: * types. Further, the type of the value is immutable once a
053: * ShaderAttributeObject is constructed. Subsequent setValue
054: * operations must be called with an object of the same type as the
055: * one that was used to construct the ShaderAttributeObject. Finally,
056: * the type of the <code>value</code> object must match the type of
057: * the corresponding <code>attrName</code> variable in the shader in
058: * which it is used. Otherwise, the shader will not be able to use the
059: * attribute and a runtime error may be generated.
060: *
061: * @see ShaderAttributeSet
062: * @see ShaderProgram
063: *
064: * @since Java 3D 1.4
065: */
066:
067: public abstract class ShaderAttributeObject extends ShaderAttribute {
068:
069: /**
070: * Specifies that this ShaderAttributeObject allows reading its value.
071: */
072: public static final int ALLOW_VALUE_READ = CapabilityBits.SHADER_ATTRIBUTE_OBJECT_ALLOW_VALUE_READ;
073:
074: /**
075: * Specifies that this ShaderAttributeObject allows writing its value.
076: */
077: public static final int ALLOW_VALUE_WRITE = CapabilityBits.SHADER_ATTRIBUTE_OBJECT_ALLOW_VALUE_WRITE;
078:
079: // Array for setting default read capabilities
080: private static final int[] readCapabilities = { ALLOW_VALUE_READ };
081:
082: /**
083: * Package scope constructor
084: */
085: ShaderAttributeObject(String attrName, Object value) {
086: super (attrName);
087:
088: // set default read capabilities
089: setDefaultReadCapabilities(readCapabilities);
090:
091: ((ShaderAttributeObjectRetained) this .retained)
092: .createObjectData(value);
093: }
094:
095: /**
096: * Retrieves the value of this shader attribute.
097: * A copy of the object is returned.
098: *
099: * @return a copy of the value of this shader attribute
100: *
101: * @exception CapabilityNotSetException if appropriate capability is
102: * not set and this object is part of live or compiled scene graph
103: */
104: public abstract Object getValue();
105:
106: /**
107: * Sets the value of this shader attribute to the specified value.
108: * A copy of the object is stored.
109: *
110: * @param value the new value of the shader attribute
111: *
112: * @exception NullPointerException if value is null
113: *
114: * @exception ClassCastException if value is not an instance of
115: * the same base class as the object used to construct this shader
116: * attribute object.
117: *
118: * @exception CapabilityNotSetException if appropriate capability is
119: * not set and this object is part of live or compiled scene graph
120: */
121: public abstract void setValue(Object value);
122:
123: /**
124: * Retrieves the base class of the value of this shader attribute.
125: * This class will always be one of the allowable classes, even if
126: * a subclass was used to construct this shader attribute object.
127: * For example, if this shader attribute object was constructed
128: * with an instance of <code>javax.vecmath.Point3f</code>, the
129: * returned class would be <code>javax.vecmath.Tuple3f</code>.
130: *
131: * @return the base class of the value of this shader attribute
132: *
133: * @exception CapabilityNotSetException if appropriate capability is
134: * not set and this object is part of live or compiled scene graph
135: */
136: public Class getValueClass() {
137:
138: return ((ShaderAttributeObjectRetained) this.retained)
139: .getValueClass();
140: }
141:
142: }
|