001: /*
002: * $RCSfile: ColoringAttributes.java,v $
003: *
004: * Copyright 1997-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:20 $
029: * $State: Exp $
030: */
031:
032: package javax.media.j3d;
033:
034: import javax.vecmath.Color3f;
035:
036: /**
037: * The ColoringAttributes object defines attributes used in
038: * color selection and shading model.
039: *
040: * <p>
041: * <b>Color</b>
042: * <p>
043: * The <code>setColor</code> methods set the current intrinsic red, green, and
044: * blue color values of this ColoringAttributes component object.
045: * This color is only used for unlit geometry. If lighting is enabled,
046: * the material colors are used in the lighting equation to produce
047: * the final color. When vertex colors are present in unlit
048: * geometry, those vertex colors are used in place of this
049: * ColoringAttributes color, unless the vertex colors are ignored.
050: * <p>
051: * There are two variations on the <code>setColor</code> methods, one
052: * that takes a Color3f and one that takes three floats. No alpha
053: * value is allowed (it's automatically set to 1.0). The float values
054: * range between 0.0 and 1.0, with 1.0 being full intensity of the
055: * color. A color value of (1.0, 1.0, 1.0) is white.
056: * <p>
057: * <b>Shading Model</b>
058: * <p>
059: * The <code>setShadeModel</code> method sets the shade model for this
060: * ColoringAttributes component object. The shade model may be one of
061: * the following:<p>
062: * <ul>
063: * <li>FASTEST - use the fastest available method for shading. This
064: * shading mode maps to whatever shading model the Java 3D implementor
065: * defines as the "fastest," which may be hardware-dependent.</li>
066: * <p>
067: * <li>NICEST - use the nicest (highest quality) available method
068: * for shading. This shading mode maps to whatever shading model
069: * the Java 3D implementor defines as the "nicest," shading
070: * model, which may be hardware-dependent.</li>
071: * <p>
072: * <li>SHADE_FLAT - use the flat shading model. This shading model
073: * does not interpolate color across the primitive.
074: * The primitive is drawn with a single color
075: * and the color of one vertex of the primitive is duplicated
076: * across all the vertices of the primitive.</li>
077: * <p>
078: * <li>SHADE_GOURAUD - use the Gouraud (smooth) shading model.
079: * This shading model smoothly interpolates the color at each vertex
080: * across the primitive.
081: * The primitive is drawn with many different colors
082: * and the color at each vertex is treated individually. For lines,
083: * the colors along the line segment are interpolated between
084: * the vertex colors. This is the default shade model if no other
085: * is specified.</li>
086: * <p></ul>
087: *
088: * @see Appearance
089: */
090: public class ColoringAttributes extends NodeComponent {
091: /**
092: * Specifies that this ColoringAttributes object allows
093: * reading its color component information.
094: */
095: public static final int ALLOW_COLOR_READ = CapabilityBits.COLORING_ATTRIBUTES_ALLOW_COLOR_READ;
096:
097: /**
098: * Specifies that this ColoringAttributes object allows
099: * writing its color component information.
100: */
101: public static final int ALLOW_COLOR_WRITE = CapabilityBits.COLORING_ATTRIBUTES_ALLOW_COLOR_WRITE;
102:
103: /**
104: * Specifies that this ColoringAttributes object allows
105: * reading its shade model component information.
106: */
107: public static final int ALLOW_SHADE_MODEL_READ = CapabilityBits.COLORING_ATTRIBUTES_ALLOW_SHADE_MODEL_READ;
108:
109: /**
110: * Specifies that this ColoringAttributes object allows
111: * writing its shade model component information.
112: */
113: public static final int ALLOW_SHADE_MODEL_WRITE = CapabilityBits.COLORING_ATTRIBUTES_ALLOW_SHADE_MODEL_WRITE;
114:
115: /**
116: * Use the fastest available method for shading.
117: */
118: public static final int FASTEST = 0;
119: /**
120: * Use the nicest available method for shading.
121: */
122: public static final int NICEST = 1;
123:
124: /**
125: * Do not interpolate color across the primitive.
126: */
127: public static final int SHADE_FLAT = 2;
128: /**
129: * Smoothly interpolate the color at each vertex across the primitive.
130: */
131: public static final int SHADE_GOURAUD = 3;
132:
133: // Array for setting default read capabilities
134: private static final int[] readCapabilities = { ALLOW_COLOR_READ,
135: ALLOW_SHADE_MODEL_READ };
136:
137: /**
138: * Constructs a ColoringAttributes node with default parameters.
139: * The default values are as follows:
140: * <ul>
141: * color = white (1,1,1)<br>
142: * shade model = SHADE_GOURAUD<br>
143: * </ul>
144: */
145: public ColoringAttributes() {
146: // Just use default attributes
147: // set default read capabilities
148: setDefaultReadCapabilities(readCapabilities);
149: }
150:
151: /**
152: * Construct ColoringAttributes object with specified values.
153: * @param color the intrisic color
154: * @param shadeModel the shade model used; one of FASTEST, NICEST,
155: * SHADE_FLAT, or SHADE_GOURAUD
156: */
157: public ColoringAttributes(Color3f color, int shadeModel) {
158: // set default read capabilities
159: setDefaultReadCapabilities(readCapabilities);
160:
161: ((ColoringAttributesRetained) this .retained).initColor(color);
162: ((ColoringAttributesRetained) this .retained)
163: .initShadeModel(shadeModel);
164:
165: }
166:
167: /**
168: * Construct ColoringAttributes object with specified values.
169: * @param red red component of the intrisic color
170: * @param green green component of the intrisic color
171: * @param blue blue component of the intrisic color
172: * @param shadeModel the shade model used; one of FASTEST, NICEST,
173: * SHADE_FLAT, or SHADE_GOURAUD
174: */
175: public ColoringAttributes(float red, float green, float blue,
176: int shadeModel) {
177: // set default read capabilities
178: setDefaultReadCapabilities(readCapabilities);
179:
180: ((ColoringAttributesRetained) this .retained).initColor(red,
181: green, blue);
182: ((ColoringAttributesRetained) this .retained)
183: .initShadeModel(shadeModel);
184: }
185:
186: /**
187: * Sets the intrinsic color of this ColoringAttributes
188: * component object. This color is only used for unlit geometry;
189: * if lighting is enabled, then the material colors are used in the
190: * lighting equation to produce the final color.
191: * When vertex colors are present in unlit geometry, those
192: * vertex colors are used in place of this ColoringAttributes color
193: * unless the vertex colors are ignored.
194: * @param color the color that is used when lighting is disabled
195: * or when material is null
196: * @exception CapabilityNotSetException if appropriate capability is
197: * not set and this object is part of live or compiled scene graph
198: * @see Material
199: * @see RenderingAttributes#setIgnoreVertexColors
200: */
201: public void setColor(Color3f color) {
202: if (isLiveOrCompiled())
203: if (!this .getCapability(ALLOW_COLOR_WRITE))
204: throw new CapabilityNotSetException(J3dI18N
205: .getString("ColoringAttributes0"));
206:
207: if (isLive())
208: ((ColoringAttributesRetained) this .retained)
209: .setColor(color);
210: else
211: ((ColoringAttributesRetained) this .retained)
212: .initColor(color);
213:
214: }
215:
216: /**
217: * Sets the intrinsic color of this ColoringAttributes
218: * component object. This color is only used for unlit geometry;
219: * if lighting is enabled, then the material colors are used in the
220: * lighting equation to produce the final color.
221: * When vertex colors are present in unlit geometry, those
222: * vertex colors are used in place of this ColoringAttributes color
223: * unless the vertex colors are ignored.
224: * @param r the red component of the color
225: * @param g the green component of the color
226: * @param b the blue component of the color
227: * @exception CapabilityNotSetException if appropriate capability is
228: * not set and this object is part of live or compiled scene graph
229: * @see Material
230: * @see RenderingAttributes#setIgnoreVertexColors
231: */
232: public void setColor(float r, float g, float b) {
233: if (isLiveOrCompiled())
234: if (!this .getCapability(ALLOW_COLOR_WRITE))
235: throw new CapabilityNotSetException(J3dI18N
236: .getString("ColoringAttributes0"));
237:
238: if (isLive())
239: ((ColoringAttributesRetained) this .retained).setColor(r, g,
240: b);
241: else
242: ((ColoringAttributesRetained) this .retained).initColor(r,
243: g, b);
244: }
245:
246: /**
247: * Gets the intrinsic color of this ColoringAttributes
248: * component object.
249: * @param color the vector that will receive color
250: * @exception CapabilityNotSetException if appropriate capability is
251: * not set and this object is part of live or compiled scene graph
252: */
253: public void getColor(Color3f color) {
254: if (isLiveOrCompiled())
255: if (!this .getCapability(ALLOW_COLOR_READ))
256: throw new CapabilityNotSetException(J3dI18N
257: .getString("ColoringAttributes2"));
258:
259: ((ColoringAttributesRetained) this .retained).getColor(color);
260: }
261:
262: /**
263: * Sets the shade mode for this ColoringAttributes component object.
264: * @param shadeModel the shade mode to be used; one of FASTEST,
265: * NICEST, SHADE_FLAT, or SHADE_GOURAUD
266: * @exception CapabilityNotSetException if appropriate capability is
267: * not set and this object is part of live or compiled scene graph
268: */
269: public void setShadeModel(int shadeModel) {
270: if (isLiveOrCompiled())
271: if (!this .getCapability(ALLOW_SHADE_MODEL_WRITE))
272: throw new CapabilityNotSetException(J3dI18N
273: .getString("ColoringAttributes3"));
274:
275: if (isLive())
276: ((ColoringAttributesRetained) this .retained)
277: .setShadeModel(shadeModel);
278: else
279: ((ColoringAttributesRetained) this .retained)
280: .initShadeModel(shadeModel);
281: }
282:
283: /**
284: * Gets the shade mode for this ColoringAttributes component object.
285: * @return shadeModel the shade mode
286: * @exception CapabilityNotSetException if appropriate capability is
287: * not set and this object is part of live or compiled scene graph
288: */
289: public int getShadeModel() {
290: if (isLiveOrCompiled())
291: if (!this .getCapability(ALLOW_SHADE_MODEL_READ))
292: throw new CapabilityNotSetException(J3dI18N
293: .getString("ColoringAttributes4"));
294:
295: return ((ColoringAttributesRetained) this .retained)
296: .getShadeModel();
297: }
298:
299: /**
300: * Creates a retained mode ColoringAttributesRetained object that this
301: * ColoringAttributes component object will point to.
302: */
303: void createRetained() {
304: this .retained = new ColoringAttributesRetained();
305: this .retained.setSource(this );
306: }
307:
308: /**
309: * @deprecated replaced with cloneNodeComponent(boolean forceDuplicate)
310: */
311:
312: public NodeComponent cloneNodeComponent() {
313: ColoringAttributes ca = new ColoringAttributes();
314: ca.duplicateNodeComponent(this );
315: return ca;
316: }
317:
318: /**
319: * Copies all node information from <code>originalNodeComponent</code> into
320: * the current node. This method is called from the
321: * <code>duplicateNode</code> method. This routine does
322: * the actual duplication of all "local data" (any data defined in
323: * this object).
324: *
325: * @param originalNodeComponent the original node to duplicate.
326: * @param forceDuplicate when set to <code>true</code>, causes the
327: * <code>duplicateOnCloneTree</code> flag to be ignored. When
328: * <code>false</code>, the value of each node's
329: * <code>duplicateOnCloneTree</code> variable determines whether
330: * NodeComponent data is duplicated or copied.
331: *
332: * @see Node#cloneTree
333: * @see NodeComponent#setDuplicateOnCloneTree
334: */
335: void duplicateAttributes(NodeComponent originalNodeComponent,
336: boolean forceDuplicate) {
337:
338: super
339: .duplicateAttributes(originalNodeComponent,
340: forceDuplicate);
341:
342: ColoringAttributesRetained attr = (ColoringAttributesRetained) originalNodeComponent.retained;
343:
344: ColoringAttributesRetained rt = (ColoringAttributesRetained) retained;
345: Color3f c = new Color3f();
346: attr.getColor(c);
347:
348: rt.initColor(c);
349: rt.initShadeModel(attr.getShadeModel());
350: }
351:
352: /**
353: * Returns a String representation of this ColoringAttributes object.
354: * If the scene graph is live only those values with their
355: * Capability read bit set will be displayed.
356: */
357: public String toString() {
358: StringBuffer str = new StringBuffer(getNamePrefix());
359: str.append("javax.media.j3d.ColoringAttributes: ");
360: String shadingModes[] = { "FASTEST", "NICEST", "SHADE_FLAT",
361: "SHADE_GOURAUD" };
362:
363: try {
364: Color3f color = new Color3f();
365: getColor(color);
366: str.append("Color=" + color);
367: } catch (CapabilityNotSetException e) {
368: str.append("Color=N/A");
369: }
370:
371: try {
372: str.append(" ShadeModel=" + shadingModes[getShadeModel()]);
373: } catch (CapabilityNotSetException ex) {
374: str.append("ShadeModel=N/A");
375: }
376:
377: return new String(str);
378: }
379:
380: }
|