shout3d.core
Interface Picker

public abstract interface Picker

An interface which represents a Picker and provides required methods.

Field Summary

static int	MATRIX
static int	NORMAL
static int	POINT
static int	POLYGON_INDEX

Method Summary

float[]	getFromPoint() Returns a reference to the world-space "from" point used in the last pick.
Node[]	getPath() Returns the last path given to this Picker using setPath().
float[]	getPickInfo(int which) Gets any info that was requested (prior to performing the pick) by setting flags in setPickInfo.
Node[]	getPickPath() Returns path to the last picked node.
int	getPixelX() Returns x location of last pixel used to pick.
int	getPixelY() Returns y location of last pixel used to pick.
boolean	getProjectedBounds(Node[] pathToNode, boolean fineGrain, float[] bounds) Projects the bounding box of the node at the end of pathToNode to screen space.
boolean	getProjectedBoundsByNode(Node node, boolean fineGrain, float[] bounds) Just like getProjectedBounds(), except that only a single node is provided as argument instead of a path.
boolean	getProjectedPixel(Node[] pathToNode, float[] localSpaceCoord, float[] pixel) Projects a point in the scene back out onto the picture plane and returns the corresponding pixel value.
boolean	getProjectedPixelByNode(Node node, float[] localSpaceCoord, float[] pixel) Just like getProjectedPixel(), except that only a single node is provided as argument instead of a path.
Node	getScene() Returns the root of the scene being used for picks.
float[]	getToPoint() Returns a reference the "to" point used in the last pick.
void	getWorldRay(int x, int y, float[] from, float[] to) Calculates the worldspace ray from the currently bound viewpoint through the given pixel.
boolean	isPickPixelBased() Returns whether the last pick was done based on a pixel location or a pair of 3D from/to coordinates.
boolean	pickAny(int x, int y) Given a pixel coordinate assumed to be in the viewer's window, returns a boolean stating whether any geometry in the scene was intersected by the ray from the eyepoint through the pixel.
boolean	pickAnyFromTo(float[] from, float[] to) Given a ray described as going from the 'from' point and towards the 'to' point, returns a boolean stating whether any geometry in the scene was intersected by the ray.
Node[]	pickClosest(int x, int y) Given a pixel coordinate assumed to be in the viewer's window, constructs a ray from the location of the viewer's currently bound Viewpoint, then intersects.
Node[]	pickClosestFromTo(float[] from, float[] to) Given a ray described as going from the 'from' point and towards the 'to' point, intersects that ray.
void	setPath(Node[] path) Establishes a new path for the picker to usre for ray intersection.
void	setPickInfo(int which, boolean doCalculation) Tells the Picker which information it needs to collect as it traverses the scene graph in order to Pick.
void	setScene(Node root) Establishes a new scene graph for the picker to use for ray intersection.
boolean	wasPicked(Node node) After performing a pick, this returns true if the given node was on the path to the pick.

Field Detail

POINT

public static final int POINT

NORMAL

public static final int NORMAL

MATRIX

public static final int MATRIX

POLYGON_INDEX

public static final int POLYGON_INDEX

Method Detail

setPickInfo

public void setPickInfo(int which,
                        boolean doCalculation)

Tells the Picker which information it needs to collect as it traverses the scene graph in order to Pick.

Parameters:

which - the flag indicating which info the user is specifying (POINT, NORMAL, or MATRIX)

doCalculation - whether this Picker should collect which's info

setScene

public void setScene(Node root)

Establishes a new scene graph for the picker to use for ray intersection. By default, intersects with the associated viewer's scene. This method overrides that default Note: setting this does NOT look for the given root below the viewers scene and attempt to pick that sub-scene. For that behavior, construct a path from the viewer's scene root down to the desired node sub-scene-root and pass that path to this interface's setPath() method.

Parameters:

root - the root of the scene to pick

getScene

public Node getScene()

Returns the root of the scene being used for picks. If setScene() has been called, then the node at the root of that scene will be returned. Otherwise, the root of the viewer's scene will be returned.

Returns:

the scene

setPath

public void setPath(Node[] path)

Establishes a new path for the picker to usre for ray intersection. Attempts1 only to intersect the ray with nodes at or below the leaf (final) node of the path. Other nodes in the path are used only to collect tranfsormation information, by calling getMatrix on Group nodes along the path. By default, the picker intersects with the associated viewer's scene. This method overrides that default.

Parameters:

path - the path to the subgraph to pick

getPath

public Node[] getPath()

Returns the last path given to this Picker using setPath(). Returns null if setPath() was never called, or if setScene() was called since the last call to setScene()

Returns:

the path

pickAny

public boolean pickAny(int x,
                       int y)

Given a pixel coordinate assumed to be in the viewer's window, returns a boolean stating whether any geometry in the scene was intersected by the ray from the eyepoint through the pixel. When this method is used, no pickInfo (POINT, NORMAL, or MATRIX) may be retrieved afterward.

Parameters:

x - the pixel's x coordinate

y - the pixel's y coordinate

Returns:

whether the ray hits anything

pickAnyFromTo

public boolean pickAnyFromTo(float[] from,
                             float[] to)

Given a ray described as going from the 'from' point and towards the 'to' point, returns a boolean stating whether any geometry in the scene was intersected by the ray. When this method is used, no pickInfo (POINT, NORMAL, or MATRIX) may be retrieved afterward.

Parameters:

from - the from point of the given ray

to - the to point of the given ray

Returns:

whether the ray hits anything

pickClosest

public Node[] pickClosest(int x,
                          int y)

Given a pixel coordinate assumed to be in the viewer's window, constructs a ray from the location of the viewer's currently bound Viewpoint, then intersects. Returns a path to the geometry node below the scene root that is intersected by the ray at a point closer to the current Viewpoint's position than any other geometry below the scene root. If no geometry below the scene root is intersected by the ray, returns null.

Parameters:

x - the pixel's x coordinate

y - the pixel's y coordinate

Returns:

the path to the picked node or null if nothing is picked.

pickClosestFromTo

public Node[] pickClosestFromTo(float[] from,
                                float[] to)

Given a ray described as going from the 'from' point and towards the 'to' point, intersects that ray. Returns a path to the geometry node below the scene root that is intersected by the ray at a point closer to the 'from' point than any other geometry below the scene root. If no geometry below the scene root is intersected by the ray, returns null.

Parameters:

from - the from point of the given ray

to - the to point of the given ray

Returns:

the path to the picked node or null if nothing is picked.

wasPicked

public boolean wasPicked(Node node)

After performing a pick, this returns true if the given node was on the path to the pick.

Parameters:

node - the node to look for on the pick path

Returns:

true if the node is on the path, false otherwise

getPickInfo

public float[] getPickInfo(int which)
                    throws Shout3DException

Gets any info that was requested (prior to performing the pick) by setting flags in setPickInfo. Must be called after the pick has been performed. Note: Normal is undefined for lines and points.

Parameters:

which - the info to receive

getPickPath

public Node[] getPickPath()

Returns path to the last picked node.

isPickPixelBased

public boolean isPickPixelBased()

Returns whether the last pick was done based on a pixel location or a pair of 3D from/to coordinates.

Returns:

true if pick was based on a pixel, false if it was based on a from/to pair

getPixelX

public int getPixelX()

Returns x location of last pixel used to pick.

Returns:

x pixel

getPixelY

public int getPixelY()

Returns y location of last pixel used to pick.

Returns:

y pixel

getFromPoint

public float[] getFromPoint()

Returns a reference to the world-space "from" point used in the last pick. If the last pick was done using pickClosestFromTo(), then this returns the given "from" point. If the last pick was done based on a pixel, then this returns the location of the camera in world space.

Returns:

the "from" point.

getToPoint

public float[] getToPoint()

Returns a reference the "to" point used in the last pick. If the last pick was done using pickClosestFromTo(), then this returns the given "to" point. If the last pick was done based on a pixel, then this returns a point which, when used in combination with the worldspace camera location, provides a worldspace ray equivalent to the one passing from the camera through the given pixel, where that pixel maps to a location on the worldspace view plane.

Returns:

the "to" point.

getWorldRay

public void getWorldRay(int x,
                        int y,
                        float[] from,
                        float[] to)

Calculates the worldspace ray from the currently bound viewpoint through the given pixel. The "from" and "to" arguments must be preallocated triplets. The "from" argument will be filled with the worldspace location of the viewpoint. The "to" argument will be filled with a point in the direction of the pixel from the viewpoint, one unit away.

Parameters:

x - the x pixel location

y - the y pixel location

from - the from point of the calculated ray

to - the to point of the calculated ray

getProjectedPixel

public boolean getProjectedPixel(Node[] pathToNode,
                                 float[] localSpaceCoord,
                                 float[] pixel)

Projects a point in the scene back out onto the picture plane and returns the corresponding pixel value. Calculates the pixel point corresponding to the given local space point as expressed in the coordinate frame of pathToNode. The first node in pathToNode should be the same node as the root of the scene used in setScene(), (or the same as the first node in the path used in setPath() if setPath() was used). The "pixel" argument should be a preallocated array of 2 floats. While pixels are normally expressed as int values, floats are used since the better accuracy is available within the context of back-projected points from the world to the picture plane. Returns true if the given point lies within the view, false otherwise.

Parameters:

pathToNode - the path to the node in whose space the localSpaceCoord is expressed.

localSpaceCoord - the coordinate to be projected

pixel - the projected 2D screenspace point

Returns:

whether the point lies within the field of view.

getProjectedPixelByNode

public boolean getProjectedPixelByNode(Node node,
                                       float[] localSpaceCoord,
                                       float[] pixel)

Just like getProjectedPixel(), except that only a single node is provided as argument instead of a path. In this case, the Picker will search for the first instance of that node and return the result based on the space of that first instance. If no instance of the node is found in the scene, then the pixel parameter will not be filled with a result. Returns true if the given point lies within the view, false otherwise.

Parameters:

node - the node in whose space the localSpaceCoord is expressed.

localSpaceCoord - the coordinate to be projected

pixel - the projected 2D screenspace point

Returns:

whether the point lies within the field of view.

getProjectedBounds

public boolean getProjectedBounds(Node[] pathToNode,
                                  boolean fineGrain,
                                  float[] bounds)

Projects the bounding box of the node at the end of pathToNode to screen space. The results will lie within the range of the pixels in the applet, and are put in the bounds parameter as 4 values: xmin, ymin, xmax, ymax If fineGrain is false then only the 8 corners of the bbox are tested. This gives a rough approximation. If fineGrain is true, then each coordinate below the end of the path will be individually projected to screen for inclusion in the bounding box. This takes longer but gives more accurate results. Returns true if any of the given node lies within the view, false otherwise.

Parameters:

pathToNode - the path to the node whose bounds are sought.

fineGrain - whether the bounds should be based on finegrain calculations.

bounds - the calculated bounds of the node.

Returns:

whether the point lies within the field of view.

getProjectedBoundsByNode

public boolean getProjectedBoundsByNode(Node node,
                                        boolean fineGrain,
                                        float[] bounds)

Just like getProjectedBounds(), except that only a single node is provided as argument instead of a path. In this case, the Picker will search for the first instance of that node and return the result based on the space of that first instance. If no instance of the node is found in the scene, then the pixel parameter will not be filled with a result. Returns true if any of the given node lies within the view, false otherwise.

Parameters:

node - the node whose bounds are sought.

fineGrain - whether the bounds should be based on finegrain calculations.

bounds - the calculated bounds of the node.

Returns:

whether the point lies within the field of view.