org.j3d.renderer.java3d.geom
Class RasterTextLabel

java.lang.Object
  javax.media.j3d.SceneGraphObject
      javax.media.j3d.Node
          javax.media.j3d.Leaf
              javax.media.j3d.Shape3D
                  org.j3d.renderer.java3d.geom.RasterTextLabel

public class RasterTextLabel

extends javax.media.j3d.Shape3D

A text label for labelling objects on screen that uses a Java 3D Raster to produce the overlay effect.

If the label text is null, then no label will be displayed. All of the setup will be done, but no raster will be created.

The text label can come in a number of flavours depending on how you configure it through the constructors. You may build a label that is only static, always fixed size regardless of text length, and/or may be hidden from other objects v always on the top. Once configured to one of these versions, it cannot be changed.

If running dynamic text, the internal images will only resize to a larger size. That is, if a new string comes in that is smaller than the original string, the image will stay the larger length than the original. The idea is to reduce the amount of garbage generated. However, in some instances this may not produce acceptable visual behaviour, so the crop() method is introduced that will force the image size to be reduced to the smallest possible size for the next time a string is set. There are also variants on the setText() methods to do this as well with a flag. Cropping is independent of the fixedSize flag but is still subject to the dynamic flag on the constructor.

Version:

$Revision: 1.1 $

Author:

Justin Couch

Field Summary

Fields inherited from class javax.media.j3d.Shape3D

ALLOW_APPEARANCE_OVERRIDE_READ, ALLOW_APPEARANCE_OVERRIDE_WRITE, ALLOW_APPEARANCE_READ, ALLOW_APPEARANCE_WRITE, ALLOW_COLLISION_BOUNDS_READ, ALLOW_COLLISION_BOUNDS_WRITE, ALLOW_GEOMETRY_READ, ALLOW_GEOMETRY_WRITE

Fields inherited from class javax.media.j3d.Node

ALLOW_AUTO_COMPUTE_BOUNDS_READ, ALLOW_AUTO_COMPUTE_BOUNDS_WRITE, ALLOW_BOUNDS_READ, ALLOW_BOUNDS_WRITE, ALLOW_COLLIDABLE_READ, ALLOW_COLLIDABLE_WRITE, ALLOW_LOCAL_TO_VWORLD_READ, ALLOW_PICKABLE_READ, ALLOW_PICKABLE_WRITE, ENABLE_COLLISION_REPORTING, ENABLE_PICK_REPORTING

Constructor Summary

RasterTextLabel()
Create a new blank label with no text.

RasterTextLabel(java.lang.String label, java.awt.Color col)
Create a new blank label with the given text located at the origin.

RasterTextLabel(java.lang.String label, java.awt.Color col, boolean alwaysOnTop)
Create a new blank label with the given text located at the origin.

RasterTextLabel(java.lang.String label, java.awt.Color col, boolean alwaysOnTop, boolean dynamic)
Create a new blank label with the given text located at the origin.

RasterTextLabel(java.lang.String label, java.awt.Color col, boolean alwaysOnTop, boolean dynamic, float x, float y, float z)
Create a new blank label with the given text located at a specific point in 3D world coordinates.

RasterTextLabel(java.lang.String label, java.awt.Color col, boolean alwaysOnTop, boolean dynamic, float x, float y, float z, java.awt.Color border, java.awt.Font font)
Create a new blank label with the given text located at a specific point in 3D world coordinates and an option to show a border and selected font.

RasterTextLabel(java.lang.String label, java.awt.Color col, boolean alwaysOnTop, float x, float y, float z)
Create a new blank label with the given text located at a specific point in 3D world coordinates.

Method Summary

void	crop() Crop the image used for the raster to the length of the string the next time a string is set.
void	fixSize(boolean fixed) Set the condition of whether the implementation should resize the canvas after each new label is set or just stick to a fixed size canvas.
void	setText(java.lang.String text) Set the label string that is to be rendered.
void	setText(java.lang.String text, boolean crop) Set the label string that is to be rendered with the option of croping it to the length of the string.
void	setText(java.lang.String text, java.awt.Color col) Set the label string that is to be rendered and changes the color to the new value.
void	setText(java.lang.String text, java.awt.Color col, boolean crop) Set the label string that is to be rendered and changes the color to the new value.

Methods inherited from class javax.media.j3d.Shape3D

addGeometry, cloneNode, duplicateNode, getAllGeometries, getAppearance, getAppearanceOverrideEnable, getBounds, getCollisionBounds, getGeometry, getGeometry, indexOfGeometry, insertGeometry, intersect, intersect, intersect, numGeometries, removeAllGeometries, removeGeometry, removeGeometry, setAppearance, setAppearanceOverrideEnable, setCollisionBounds, setGeometry, setGeometry

Methods inherited from class javax.media.j3d.Node

cloneTree, cloneTree, cloneTree, cloneTree, cloneTree, cloneTree, getBoundsAutoCompute, getCollidable, getLocalToVworld, getLocalToVworld, getParent, getPickable, setBounds, setBoundsAutoCompute, setCollidable, setPickable

Methods inherited from class javax.media.j3d.SceneGraphObject

clearCapability, clearCapabilityIsFrequent, duplicateSceneGraphObject, getCapability, getCapabilityIsFrequent, getUserData, isCompiled, isLive, setCapability, setCapabilityIsFrequent, setUserData, updateNodeReferences

Methods inherited from class java.lang.Object

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

Constructor Detail

RasterTextLabel

public RasterTextLabel()

Create a new blank label with no text. It is located at the origin. It is assumed to be dynamic and always on top.

RasterTextLabel

public RasterTextLabel(java.lang.String label,
                       java.awt.Color col)

Create a new blank label with the given text located at the origin. If the text color is not specified, white is used and the code assumes static text, it will always be on top.

Parameters:

label - The string to use on the label

col - The text color to be drawn in

RasterTextLabel

public RasterTextLabel(java.lang.String label,
                       java.awt.Color col,
                       boolean alwaysOnTop)

Create a new blank label with the given text located at the origin. If the text color is not specified, white is used and the code assumes static text, it will always be on top.

Parameters:

label - The string to use on the label

col - The text color to be drawn in

alwaysOnTop - true if this should never be obscured by content

RasterTextLabel

public RasterTextLabel(java.lang.String label,
                       java.awt.Color col,
                       boolean alwaysOnTop,
                       boolean dynamic)

Create a new blank label with the given text located at the origin. If the text color is not specified, white is used.

Parameters:

label - The string to use on the label

col - The text color to be drawn in

dynamic - True if this will change text over time

alwaysOnTop - true if this should never be obscured by content

RasterTextLabel

public RasterTextLabel(java.lang.String label,
                       java.awt.Color col,
                       boolean alwaysOnTop,
                       float x,
                       float y,
                       float z)

Create a new blank label with the given text located at a specific point in 3D world coordinates. The code assumes a static label.

Parameters:

label - The string to use on the label

col - The text color to be drawn in

alwaysOnTop - true if this should never be obscured by content

x - The x world coordinate to place the label

y - The y world coordinate to place the label

z - The z world coordinate to place the label

RasterTextLabel

public RasterTextLabel(java.lang.String label,
                       java.awt.Color col,
                       boolean alwaysOnTop,
                       boolean dynamic,
                       float x,
                       float y,
                       float z)

Create a new blank label with the given text located at a specific point in 3D world coordinates.

Parameters:

label - The string to use on the label

col - The text color to be drawn in

x - The x world coordinate to place the label

y - The y world coordinate to place the label

z - The z world coordinate to place the label

alwaysOnTop - true if this should never be obscured by content

dynamic - True if this will change text over time

RasterTextLabel

public RasterTextLabel(java.lang.String label,
                       java.awt.Color col,
                       boolean alwaysOnTop,
                       boolean dynamic,
                       float x,
                       float y,
                       float z,
                       java.awt.Color border,
                       java.awt.Font font)

Create a new blank label with the given text located at a specific point in 3D world coordinates and an option to show a border and selected font. If the border color is specified, it will show a 1 pixel wide border in that color. If no font is defined, the system default font will be used.

Parameters:

label - The string to use on the label

col - The text color to be drawn in

x - The x world coordinate to place the label

y - The y world coordinate to place the label

z - The z world coordinate to place the label

border - The color to use for the border or null for none

font - The font to draw the string in or null for default

dynamic - True if this will change text over time

Method Detail

setText

public void setText(java.lang.String text)
             throws java.lang.IllegalStateException

Set the label string that is to be rendered. This maintains the current text color. If this was not set up to be a dynamic image, an exception is thrown.

Parameters:

text - The string to be rendered

Throws:

java.lang.IllegalStateException - The label was not set up to be dynamic in the constructor

setText

public void setText(java.lang.String text,
                    boolean crop)
             throws java.lang.IllegalStateException

Set the label string that is to be rendered with the option of croping it to the length of the string. This maintains the current text color. If this was not set up to be a dynamic image, an exception is thrown.

Parameters:

text - The string to be rendered

crop - true to crop the underlying raster

Throws:

java.lang.IllegalStateException - The label was not set up to be dynamic in the constructor

setText

public void setText(java.lang.String text,
                    java.awt.Color col)
             throws java.lang.IllegalStateException

Set the label string that is to be rendered and changes the color to the new value. If this was not set up to be a dynamic image, an exception is thrown.

Parameters:

text - The string to be rendered

col - The new color to be used or null for the default (white)

Throws:

java.lang.IllegalStateException - The label was not set up to be dynamic in the constructor

setText

public void setText(java.lang.String text,
                    java.awt.Color col,
                    boolean crop)
             throws java.lang.IllegalStateException

Set the label string that is to be rendered and changes the color to the new value. If this was not set up to be a dynamic image, an exception is thrown.

Parameters:

text - The string to be rendered

col - The new color to be used or null for the default (white)

crop - true to crop the underlying raster

Throws:

java.lang.IllegalStateException - The label was not set up to be dynamic in the constructor

fixSize

public void fixSize(boolean fixed)
             throws java.lang.IllegalStateException

Set the condition of whether the implementation should resize the canvas after each new label is set or just stick to a fixed size canvas. A fixed size label is useful when you are making fast updates such as a counter. When this is called, the label will not be resized from it's current dimensions. This may be changed dynamically and will only take effect next time a text string is set and the size is based on the biggest image used to date, not on the next string that is set.

Parameters:

fixed - true if the label size should remain fixed

Throws:

java.lang.IllegalStateException - The label was not set up to be dynamic in the constructor

crop

public void crop()
          throws java.lang.IllegalStateException

Crop the image used for the raster to the length of the string the next time a string is set. This will not crop the current string, only the next one.

Throws:

java.lang.IllegalStateException - The label was not set up to be dynamic in the constructor