gumbo.graphic.probe
Interface PickEngine

All Superinterfaces:

Graphic

All Known Implementing Classes:

AbstractPickEngine

public interface PickEngine

extends Graphic

An interface for a strategy implementing a "pull" style of pick operation. The engine can be stateless since all picking data must be provided for each pick operation (the shape and control of the picker and pickable are outside the scope of this interface). A pick operation, unlike an intersection operation (see IntersectionEngine), produces a pick result containing information about each hit.

The pick engine is responsible for verifying picker and pickable types for compatibility, and for compiling the pick result according to the pick specifications. If multiple picker and pickable types are available pick specs can provide guidance as to which ones to use.

In a "pull" system, such as Java 3D, the client invokes pick operations on the graphic system, as opposed to a "push" system, such as Swing, where the client is notified by the graphic system that a target has been picked. Typically, one form can be readily translated into the other. TODO: Should a pick engine work only with SpaceNode pickers and pickables, with hits being Interactor? TODO: Should allowable hits also be provided to the pick engine?

Version:

$Revision: 1.2 $

Author:

Jon Barrilleaux (jonb@jmbaai.com) of JMB and Associates Inc.

Method Summary

PickResult

doGraphicPick(java.util.Set specs, java.util.Collection pickers, java.util.Collection pickables) Performs a pick operation on a group of pickable objects using a group of picker objects, and returns a pick result that conforms to the pick specs.

Methods inherited from interface gumbo.graphic.Graphic

getGraphic

Method Detail

doGraphicPick

public PickResult doGraphicPick(java.util.Set specs,
                                java.util.Collection pickers,
                                java.util.Collection pickables)

Performs a pick operation on a group of pickable objects using a group of picker objects, and returns a pick result that conforms to the pick specs. Typically, the result contains the hits from all pickers, and as much of the requested hit information as is readily and efficiently available.

Parameters:

specs - Flags (Picks.PICK_???, Picks.HIT_???) specifying the pick operation and its result. Never null. PICK_??? flag compliance is mandatory. HIT_??? flag compliance is typically optional.

pickers - Group of pickers (Object). Never null. If empty, no hits. A picker's reference space is assumed to be absolute or natively defined unless it implements GraphicGeometry.

pickables - Group of pickables (Object). Never null. If empty, no hits. A pickable's reference space is assumed to be absolute or natively defined unless it implements GraphicGeometry.

Returns:

New pick result. Null if the pick operation is benignly invalid (picking is inactive) or should be ignored (consumed by the native graphic system).

Throws:

java.lang.UnsupportedOperationException - A picker's type is incompatible.