001: /*
002: * $RCSfile: PolygonAttributes.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:28 $
029: * $State: Exp $
030: */
031:
032: package javax.media.j3d;
033:
034: /**
035: * The PolygonAttributes object defines attributes for rendering polygon
036: * primitives.
037: * Polygon primitives include triangles, triangle strips, triangle fans,
038: * and quads.
039: * The polygon attributes that can be defined are:</li>
040: * <p><ul>
041: * <li>Rasterization mode - defines how the polygon is drawn: as points,
042: * outlines, or filled.<p>
043: * <ul>
044: * <li>POLYGON_POINT - the polygon is rendered as points
045: * drawn at the vertices.</li><p>
046: * <li>POLYGON_LINE - the polygon is rendered as lines
047: * drawn between consecutive vertices.</li><p>
048: * <li>POLYGON_FILL - the polygon is rendered by filling the interior
049: * between the vertices. The default mode.</li>
050: * <p></ul>
051: * <li>Face culling - defines which polygons are culled (discarded)
052: * before they are converted to screen coordinates.<p>
053: * <ul>
054: * <li>CULL_NONE - disables face culling.</li>
055: * <li>CULL_BACK - culls all back-facing polygons. The default.</li>
056: * <li>CULL_FRONT - culls all front-facing polygons.</li>
057: * <p></ul>
058: * <li>Back-face normal flip - specifies whether vertex normals of
059: * back-facing polygons are flipped (negated) prior to lighting. The
060: * setting is either true, meaning to flip back-facing normals, or
061: * false. The default is false.</li>
062: * <p>
063: * <li>Offset - the depth values of all pixels generated by polygon
064: * rasterization can be offset by a value that is computed for that
065: * polygon. Two values are used to specify the offset:</li><p>
066: * <ul>
067: * <li>Offset bias - the constant polygon offset that is added to
068: * the final device coordinate Z value of polygon primitives.</li>
069: * <p>
070: * <li>Offset factor - the factor to be multiplied by the
071: * slope of the polygon and then added to the final, device coordinate
072: * Z value of the polygon primitives.</li><p>
073: * </ul>
074: * These values can be either positive or negative. The default
075: * for both of these values is 0.0.<p>
076: * </ul>
077: *
078: * @see Appearance
079: */
080: public class PolygonAttributes extends NodeComponent {
081:
082: /**
083: * Specifies that this PolygonAttributes object allows reading its
084: * cull face information.
085: */
086: public static final int ALLOW_CULL_FACE_READ = CapabilityBits.POLYGON_ATTRIBUTES_ALLOW_CULL_FACE_READ;
087:
088: /**
089: * Specifies that this PolygonAttributes object allows writing its
090: * cull face information.
091: */
092: public static final int ALLOW_CULL_FACE_WRITE = CapabilityBits.POLYGON_ATTRIBUTES_ALLOW_CULL_FACE_WRITE;
093:
094: /**
095: * Specifies that this PolygonAttributes object allows reading its
096: * back face normal flip flag.
097: */
098: public static final int ALLOW_NORMAL_FLIP_READ = CapabilityBits.POLYGON_ATTRIBUTES_ALLOW_NORMAL_FLIP_READ;
099:
100: /**
101: * Specifies that this PolygonAttributes object allows writing its
102: * back face normal flip flag.
103: */
104: public static final int ALLOW_NORMAL_FLIP_WRITE = CapabilityBits.POLYGON_ATTRIBUTES_ALLOW_NORMAL_FLIP_WRITE;
105:
106: /**
107: * Specifies that this PolygonAttributes object allows reading its
108: * polygon mode information.
109: */
110: public static final int ALLOW_MODE_READ = CapabilityBits.POLYGON_ATTRIBUTES_ALLOW_MODE_READ;
111:
112: /**
113: * Specifies that this PolygonAttributes object allows writing its
114: * polygon mode information.
115: */
116: public static final int ALLOW_MODE_WRITE = CapabilityBits.POLYGON_ATTRIBUTES_ALLOW_MODE_WRITE;
117:
118: /**
119: * Specifies that this PolygonAttributes object allows reading its
120: * polygon offset information.
121: */
122: public static final int ALLOW_OFFSET_READ = CapabilityBits.POLYGON_ATTRIBUTES_ALLOW_OFFSET_READ;
123:
124: /**
125: * Specifies that this PolygonAttributes object allows writing its
126: * polygon offset information.
127: */
128: public static final int ALLOW_OFFSET_WRITE = CapabilityBits.POLYGON_ATTRIBUTES_ALLOW_OFFSET_WRITE;
129:
130: // Polygon rasterization modes
131: /**
132: * Render polygonal primitives as points drawn at the vertices
133: * of the polygon.
134: */
135: public static final int POLYGON_POINT = 0;
136: /**
137: * Render polygonal primitives as lines drawn between consecutive
138: * vertices of the polygon.
139: */
140: public static final int POLYGON_LINE = 1;
141: /**
142: * Render polygonal primitives by filling the interior of the polygon.
143: */
144: public static final int POLYGON_FILL = 2;
145:
146: /**
147: * Don't perform any face culling.
148: */
149: public static final int CULL_NONE = 0;
150: /**
151: * Cull all back-facing polygons. This is the default mode.
152: */
153: public static final int CULL_BACK = 1;
154: /**
155: * Cull all front-facing polygons.
156: */
157: public static final int CULL_FRONT = 2;
158:
159: // Array for setting default read capabilities
160: private static final int[] readCapabilities = {
161: ALLOW_CULL_FACE_READ, ALLOW_MODE_READ,
162: ALLOW_NORMAL_FLIP_READ, ALLOW_OFFSET_READ };
163:
164: /**
165: * Constructs a PolygonAttributes object with default parameters.
166: * The default values are as follows:
167: * <ul>
168: * cull face : CULL_BACK<br>
169: * back face normal flip : false<br>
170: * polygon mode : POLYGON_FILL<br>
171: * polygon offset : 0.0<br>
172: * polygon offset factor : 0.0<br>
173: * </ul>
174: */
175: public PolygonAttributes() {
176: // Just use defaults for all attributes
177: // set default read capabilities
178: setDefaultReadCapabilities(readCapabilities);
179: }
180:
181: /**
182: * Constructs a PolygonAttributes object with specified values.
183: * @param polygonMode polygon rasterization mode; one of POLYGON_POINT,
184: * POLYGON_LINE, or POLYGON_FILL
185: * @param cullFace polygon culling mode; one of CULL_NONE,
186: * CULL_BACK, or CULL_FRONT
187: * @param polygonOffset constant polygon offset
188: */
189: public PolygonAttributes(int polygonMode, int cullFace,
190: float polygonOffset) {
191: this (polygonMode, cullFace, polygonOffset, false, 0.0f);
192: }
193:
194: /**
195: * Constructs PolygonAttributes object with specified values.
196: * @param polygonMode polygon rasterization mode; one of POLYGON_POINT,
197: * POLYGON_LINE, or POLYGON_FILL
198: * @param cullFace polygon culling mode; one of CULL_NONE,
199: * CULL_BACK, or CULL_FRONT
200: * @param polygonOffset constant polygon offset
201: * @param backFaceNormalFlip back face normal flip flag; true or false
202: */
203: public PolygonAttributes(int polygonMode, int cullFace,
204: float polygonOffset, boolean backFaceNormalFlip) {
205: this (polygonMode, cullFace, polygonOffset, backFaceNormalFlip,
206: 0.0f);
207: }
208:
209: /**
210: * Constructs PolygonAttributes object with specified values.
211: * @param polygonMode polygon rasterization mode; one of POLYGON_POINT,
212: * POLYGON_LINE, or POLYGON_FILL
213: * @param cullFace polygon culling mode; one of CULL_NONE,
214: * CULL_BACK, or CULL_FRONT
215: * @param polygonOffset constant polygon offset
216: * @param backFaceNormalFlip back face normal flip flag; true or false
217: * @param polygonOffsetFactor polygon offset factor for slope-based polygon
218: * offset
219: *
220: * @since Java 3D 1.2
221: */
222: public PolygonAttributes(int polygonMode, int cullFace,
223: float polygonOffset, boolean backFaceNormalFlip,
224: float polygonOffsetFactor) {
225:
226: if (polygonMode < POLYGON_POINT || polygonMode > POLYGON_FILL)
227: throw new IllegalArgumentException(J3dI18N
228: .getString("PolygonAttributes0"));
229:
230: if (cullFace < CULL_NONE || cullFace > CULL_FRONT)
231: throw new IllegalArgumentException(J3dI18N
232: .getString("PolygonAttributes12"));
233:
234: // set default read capabilities
235: setDefaultReadCapabilities(readCapabilities);
236:
237: ((PolygonAttributesRetained) this .retained)
238: .initPolygonMode(polygonMode);
239: ((PolygonAttributesRetained) this .retained)
240: .initCullFace(cullFace);
241: ((PolygonAttributesRetained) this .retained)
242: .initPolygonOffset(polygonOffset);
243: ((PolygonAttributesRetained) this .retained)
244: .initBackFaceNormalFlip(backFaceNormalFlip);
245: ((PolygonAttributesRetained) this .retained)
246: .initPolygonOffsetFactor(polygonOffsetFactor);
247: }
248:
249: /**
250: * Sets the face culling for this
251: * appearance component object.
252: * @param cullFace the face to be culled, one of:
253: * CULL_NONE, CULL_FRONT, or CULL_BACK
254: * @exception CapabilityNotSetException if appropriate capability is
255: * not set and this object is part of live or compiled scene graph
256: */
257: public void setCullFace(int cullFace) {
258: if (isLiveOrCompiled())
259: if (!this .getCapability(ALLOW_CULL_FACE_WRITE))
260: throw new CapabilityNotSetException(J3dI18N
261: .getString("PolygonAttributes2"));
262:
263: if (cullFace < CULL_NONE || cullFace > CULL_FRONT)
264: throw new IllegalArgumentException(J3dI18N
265: .getString("PolygonAttributes3"));
266: if (isLive())
267: ((PolygonAttributesRetained) this .retained)
268: .setCullFace(cullFace);
269: else
270: ((PolygonAttributesRetained) this .retained)
271: .initCullFace(cullFace);
272:
273: }
274:
275: /**
276: * Gets the face culling for this
277: * appearance component object.
278: * @return the face to be culled
279: * @exception CapabilityNotSetException if appropriate capability is
280: * not set and this object is part of live or compiled scene graph
281: */
282: public int getCullFace() {
283: if (isLiveOrCompiled())
284: if (!this .getCapability(ALLOW_CULL_FACE_READ))
285: throw new CapabilityNotSetException(J3dI18N
286: .getString("PolygonAttributes4"));
287:
288: return ((PolygonAttributesRetained) this .retained)
289: .getCullFace();
290: }
291:
292: /**
293: * Sets the back face normal flip flag to the specified value.
294: * This flag indicates whether vertex normals of back facing polygons
295: * should be flipped (negated) prior to lighting. When this flag
296: * is set to true and back face culling is disabled, polygons are
297: * rendered as if the polygon had two sides with opposing normals.
298: * This feature is disabled by default.
299: * @param backFaceNormalFlip the back face normal flip flag
300: * @exception CapabilityNotSetException if appropriate capability is
301: * not set and this object is part of live or compiled scene graph
302: */
303: public void setBackFaceNormalFlip(boolean backFaceNormalFlip) {
304: if (isLiveOrCompiled())
305: if (!this .getCapability(ALLOW_NORMAL_FLIP_WRITE))
306: throw new CapabilityNotSetException(J3dI18N
307: .getString("PolygonAttributes5"));
308: if (isLive())
309: ((PolygonAttributesRetained) this .retained)
310: .setBackFaceNormalFlip(backFaceNormalFlip);
311: else
312: ((PolygonAttributesRetained) this .retained)
313: .initBackFaceNormalFlip(backFaceNormalFlip);
314:
315: }
316:
317: /**
318: * Gets the back face normal flip flag.
319: * @return the back face normal flip flag
320: * @exception CapabilityNotSetException if appropriate capability is
321: * not set and this object is part of live or compiled scene graph
322: */
323: public boolean getBackFaceNormalFlip() {
324: if (isLiveOrCompiled())
325: if (!this .getCapability(ALLOW_NORMAL_FLIP_READ))
326: throw new CapabilityNotSetException(J3dI18N
327: .getString("PolygonAttributes6"));
328:
329: return ((PolygonAttributesRetained) this .retained)
330: .getBackFaceNormalFlip();
331: }
332:
333: /**
334: * Sets the polygon rasterization mode for this
335: * appearance component object.
336: * @param polygonMode the polygon rasterization mode to be used; one of
337: * POLYGON_FILL, POLYGON_LINE, or POLYGON_POINT
338: * @exception CapabilityNotSetException if appropriate capability is
339: * not set and this object is part of live or compiled scene graph
340: */
341: public void setPolygonMode(int polygonMode) {
342: if (isLiveOrCompiled())
343: if (!this .getCapability(ALLOW_MODE_WRITE))
344: throw new CapabilityNotSetException(J3dI18N
345: .getString("PolygonAttributes7"));
346:
347: if (polygonMode < POLYGON_POINT || polygonMode > POLYGON_FILL)
348: throw new IllegalArgumentException(J3dI18N
349: .getString("PolygonAttributes8"));
350: if (isLive())
351: ((PolygonAttributesRetained) this .retained)
352: .setPolygonMode(polygonMode);
353: else
354: ((PolygonAttributesRetained) this .retained)
355: .initPolygonMode(polygonMode);
356:
357: }
358:
359: /**
360: * Gets the polygon rasterization mode for this
361: * appearance component object.
362: * @return the polygon rasterization mode
363: * @exception CapabilityNotSetException if appropriate capability is
364: * not set and this object is part of live or compiled scene graph
365: */
366: public int getPolygonMode() {
367: if (isLiveOrCompiled())
368: if (!this .getCapability(ALLOW_MODE_READ))
369: throw new CapabilityNotSetException(J3dI18N
370: .getString("PolygonAttributes9"));
371:
372: return ((PolygonAttributesRetained) this .retained)
373: .getPolygonMode();
374: }
375:
376: /**
377: * Sets the constant polygon offset to the specified value.
378: * This screen space
379: * offset is added to the final, device coordinate Z value of polygon
380: * primitives.
381: * @param polygonOffset the constant polygon offset
382: * @exception CapabilityNotSetException if appropriate capability is
383: * not set and this object is part of live or compiled scene graph
384: */
385: public void setPolygonOffset(float polygonOffset) {
386: if (isLiveOrCompiled())
387: if (!this .getCapability(ALLOW_OFFSET_WRITE))
388: throw new CapabilityNotSetException(J3dI18N
389: .getString("PolygonAttributes10"));
390:
391: if (isLive())
392: ((PolygonAttributesRetained) this .retained)
393: .setPolygonOffset(polygonOffset);
394: else
395: ((PolygonAttributesRetained) this .retained)
396: .initPolygonOffset(polygonOffset);
397:
398: }
399:
400: /**
401: * Gets the constant polygon offset.
402: * @return the constant polygon offset
403: * @exception CapabilityNotSetException if appropriate capability is
404: * not set and this object is part of live or compiled scene graph
405: */
406: public float getPolygonOffset() {
407: if (isLiveOrCompiled())
408: if (!this .getCapability(ALLOW_OFFSET_READ))
409: throw new CapabilityNotSetException(J3dI18N
410: .getString("PolygonAttributes11"));
411:
412: return ((PolygonAttributesRetained) this .retained)
413: .getPolygonOffset();
414: }
415:
416: /**
417: * Sets the polygon offset factor to the specified value.
418: * This factor is multiplied by the slope of the polygon, and
419: * then added to the final, device coordinate Z value of polygon
420: * primitives.
421: * @param polygonOffsetFactor the polygon offset factor
422: * @exception CapabilityNotSetException if appropriate capability is
423: * not set and this object is part of live or compiled scene graph
424: *
425: * @since Java 3D 1.2
426: */
427: public void setPolygonOffsetFactor(float polygonOffsetFactor) {
428: if (isLiveOrCompiled())
429: if (!this .getCapability(ALLOW_OFFSET_WRITE))
430: throw new CapabilityNotSetException(J3dI18N
431: .getString("PolygonAttributes10"));
432:
433: if (isLive())
434: ((PolygonAttributesRetained) this .retained)
435: .setPolygonOffsetFactor(polygonOffsetFactor);
436: else
437: ((PolygonAttributesRetained) this .retained)
438: .initPolygonOffsetFactor(polygonOffsetFactor);
439: }
440:
441: /**
442: * Gets the polygon offset factor.
443: * @return the polygon offset factor.
444: * @exception CapabilityNotSetException if appropriate capability is
445: * not set and this object is part of live or compiled scene graph
446: *
447: * @since Java 3D 1.2
448: */
449: public float getPolygonOffsetFactor() {
450: if (isLiveOrCompiled())
451: if (!this .getCapability(ALLOW_OFFSET_READ))
452: throw new CapabilityNotSetException(J3dI18N
453: .getString("PolygonAttributes11"));
454:
455: return ((PolygonAttributesRetained) this .retained)
456: .getPolygonOffsetFactor();
457: }
458:
459: /**
460: * Creates a retained mode PolygonAttributesRetained object that this
461: * PolygonAttributes component object will point to.
462: */
463: void createRetained() {
464: this .retained = new PolygonAttributesRetained();
465: this .retained.setSource(this );
466: }
467:
468: /**
469: * @deprecated replaced with cloneNodeComponent(boolean forceDuplicate)
470: */
471: public NodeComponent cloneNodeComponent() {
472: PolygonAttributes pga = new PolygonAttributes();
473: pga.duplicateNodeComponent(this );
474: return pga;
475: }
476:
477: /**
478: * Copies all node information from <code>originalNodeComponent</code> into
479: * the current node. This method is called from the
480: * <code>duplicateNode</code> method. This routine does
481: * the actual duplication of all "local data" (any data defined in
482: * this object).
483: *
484: * @param originalNodeComponent the original node to duplicate.
485: * @param forceDuplicate when set to <code>true</code>, causes the
486: * <code>duplicateOnCloneTree</code> flag to be ignored. When
487: * <code>false</code>, the value of each node's
488: * <code>duplicateOnCloneTree</code> variable determines whether
489: * NodeComponent data is duplicated or copied.
490: *
491: * @see Node#cloneTree
492: * @see NodeComponent#setDuplicateOnCloneTree
493: */
494:
495: void duplicateAttributes(NodeComponent originalNodeComponent,
496: boolean forceDuplicate) {
497:
498: super
499: .duplicateAttributes(originalNodeComponent,
500: forceDuplicate);
501:
502: PolygonAttributesRetained attr = (PolygonAttributesRetained) originalNodeComponent.retained;
503:
504: PolygonAttributesRetained rt = (PolygonAttributesRetained) retained;
505:
506: rt.initCullFace(attr.getCullFace());
507: rt.initBackFaceNormalFlip(attr.getBackFaceNormalFlip());
508: rt.initPolygonMode(attr.getPolygonMode());
509: rt.initPolygonOffset(attr.getPolygonOffset());
510: rt.initPolygonOffsetFactor(attr.getPolygonOffsetFactor());
511: }
512: }
|