AWT Shape Extruder

com.interactivemesh.j3d.community.utils.geometry
Class String3D

java.lang.Object
  extended by com.interactivemesh.j3d.community.utils.geometry.String3D

public class String3D
extends java.lang.Object

String3D converts a text string to a 3D geometry in a factory manner.

Each String3D object has the following parameters:

The size and original position of a text string can be ascertained without generating geometry data by


According to the current state of these parameters a String3D object creates for a given string a single javax.media.j3d.GeometryArray for the entire text or a single javax.media.j3d.GeometryArray for each character:

A returned GeometryArray includes triangle resp. line primitives and normals.

Sample strings:

 String string0 = new String("String3D");
 String string1 = new String("Two Words !");
 String string2 = new String("  9        8       7      6     5    4   3  2 1  ");
 
 int[] codePoints = new int[] {9992, 9786}; // Airplane, Smiley (e.g. Lucida Sans)
 String string3 = new String(codePoints, 0, 2);        
 

String3D is a generalized version of javax.media.j3d.Text3D.

Version:
1.2

Nested Class Summary
static class String3D.Alignment
          Specifies how the string is placed in relation to the position parameter.
static class String3D.Path
          Specifies how succeeding characters in the string are placed in relation to the previous characters and are aligned in relation to the position parameter.
 
Constructor Summary
String3D()
          Constructs a String3D object with default parameters.
String3D(java.awt.Font font, AWTShapeExtruder extruder)
          Constructs a String3D object given a font and an extruder.
String3D(java.awt.Font font, AWTShapeExtruder extruder, javax.vecmath.Point3f position)
          Constructs a String3D object given a font, an extruder, and a position.
String3D(java.awt.Font font, AWTShapeExtruder extruder, javax.vecmath.Point3f position, String3D.Alignment alignment, String3D.Path path)
          Constructs a String3D object given a font, an extruder, a position, an alignment, and a path.
 
Method Summary
 String3D.Alignment getAlignment()
          Returns the string alignment policy for this String3D object.
 javax.media.j3d.GeometryArray[] getCharacterGeometry(java.lang.String string)
          Generates GeometryArray objects for the given string's characters according to the specified font, extruder, spacing, position, alignment, and path of this String3D object.
 javax.media.j3d.GeometryArray[] getCharacterGeometry(java.lang.String string, javax.media.j3d.BoundingBox bounds)
          Generates GeometryArray objects for the given string's characters according to the specified font, extruder, spacing, position, alignment, and path of this String3D object and returns the geometries' bounding box to the given BoundingBox object.
 javax.media.j3d.GeometryArray[] getCharacterOutlineGeometry(java.lang.String string)
          Generates GeometryArray objects representing the outline for the given string's characters according to the specified font, spacing, position, alignment, and path of this String3D object.
 javax.media.j3d.GeometryArray[] getCharacterOutlineGeometry(java.lang.String string, javax.media.j3d.BoundingBox bounds)
          Generates GeometryArray objects representing the outline for the given string's characters according to the specified font, spacing, position, alignment, and path of this String3D object and returns the geometries' bounding box to the given BoundingBox object.
 float getCharacterSpacing()
          Returns the character spacing used when creating the string's geometry.
 AWTShapeExtruder getExtruder()
          Returns the AWTShapeExtruder object used by this String3D object.
 java.awt.Font getFont()
          Returns the Font object used by this String3D object.
 void getGeometryBounds(java.lang.String string, javax.media.j3d.BoundingBox bounds)
          Returns the bounding box for the given string according to the specified font, extrusion depth, spacing, alignment, and path of this String3D object without generating geometry data.
 String3D.Path getPath()
          Returns the characters path policy.
 void getPosition(javax.vecmath.Point3f position)
          Copies the position field into the supplied parameter.
 javax.media.j3d.GeometryArray getStringGeometry(java.lang.String string)
          Generates a GeometryArray object for the given string according to the specified font, extruder, spacing, position, alignment, and path of this String3D object.
 javax.media.j3d.GeometryArray getStringGeometry(java.lang.String string, javax.media.j3d.BoundingBox bounds)
          Generates a GeometryArray object for the given string according to the specified font, extruder, spacing, position, alignment, and path of this String3D object and returns the geometry's bounding box to the given BoundingBox object.
 javax.media.j3d.GeometryArray getStringOutlineGeometry(java.lang.String string)
          Generates a GeometryArray object representing the outline for the given string according to the specified font, spacing, position, alignment, and path of this String3D object.
 javax.media.j3d.GeometryArray getStringOutlineGeometry(java.lang.String string, javax.media.j3d.BoundingBox bounds)
          Generates a GeometryArray object representing the outline for the given string according to the specified font, spacing, position, alignment, and path of this String3D object and returns the geometry's bounding box to the given BoundingBox object.
 void setAlignment(String3D.Alignment alignment)
          Sets the string alignment policy for this String3D object.
 void setCharacterSpacing(float characterSpacing)
          Sets the character spacing used when creating the string's geometry.
 void setExtruder(AWTShapeExtruder extruder)
          Sets the AWTShapeExtruder object used by this String3D object.
 void setFont(java.awt.Font font)
          Sets the Font object used by this String3D object.
 void setPath(String3D.Path path)
          Sets the characters path policy.
 void setPosition(javax.vecmath.Point3f position)
          Sets the position field to the supplied parameter.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

String3D

public String3D()
Constructs a String3D object with default parameters. The default values are as follows:


String3D

public String3D(java.awt.Font font,
                AWTShapeExtruder extruder)
Constructs a String3D object given a font and an extruder.

See Also:
AWTShapeExtruder

String3D

public String3D(java.awt.Font font,
                AWTShapeExtruder extruder,
                javax.vecmath.Point3f position)
Constructs a String3D object given a font, an extruder, and a position.

See Also:
AWTShapeExtruder

String3D

public String3D(java.awt.Font font,
                AWTShapeExtruder extruder,
                javax.vecmath.Point3f position,
                String3D.Alignment alignment,
                String3D.Path path)
Constructs a String3D object given a font, an extruder, a position, an alignment, and a path.

See Also:
AWTShapeExtruder
Method Detail

getFont

public java.awt.Font getFont()
Returns the Font object used by this String3D object.

The default font is null.

Returns:
the Font object of this String3D object - null if no Font has been associated with this object.

setFont

public void setFont(java.awt.Font font)
Sets the Font object used by this String3D object.

The default font is null.

Parameters:
font - the Font object to associate with this String3D.

getExtruder

public AWTShapeExtruder getExtruder()
Returns the AWTShapeExtruder object used by this String3D object.

The default extruder is null.

Returns:
the AWTShapeExtruder object of this String3D object - null if no AWTShapeExtruder has been associated with this object.

setExtruder

public void setExtruder(AWTShapeExtruder extruder)
Sets the AWTShapeExtruder object used by this String3D object.

The default extruder is null.

Parameters:
extruder - the AWTShapeExtruder object to associate with this String3D.

getPosition

public void getPosition(javax.vecmath.Point3f position)
Copies the position field into the supplied parameter. The position is used to determine the initial placement of the String3D string. The position, combined with the path and alignment control how the string is displayed.

The default position is (0, 0, 0).

Parameters:
position - the point to position the string.
Throws:
java.lang.NullPointerException - if position is null.
See Also:
getAlignment(), getPath()

setPosition

public void setPosition(javax.vecmath.Point3f position)
Sets the position field to the supplied parameter. The position is used to determine the initial placement of the String3D string. The position, combined with the path and alignment control how the string is displayed.

The default position is (0, 0, 0).

Parameters:
position - the point to position the string.
Throws:
java.lang.NullPointerException - if position is null.
See Also:
getAlignment(), getPath()

getAlignment

public String3D.Alignment getAlignment()
Returns the string alignment policy for this String3D object. The alignment is used to specify how characters in the string are placed in relation to the position field.

The default value is String3D.Alignment.FIRST.

Returns:
the current alignment policy for this object.
See Also:
getPosition(javax.vecmath.Point3f)

setAlignment

public void setAlignment(String3D.Alignment alignment)
Sets the string alignment policy for this String3D object. The alignment is used to specify how characters in the string are placed in relation to the position field.

The default value is String3D.Alignment.FIRST.

Parameters:
alignment - the new alignment policy for this object
See Also:
getPosition(javax.vecmath.Point3f)

getPath

public String3D.Path getPath()
Returns the characters path policy. This field is used to specify how succeeding characters in the string are placed in relation to the previous characters and are aligned in relation to the position parameter.

The default value is String3D.Path.RIGHT.

Returns:
the current characters path policy for this object.

setPath

public void setPath(String3D.Path path)
Sets the characters path policy. This field is used to specify how succeeding characters in the string are placed in relation to the previous characters and are aligned in relation to the position parameter.

The default value is String3D.Path.RIGHT.

Parameters:
path - the new characters path policy for this object.

getCharacterSpacing

public float getCharacterSpacing()
Returns the character spacing used when creating the string's geometry. This spacing is in addition to the regular spacing between characters as defined in the Font object. The value is measured in meters.

The default value is 0.0.

Returns:
the current character spacing value

setCharacterSpacing

public void setCharacterSpacing(float characterSpacing)
Sets the character spacing used when creating the string's geometry. This spacing is in addition to the regular spacing between characters as defined in the Font object. The value is measured in meters.

The default value is 0.0.

Parameters:
characterSpacing - the new character spacing value

getGeometryBounds

public void getGeometryBounds(java.lang.String string,
                              javax.media.j3d.BoundingBox bounds)
Returns the bounding box for the given string according to the specified font, extrusion depth, spacing, alignment, and path of this String3D object without generating geometry data.

Neither the position nor the geometry transform attributes are applied. The edge contour of a specified extrusion shape is ignored.

The returned lower and upper corners of the BoundingBox object allow to ascertain the width, height, and depth as well as the center of the tessellated and extruded geometry.

Parameters:
string - a String from which to generate the geometry's bounding box
bounds - a BoundingBox to receive the geometry's lower and upper corners
Throws:
java.lang.NullPointerException - if string is null or of length < 1
java.lang.NullPointerException - if bounds is null
java.lang.IllegalStateException - if no extruder or font object is set
java.lang.IllegalArgumentException - if string consists of whitespaces only

getStringGeometry

public javax.media.j3d.GeometryArray getStringGeometry(java.lang.String string)
Generates a GeometryArray object for the given string according to the specified font, extruder, spacing, position, alignment, and path of this String3D object.

All whitespaces within the string influence the characters' position, alignment, and path. But a non-straight extrusion shape remains unconsidered.

The returned GeometryArray object comprises the geometry of all non-whitespace characters and includes triangle primitives as well as normals.

Parameters:
string - a String from which to generate a tessellated extruded geometry
Returns:
a GeometryArray or null if no GeometryArray could be created
Throws:
java.lang.NullPointerException - if string is null or of length < 1
java.lang.IllegalStateException - if no extruder or font object is set
java.lang.IllegalArgumentException - if string consists of whitespaces only

getStringGeometry

public javax.media.j3d.GeometryArray getStringGeometry(java.lang.String string,
                                                       javax.media.j3d.BoundingBox bounds)
Generates a GeometryArray object for the given string according to the specified font, extruder, spacing, position, alignment, and path of this String3D object and returns the geometry's bounding box to the given BoundingBox object.

All whitespaces within the string influence the characters' position, alignment and path. But a non-straight extrusion shape remains unconsidered.

The returned GeometryArray object comprises the geometry of all non-whitespace characters and includes triangle primitives as well as normals.

The specified BoundingBox object, if not null, receives the bounding box of the returned GeometryArray object.

Parameters:
string - a String from which to generate a tessellated extruded geometry
bounds - a BoundingBox to receive the geometry's bounding box
Returns:
a GeometryArray or null if no GeometryArray could be created
Throws:
java.lang.NullPointerException - if string is null or of length < 1
java.lang.IllegalStateException - if no extruder or font object is set
java.lang.IllegalArgumentException - if string consists of whitespaces only

getStringOutlineGeometry

public javax.media.j3d.GeometryArray getStringOutlineGeometry(java.lang.String string)
Generates a GeometryArray object representing the outline for the given string according to the specified font, spacing, position, alignment, and path of this String3D object. Neither the extrusion path nor the crease angle are applied.

All whitespaces within the string influence the characters' position, alignment, and path.

The returned GeometryArray object comprises the geometry of all non-whitespace characters and includes line primitives as well as normals which are directed along the positive Z axis (0, 0, 1).

Parameters:
string - a String from which to generate an outline geometry
Returns:
a GeometryArray or null if no GeometryArray could be created
Throws:
java.lang.NullPointerException - if string is null or of length < 1
java.lang.IllegalStateException - if no extruder or font object is set
java.lang.IllegalArgumentException - if string consists of whitespaces only

getStringOutlineGeometry

public javax.media.j3d.GeometryArray getStringOutlineGeometry(java.lang.String string,
                                                              javax.media.j3d.BoundingBox bounds)
Generates a GeometryArray object representing the outline for the given string according to the specified font, spacing, position, alignment, and path of this String3D object and returns the geometry's bounding box to the given BoundingBox object. Neither the extrusion path nor the crease angle are applied.

All whitespaces within the string influence the characters' position, alignment, and path.

The returned GeometryArray object comprises the geometry of all non-whitespace characters and includes line primitives as well as normals which are directed along the positive Z axis (0, 0, 1).

The specified BoundingBox object, if not null, receives the bounding box of the returned GeometryArray object.

Parameters:
string - a String from which to generate an outline geometry
bounds - a BoundingBox to receive the geometry's bounding box
Returns:
a GeometryArray or null if no GeometryArray could be created
Throws:
java.lang.NullPointerException - if string is null or of length < 1
java.lang.IllegalStateException - if no extruder or font object is set
java.lang.IllegalArgumentException - if string consists of whitespaces only

getCharacterGeometry

public javax.media.j3d.GeometryArray[] getCharacterGeometry(java.lang.String string)
Generates GeometryArray objects for the given string's characters according to the specified font, extruder, spacing, position, alignment, and path of this String3D object.

All whitespaces within the string influence the characters' position, alignment, and path. But a non-straight extrusion shape remains unconsidered.

The returned GeometryArray objects comprise the geometry of all non-whitespace characters and include triangle primitives as well as normals.

Parameters:
string - a String from which to generate for each character a tessellated extruded geometry
Returns:
GeometryArray objects or null if no GeometryArray could be created
Throws:
java.lang.NullPointerException - if string is null or of length < 1
java.lang.IllegalStateException - if no extruder or font object is set
java.lang.IllegalArgumentException - if string consists of whitespaces only

getCharacterGeometry

public javax.media.j3d.GeometryArray[] getCharacterGeometry(java.lang.String string,
                                                            javax.media.j3d.BoundingBox bounds)
Generates GeometryArray objects for the given string's characters according to the specified font, extruder, spacing, position, alignment, and path of this String3D object and returns the geometries' bounding box to the given BoundingBox object.

All whitespaces within the string influence the characters' position, alignment, and path. But a non-straight extrusion shape remains unconsidered.

The returned GeometryArray objects comprise the geometry of all non-whitespace characters and include triangle primitives as well as normals.

The specified BoundingBox object, if not null, receives the combined bounding box of all returned GeometryArray objects.

Parameters:
string - a String from which to generate for each character a tessellated extruded geometry
bounds - a BoundingBox to receive the geometries' bounding box
Returns:
GeometryArray objects or null if no GeometryArray could be created
Throws:
java.lang.NullPointerException - if string is null or of length < 1
java.lang.IllegalStateException - if no extruder or font object is set
java.lang.IllegalArgumentException - if string consists of whitespaces only

getCharacterOutlineGeometry

public javax.media.j3d.GeometryArray[] getCharacterOutlineGeometry(java.lang.String string)
Generates GeometryArray objects representing the outline for the given string's characters according to the specified font, spacing, position, alignment, and path of this String3D object. Neither the extrusion path nor the crease angle are applied

All whitespaces within the string influence the characters' position, alignment, and path.

The returned GeometryArray objects comprise the geometry of all non-whitespace characters and include line primitives as well as normals which are directed along the positive Z axis (0, 0, 1).

Parameters:
string - a String from which to generate for each character an outline geometry
Returns:
GeometryArray objects or null if no GeometryArray could be created
Throws:
java.lang.NullPointerException - if string is null or of length < 1
java.lang.IllegalStateException - if no extruder or font object is set
java.lang.IllegalArgumentException - if string consists of whitespaces only

getCharacterOutlineGeometry

public javax.media.j3d.GeometryArray[] getCharacterOutlineGeometry(java.lang.String string,
                                                                   javax.media.j3d.BoundingBox bounds)
Generates GeometryArray objects representing the outline for the given string's characters according to the specified font, spacing, position, alignment, and path of this String3D object and returns the geometries' bounding box to the given BoundingBox object. Neither the extrusion path nor the crease angle are applied

All whitespaces within the string influence the characters' position, alignment, and path.

The returned GeometryArray objects comprise the geometry of all non-whitespace characters and include line primitives as well as normals which are directed along the positive Z axis (0, 0, 1).

The specified BoundingBox object, if not null, receives the combined bounding box of all returned GeometryArray objects.

Parameters:
string - a String from which to generate for each character an outline geometry
bounds - a BoundingBox to receive the geometries' bounding box
Returns:
GeometryArray objects or null if no GeometryArray could be created
Throws:
java.lang.NullPointerException - if string is null or of length < 1
java.lang.IllegalStateException - if no extruder or font object is set
java.lang.IllegalArgumentException - if string consists of whitespaces only

AWT Shape Extruder