text3d.java

JAVA3D矩陈的相关类

/*
 * $RCSfile: Text3D.java,v $
 *
 * Copyright (c) 2007 Sun Microsystems, Inc. All rights reserved.
 *
 * Use is subject to license terms.
 *
 * $Revision: 1.5 $
 * $Date: 2007/02/09 17:18:25 $
 * $State: Exp $
 */

package javax.media.j3d;

import javax.vecmath.Point3f;

/**
 * A Text3D object is a text string that has been converted to 3D
 * geometry.  The Font3D object determines the appearance of the
 * Text3D NodeComponent object. Each Text3D object has the following
 * parameters:<P>
 * <UL>
 * <LI>Font3D object - describes the font style of the text string,
 * such as the font family (Helvetica, Courier, etc.), style (Italic,
 * bold, etc.), and point size. The size of the resulting characters will 
 * be equal to the point size. For example, a 12 point font will result in 
 * a Font3D with characters 12 meters tall.  </LI><P>
 * <LI>Text string - the text string to be written.</LI><P>
 * <LI>Position - determines the initial placement of the Text3D string
 * in three-space.</LI><P>
 * <LI>Alignment - specifies how glyphs in the string are placed in
 * relation to the position parameter. Valid values are:
 * <UL>
 * <LI> ALIGN_CENTER - the center of the string is placed on the
 *  <code>position</code> point.</LI>
 * <LI> ALIGN_FIRST - the first character of the string is placed on
 *   the <code>position</code> point.</LI>
 * <LI> ALIGN_LAST - the last character of the string is placed on the
 *   <code>position</code> point.</LI>
 * </UL><P>
 * <LI>Path - specifies how succeeding glyphs in the string are placed
 * in relation to the previous glyph. Valid values are:</LI><P>
 * <UL>
 * <LI> PATH_LEFT - succeeding glyphs are placed to the left of the
 *  current glyph.</LI>
 * <LI> PATH_RIGHT - succeeding glyphs are placed to the right of the
 *  current glyph.</LI>
 * <LI> PATH_UP - succeeding glyphs are placed above the current glyph.</LI>
 * <LI> PATH_DOWN - succeeding glyphs are placed below the current glyph.</LI>
 * </UL><P>
 * <LI>Character spacing - the space between characters. This spacing is
 * in addition to the regular spacing between glyphs as defined in the
 * Font object.</LI></UL><P>
 *
 * @see Font3D
 */
public class Text3D extends Geometry {

    /**
     * Specifies that this Text3D object allows
     * reading the Font3D component information.
     *
     * @see Font3D
     */
    public static final int
    ALLOW_FONT3D_READ = CapabilityBits.TEXT3D_ALLOW_FONT3D_READ;

    /**
     * Specifies that this Text3D object allows
     * writing the Font3D component information.
     *
     * @see Font3D
     */
    public static final int
    ALLOW_FONT3D_WRITE = CapabilityBits.TEXT3D_ALLOW_FONT3D_WRITE;

    /**
     * Specifies that this Text3D object allows
     * reading the String object.
     */
    public static final int
    ALLOW_STRING_READ = CapabilityBits.TEXT3D_ALLOW_STRING_READ;

    /**
     * Specifies that this Text3D object allows
     * writing the String object.
     */
    public static final int
    ALLOW_STRING_WRITE = CapabilityBits.TEXT3D_ALLOW_STRING_WRITE;

    /**
     * Specifies that this Text3D object allows
     * reading the text position value.
     */
    public static final int
    ALLOW_POSITION_READ = CapabilityBits.TEXT3D_ALLOW_POSITION_READ;

    /**
     * Specifies that this Text3D object allows
     * writing the text position value.
     */
    public static final int
    ALLOW_POSITION_WRITE = CapabilityBits.TEXT3D_ALLOW_POSITION_WRITE;

    /**
     * Specifies that this Text3D object allows
     * reading the text alignment value.
     */
    public static final int
    ALLOW_ALIGNMENT_READ = CapabilityBits.TEXT3D_ALLOW_ALIGNMENT_READ;

    /**
     * Specifies that this Text3D object allows
     * writing the text alignment value.
     */
    public static final int
    ALLOW_ALIGNMENT_WRITE = CapabilityBits.TEXT3D_ALLOW_ALIGNMENT_WRITE;

    /**
     * Specifies that this Text3D object allows
     * reading the text path value.
     */
    public static final int
    ALLOW_PATH_READ = CapabilityBits.TEXT3D_ALLOW_PATH_READ;

    /**
     * Specifies that this Text3D object allows
     * writing the text path value.
     */
    public static final int
    ALLOW_PATH_WRITE = CapabilityBits.TEXT3D_ALLOW_PATH_WRITE;

    /**
     * Specifies that this Text3D object allows
     * reading the text character spacing value.
     */
    public static final int
    ALLOW_CHARACTER_SPACING_READ = CapabilityBits.TEXT3D_ALLOW_CHARACTER_SPACING_READ;

    /**
     * Specifies that this Text3D object allows
     * writing the text character spacing value.
     */
    public static final int
    ALLOW_CHARACTER_SPACING_WRITE = CapabilityBits.TEXT3D_ALLOW_CHARACTER_SPACING_WRITE;

    /**
     * Specifies that this Text3D object allows
     * reading the text string bounding box value
     */
    public static final int
    ALLOW_BOUNDING_BOX_READ = CapabilityBits.TEXT3D_ALLOW_BOUNDING_BOX_READ;

    /**
     * <code>alignment</code>: the center of the string is placed on the
     * <code>position</code> point.
     *
     * @see #getAlignment
     */
    public static final int ALIGN_CENTER = 0;

    /**
     * <code>alignment</code>: the first character of the string is placed
     * on the <code>position</code> point.
     *
     * @see #getAlignment
     */
    public static final int ALIGN_FIRST = 1;

    /**
     * <code>alignment</code>: the last character of the string is placed
     * on the <code>position</code> point.
     *
     * @see #getAlignment
     */
    public static final int ALIGN_LAST = 2;

    /**
     * <code>path</code>: succeeding glyphs are placed to the left of
     * the current glyph.
     *
     * @see #getPath
     */
    public static final int PATH_LEFT = 0;
    /**
     * <code>path</code>: succeeding glyphs are placed to the left of
     * the current glyph.
     *
     * @see #getPath
     */
    public static final int PATH_RIGHT = 1;

    /**
     * <code>path</code>: succeeding glyphs are placed above the
     * current glyph.
     *
     * @see #getPath
     */
    public static final int PATH_UP = 2;

    /**
     * <code>path</code>: succeeding glyphs are placed below the
     * current glyph.
     *
     * @see #getPath
     */
    public static final int PATH_DOWN = 3;

    // Array for setting default read capabilities
    private static final int[] readCapabilities = {
	ALLOW_FONT3D_READ,
	ALLOW_STRING_READ,
	ALLOW_POSITION_READ,
	ALLOW_ALIGNMENT_READ,
	ALLOW_PATH_READ,
	ALLOW_CHARACTER_SPACING_READ,
	ALLOW_BOUNDING_BOX_READ
    };

    /**
     * Constructs a Text3D object with default parameters.
     * The default values are as follows:
     * <ul>
     * font 3D : null<br>
     * string : null<br>
     * position : (0,0,0)<br>
     * alignment : ALIGN_FIRST<br>
     * path : PATH_RIGHT<br>
     * character spacing : 0.0<br>
     * </ul>
     */
    public Text3D() {
        // set default read capabilities
        setDefaultReadCapabilities(readCapabilities);
    }

    /**
     * Creates a Text3D object with the given Font3D object.
     *
     * @see Font3D
     */
    public Text3D(Font3D font3D) {
        // set default read capabilities
        setDefaultReadCapabilities(readCapabilities);

	((Text3DRetained)this.retained).setFont3D(font3D);
    }

    /**
     * Creates a Text3D object given a Font3D object and a string.  The
     * string is converted into 3D glyphs.  The first glyph from the
     * string is placed at (0.0, 0.0, 0.0) and succeeding glyphs are
     * placed to the right of the initial glyph.
     *
     * @see Font3D
     */
    public Text3D(Font3D font3D, String string) {
        // set default read capabilities
        setDefaultReadCapabilities(readCapabilities);

	((Text3DRetained)this.retained).setFont3D(font3D);
	((Text3DRetained)this.retained).setString(string);
    }

    /**
     * Creates a Text3D object given a Font3D, a string and position. The
     * string is converted into 3D glyphs.  The first glyph from the
     * string is placed at position <code>position</code> and succeeding
     * glyphs are placed to the right of the initial glyph.
     *
     * @see Font3D
     */
    public Text3D(Font3D font3D, String string, Point3f position) {
        // set default read capabilities
        setDefaultReadCapabilities(readCapabilities);

	((Text3DRetained)this.retained).setFont3D(font3D);
	((Text3DRetained)this.retained).setString(string);
	((Text3DRetained)this.retained).setPosition(position);
    }

    /**
     * Creates a Text3D object given a Font3D, string, position, alignment
     * and path along which string is to be placed. The
     * string is converted into 3D glyphs.  The placement of the glyphs
     * with respect to the <code>position</code> position depends on
     * the alignment parameter and the path parameter.
     *
     * @see Font3D
     */
    public Text3D(Font3D font3D, String string, Point3f position,
		  int alignment, int path) {
        // set default read capabilities
        setDefaultReadCapabilities(readCapabilities);

	((Text3DRetained)this.retained).setFont3D(font3D);
	((Text3DRetained)this.retained).setString(string);
	((Text3DRetained)this.retained).setPosition(position);
	((Text3DRetained)this.retained).setAlignment(alignment);
	((Text3DRetained)this.retained).setPath(path);
    }

    /**
     * Creates the retained mode Text3DRetained object that this
     * Text3D component object will point to.
     */
    void createRetained() {
        this.retained = new Text3DRetained();
        this.retained.setSource(this);
    }


    /**
     * Returns the Font3D objects used by this Text3D NodeComponent object.
     *
     * @return the Font3D object of this Text3D node - null if no Font3D
     *  has been associated with this node.
     *
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */
    public Font3D getFont3D() {
        if (isLiveOrCompiled())