001: /*
002: * $RCSfile: LineAttributes.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:25 $
029: * $State: Exp $
030: */
031:
032: package javax.media.j3d;
033:
034: /**
035: * The LineAttributes object defines all rendering state that can be set
036: * as a component object of a Shape3D node.
037: * The line attributes that can be defined are:<P>
038: * <UL><LI>Pattern - specifies the pattern used to draw the line:<p>
039: * <ul>
040: * <li>PATTERN_SOLID - draws a solid line with no pattern. This is
041: * the default.</li>
042: * <p>
043: * <li>PATTERN_DASH - draws dashed lines. Ideally, these will be drawn with
044: * a repeating pattern of 8 pixels on and 8 pixels off.</li>
045: * <p>
046: * <li>PATTERN_DOT - draws dotted lines. Ideally, these will be drawn with
047: * a repeating pattern of 1 pixel on and 7 pixels off.</li>
048: * <p>
049: * <li>PATTERN_DASH_DOT - draws dashed-dotted lines. Ideally, these will be
050: * drawn with a repeating pattern of 7 pixels on, 4 pixels off, 1 pixel on,
051: * and 4 pixels off.</li>
052: * <p>
053: * <li>PATTERN_USER_DEFINED - draws lines with a user-defined line pattern.
054: * See "User-defined Line Patterns," below.</li><p>
055: * </ul>
056: * <p>
057: * <LI>Antialiasing (enabled or disabled). By default, antialiasing
058: * is disabled.</LI>
059: * <p>
060: * <p>
061: * If antialiasing is enabled, the lines are considered transparent
062: * for rendering purposes. They are rendered with all the other transparent
063: * objects and adhere to the other transparency settings such as the
064: * View transparency sorting policy and the View depth buffer freeze
065: * transparent enable.
066: * </p>
067: * <LI>Width (in pixels). The default is a line width of one pixel.
068: * </LI></UL><p>
069: *
070: * <b>User-defined Line Patterns</b>
071: * <p>
072: * A user-defined line pattern is specified with a pattern mask and
073: * an optional scale factor.
074: * <p>
075: * The Pattern Mask<p>
076: *
077: * The pattern is specified
078: * using a 16-bit mask that specifies on and off segments. Bit 0 in
079: * the pattern mask corresponds to the first pixel of the line or line
080: * strip primitive. A value of 1 for a bit in the pattern mask indicates
081: * that the corresponding pixel is drawn, while a value of 0
082: * indicates that the corresponding pixel is not drawn. After all 16 bits
083: * in the pattern are used, the pattern is repeated.
084: * <p>
085: * For example, a mask of 0x00ff defines a dashed line with a repeating
086: * pattern of 8 pixels on followed by 8 pixels off. A value of 0x0101
087: * defines a a dotted line with a repeating pattern of 1 pixel on and 7
088: * pixels off.
089: * <p>
090: * The pattern continues around individual line segments of a line strip
091: * primitive. It is restarted at the beginning of each new line strip.
092: * For line array primitives, the pattern is restarted at the beginning
093: * of each line.
094: * <p>
095: * The Scale Factor
096: * <p>
097: * The pattern is multiplied by the scale factor such that each bit in
098: * the pattern mask corresponds to that many consecutive pixels.
099: * For example, a scale factor of 3 applied to a pattern mask of 0x001f
100: * would produce a repeating pattern of 15 pixels on followed by 33
101: * pixels off. The valid range for this attribute is [1,15]. Values
102: * outside this range are clamped.<p>
103: *
104: * @see Appearance
105: * @see View
106: */
107: public class LineAttributes extends NodeComponent {
108:
109: /**
110: * Specifies that this LineAttributes object allows reading its
111: * line width information.
112: */
113: public static final int ALLOW_WIDTH_READ = CapabilityBits.LINE_ATTRIBUTES_ALLOW_WIDTH_READ;
114:
115: /**
116: * Specifies that this LineAttributes object allows writing its
117: * line width information.
118: */
119: public static final int ALLOW_WIDTH_WRITE = CapabilityBits.LINE_ATTRIBUTES_ALLOW_WIDTH_WRITE;
120:
121: /**
122: * Specifies that this LineAttributes object allows reading its
123: * line pattern information.
124: */
125: public static final int ALLOW_PATTERN_READ = CapabilityBits.LINE_ATTRIBUTES_ALLOW_PATTERN_READ;
126:
127: /**
128: * Specifies that this LineAttributes object allows writing its
129: * line pattern information.
130: */
131: public static final int ALLOW_PATTERN_WRITE = CapabilityBits.LINE_ATTRIBUTES_ALLOW_PATTERN_WRITE;
132:
133: /**
134: * Specifies that this LineAttributes object allows reading its
135: * line antialiasing flag.
136: */
137: public static final int ALLOW_ANTIALIASING_READ = CapabilityBits.LINE_ATTRIBUTES_ALLOW_ANTIALIASING_READ;
138:
139: /**
140: * Specifies that this LineAttributes object allows writing its
141: * line antialiasing flag.
142: */
143: public static final int ALLOW_ANTIALIASING_WRITE = CapabilityBits.LINE_ATTRIBUTES_ALLOW_ANTIALIASING_WRITE;
144:
145: /**
146: * Draw solid lines with no pattern.
147: * @see #setLinePattern
148: */
149: public static final int PATTERN_SOLID = 0;
150:
151: /**
152: * Draw dashed lines. Ideally, these will be drawn with
153: * a repeating pattern of 8 pixels on and 8 pixels off.
154: * @see #setLinePattern
155: */
156: public static final int PATTERN_DASH = 1;
157:
158: /**
159: * Draw dotted lines. Ideally, these will be drawn with
160: * a repeating pattern of 1 pixel on and 7 pixels off.
161: * @see #setLinePattern
162: */
163: public static final int PATTERN_DOT = 2;
164:
165: /**
166: * Draw dashed-dotted lines. Ideally, these will be drawn with
167: * a repeating pattern of 7 pixels on, 4 pixels off, 1 pixel on,
168: * and 4 pixels off.
169: * @see #setLinePattern
170: */
171: public static final int PATTERN_DASH_DOT = 3;
172:
173: /**
174: * Draw lines with a user-defined line pattern. The line pattern
175: * is specified with a pattern mask and scale factor.
176: * @see #setLinePattern
177: * @see #setPatternMask
178: * @see #setPatternScaleFactor
179: *
180: * @since Java 3D 1.2
181: */
182: public static final int PATTERN_USER_DEFINED = 4;
183:
184: // Array for setting default read capabilities
185: private static final int[] readCapabilities = {
186: ALLOW_ANTIALIASING_READ, ALLOW_PATTERN_READ,
187: ALLOW_WIDTH_READ };
188:
189: /**
190: * Constructs a LineAttributes object with default parameters.
191: * The default values are as follows:
192: * <ul>
193: * line width : 1<br>
194: * line pattern : PATTERN_SOLID<br>
195: * pattern mask : 0xffff<br>
196: * pattern scale factor : 1<br>
197: * line antialiasing : false<br>
198: * </ul>
199: */
200: public LineAttributes() {
201: // set default read capabilities
202: setDefaultReadCapabilities(readCapabilities);
203: }
204:
205: /**
206: * Constructs a LineAttributes object with specified values.
207: * @param lineWidth the width of lines in pixels
208: * @param linePattern the line pattern, one of PATTERN_SOLID,
209: * PATTERN_DASH, PATTERN_DOT, or PATTERN_DASH_DOT
210: * @param lineAntialiasing flag to set line antialising ON or OFF
211: */
212: public LineAttributes(float lineWidth, int linePattern,
213: boolean lineAntialiasing) {
214:
215: if (linePattern < PATTERN_SOLID
216: || linePattern > PATTERN_DASH_DOT)
217: throw new IllegalArgumentException(J3dI18N
218: .getString("LineAttributes0"));
219:
220: // set default read capabilities
221: setDefaultReadCapabilities(readCapabilities);
222:
223: ((LineAttributesRetained) this .retained)
224: .initLineWidth(lineWidth);
225: ((LineAttributesRetained) this .retained)
226: .initLinePattern(linePattern);
227: ((LineAttributesRetained) this .retained)
228: .initLineAntialiasingEnable(lineAntialiasing);
229: }
230:
231: /**
232: * Sets the line width for this LineAttributes component object.
233: * @param lineWidth the width, in pixels, of line primitives
234: * @exception CapabilityNotSetException if appropriate capability is
235: * not set and this object is part of live or compiled scene graph
236: */
237: public void setLineWidth(float lineWidth) {
238: if (isLiveOrCompiled())
239: if (!this .getCapability(ALLOW_WIDTH_WRITE))
240: throw new CapabilityNotSetException(J3dI18N
241: .getString("LineAttributes1"));
242: if (isLive())
243: ((LineAttributesRetained) this .retained)
244: .setLineWidth(lineWidth);
245: else
246: ((LineAttributesRetained) this .retained)
247: .initLineWidth(lineWidth);
248:
249: }
250:
251: /**
252: * Gets the line width for this LineAttributes component object.
253: * @return the width, in pixels, of line primitives
254: * @exception CapabilityNotSetException if appropriate capability is
255: * not set and this object is part of live or compiled scene graph
256: */
257: public float getLineWidth() {
258: if (isLiveOrCompiled())
259: if (!this .getCapability(ALLOW_WIDTH_READ))
260: throw new CapabilityNotSetException(J3dI18N
261: .getString("LineAttributes2"));
262: return ((LineAttributesRetained) this .retained).getLineWidth();
263: }
264:
265: /**
266: * Sets the line pattern for this LineAttributes component object.
267: * @param linePattern the line pattern to be used, one of:
268: * PATTERN_SOLID, PATTERN_DASH, PATTERN_DOT, PATTERN_DASH_DOT, or
269: * PATTERN_USER_DEFINED.
270: * @exception CapabilityNotSetException if appropriate capability is
271: * not set and this object is part of live or compiled scene graph
272: */
273: public void setLinePattern(int linePattern) {
274: if (isLiveOrCompiled())
275: if (!this .getCapability(ALLOW_PATTERN_WRITE))
276: throw new CapabilityNotSetException(J3dI18N
277: .getString("LineAttributes3"));
278:
279: if (linePattern < PATTERN_SOLID
280: || linePattern > PATTERN_USER_DEFINED)
281: throw new IllegalArgumentException(J3dI18N
282: .getString("LineAttributes4"));
283:
284: if (isLive())
285: ((LineAttributesRetained) this .retained)
286: .setLinePattern(linePattern);
287: else
288: ((LineAttributesRetained) this .retained)
289: .initLinePattern(linePattern);
290:
291: }
292:
293: /**
294: * Gets the line pattern for this LineAttributes component object.
295: * @return the line pattern
296: * @exception CapabilityNotSetException if appropriate capability is
297: * not set and this object is part of live or compiled scene graph
298: */
299: public int getLinePattern() {
300: if (isLiveOrCompiled())
301: if (!this .getCapability(ALLOW_PATTERN_READ))
302: throw new CapabilityNotSetException(J3dI18N
303: .getString("LineAttributes5"));
304:
305: return ((LineAttributesRetained) this .retained)
306: .getLinePattern();
307: }
308:
309: /**
310: * Sets the line pattern mask to the specified value. This is
311: * used when the linePattern attribute is set to
312: * PATTERN_USER_DEFINED. In this mode, the pattern is specified
313: * using a 16-bit mask that specifies on and off segments. Bit 0
314: * in the pattern mask corresponds to the first pixel of the line
315: * or line strip primitive. A value of 1 for a bit in the pattern
316: * mask indicates that the corresponding pixel is drawn, while a
317: * value of 0 indicates that the corresponding pixel is not drawn.
318: * After all 16 bits in the pattern are used, the pattern is
319: * repeated. For example, a mask of 0x00ff defines a dashed line
320: * with a repeating pattern of 8 pixels on followed by 8 pixels
321: * off. A value of 0x0101 defines a a dotted line with a
322: * repeating pattern of 1 pixel on and 7 pixels off
323: * <p>
324: * The pattern continues around individual line segments of a line
325: * strip primitive. It is restarted at the beginning of each new
326: * line strip. For line array primitives, the pattern is
327: * restarted at the beginning of each line.
328: * @param mask the new line pattern mask
329: * @exception CapabilityNotSetException if appropriate capability is
330: * not set and this object is part of live or compiled scene graph
331: * @see #setPatternScaleFactor
332: *
333: * @since Java 3D 1.2
334: */
335: public void setPatternMask(int mask) {
336: if (isLiveOrCompiled()
337: && !this .getCapability(ALLOW_PATTERN_WRITE))
338: throw new CapabilityNotSetException(J3dI18N
339: .getString("LineAttributes8"));
340:
341: if (isLive())
342: ((LineAttributesRetained) this .retained)
343: .setPatternMask(mask);
344: else
345: ((LineAttributesRetained) this .retained)
346: .initPatternMask(mask);
347: }
348:
349: /**
350: * Retrieves the line pattern mask.
351: * @return the line pattern mask
352: * @exception CapabilityNotSetException if appropriate capability is
353: * not set and this object is part of live or compiled scene graph
354: *
355: * @since Java 3D 1.2
356: */
357: public int getPatternMask() {
358: if (isLiveOrCompiled()
359: && !this .getCapability(ALLOW_PATTERN_READ))
360: throw new CapabilityNotSetException(J3dI18N
361: .getString("LineAttributes9"));
362:
363: return ((LineAttributesRetained) this .retained)
364: .getPatternMask();
365: }
366:
367: /**
368: * Sets the line pattern scale factor to the specified value.
369: * This is used in conjunction with the patternMask when the
370: * linePattern attribute is set to PATTERN_USER_DEFINED. The
371: * pattern is multiplied by the scale factor such that each bit in
372: * the pattern mask corresponds to that many consecutive pixels.
373: * For example, a scale factor of 3 applied to a pattern mask of
374: * 0x001f would produce a repeating pattern of 15 pixels on
375: * followed by 33 pixels off. The valid range for this attribute
376: * is [1,15]. Values outside this range are clamped.
377: * @param scaleFactor the new line pattern scale factor
378: * @exception CapabilityNotSetException if appropriate capability is
379: * not set and this object is part of live or compiled scene graph
380: * @see #setPatternMask
381: *
382: * @since Java 3D 1.2
383: */
384: public void setPatternScaleFactor(int scaleFactor) {
385: if (isLiveOrCompiled()
386: && !this .getCapability(ALLOW_PATTERN_WRITE))
387: throw new CapabilityNotSetException(J3dI18N
388: .getString("LineAttributes10"));
389:
390: if (isLive())
391: ((LineAttributesRetained) this .retained)
392: .setPatternScaleFactor(scaleFactor);
393: else
394: ((LineAttributesRetained) this .retained)
395: .initPatternScaleFactor(scaleFactor);
396: }
397:
398: /**
399: * Retrieves the line pattern scale factor.
400: * @return the line pattern scale factor
401: * @exception CapabilityNotSetException if appropriate capability is
402: * not set and this object is part of live or compiled scene graph
403: *
404: * @since Java 3D 1.2
405: */
406: public int getPatternScaleFactor() {
407: if (isLiveOrCompiled()
408: && !this .getCapability(ALLOW_PATTERN_READ))
409: throw new CapabilityNotSetException(J3dI18N
410: .getString("LineAttributes11"));
411:
412: return ((LineAttributesRetained) this .retained)
413: .getPatternScaleFactor();
414: }
415:
416: /**
417: * Enables or disables line antialiasing
418: * for this LineAttributes component object.
419: * <p>
420: * If antialiasing is enabled, the lines are considered transparent
421: * for rendering purposes. They are rendered with all the other
422: * transparent objects and adhere to the other transparency settings
423: * such as the View transparency sorting policy and the View depth buffer
424: * freeze transparent enable.
425: * </p>
426: * @param state true or false to enable or disable line antialiasing
427: * @exception CapabilityNotSetException if appropriate capability is
428: * not set and this object is part of live or compiled scene graph
429: * @see View
430: */
431: public void setLineAntialiasingEnable(boolean state) {
432: if (isLiveOrCompiled())
433: if (!this .getCapability(ALLOW_ANTIALIASING_WRITE))
434: throw new CapabilityNotSetException(J3dI18N
435: .getString("LineAttributes6"));
436: if (isLive())
437: ((LineAttributesRetained) this .retained)
438: .setLineAntialiasingEnable(state);
439: else
440: ((LineAttributesRetained) this .retained)
441: .initLineAntialiasingEnable(state);
442:
443: }
444:
445: /**
446: * Retrieves the state of the line antialiasing flag.
447: * @return true if line antialiasing is enabled,
448: * false if line antialiasing is disabled
449: * @exception CapabilityNotSetException if appropriate capability is
450: * not set and this object is part of live or compiled scene graph
451: */
452: public boolean getLineAntialiasingEnable() {
453: if (isLiveOrCompiled())
454: if (!this .getCapability(ALLOW_ANTIALIASING_READ))
455: throw new CapabilityNotSetException(J3dI18N
456: .getString("LineAttributes7"));
457:
458: return ((LineAttributesRetained) this .retained)
459: .getLineAntialiasingEnable();
460: }
461:
462: /**
463: * Creates a retained mode LineAttributesRetained object that this
464: * LineAttributes component object will point to.
465: */
466: void createRetained() {
467: this .retained = new LineAttributesRetained();
468: this .retained.setSource(this );
469: }
470:
471: /**
472: * @deprecated replaced with cloneNodeComponent(boolean forceDuplicate)
473: */
474: public NodeComponent cloneNodeComponent() {
475: LineAttributes la = new LineAttributes();
476: la.duplicateNodeComponent(this );
477: return la;
478: }
479:
480: /**
481: * Copies all node information from <code>originalNodeComponent</code> into
482: * the current node. This method is called from the
483: * <code>duplicateNode</code> method. This routine does
484: * the actual duplication of all "local data" (any data defined in
485: * this object).
486: *
487: * @param originalNodeComponent the original node to duplicate.
488: * @param forceDuplicate when set to <code>true</code>, causes the
489: * <code>duplicateOnCloneTree</code> flag to be ignored. When
490: * <code>false</code>, the value of each node's
491: * <code>duplicateOnCloneTree</code> variable determines whether
492: * NodeComponent data is duplicated or copied.
493: *
494: * @see Node#cloneTree
495: * @see NodeComponent#setDuplicateOnCloneTree
496: */
497: void duplicateAttributes(NodeComponent originalNodeComponent,
498: boolean forceDuplicate) {
499: super
500: .duplicateAttributes(originalNodeComponent,
501: forceDuplicate);
502:
503: LineAttributesRetained attr = (LineAttributesRetained) originalNodeComponent.retained;
504: LineAttributesRetained rt = (LineAttributesRetained) retained;
505:
506: rt.initLineWidth(attr.getLineWidth());
507: rt.initLinePattern(attr.getLinePattern());
508: rt.initLineAntialiasingEnable(attr.getLineAntialiasingEnable());
509: rt.initPatternMask(attr.getPatternMask());
510: rt.initPatternScaleFactor(attr.getPatternScaleFactor());
511: }
512:
513: }
|