001: /*
002: * $RCSfile: ShaderAttributeSet.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.6 $
028: * $Date: 2008/02/28 20:17:29 $
029: * $State: Exp $
030: */
031:
032: package javax.media.j3d;
033:
034: import java.util.Iterator;
035: import java.util.Map;
036: import java.util.HashMap;
037: import javax.vecmath.*;
038:
039: /**
040: * The ShaderAttributeSet object provides uniform attributes to shader
041: * programs. Uniform attributes (variables) are those attributes whose
042: * values are constant during the rendering of a primitive. Their
043: * values may change from primitive to primitive, but are constant for
044: * each vertex (for vertex shaders) or fragment (for fragment shaders)
045: * of a single primitive. Examples of uniform attributes include a
046: * transformation matrix, a texture map, lights, lookup tables, etc.
047: * The ShaderAttributeSet object contains a set of ShaderAttribute
048: * objects. Each ShaderAttribute object defines the value of a single
049: * uniform shader variable. The set of attributes is unique with respect
050: * to attribute names: no two attributes in the set will have the same
051: * name.
052: *
053: * <p>
054: * There are two ways in which values can be specified for uniform
055: * attributes: explicitly, by providing a value; and implicitly, by
056: * defining a binding between a Java 3D system attribute and a uniform
057: * attribute. This functionality is provided by two subclasses of
058: * ShaderAttribute: ShaderAttributeObject, which is used to specify
059: * explicitly defined attributes; and ShaderAttributeBinding, which is
060: * used to specify implicitly defined, automatically tracked attributes.
061: *
062: * <p>
063: * Depending on the shading language (and profile) being used, several
064: * Java 3D state attributes are automatically made available to the
065: * shader program as pre-defined uniform attributes. The application
066: * doesn't need to do anything to pass these attributes in to the
067: * shader program. The implementation of each shader language (e.g.,
068: * Cg, GLSL) defines its own bindings from Java 3D attribute to uniform
069: * variable name. A list of these attributes for each shader language
070: * can be found in the concrete subclass of ShaderProgram for that
071: * shader language.
072: *
073: * @see ShaderAttribute
074: * @see ShaderProgram
075: * @see ShaderAppearance#setShaderAttributeSet
076: *
077: * @since Java 3D 1.4
078: */
079:
080: public class ShaderAttributeSet extends NodeComponent {
081:
082: /**
083: * Specifies that this ShaderAttributeSet object allows reading
084: * its attributes.
085: */
086: public static final int ALLOW_ATTRIBUTES_READ = CapabilityBits.SHADER_ATTRIBUTE_SET_ALLOW_ATTRIBUTES_READ;
087:
088: /**
089: * Specifies that this ShaderAttributeSet object allows writing
090: * its attributes.
091: */
092: public static final int ALLOW_ATTRIBUTES_WRITE = CapabilityBits.SHADER_ATTRIBUTE_SET_ALLOW_ATTRIBUTES_WRITE;
093:
094: // Array for setting default read capabilities
095: private static final int[] readCapabilities = { ALLOW_ATTRIBUTES_READ };
096:
097: /**
098: * Constructs an empty ShaderAttributeSet object. The attributes set
099: * is initially empty.
100: */
101: public ShaderAttributeSet() {
102: // set default read capabilities
103: setDefaultReadCapabilities(readCapabilities);
104: }
105:
106: //
107: // Methods for dealing with the (name, value) pairs for explicit
108: // attributes
109: //
110:
111: /**
112: * Adds the specified shader attribute to the attributes set.
113: * The newly specified attribute replaces an attribute with the
114: * same name, if one already exists in the attributes set.
115: *
116: * @param attr the shader attribute to be added to the set
117: *
118: * @exception NullPointerException if attr is null
119: *
120: * @exception CapabilityNotSetException if appropriate capability is
121: * not set and this object is part of live or compiled scene graph
122: */
123: public void put(ShaderAttribute attr) {
124: if (attr == null) {
125: throw new NullPointerException();
126: }
127:
128: if (isLiveOrCompiled())
129: if (!this .getCapability(ALLOW_ATTRIBUTES_WRITE))
130: throw new CapabilityNotSetException(J3dI18N
131: .getString("ShaderAttributeSet1"));
132:
133: ((ShaderAttributeSetRetained) this .retained).put(attr);
134:
135: }
136:
137: /**
138: * Retrieves the shader attribute with the specified
139: * <code>attrName</code> from the attributes set. If attrName does
140: * not exist in the attributes set, null is returned.
141: *
142: * @param attrName the name of the shader attribute to be retrieved
143: *
144: * @exception NullPointerException if attrName is null
145: *
146: * @return a the shader attribute associated with the specified
147: * attribute name, or null if the name is not in the attributes
148: * set
149: *
150: * @exception CapabilityNotSetException if appropriate capability is
151: * not set and this object is part of live or compiled scene graph
152: */
153: public ShaderAttribute get(String attrName) {
154:
155: if (attrName == null) {
156: throw new NullPointerException();
157: }
158:
159: if (isLiveOrCompiled())
160: if (!this .getCapability(ALLOW_ATTRIBUTES_READ))
161: throw new CapabilityNotSetException(J3dI18N
162: .getString("ShaderAttributeSet0"));
163:
164: return ((ShaderAttributeSetRetained) this .retained)
165: .get(attrName);
166: }
167:
168: /**
169: * Removes the shader attribute with the specified
170: * <code>attrName</code> from the attributes set. If attrName does
171: * not exist in the attributes set then nothing happens.
172: *
173: * @param attrName the name of the shader attribute to be removed
174: *
175: * @exception NullPointerException if attrName is null
176: *
177: * @exception CapabilityNotSetException if appropriate capability is
178: * not set and this object is part of live or compiled scene graph
179: */
180: public void remove(String attrName) {
181: if (attrName == null) {
182: throw new NullPointerException();
183: }
184:
185: if (isLiveOrCompiled())
186: if (!this .getCapability(ALLOW_ATTRIBUTES_WRITE))
187: throw new CapabilityNotSetException(J3dI18N
188: .getString("ShaderAttributeSet1"));
189:
190: ((ShaderAttributeSetRetained) this .retained).remove(attrName);
191: }
192:
193: /**
194: * Removes the specified shader attribute from the attributes
195: * set. If the attribute does not exist in the attributes set then
196: * nothing happens. Note that this method will <i>not</i> remove a
197: * shader object other than the one specified, even if it has the
198: * same name as the specified attribute. Applications that wish to
199: * remove an attribute by name should use
200: * <code>removeAttribute(String)</code>.
201: *
202: * @param attr the shader attribute to be removed
203: *
204: * @exception NullPointerException if attr is null
205: *
206: * @exception CapabilityNotSetException if appropriate capability is
207: * not set and this object is part of live or compiled scene graph
208: */
209: public void remove(ShaderAttribute attr) {
210: if (attr == null) {
211: throw new NullPointerException();
212: }
213:
214: if (isLiveOrCompiled())
215: if (!this .getCapability(ALLOW_ATTRIBUTES_WRITE))
216: throw new CapabilityNotSetException(J3dI18N
217: .getString("ShaderAttributeSet1"));
218:
219: ((ShaderAttributeSetRetained) this .retained).remove(attr);
220: }
221:
222: /**
223: * Removes all shader attributes from the attributes set. The
224: * attributes set will be empty following this call.
225: *
226: * @exception CapabilityNotSetException if appropriate capability is
227: * not set and this object is part of live or compiled scene graph
228: */
229: public void clear() {
230:
231: if (isLiveOrCompiled())
232: if (!this .getCapability(ALLOW_ATTRIBUTES_WRITE))
233: throw new CapabilityNotSetException(J3dI18N
234: .getString("ShaderAttributeSet1"));
235:
236: ((ShaderAttributeSetRetained) this .retained).clear();
237: }
238:
239: /**
240: * Returns a shallow copy of the attributes set.
241: *
242: * @return a shallow copy of the attributes set
243: *
244: * @exception CapabilityNotSetException if appropriate capability is
245: * not set and this object is part of live or compiled scene graph
246: */
247: public ShaderAttribute[] getAll() {
248:
249: if (isLiveOrCompiled())
250: if (!this .getCapability(ALLOW_ATTRIBUTES_READ))
251: throw new CapabilityNotSetException(J3dI18N
252: .getString("ShaderAttributeSet0"));
253:
254: return ((ShaderAttributeSetRetained) this .retained).getAll();
255: }
256:
257: /**
258: * Returns the number of elements in the attributes set.
259: *
260: * @return the number of elements in the attributes set
261: *
262: * @exception CapabilityNotSetException if appropriate capability is
263: * not set and this object is part of live or compiled scene graph
264: */
265: public int size() {
266:
267: if (isLiveOrCompiled())
268: if (!this .getCapability(ALLOW_ATTRIBUTES_READ))
269: throw new CapabilityNotSetException(J3dI18N
270: .getString("ShaderAttributeSet0"));
271:
272: return ((ShaderAttributeSetRetained) this .retained).size();
273: }
274:
275: /**
276: * Creates a retained mode ShaderAttributeSetRetained object that this
277: * ShaderAttributeSet component object will point to.
278: */
279: void createRetained() {
280: // System.err.println("ShaderAttributeSet : createRetained() ...");
281: this .retained = new ShaderAttributeSetRetained();
282: this.retained.setSource(this);
283: }
284: }
|