001: /*
002: * $RCSfile: Text3D.java,v $
003: *
004: * Copyright 1996-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:31 $
029: * $State: Exp $
030: */
031:
032: package javax.media.j3d;
033:
034: import javax.vecmath.Point3f;
035:
036: /**
037: * A Text3D object is a text string that has been converted to 3D
038: * geometry. The Font3D object determines the appearance of the
039: * Text3D NodeComponent object. Each Text3D object has the following
040: * parameters:<P>
041: * <UL>
042: * <LI>Font3D object - describes the font style of the text string,
043: * such as the font family (Helvetica, Courier, etc.), style (Italic,
044: * bold, etc.), and point size. The size of the resulting characters will
045: * be equal to the point size. For example, a 12 point font will result in
046: * a Font3D with characters 12 meters tall. </LI><P>
047: * <LI>Text string - the text string to be written.</LI><P>
048: * <LI>Position - determines the initial placement of the Text3D string
049: * in three-space.</LI><P>
050: * <LI>Alignment - specifies how glyphs in the string are placed in
051: * relation to the position parameter. Valid values are:
052: * <UL>
053: * <LI> ALIGN_CENTER - the center of the string is placed on the
054: * <code>position</code> point.</LI>
055: * <LI> ALIGN_FIRST - the first character of the string is placed on
056: * the <code>position</code> point.</LI>
057: * <LI> ALIGN_LAST - the last character of the string is placed on the
058: * <code>position</code> point.</LI>
059: * </UL><P>
060: * <LI>Path - specifies how succeeding glyphs in the string are placed
061: * in relation to the previous glyph. Valid values are:</LI><P>
062: * <UL>
063: * <LI> PATH_LEFT - succeeding glyphs are placed to the left of the
064: * current glyph.</LI>
065: * <LI> PATH_RIGHT - succeeding glyphs are placed to the right of the
066: * current glyph.</LI>
067: * <LI> PATH_UP - succeeding glyphs are placed above the current glyph.</LI>
068: * <LI> PATH_DOWN - succeeding glyphs are placed below the current glyph.</LI>
069: * </UL><P>
070: * <LI>Character spacing - the space between characters. This spacing is
071: * in addition to the regular spacing between glyphs as defined in the
072: * Font object.</LI></UL><P>
073: *
074: * @see Font3D
075: */
076: public class Text3D extends Geometry {
077:
078: /**
079: * Specifies that this Text3D object allows
080: * reading the Font3D component information.
081: *
082: * @see Font3D
083: */
084: public static final int ALLOW_FONT3D_READ = CapabilityBits.TEXT3D_ALLOW_FONT3D_READ;
085:
086: /**
087: * Specifies that this Text3D object allows
088: * writing the Font3D component information.
089: *
090: * @see Font3D
091: */
092: public static final int ALLOW_FONT3D_WRITE = CapabilityBits.TEXT3D_ALLOW_FONT3D_WRITE;
093:
094: /**
095: * Specifies that this Text3D object allows
096: * reading the String object.
097: */
098: public static final int ALLOW_STRING_READ = CapabilityBits.TEXT3D_ALLOW_STRING_READ;
099:
100: /**
101: * Specifies that this Text3D object allows
102: * writing the String object.
103: */
104: public static final int ALLOW_STRING_WRITE = CapabilityBits.TEXT3D_ALLOW_STRING_WRITE;
105:
106: /**
107: * Specifies that this Text3D object allows
108: * reading the text position value.
109: */
110: public static final int ALLOW_POSITION_READ = CapabilityBits.TEXT3D_ALLOW_POSITION_READ;
111:
112: /**
113: * Specifies that this Text3D object allows
114: * writing the text position value.
115: */
116: public static final int ALLOW_POSITION_WRITE = CapabilityBits.TEXT3D_ALLOW_POSITION_WRITE;
117:
118: /**
119: * Specifies that this Text3D object allows
120: * reading the text alignment value.
121: */
122: public static final int ALLOW_ALIGNMENT_READ = CapabilityBits.TEXT3D_ALLOW_ALIGNMENT_READ;
123:
124: /**
125: * Specifies that this Text3D object allows
126: * writing the text alignment value.
127: */
128: public static final int ALLOW_ALIGNMENT_WRITE = CapabilityBits.TEXT3D_ALLOW_ALIGNMENT_WRITE;
129:
130: /**
131: * Specifies that this Text3D object allows
132: * reading the text path value.
133: */
134: public static final int ALLOW_PATH_READ = CapabilityBits.TEXT3D_ALLOW_PATH_READ;
135:
136: /**
137: * Specifies that this Text3D object allows
138: * writing the text path value.
139: */
140: public static final int ALLOW_PATH_WRITE = CapabilityBits.TEXT3D_ALLOW_PATH_WRITE;
141:
142: /**
143: * Specifies that this Text3D object allows
144: * reading the text character spacing value.
145: */
146: public static final int ALLOW_CHARACTER_SPACING_READ = CapabilityBits.TEXT3D_ALLOW_CHARACTER_SPACING_READ;
147:
148: /**
149: * Specifies that this Text3D object allows
150: * writing the text character spacing value.
151: */
152: public static final int ALLOW_CHARACTER_SPACING_WRITE = CapabilityBits.TEXT3D_ALLOW_CHARACTER_SPACING_WRITE;
153:
154: /**
155: * Specifies that this Text3D object allows
156: * reading the text string bounding box value
157: */
158: public static final int ALLOW_BOUNDING_BOX_READ = CapabilityBits.TEXT3D_ALLOW_BOUNDING_BOX_READ;
159:
160: /**
161: * <code>alignment</code>: the center of the string is placed on the
162: * <code>position</code> point.
163: *
164: * @see #getAlignment
165: */
166: public static final int ALIGN_CENTER = 0;
167:
168: /**
169: * <code>alignment</code>: the first character of the string is placed
170: * on the <code>position</code> point.
171: *
172: * @see #getAlignment
173: */
174: public static final int ALIGN_FIRST = 1;
175:
176: /**
177: * <code>alignment</code>: the last character of the string is placed
178: * on the <code>position</code> point.
179: *
180: * @see #getAlignment
181: */
182: public static final int ALIGN_LAST = 2;
183:
184: /**
185: * <code>path</code>: succeeding glyphs are placed to the left of
186: * the current glyph.
187: *
188: * @see #getPath
189: */
190: public static final int PATH_LEFT = 0;
191: /**
192: * <code>path</code>: succeeding glyphs are placed to the left of
193: * the current glyph.
194: *
195: * @see #getPath
196: */
197: public static final int PATH_RIGHT = 1;
198:
199: /**
200: * <code>path</code>: succeeding glyphs are placed above the
201: * current glyph.
202: *
203: * @see #getPath
204: */
205: public static final int PATH_UP = 2;
206:
207: /**
208: * <code>path</code>: succeeding glyphs are placed below the
209: * current glyph.
210: *
211: * @see #getPath
212: */
213: public static final int PATH_DOWN = 3;
214:
215: // Array for setting default read capabilities
216: private static final int[] readCapabilities = { ALLOW_FONT3D_READ,
217: ALLOW_STRING_READ, ALLOW_POSITION_READ,
218: ALLOW_ALIGNMENT_READ, ALLOW_PATH_READ,
219: ALLOW_CHARACTER_SPACING_READ, ALLOW_BOUNDING_BOX_READ };
220:
221: /**
222: * Constructs a Text3D object with default parameters.
223: * The default values are as follows:
224: * <ul>
225: * font 3D : null<br>
226: * string : null<br>
227: * position : (0,0,0)<br>
228: * alignment : ALIGN_FIRST<br>
229: * path : PATH_RIGHT<br>
230: * character spacing : 0.0<br>
231: * </ul>
232: */
233: public Text3D() {
234: // set default read capabilities
235: setDefaultReadCapabilities(readCapabilities);
236: }
237:
238: /**
239: * Creates a Text3D object with the given Font3D object.
240: *
241: * @see Font3D
242: */
243: public Text3D(Font3D font3D) {
244: // set default read capabilities
245: setDefaultReadCapabilities(readCapabilities);
246:
247: ((Text3DRetained) this .retained).setFont3D(font3D);
248: }
249:
250: /**
251: * Creates a Text3D object given a Font3D object and a string. The
252: * string is converted into 3D glyphs. The first glyph from the
253: * string is placed at (0.0, 0.0, 0.0) and succeeding glyphs are
254: * placed to the right of the initial glyph.
255: *
256: * @see Font3D
257: */
258: public Text3D(Font3D font3D, String string) {
259: // set default read capabilities
260: setDefaultReadCapabilities(readCapabilities);
261:
262: ((Text3DRetained) this .retained).setFont3D(font3D);
263: ((Text3DRetained) this .retained).setString(string);
264: }
265:
266: /**
267: * Creates a Text3D object given a Font3D, a string and position. The
268: * string is converted into 3D glyphs. The first glyph from the
269: * string is placed at position <code>position</code> and succeeding
270: * glyphs are placed to the right of the initial glyph.
271: *
272: * @see Font3D
273: */
274: public Text3D(Font3D font3D, String string, Point3f position) {
275: // set default read capabilities
276: setDefaultReadCapabilities(readCapabilities);
277:
278: ((Text3DRetained) this .retained).setFont3D(font3D);
279: ((Text3DRetained) this .retained).setString(string);
280: ((Text3DRetained) this .retained).setPosition(position);
281: }
282:
283: /**
284: * Creates a Text3D object given a Font3D, string, position, alignment
285: * and path along which string is to be placed. The
286: * string is converted into 3D glyphs. The placement of the glyphs
287: * with respect to the <code>position</code> position depends on
288: * the alignment parameter and the path parameter.
289: *
290: * @see Font3D
291: */
292: public Text3D(Font3D font3D, String string, Point3f position,
293: int alignment, int path) {
294: // set default read capabilities
295: setDefaultReadCapabilities(readCapabilities);
296:
297: ((Text3DRetained) this .retained).setFont3D(font3D);
298: ((Text3DRetained) this .retained).setString(string);
299: ((Text3DRetained) this .retained).setPosition(position);
300: ((Text3DRetained) this .retained).setAlignment(alignment);
301: ((Text3DRetained) this .retained).setPath(path);
302: }
303:
304: /**
305: * Creates the retained mode Text3DRetained object that this
306: * Text3D component object will point to.
307: */
308: void createRetained() {
309: this .retained = new Text3DRetained();
310: this .retained.setSource(this );
311: }
312:
313: /**
314: * Returns the Font3D objects used by this Text3D NodeComponent object.
315: *
316: * @return the Font3D object of this Text3D node - null if no Font3D
317: * has been associated with this node.
318: *
319: * @exception CapabilityNotSetException if appropriate capability is
320: * not set and this object is part of live or compiled scene graph
321: */
322: public Font3D getFont3D() {
323: if (isLiveOrCompiled())
324: if (!this .getCapability(ALLOW_FONT3D_READ))
325: throw new CapabilityNotSetException(J3dI18N
326: .getString("Text3D0"));
327: return ((Text3DRetained) this .retained).getFont3D();
328:
329: }
330:
331: /**
332: * Sets the Font3D object used by this Text3D NodeComponent object.
333: *
334: * @param font3d the Font3D object to associate with this Text3D node.
335: *
336: * @exception CapabilityNotSetException if appropriate capability is
337: * not set and this object is part of live or compiled scene graph
338: */
339: public void setFont3D(Font3D font3d) {
340: if (isLiveOrCompiled())
341: if (!this .getCapability(ALLOW_FONT3D_WRITE))
342: throw new CapabilityNotSetException(J3dI18N
343: .getString("Text3D1"));
344: ((Text3DRetained) this .retained).setFont3D(font3d);
345:
346: }
347:
348: /**
349: * Copies the character string used in the construction of the
350: * Text3D node into the supplied parameter.
351: *
352: * @return a copy of the String object in this Text3D node.
353: *
354: * @exception CapabilityNotSetException if appropriate capability is
355: * not set and this object is part of live or compiled scene graph
356: */
357: public String getString() {
358: if (isLiveOrCompiled())
359: if (!this .getCapability(ALLOW_STRING_READ))
360: throw new CapabilityNotSetException(J3dI18N
361: .getString("Text3D2"));
362: return ((Text3DRetained) this .retained).getString();
363: }
364:
365: /**
366: * Copies the character string from the supplied parameter into the
367: * Text3D node.
368: *
369: * @param string the String object to recieve the Text3D node's string.
370: *
371: * @exception CapabilityNotSetException if appropriate capability is
372: * not set and this object is part of live or compiled scene graph
373: */
374: public void setString(String string) {
375: if (isLiveOrCompiled())
376: if (!this .getCapability(ALLOW_STRING_WRITE))
377: throw new CapabilityNotSetException(J3dI18N
378: .getString("Text3D3"));
379: ((Text3DRetained) this .retained).setString(string);
380: }
381:
382: /**
383: * Copies the node's <code>position</code> field into the supplied
384: * parameter. The <code>position</code> is used to determine the
385: * initial placement of the Text3D string. The position, combined with
386: * the path and alignment control how the text is displayed.
387: *
388: * @param position the point to position the text.
389: *
390: * @exception CapabilityNotSetException if appropriate capability is
391: * not set and this object is part of live or compiled scene graph
392: *
393: * @see #getAlignment
394: * @see #getPath
395: */
396: public void getPosition(Point3f position) {
397: if (isLiveOrCompiled())
398: if (!this .getCapability(ALLOW_POSITION_READ))
399: throw new CapabilityNotSetException(J3dI18N
400: .getString("Text3D4"));
401: ((Text3DRetained) this .retained).getPosition(position);
402: }
403:
404: /**
405: * Sets the node's <code>position</code> field to the supplied
406: * parameter. The <code>position</code> is used to determine the
407: * initial placement of the Text3D string. The position, combined with
408: * the path and alignment control how the text is displayed.
409: *
410: * @param position the point to position the text.
411: *
412: * @exception CapabilityNotSetException if appropriate capability is
413: * not set and this object is part of live or compiled scene graph
414: *
415: * @see #getAlignment
416: * @see #getPath
417: */
418: public void setPosition(Point3f position) {
419: if (isLiveOrCompiled())
420: if (!this .getCapability(ALLOW_POSITION_WRITE))
421: throw new CapabilityNotSetException(J3dI18N
422: .getString("Text3D5"));
423: ((Text3DRetained) this .retained).setPosition(position);
424: }
425:
426: /**
427: * Retrieves the text alignment policy for this Text3D NodeComponent
428: * object. The <code>alignment</code> is used to specify how
429: * glyphs in the string are placed in relation to the
430: * <code>position</code> field. Valid values for this field
431: * are:
432: * <UL>
433: * <LI> ALIGN_CENTER - the center of the string is placed on the
434: * <code>position</code> point.
435: * <LI> ALIGN_FIRST - the first character of the string is placed on
436: * the <code>position</code> point.
437: * <LI> ALIGN_LAST - the last character of the string is placed on the
438: * <code>position</code> point.
439: * </UL>
440: * The default value of this field is <code>ALIGN_FIRST</code>.
441: *
442: * @return the current alingment policy for this node.
443: *
444: * @exception CapabilityNotSetException if appropriate capability is
445: * not set and this object is part of live or compiled scene graph
446: *
447: * @see #getPosition
448: */
449: public int getAlignment() {
450: if (isLiveOrCompiled())
451: if (!this .getCapability(ALLOW_ALIGNMENT_READ))
452: throw new CapabilityNotSetException(J3dI18N
453: .getString("Text3D6"));
454: return ((Text3DRetained) this .retained).getAlignment();
455: }
456:
457: /**
458: * Sets the text alignment policy for this Text3D NodeComponent
459: * object. The <code>alignment</code> is used to specify how
460: * glyphs in the string are placed in relation to the
461: * <code>position</code> field. Valid values for this field
462: * are:
463: * <UL>
464: * <LI> ALIGN_CENTER - the center of the string is placed on the
465: * <code>position</code> point.
466: * <LI> ALIGN_FIRST - the first character of the string is placed on
467: * the <code>position</code> point.
468: * <LI> ALIGN_LAST - the last character of the string is placed on the
469: * <code>position</code> point.
470: * </UL>
471: * The default value of this field is <code>ALIGN_FIRST</code>.
472: *
473: * @param alignment specifies how glyphs in the string are placed
474: * in relation to the position field
475: *
476: * @exception CapabilityNotSetException if appropriate capability is
477: * not set and this object is part of live or compiled scene graph
478: *
479: * @see #getPosition
480: */
481: public void setAlignment(int alignment) {
482: if (isLiveOrCompiled())
483: if (!this .getCapability(ALLOW_ALIGNMENT_WRITE))
484: throw new CapabilityNotSetException(J3dI18N
485: .getString("Text3D7"));
486: ((Text3DRetained) this .retained).setAlignment(alignment);
487: }
488:
489: /**
490: * Retrieves the node's <code>path</code> field. This field
491: * is used to specify how succeeding
492: * glyphs in the string are placed in relation to the previous glyph.
493: * Valid values for this field are:
494: * <UL>
495: * <LI> PATH_LEFT: - succeeding glyphs are placed to the left of the
496: * current glyph.
497: * <LI> PATH_RIGHT: - succeeding glyphs are placed to the right of the
498: * current glyph.
499: * <LI> PATH_UP: - succeeding glyphs are placed above the current glyph.
500: * <LI> PATH_DOWN: - succeeding glyphs are placed below the current glyph.
501: * </UL>
502: * The default value of this field is <code>PATH_RIGHT</code>.
503: *
504: * @return the current alingment policy for this node.
505: *
506: * @exception CapabilityNotSetException if appropriate capability is
507: * not set and this object is part of live or compiled scene graph
508: */
509: public int getPath() {
510: if (isLiveOrCompiled())
511: if (!this .getCapability(ALLOW_PATH_READ))
512: throw new CapabilityNotSetException(J3dI18N
513: .getString("Text3D8"));
514: return ((Text3DRetained) this .retained).getPath();
515: }
516:
517: /**
518: * Sets the node's <code>path</code> field. This field
519: * is used to specify how succeeding
520: * glyphs in the string are placed in relation to the previous glyph.
521: * Valid values for this field are:
522: * <UL>
523: * <LI> PATH_LEFT - succeeding glyphs are placed to the left of the
524: * current glyph.
525: * <LI> PATH_RIGHT - succeeding glyphs are placed to the right of the
526: * current glyph.
527: * <LI> PATH_UP - succeeding glyphs are placed above the current glyph.
528: * <LI> PATH_DOWN - succeeding glyphs are placed below the current glyph.
529: * </UL>
530: * The default value of this field is <code>PATH_RIGHT</code>.
531: *
532: * @param path the value to set the path to
533: *
534: * @exception CapabilityNotSetException if appropriate capability is
535: * not set and this object is part of live or compiled scene graph
536: */
537: public void setPath(int path) {
538: if (isLiveOrCompiled())
539: if (!this .getCapability(ALLOW_PATH_WRITE))
540: throw new CapabilityNotSetException(J3dI18N
541: .getString("Text3D9"));
542: ((Text3DRetained) this .retained).setPath(path);
543: }
544:
545: /**
546: * Retrieves the 3D bounding box that encloses this Text3D object.
547: *
548: * @param bounds the object to copy the bounding information to.
549: *
550: * @exception CapabilityNotSetException if appropriate capability is
551: * not set and this object is part of live or compiled scene graph
552: *
553: * @see BoundingBox
554: */
555: public void getBoundingBox(BoundingBox bounds) {
556: if (isLiveOrCompiled())
557: if (!this .getCapability(ALLOW_BOUNDING_BOX_READ))
558: throw new CapabilityNotSetException(J3dI18N
559: .getString("Text3D10"));
560: ((Text3DRetained) this .retained).getBoundingBox(bounds);
561: }
562:
563: /**
564: * Retrieves the character spacing used to construct the Text3D string.
565: * This spacing is in addition to the regular spacing between glyphs as
566: * defined in the Font object. 1.0 in this space is measured as the
567: * width of the largest glyph in the 2D Font. The default value is
568: * 0.0.
569: *
570: * @return the current character spacing value
571: *
572: * @exception CapabilityNotSetException if appropriate capability is
573: * not set and this object is part of live or compiled scene graph
574: */
575: public float getCharacterSpacing() {
576: if (isLiveOrCompiled())
577: if (!this .getCapability(ALLOW_CHARACTER_SPACING_READ))
578: throw new CapabilityNotSetException(J3dI18N
579: .getString("Text3D11"));
580: return ((Text3DRetained) this .retained).getCharacterSpacing();
581: }
582:
583: /**
584: * Sets the character spacing used when constructing the Text3D string.
585: * This spacing is in addition to the regular spacing between glyphs as
586: * defined in the Font object. 1.0 in this space is measured as the
587: * width of the largest glyph in the 2D Font. The default value is
588: * 0.0.
589: *
590: * @param characterSpacing the new character spacing value
591: *
592: * @exception CapabilityNotSetException if appropriate capability is
593: * not set and this object is part of live or compiled scene graph
594: */
595: public void setCharacterSpacing(float characterSpacing) {
596: if (isLiveOrCompiled())
597: if (!this .getCapability(ALLOW_CHARACTER_SPACING_WRITE))
598: throw new CapabilityNotSetException(J3dI18N
599: .getString("Text3D12"));
600: ((Text3DRetained) this .retained)
601: .setCharacterSpacing(characterSpacing);
602: }
603:
604: /**
605: * @deprecated replaced with cloneNodeComponent(boolean forceDuplicate)
606: */
607: public NodeComponent cloneNodeComponent() {
608: Text3D t = new Text3D();
609: t.duplicateNodeComponent(this );
610: return t;
611: }
612:
613: /**
614: * Copies all node information from <code>originalNodeComponent</code> into
615: * the current node. This method is called from the
616: * <code>duplicateNode</code> method. This routine does
617: * the actual duplication of all "local data" (any data defined in
618: * this object).
619: *
620: * @param originalNodeComponent the original node to duplicate.
621: * @param forceDuplicate when set to <code>true</code>, causes the
622: * <code>duplicateOnCloneTree</code> flag to be ignored. When
623: * <code>false</code>, the value of each node's
624: * <code>duplicateOnCloneTree</code> variable determines whether
625: * NodeComponent data is duplicated or copied.
626: *
627: * @see Node#cloneTree
628: * @see NodeComponent#setDuplicateOnCloneTree
629: */
630: void duplicateAttributes(NodeComponent originalNodeComponent,
631: boolean forceDuplicate) {
632: super
633: .duplicateAttributes(originalNodeComponent,
634: forceDuplicate);
635:
636: Text3DRetained text = (Text3DRetained) originalNodeComponent.retained;
637: Text3DRetained rt = (Text3DRetained) retained;
638:
639: Font3D font3D = text.getFont3D();
640: if (font3D != null) {
641: rt.setFont3D(font3D);
642: }
643:
644: String s = text.getString();
645: if (s != null) {
646: rt.setString(s);
647: }
648:
649: Point3f p = new Point3f();
650: text.getPosition(p);
651: rt.setPosition(p);
652: rt.setAlignment(text.getAlignment());
653: rt.setPath(text.getPath());
654: rt.setCharacterSpacing(text.getCharacterSpacing());
655: }
656:
657: }
|