org.j3d.renderer.aviatrix3d.geom

Class Text2D

java.lang.Object

org.j3d.aviatrix3d.SceneGraphObject

org.j3d.aviatrix3d.NodeComponent

org.j3d.aviatrix3d.Geometry

org.j3d.renderer.aviatrix3d.geom.Text2D

All Implemented Interfaces:

Comparable, LeafPickTarget, PickableObject, PickTarget, GeometryRenderable, Renderable

public class Text2D
extends Geometry

Flat, ploygonalised 2D text representation.

A single line of text is normalise to always be one unit high regardless of the original font size. The relative size can then be changed using a multiplication factor, though the polygonalisation stays the same. If using large text, and need fine polygonalisation, then making use of a custom CharacterCreator with a large point size font and finer flatness would be recommended.

Because all the methods for setting values in this class can influence the final bounds of the object, they are all required to use the boundsChanged() callback from NodeUpdateListener.

Since the text is 2D, it has no depth. If an intersection test is created such that the ray is parallel to the local X-Y plane and does not change in Z depth, then no intersection will be generated. The implementation attempts to optimise the testing based on the bounds of the individual character before checking polygons.

The default setup following construction follows English requirements:
horizontal: true
leftToRight: true
topToBottom: true
size: 1.0
spacing: 1.0
horizontal justification: JUSTIFY_BEGIN
vertical justification: JUSTIFY_BEGIN

Internationalisation Resource Names

• invalidSpacingMsg: Error message when text spacing is not positive.
• invalidSizeMsg: Error message when text size is not positive
• invalidJustificationMsg: Error message when an invalid justification type is requested

Version:

$Revision: 1.19 $

Author:

Justin Couch

Field Summary

Fields

Modifier and Type	Field and Description
static int	JUSTIFY_BEGIN Justify to the beginning of the line
static int	JUSTIFY_END Justify to the end of the string
static int	JUSTIFY_FIRST Justify to the first character of the line
static int	JUSTIFY_MIDDLE Justify about the middle

Fields inherited from class org.j3d.aviatrix3d.Geometry

bounds, implicitBounds, internalUpdater, INVALID_BOUNDS, lastParentList, parentList, pickFlags, validAlpha

Fields inherited from class org.j3d.aviatrix3d.NodeComponent

lastParent, liveCount

Fields inherited from class org.j3d.aviatrix3d.SceneGraphObject

alive, LISTENER_SET_TIMING_ERR_PROP, updateHandler

Fields inherited from interface org.j3d.aviatrix3d.picking.PickableObject

COLLIDABLE_OBJECT, GENERAL_OBJECT, PROXIMITY_OBJECT, VISIBLE_OBJECT

Fields inherited from interface org.j3d.aviatrix3d.picking.PickTarget

CUSTOM_PICK_TYPE, GROUP_PICK_TYPE, LEAF_PICK_TYPE, SINGLE_PICK_TYPE

Constructor Summary

Constructors

Constructor and Description
Text2D() Create a new, default text representation.
Text2D(org.j3d.geom.CharacterCreator charGen) Create a new text representation using the provided CharacterCreator.

Method Summary

Modifier and Type	Method and Description
int	compareTo(Object o) Compares this object with the specified object for order.
int	compareTo(Text2D txt) Compares this object with the specified object for order.
boolean	equals(Object o) Compare this object for equality to the given object.
boolean	equals(Text2D txt) Compares this object with the specified object to check for equivalence.
float	getHorizontalJustification() Get the value of the line size multiplier.
float	getSize() Get the value of the line size multiplier.
float	getSpacing() Get the value of the line spacing multiplier.
String[]	getText() Get a reference to the currently set collection of strings.
float	getVerticalJustification() Get the value of the line size multiplier.
boolean	is2D() Check to see whether this shape is something that represents 2D or 3D geometry.
boolean	isHorizontal() Get the state of the horizontal rendering flag.
boolean	isLeftToRight() Get the state of the left to right rendering flag.
boolean	isTopToBottom() Get the state of the top to bottom rendering flag.
protected boolean	isVisible() Check to see if this geometry is making the geometry visible or not.
boolean	pickLineRay(float[] origin, float[] direction, boolean findAny, float[] dataOut, int dataOutFlags) Check for all intersections against this geometry using a line ray and return the exact distance away of the closest picking point.
boolean	pickLineSegment(float[] start, float[] end, boolean findAny, float[] dataOut, int dataOutFlags) Check for all intersections against this geometry using a line segment and return the exact distance away of the closest picking point.
protected void	recomputeBounds() Internal method to recalculate the implicit bounds of this Node.
void	render(com.jogamp.opengl.GL2 gl) This method is called to render this node.
void	setCharacterCreator(org.j3d.geom.CharacterCreator charGen) Replace the internal character generator with another.
void	setHorizontal(boolean horizontal) Change whether the text should be rendered vertically or horizontally.
void	setHorizontalJustification(int justify) Change the horizontal justification of the text.
void	setLeftToRight(boolean leftToRight) Change whether the text should be placing characters left to right or right to left.
protected void	setLive(boolean state) Notification that this object is live now.
void	setSize(float size) Change size multiplier of a single row of text.
void	setSpacing(float spacing) Change spacing multiplier between rows of text.
void	setText(String[] text, int numText) Set the list of strings that you want to have rendered.
void	setTopToBottom(boolean topToBottom) Change whether the text should be placed from top to bottom or bottom to top.
void	setVerticalJustification(int justify) Change the vertical justification of the text.

Methods inherited from class org.j3d.aviatrix3d.Geometry

addParent, boundsChanged, checkPickMask, getBounds, getPickableBounds, getPickMask, getPickTargetType, hasTransparency, markBoundsDirty, pickBatch, pickSingle, removeParent, setBounds, setPickMask, updateBounds

Methods inherited from class org.j3d.aviatrix3d.NodeComponent

addParent, getParents, numParents, removeParent

Methods inherited from class org.j3d.aviatrix3d.SceneGraphObject

checkForCyclicChild, checkForCyclicParent, dataChanged, getAppUpdateWriteTimingMessage, getBoundsWriteTimingMessage, getDataWriteTimingMessage, getUserData, isLive, setUpdateHandler, setUserData

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

JUSTIFY_FIRST

public static final int JUSTIFY_FIRST

Justify to the first character of the line

See Also:

Constant Field Values

JUSTIFY_BEGIN

public static final int JUSTIFY_BEGIN

Justify to the beginning of the line

See Also:

Constant Field Values

JUSTIFY_MIDDLE

public static final int JUSTIFY_MIDDLE

Justify about the middle

See Also:

Constant Field Values

JUSTIFY_END

public static final int JUSTIFY_END

Justify to the end of the string

See Also:

Constant Field Values

Constructor Detail

Text2D

public Text2D()

Create a new, default text representation. No font information is set, so a plain, 12 point font is used.

Text2D

public Text2D(org.j3d.geom.CharacterCreator charGen)

Create a new text representation using the provided CharacterCreator. If the argument is null, then the default generator is used.

Parameters:

charGen - The creator of characters to use, or null

Method Detail

render

public void render(com.jogamp.opengl.GL2 gl)

This method is called to render this node. All openGL commands needed to render the node should be executed. Any transformations needed should be added to the transformation stack premultiplied. This method must be re-entrant as it can be called from multiple places at once.

Parameters:

gl - The gl context to draw with

compareTo

public int compareTo(Object o)
              throws ClassCastException

Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Parameters:

o - The objec to be compared

Returns:

-1, 0 or 1 depending on order

Throws:

ClassCastException - The specified object's type prevents it from being compared to this Object

equals

public boolean equals(Object o)

Compare this object for equality to the given object.

Overrides:

equals in class Object

Parameters:

o - The object to be compared

Returns:

True if these represent the same values

isVisible

protected boolean isVisible()

Check to see if this geometry is making the geometry visible or not. Returns true if the defined number of coordinates and strips are both non-zero.

Overrides:

isVisible in class Geometry

Returns:

true when the geometry is visible

is2D

public boolean is2D()

Check to see whether this shape is something that represents 2D or 3D geometry. Pure 2D geometry is not effected by any EffectRenderable, while 3D is. Note that this can be changed depending on the type of geometry itself. A Shape3D node with an IndexedLineArray that only has 2D coordinates is as much a 2D geometry as a raster object.

Specified by:

is2D in class Geometry

Returns:

True if this is 2D geometry, false if this is 3D

setLive

protected void setLive(boolean state)

Notification that this object is live now. Overridden to make sure that the live state of the nodes represents the same state as the parent scene graph.

Overrides:

setLive in class SceneGraphObject

Parameters:

state - true if this should be marked as live now

recomputeBounds

protected void recomputeBounds()

Internal method to recalculate the implicit bounds of this Node. By default the bounds are a point sphere, so derived classes should override this method with something better.

Specified by:

recomputeBounds in class Geometry

pickLineSegment

public boolean pickLineSegment(float[] start,
                               float[] end,
                               boolean findAny,
                               float[] dataOut,
                               int dataOutFlags)
                        throws NotPickableException

Check for all intersections against this geometry using a line segment and return the exact distance away of the closest picking point. Default implementation always returns false indicating that nothing was found. Derived classes should override and provide a real implementation.

Specified by:

pickLineSegment in interface LeafPickTarget

Overrides:

pickLineSegment in class Geometry

Parameters:

start - The start point of the segment

end - The end point of the segment

findAny - True if it only has to find a single intersection and can exit as soon as it finds the first intersection. False if it must find the closest polygon

dataOut - An array to put the data in for the intersection. Exact format is described by the flags

dataOutFlags - A set of derived-class specific flags describing what data should be included in the output array

Returns:

True if an intersection was found according to the input request

Throws:

NotPickableException - This object has been marked as non pickable, but you decided to try to call the method anyway

pickLineRay

public boolean pickLineRay(float[] origin,
                           float[] direction,
                           boolean findAny,
                           float[] dataOut,
                           int dataOutFlags)
                    throws NotPickableException

Check for all intersections against this geometry using a line ray and return the exact distance away of the closest picking point. Default implementation always returns false indicating that nothing was found. Derived classes should override and provide a real implementation.

Specified by:

pickLineRay in interface LeafPickTarget

Overrides:

pickLineRay in class Geometry

Parameters:

origin - The start point of the ray

direction - The direction vector of the ray

findAny - True if it only has to find a single intersection and can exit as soon as it finds the first intersection. False if it must find the closest polygon

dataOut - An array to put the data in for the intersection. Exact format is described by the flags

dataOutFlags - A set of derived-class specific flags describing what data should be included in the output array

Returns:

True if an intersection was found according to the input request

Throws:

NotPickableException - This object has been marked as non pickable, but you decided to try to call the method anyway

setCharacterCreator

public void setCharacterCreator(org.j3d.geom.CharacterCreator charGen)

Replace the internal character generator with another. If the argument is null, then the default is used again.

Parameters:

charGen - The creator of characters to use, or null

setText

public void setText(String[] text,
                    int numText)

Set the list of strings that you want to have rendered. Each string appears on a new line.

Parameters:

text - An array of strings to render

numText - The number of strings to render

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener bounds callback method

getText

public String[] getText()

Get a reference to the currently set collection of strings. If no strings are set, then this returns null.

Returns:

The current internal array of strings

setHorizontal

public void setHorizontal(boolean horizontal)
                   throws InvalidWriteTimingException

Change whether the text should be rendered vertically or horizontally. Horizontal text is the default setting.

Parameters:

horizontal - true if the text should be rendered horizontally

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener bounds callback method

isHorizontal

public boolean isHorizontal()

Get the state of the horizontal rendering flag. If this returns true, text is rendered horizontally.

Returns:

true if rendering horizontally, false for vertical

setLeftToRight

public void setLeftToRight(boolean leftToRight)
                    throws InvalidWriteTimingException

Change whether the text should be placing characters left to right or right to left. Left to right is the default setting.

Parameters:

leftToRight - true if the text should be rendered leftToRightly

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener bounds callback method

isLeftToRight

public boolean isLeftToRight()

Get the state of the left to right rendering flag. If this returns true, text is rendered left to right.

Returns:

true if rendering left to right, false for right to left

setTopToBottom

public void setTopToBottom(boolean topToBottom)
                    throws InvalidWriteTimingException

Change whether the text should be placed from top to bottom or bottom to top. Top to bottom is the default setting.

Parameters:

topToBottom - true if the text should be rendered top to bottom

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener bounds callback method

isTopToBottom

public boolean isTopToBottom()

Get the state of the top to bottom rendering flag. If this returns true, text is rendered top to bottom.

Returns:

true if rendering top to bottom, false for bottom to top

setSpacing

public void setSpacing(float spacing)
                throws InvalidWriteTimingException,
                       IllegalArgumentException

Change spacing multiplier between rows of text. Spacing is used to multiply the standard height between lines to generate a wider distance between lines - such as double spaced text. The value must be a non-zero, non-negative value.

Parameters:

spacing - true if the text should be rendered horizontally

Throws:

IllegalArgumentException - The value was not positive

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener bounds callback method

getSpacing

public float getSpacing()

Get the value of the line spacing multiplier.

Returns:

A value greater than zero

setSize

public void setSize(float size)
             throws InvalidWriteTimingException,
                    IllegalArgumentException

Change size multiplier of a single row of text. Size is used to adjust the raw text size in units of the text. The default text size scales the text to be one unit high (or wide, depending on horizontal rendering setting) and this allows the text to be some other size than that. The value must be a non-zero, non-negative value.

Parameters:

size - true if the text should be rendered horizontally

Throws:

IllegalArgumentException - The value was not positive

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener bounds callback method

getSize

public float getSize()

Get the value of the line size multiplier.

Returns:

A value greater than zero

setHorizontalJustification

public void setHorizontalJustification(int justify)
                                throws InvalidWriteTimingException,
                                       IllegalArgumentException

Change the horizontal justification of the text.

Parameters:

justify - One of the JUSTIFY_ values

Throws:

IllegalArgumentException - The value was not valid

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener bounds callback method

getHorizontalJustification

public float getHorizontalJustification()

Get the value of the line size multiplier.

Returns:

A value greater than zero

setVerticalJustification

public void setVerticalJustification(int justify)
                              throws InvalidWriteTimingException,
                                     IllegalArgumentException

Change the vertical justification of the text.

Parameters:

justify - One of the JUSTIFY_ values

Throws:

IllegalArgumentException - The value was not valid

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener bounds callback method

getVerticalJustification

public float getVerticalJustification()

Get the value of the line size multiplier.

Returns:

A value greater than zero

compareTo

public int compareTo(Text2D txt)

Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Parameters:

txt - The argument instance to be compared

Returns:

-1, 0 or 1 depending on order

equals

public boolean equals(Text2D txt)

Compares this object with the specified object to check for equivalence.

Parameters:

txt - The Text2D instance to be compared

Returns:

true if the objects represent identical values