NAME SoRayPickAction SoRayAct "" {
intersects objects with a ray cast into scene
}

INCLUDE actions/SoRayPickAction.h

DESC {
This class performs picking by casting a ray into a scene and
performing intersection tests with each object. The ray is extended to
be a cone or cylinder, depending on the camera type, for intersection
with points and lines. Each intersection is returned as an
\cSoPickedPoint\. instance.
\p
The picking ray can be specified as either a ray from the camera
location through a particular viewport pixel, or as a world-space ray.
In the former case, a valid camera must be encountered during
traversal of the graph to determine the location of the ray in world
space.
\p
Callers can cause the action to compute all intersections along the
ray (sorted closest to farthest) by setting the \vpickAll\. flag to 
TRUE. By default, the action computes only the closest intersection.
In either case, the
intersections are returned in an \cSoPickedPointList\.. Each
intersection can be examined by accessing the appropriate
\cSoPickedPoint\. in the list. The \cSoPickedPoint\. class provides
methods to get the intersection point, normal, and other info.
}

METHOD "" SoRayPickAction(const SbViewportRegion &viewportRegion) {
Constructor takes viewport region to use for picking. Even though
the picking operation may not involve a window per se, some nodes need
this information to determine their size and placement.
}

METHOD setPt void setPoint(const SbVec2s &viewportPoint) {
Sets the viewport-space point through which the ray passes, starting
at the camera's viewpoint. Viewport coordinates range from (0,0) at
the lower left to (width-1,height-1) at the upper right.
}

METHOD setNormPt void setNormalizedPoint(const SbVec2f &normPoint) {
Sets the viewport point in normalized coordinates, which range
from (0,0) at the lower left to (1,1) at the upper right.
}

METHOD "" void setRadius(float radiusInPixels) {
Set the radius (in pixels) around the point. This is used when testing
the ray against lines and points. By default, the radius is 5 pixels.
For perspective cameras, the ray is extended to be a cone when testing
against lines and points. For orthographic cameras, the ray is
extended to be a cylinder. The radius has no effect for shapes of
other types.
}

METHOD "" void setRay(const SbVec3f &start, const SbVec3f &direction,
			float nearDistance = -1.0, float farDistance = -1.0) {
Sets a world-space ray along which to pick. The ray is defined as a
world space starting point and direction vector. The direction vector
will be normalized automatically. The last two arguments are the
parametric distances between which intersections along the ray must
occur. The distances are measured as if the direction vector is unit
length; e.g., if \anearDistance\. is 2.0, the intersection must occur
past (\astart\. + 2*(length of the direction vector)) units along the 
ray. These distances can be used to achieve near and far plane clipping. 
A negative distance (such as the default values) means disable clipping 
to that plane.
}

METHOD "" void setPickAll(SbBool flag) {}
METHOD "" SbBool isPickAll() const {
Sets/returns whether the action will return all objects intersected or
just the closest one.
}

METHOD getPickPtList const SoPickedPointList &getPickedPointList() const {
Returns list of picked points.
}

METHOD getPickPt SoPickedPoint * getPickedPoint(int index = 0) const {
Returns the indexed picked point from the list.
}

ALSO { SoPickedPoint, SoPickedPointList }

