yaarq.sys
Class yrqFrame

java.lang.Object
  |
  +--yaarq.sys.yrqFrame

public class yrqFrame
extends java.lang.Object

This class serves as a transformable root to which other frames or visuals can be added. Frames build the Yaarq engines internal scene graph.

A frame is attached to the root frame kept internally by the engine, or to another frame. Frames can only be attached or detached at live-time when the root frame has been detached from the scene graph. It is common practice to construct complex objects from a root frame on, and to attach that root frame to the engine when needed.

Visuals can be added to frames to provide geometry to be displayed at the position and with the orientation provided by the frame. BasicVisuals and EffectVisuals can be added, the other visual types have to be added to defined roots in the engine class.

Frames provide support for animation. Animation keys can be stored in a frame under a name. At runtime, applications can set the desired target animation key and a frame will seamlessly transit from its current transform state to the target state. Another option is to set two animation keys, a source and a target: A frame will seamlessly transform from source to target in this case. Finally, setting an array of animation keys to create an animation path is supported. TODO: Incorporate rotation into setting anikeys, provide methods for translating, moving and rotation the frame without animation key (extend the relative/absolute approach)


Constructor Summary
yrqFrame()
          Constructs a new, empty instance
 
Method Summary
 void addAnimationKey(java.lang.String a_name, com.sun.j3d.utils.behaviors.interpolators.KBKeyFrame a_key)
          This method adds a new animation key to the frame.
 void addChild(java.lang.String a_name, yrqFrame a_child)
          This method adds a yrqFrame instance as a child to this frame.
 void addVisual(java.lang.String a_name, yrqVisual a_visual)
          This method adds a visual to the frame.
 void attach(javax.media.j3d.BranchGroup a_group)
          This method attaches the frame to a parent.
 void attach(javax.media.j3d.BranchGroup a_group, javax.media.j3d.BranchGroup a_root)
          This method attaches the frame to a parent and sets the root branch so that the frame can detach itself at runtime.
 void attach(javax.media.j3d.TransformGroup a_group)
          This method attaches the frame to a parent.
 void clearAnimationKeys()
          This method clears all animation keys from the key list.
 void clearVisuals()
          This method clears all visuals from the hierarchy, detaching them in the process.
 void compile()
          This function compiles the local branch graph of the frame It is automatically called by the engine before a frame is attached to the scene root.
 void detach()
          This method detaches the frame from its current parent.
 javax.vecmath.Vector3d getAbsoluteDirection()
          This function retrieves the absolute direction, as a unit vector, of this frame in world coordinates.
 javax.vecmath.Point3d getAbsolutePosition()
          This function retrieves the location of the center of the frame in world coordinates.
 com.sun.j3d.utils.behaviors.interpolators.KBKeyFrame getAnimationKey(java.lang.String a_name)
          This method retrieves an animationkey by name
 yrqFrame getChild(java.lang.String a_name)
          This function returns a child frame specified by name, or null if no child exists under the given name.
 javax.media.j3d.TransformGroup getInternalGroup()
          This function returns the frames internal transform group.
 javax.media.j3d.Group getParent()
          This function returns the parent group this frame is currently attached to or null, if it isnt attached to a group.
 javax.vecmath.Vector3d getRelativeDirection()
          This function retrieves the relative direction, as a unit vector, of this frame in local coordinates.
 javax.vecmath.Point3d getRelativePosition()
          This function retrieves the location of the center of the frame in local coordinates.
 yrqVisual getVisual(java.lang.String a_name)
          This method retrieves a visual which has been added to the frame by its name.
 java.util.Iterator getVisuals()
          This method returns an iterator over all visuals attached to this frame .
 void removeAnimationKey(com.sun.j3d.utils.behaviors.interpolators.KBKeyFrame a_key)
          This method removes an animation key by reference
 void removeAnimationKey(java.lang.String a_name)
          This method removes an animation key by name
 void removeChild(java.lang.String a_name)
          This method removes a yrqFrame instance From this frame.
 void removeChild(yrqFrame a_frame)
          This method removes a yrqFrame instance From this frame.
 void removeVisual(java.lang.String a_name)
          This method removes a visual specified by name from the frame.
 void setAnimationKey(java.lang.String a_name)
          This method sets the target animation key for the frame and all its hierarchical children which have inheritance enabled and have a key of the same name assigned.
 void setAnimationSequence(java.lang.String[] a_keyName)
          This method sets an animation key sequence for frame and all its hierarchical children which have inheritance enabled and have keys of the same name assigned.
 void setAnimationSequence(java.lang.String a_srcname, java.lang.String a_dstname)
          This method sets source and target animation key for frame and all its hierarchical children which have inheritance enabled and have a key of the same name assigned.
 void setAnimationTime(float a_time)
          This method sets the time in the animation from source to target animation key.
 void setRelativeLookat(javax.vecmath.Point3d a_position, javax.vecmath.Point3d a_target)
          This method sets the location and orientation of the frame relatively to its parent by using a look-at from the given camera to the given target.
 void setRelativeLookat(javax.vecmath.Point3d a_position, javax.vecmath.Point3d a_target, javax.vecmath.Vector3d a_up)
          This method sets the location and orientation of the frame relatively to its parent by using a look-at from the given camera to the given target.
 void setRelativePosition(javax.vecmath.Point3d a_position)
          This method sets the location of the center of the frame relatively to its parent.
 void setRelativeRotation(javax.vecmath.AxisAngle4d a_angle)
          This method sets the rotation of the frame relatively to its parent.
 void setSize(double a_size)
          ..
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

yrqFrame

public yrqFrame()
Constructs a new, empty instance

Method Detail

addAnimationKey

public void addAnimationKey(java.lang.String a_name,
                            com.sun.j3d.utils.behaviors.interpolators.KBKeyFrame a_key)
This method adds a new animation key to the frame. The yaarq engine uses KB keyframes supporting tcb parameters.

Parameters:
a_name - The name under which to add the key
a_key - The animationkey

addChild

public void addChild(java.lang.String a_name,
                     yrqFrame a_child)
This method adds a yrqFrame instance as a child to this frame. The instance is automatically attached to the local transform group.

Children can only be added to a frame as long as it isnt attached to the engine by adding it, or its parent hierarchy, to the engine.

Parameters:
a_name - The name under which to add the frame
a_child - The frame to be added

addVisual

public void addVisual(java.lang.String a_name,
                      yrqVisual a_visual)
This method adds a visual to the frame. Added visuals are automatically attached to the frame.

Visuals added to the viewport frame are automatically moved with the viewport: OverlayVisuals and FlareVisuals should be added to the viewport frame to achieve their functionallity.

Visuals added to frames attached to the engine are automatically moved with their respective frames. BasicVisuals and EffectVisuals should be added to engine-frames to form world objects.

Visuals can only be added to a frame as long as it isnt attached to the engine by adding it, or its parent hierarchy, to the engine.

Parameters:
a_name - The name under which to add the visual
a_visual - The visual to be added

attach

public void attach(javax.media.j3d.BranchGroup a_group)
This method attaches the frame to a parent.

Parameters:
a_group - The branch group to which to attach

attach

public void attach(javax.media.j3d.BranchGroup a_group,
                   javax.media.j3d.BranchGroup a_root)
This method attaches the frame to a parent and sets the root branch so that the frame can detach itself at runtime. Setting the root branch enables manipulation of frame content. The frame will automatically take the root branch offline before any modifications normally not allowed at runtime, and will take the root branch online again afterwards.

Parameters:
a_group - The branch group to which to attach
a_root - The root to which the frame's parent is attached

attach

public void attach(javax.media.j3d.TransformGroup a_group)
This method attaches the frame to a parent.

Parameters:
a_group - The transform group to which to attach

clearAnimationKeys

public void clearAnimationKeys()
This method clears all animation keys from the key list.


clearVisuals

public void clearVisuals()
This method clears all visuals from the hierarchy, detaching them in the process.


compile

public void compile()
This function compiles the local branch graph of the frame It is automatically called by the engine before a frame is attached to the scene root.


detach

public void detach()
This method detaches the frame from its current parent.


getAbsoluteDirection

public javax.vecmath.Vector3d getAbsoluteDirection()
This function retrieves the absolute direction, as a unit vector, of this frame in world coordinates.

Returns:
The direction of the frame in world coords

getAbsolutePosition

public javax.vecmath.Point3d getAbsolutePosition()
This function retrieves the location of the center of the frame in world coordinates.

Returns:
The center of the frame in world coordinates

getAnimationKey

public com.sun.j3d.utils.behaviors.interpolators.KBKeyFrame getAnimationKey(java.lang.String a_name)
This method retrieves an animationkey by name

Parameters:
a_name - The name of the desired key
Returns:
The key having the given name, or null if no key has been found

getChild

public yrqFrame getChild(java.lang.String a_name)
This function returns a child frame specified by name, or null if no child exists under the given name.

Returns:
The desired child frame

getInternalGroup

public javax.media.j3d.TransformGroup getInternalGroup()
This function returns the frames internal transform group.

Returns:
the transformgroup of the frame.

getParent

public javax.media.j3d.Group getParent()
This function returns the parent group this frame is currently attached to or null, if it isnt attached to a group.

Returns:
The group to which the frame is attached.

getRelativeDirection

public javax.vecmath.Vector3d getRelativeDirection()
This function retrieves the relative direction, as a unit vector, of this frame in local coordinates.

Returns:
The direction of the frame in local coords

getRelativePosition

public javax.vecmath.Point3d getRelativePosition()
This function retrieves the location of the center of the frame in local coordinates.

Returns:
The center of the frame in local coordinates

getVisual

public yrqVisual getVisual(java.lang.String a_name)
This method retrieves a visual which has been added to the frame by its name.

Parameters:
a_name - The name of the visual to be retrieved
Returns:
the desired visual

getVisuals

public java.util.Iterator getVisuals()
This method returns an iterator over all visuals attached to this frame .

Returns:
an iterator over all visuals in this frame

removeAnimationKey

public void removeAnimationKey(com.sun.j3d.utils.behaviors.interpolators.KBKeyFrame a_key)
This method removes an animation key by reference

Parameters:
a_key - The key to remove

removeAnimationKey

public void removeAnimationKey(java.lang.String a_name)
This method removes an animation key by name

Parameters:
a_name - The name of the key to remove

removeChild

public void removeChild(java.lang.String a_name)
This method removes a yrqFrame instance From this frame. The instance is automatically detached from the local transform group.

Children can only be removed to a frame as long as it isnt attached to the engine by adding it, or its parent hierarchy, to the engine.

Parameters:
a_name - The name of the frame to be detached

removeChild

public void removeChild(yrqFrame a_frame)
This method removes a yrqFrame instance From this frame. The instance is automatically detached from the local transform group.

Children can only be removed to a frame as long as it isnt attached to the engine by adding it, or its parent hierarchy, to the engine.

Parameters:
a_frame - the frame to be removed

removeVisual

public void removeVisual(java.lang.String a_name)
This method removes a visual specified by name from the frame. The visual is automatically detached from the local transformgroup.

Visuals can only be added to a frame as long as it isnt attached to the engine by adding it, or its parent hierarchy, to the engine.

Parameters:
a_name - The name of the visual to be removed

setAnimationKey

public void setAnimationKey(java.lang.String a_name)
This method sets the target animation key for the frame and all its hierarchical children which have inheritance enabled and have a key of the same name assigned. The key is set as a target, and the source key is constructed of the current frame properties. Setting the animation time from 0 to 1 tranits from the source to the set target.

Parameters:
a_name - The name of the animation key to set

setAnimationSequence

public void setAnimationSequence(java.lang.String[] a_keyName)
This method sets an animation key sequence for frame and all its hierarchical children which have inheritance enabled and have keys of the same name assigned.

Parameters:
a_keyName - The names of the animation keys to set. Note: Keys must have time values assigned.

setAnimationSequence

public void setAnimationSequence(java.lang.String a_srcname,
                                 java.lang.String a_dstname)
This method sets source and target animation key for frame and all its hierarchical children which have inheritance enabled and have a key of the same name assigned.

Parameters:
a_srcname - The name of the source animation key to set
a_dstname - The name of the destination animation key

setAnimationTime

public void setAnimationTime(float a_time)
This method sets the time in the animation from source to target animation key. The time is propagated to all the frames hierarchical children which have inheritance enabled.

Parameters:
a_time - The animation time, 0-1

setRelativeLookat

public void setRelativeLookat(javax.vecmath.Point3d a_position,
                              javax.vecmath.Point3d a_target)
This method sets the location and orientation of the frame relatively to its parent by using a look-at from the given camera to the given target. Setting an animation key time overrides values set with this method.

Parameters:
a_position - The position to which to translate the object
a_target - The position towards which to orient the object

setRelativeLookat

public void setRelativeLookat(javax.vecmath.Point3d a_position,
                              javax.vecmath.Point3d a_target,
                              javax.vecmath.Vector3d a_up)
This method sets the location and orientation of the frame relatively to its parent by using a look-at from the given camera to the given target. Setting an animation key time overrides values set with this method.

Parameters:
a_position - The position to which to translate the object
a_target - The position towards which to orient the object
a_up - The up vector

setRelativePosition

public void setRelativePosition(javax.vecmath.Point3d a_position)
This method sets the location of the center of the frame relatively to its parent. Setting an animation key time overrides values set with this method.

Parameters:
a_position - The position to which to translate the object

setRelativeRotation

public void setRelativeRotation(javax.vecmath.AxisAngle4d a_angle)
This method sets the rotation of the frame relatively to its parent. Setting an animation key time overrides values set with this method.


setSize

public void setSize(double a_size)
..

Parameters:
a_size - The new relative size of the object