public interface Tool
Tools are attatched to a SceneGraphComponent and are intended to
to perform interactive changes to the scene - usually driven by
user input. The corresponding methods are
activate(ToolContext),
perform(ToolContext) and deactivate(ToolContext).
User input is passed to the Tool either as an AxisState, which represents
a double value (i.e. a mouse button position) or a DoubleArray of length 16, which
represents a 4 by 4 matrix. This matrix typically represents a euclidean
isometry that represents the original user input converted into a suitable coordinate
system. (Tool writers for non-euclidean settings need to be careful to convert
these matrices if necessary.)
These inputs are called virtual devices,
since they are usually hardware independent and "live in the scene".
These virtual devices are mapped to InputSlots,
which should represent them under a meaningful name. Some examples (which
are available in the default configuration file toolconfig.xml):
"PointerTransformation" A pointer device in scene coordinates.
On a desktop this represents the mouse pointer as a free vector whose base
point is on the near clipping plane, and whose direction points away from the camera;
in a traditional immersive environment this would be the actual 3D position and
direction of the wand. Both are represented by 4x4 matrices as indicated above.
The direction of the pointer is the -Z axis.[steffen: is this last sentence correct, or only
for non-perspective cameras?]"PrimaryActivation" An axis state used for default interaction
with the scene. On a desktop per default it is the left mouse button;
in the Portal the left wand button."SystemTime" is an axis state which is permanently triggered.
The intValue() of its AxisState gives the time in milli-seconds since the
last emission of the SystemTime device.
Tools may be always active or activated by some virtual device.
A Tool which is not always active (getActivationSlot() returns
not null) will be activated as soon as one of its activation slots reaches
the state AxisState.PRESSED. Warning: If the activation slot does not
represent an AxisState, the tool will never become active.
A single Tool instance can be attached to different scene graph components. A tool
attached to a scene graph component that appears at multiple positions in the scene graph
will also, implicitly, be instanced multiple times; each instance will have its own local state
not shared with other instances. [steffen: is this right?] The current path is
always available via the ToolContext: de.jreality.scene.tool.ToolContext.getRootToLocal()
and de.jreality.scene.tool.ToolContext.getRootToToolComponent()
return the paths for the current activate(ToolContext)/perform(ToolContext)/
deactivate(ToolContext) call.
| Modifier and Type | Method and Description |
|---|---|
void |
activate(ToolContext tc)
This method is called when the tool gets activated.
|
void |
deactivate(ToolContext tc)
this method is called when the tool was activate and the
AxisState of the activation slot changes to AxisState.RELEASED - to zero.
|
List<InputSlot> |
getActivationSlots()
If the result is empty, then the tool is always active.
|
List<InputSlot> |
getCurrentSlots()
This method will only be called for active tools.
|
String |
getDescription()
Gives an overall description of this Tool.
|
String |
getDescription(InputSlot slot)
Gives a description of the meaning of the given InputSlot.
|
void |
perform(ToolContext tc)
This method is called when the tool is activated and any
AxisState or TransformationMatrix of the current slots changes.
|
List<InputSlot> getActivationSlots()
InputSlots must be associated to
AxisStates, otherwise the Tool will never become active.
AxisState.RELEASED.
Tools down the path.
The result must remain constant.List<InputSlot> getCurrentSlots()
activate(..)
or perform(..).void activate(ToolContext tc)
tc - The current tool contextvoid perform(ToolContext tc)
tc - The current tool contextvoid deactivate(ToolContext tc)
tc - The current tool contextString getDescription(InputSlot slot)
slot - to describeString getDescription()