001: /*
002: * $RCSfile: TextureUnitState.java,v $
003: *
004: * Copyright 1999-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.7 $
028: * $Date: 2008/02/28 20:17:32 $
029: * $State: Exp $
030: */
031:
032: package javax.media.j3d;
033:
034: import java.util.Hashtable;
035:
036: /**
037: * The TextureUnitState object defines all texture mapping state for a
038: * single texture unit. An appearance object contains an array of
039: * texture unit state objects to define the state for multiple texture
040: * mapping units. The texture unit state consists of the
041: * following:
042: *
043: * <p>
044: * <ul>
045: * <li>Texture - defines the texture image and filtering
046: * parameters used when texture mapping is enabled. These attributes
047: * are defined in a Texture object.</li><p>
048: *
049: * <li>Texture attributes - defines the attributes that apply to
050: * texture mapping, such as the texture mode, texture transform,
051: * blend color, and perspective correction mode. These attributes
052: * are defined in a TextureAttributes object.</li><p>
053: *
054: * <li>Texture coordinate generation - defines the attributes
055: * that apply to texture coordinate generation, such as whether
056: * texture coordinate generation is enabled, coordinate format
057: * (2D or 3D coordinates), coordinate generation mode (object
058: * linear, eye linear, or spherical reflection mapping), and the
059: * R, S, and T coordinate plane equations. These attributes
060: * are defined in a TexCoordGeneration object.</li><p>
061: * </ul>
062: *
063: * @see Appearance
064: * @see Texture
065: * @see TextureAttributes
066: * @see TexCoordGeneration
067: *
068: * @since Java 3D 1.2
069: */
070: public class TextureUnitState extends NodeComponent {
071:
072: /**
073: * Specifies that this TextureUnitState object allows reading its
074: * texture, texture attribute, or texture coordinate generation
075: * component information.
076: */
077: public static final int ALLOW_STATE_READ = CapabilityBits.TEXTURE_UNIT_STATE_ALLOW_STATE_READ;
078:
079: /**
080: * Specifies that this TextureUnitState object allows writing its
081: * texture, texture attribute, or texture coordinate generation
082: * component information.
083: */
084: public static final int ALLOW_STATE_WRITE = CapabilityBits.TEXTURE_UNIT_STATE_ALLOW_STATE_WRITE;
085:
086: // Array for setting default read capabilities
087: private static final int[] readCapabilities = { ALLOW_STATE_READ };
088:
089: /**
090: * Constructs a TextureUnitState component object using defaults for all
091: * state variables. All component object references are initialized
092: * to null.
093: */
094: public TextureUnitState() {
095: // Just use default values
096: // set default read capabilities
097: setDefaultReadCapabilities(readCapabilities);
098: }
099:
100: /**
101: * Constructs a TextureUnitState component object using the specified
102: * component objects.
103: *
104: * @param texture object that specifies the desired texture
105: * map and texture parameters
106: * @param textureAttributes object that specifies the desired
107: * texture attributes
108: * @param texCoordGeneration object that specifies the texture coordinate
109: * generation parameters
110: */
111: public TextureUnitState(Texture texture,
112: TextureAttributes textureAttributes,
113: TexCoordGeneration texCoordGeneration) {
114: // set default read capabilities
115: setDefaultReadCapabilities(readCapabilities);
116:
117: ((TextureUnitStateRetained) this .retained).initTexture(texture);
118: ((TextureUnitStateRetained) this .retained)
119: .initTextureAttributes(textureAttributes);
120: ((TextureUnitStateRetained) this .retained)
121: .initTexCoordGeneration(texCoordGeneration);
122: }
123:
124: /**
125: * Creates the retained mode TextureUnitStateRetained object that this
126: * TextureUnitState component object will point to.
127: */
128: void createRetained() {
129: this .retained = new TextureUnitStateRetained();
130: this .retained.setSource(this );
131: }
132:
133: /**
134: * Sets the texture, texture attributes, and texture coordinate
135: * generation components in this TextureUnitState object to the
136: * specified component objects.
137: *
138: * @param texture object that specifies the desired texture
139: * map and texture parameters
140: * @param textureAttributes object that specifies the desired
141: * texture attributes
142: * @param texCoordGeneration object that specifies the texture coordinate
143: * generation parameters
144: *
145: * @exception IllegalSharingException if this TextureUnitState is live and
146: * the specified texture refers to an ImageComponent2D that is being used
147: * by a Canvas3D as an off-screen buffer.
148: *
149: * @exception IllegalSharingException if this TextureUnitState is
150: * being used by an immediate mode context and
151: * the specified texture refers to an ImageComponent2D that is being used
152: * by a Canvas3D as an off-screen buffer.
153: */
154: public void set(Texture texture,
155: TextureAttributes textureAttributes,
156: TexCoordGeneration texCoordGeneration) {
157:
158: if (isLiveOrCompiled())
159: if (!this .getCapability(ALLOW_STATE_WRITE))
160: throw new CapabilityNotSetException(J3dI18N
161: .getString("TextureUnitState0"));
162:
163: // Do illegal sharing check
164: if (texture != null) {
165: TextureRetained texRetained = (TextureRetained) texture.retained;
166: ImageComponent[] images = texRetained.getImages();
167: if (images != null) {
168: for (int i = 0; i < images.length; i++) {
169: validateImageIllegalSharing(images[i]);
170: }
171: }
172: }
173:
174: ((TextureUnitStateRetained) this .retained).setTextureUnitState(
175: texture, textureAttributes, texCoordGeneration);
176: }
177:
178: /**
179: * Sets the texture object to the specified object.
180: * Setting it to null disables texture mapping for the
181: * texture unit corresponding to this TextureUnitState object.
182: *
183: * @param texture object that specifies the desired texture
184: * map and texture parameters
185: *
186: * @exception CapabilityNotSetException if appropriate capability is
187: * not set and this object is part of live or compiled scene graph
188: *
189: * @exception IllegalSharingException if this TextureUnitState is live and
190: * the specified texture refers to an ImageComponent2D that is being used
191: * by a Canvas3D as an off-screen buffer.
192: *
193: * @exception IllegalSharingException if this TextureUnitState is
194: * being used by an immediate mode context and
195: * the specified texture refers to an ImageComponent2D that is being used
196: * by a Canvas3D as an off-screen buffer.
197: */
198: public void setTexture(Texture texture) {
199: if (isLiveOrCompiled())
200: if (!this .getCapability(ALLOW_STATE_WRITE))
201: throw new CapabilityNotSetException(J3dI18N
202: .getString("TextureUnitState0"));
203:
204: // Do illegal sharing check
205: if (texture != null) {
206: TextureRetained texRetained = (TextureRetained) texture.retained;
207: ImageComponent[] images = texRetained.getImages();
208: if (images != null) {
209: for (int i = 0; i < images.length; i++) {
210: validateImageIllegalSharing(images[i]);
211: }
212: }
213: }
214:
215: ((TextureUnitStateRetained) this .retained).setTexture(texture);
216: }
217:
218: /**
219: * Retrieves the current texture object.
220: * @return the texture object
221: * @exception CapabilityNotSetException if appropriate capability is
222: * not set and this object is part of live or compiled scene graph
223: */
224: public Texture getTexture() {
225: if (isLiveOrCompiled())
226: if (!this .getCapability(ALLOW_STATE_READ))
227: throw new CapabilityNotSetException(J3dI18N
228: .getString("TextureUnitState1"));
229:
230: return ((TextureUnitStateRetained) this .retained).getTexture();
231: }
232:
233: /**
234: * Sets the textureAttributes object to the specified object.
235: * Setting it to null will result in default attribute usage for the.
236: * texture unit corresponding to this TextureUnitState object.
237: * @param textureAttributes object that specifies the desired
238: * texture attributes
239: * @exception CapabilityNotSetException if appropriate capability is
240: * not set and this object is part of live or compiled scene graph
241: */
242: public void setTextureAttributes(TextureAttributes textureAttributes) {
243: if (isLiveOrCompiled())
244: if (!this .getCapability(ALLOW_STATE_WRITE))
245: throw new CapabilityNotSetException(J3dI18N
246: .getString("TextureUnitState2"));
247:
248: ((TextureUnitStateRetained) this .retained)
249: .setTextureAttributes(textureAttributes);
250: }
251:
252: /**
253: * Retrieves the current textureAttributes object.
254: * @return the textureAttributes object
255: * @exception CapabilityNotSetException if appropriate capability is
256: * not set and this object is part of live or compiled scene graph
257: */
258: public TextureAttributes getTextureAttributes() {
259: if (isLiveOrCompiled())
260: if (!this .getCapability(ALLOW_STATE_READ))
261: throw new CapabilityNotSetException(J3dI18N
262: .getString("TextureUnitState3"));
263:
264: return ((TextureUnitStateRetained) this .retained)
265: .getTextureAttributes();
266: }
267:
268: /**
269: * Sets the texCoordGeneration object to the specified object.
270: * Setting it to null disables texture coordinate generation for the
271: * texture unit corresponding to this TextureUnitState object.
272: * @param texCoordGeneration object that specifies the texture coordinate
273: * generation parameters
274: * @exception CapabilityNotSetException if appropriate capability is
275: * not set and this object is part of live or compiled scene graph
276: */
277: public void setTexCoordGeneration(
278: TexCoordGeneration texCoordGeneration) {
279: if (isLiveOrCompiled())
280: if (!this .getCapability(ALLOW_STATE_WRITE))
281: throw new CapabilityNotSetException(J3dI18N
282: .getString("TextureUnitState4"));
283:
284: ((TextureUnitStateRetained) this .retained)
285: .setTexCoordGeneration(texCoordGeneration);
286: }
287:
288: /**
289: * Retrieves the current texCoordGeneration object.
290: * @return the texCoordGeneration object
291: * @exception CapabilityNotSetException if appropriate capability is
292: * not set and this object is part of live or compiled scene graph
293: */
294: public TexCoordGeneration getTexCoordGeneration() {
295: if (isLiveOrCompiled())
296: if (!this .getCapability(ALLOW_STATE_READ))
297: throw new CapabilityNotSetException(J3dI18N
298: .getString("TextureUnitState5"));
299:
300: return ((TextureUnitStateRetained) this .retained)
301: .getTexCoordGeneration();
302: }
303:
304: /**
305: * @deprecated replaced with cloneNodeComponent(boolean forceDuplicate)
306: */
307: public NodeComponent cloneNodeComponent() {
308: TextureUnitState ts = new TextureUnitState();
309: ts.duplicateNodeComponent(this );
310: return ts;
311: }
312:
313: /**
314: * NOTE: Applications should <i>not</i> call this method directly.
315: * It should only be called by the cloneNode method.
316: *
317: * @deprecated replaced with duplicateNodeComponent(
318: * NodeComponent originalNodeComponent, boolean forceDuplicate)
319: */
320: public void duplicateNodeComponent(
321: NodeComponent originalNodeComponent) {
322: checkDuplicateNodeComponent(originalNodeComponent);
323: }
324:
325: /**
326: * Copies all TextureUnitState information from
327: * <code>originalNodeComponent</code> into
328: * the current node. This method is called from the
329: * <code>cloneNode</code> method which is, in turn, called by the
330: * <code>cloneTree</code> method.<P>
331: *
332: * @param originalNodeComponent the original node to duplicate.
333: * @param forceDuplicate when set to <code>true</code>, causes the
334: * <code>duplicateOnCloneTree</code> flag to be ignored. When
335: * <code>false</code>, the value of each node's
336: * <code>duplicateOnCloneTree</code> variable determines whether
337: * NodeComponent data is duplicated or copied.
338: *
339: * @exception RestrictedAccessException if this object is part of a live
340: * or compiled scenegraph.
341: *
342: * @see Node#cloneTree
343: * @see NodeComponent#setDuplicateOnCloneTree
344: */
345: void duplicateAttributes(NodeComponent originalNodeComponent,
346: boolean forceDuplicate) {
347: super
348: .duplicateAttributes(originalNodeComponent,
349: forceDuplicate);
350:
351: Hashtable hashtable = originalNodeComponent.nodeHashtable;
352:
353: TextureUnitStateRetained app = (TextureUnitStateRetained) originalNodeComponent.retained;
354:
355: TextureUnitStateRetained rt = (TextureUnitStateRetained) retained;
356:
357: rt.setTexture((Texture) getNodeComponent(app.getTexture(),
358: forceDuplicate, hashtable));
359:
360: rt.setTextureAttributes((TextureAttributes) getNodeComponent(
361: app.getTextureAttributes(), forceDuplicate, hashtable));
362:
363: rt
364: .setTexCoordGeneration((TexCoordGeneration) getNodeComponent(
365: app.getTexCoordGeneration(), forceDuplicate,
366: hashtable));
367: }
368:
369: /**
370: * This function is called from getNodeComponent() to see if any of
371: * the sub-NodeComponents duplicateOnCloneTree flag is true.
372: * If it is the case, current NodeComponent needs to
373: * duplicate also even though current duplicateOnCloneTree flag is false.
374: * This should be overwrite by NodeComponent which contains sub-NodeComponent.
375: */
376: boolean duplicateChild() {
377: if (getDuplicateOnCloneTree())
378: return true;
379:
380: TextureUnitStateRetained rt = (TextureUnitStateRetained) retained;
381:
382: NodeComponent nc = rt.getTexture();
383: if ((nc != null) && nc.duplicateChild())
384: return true;
385:
386: nc = rt.getTextureAttributes();
387: if ((nc != null) && nc.getDuplicateOnCloneTree())
388: return true;
389:
390: nc = rt.getTexCoordGeneration();
391: if ((nc != null) && nc.getDuplicateOnCloneTree())
392: return true;
393:
394: return false;
395: }
396: }
|