NAME

       SoRayPickAction — intersects objects with a ray cast into scene

INHERITS FROM

       SoAction > SoPickAction > SoRayPickAction

SYNOPSIS

       #include <Inventor/actions/SoRayPickAction.h>

          Methods from class SoRayPickAction:

                                SoRayPickAction(const SbViewportRegion &viewportRegion)
     void                       setPoint(const SbVec2s &viewportPoint)
     void                       setNormalizedPoint(const SbVec2f &normPoint)
     void                       setRadius(float radiusInPixels)
     void                       setRay(const  SbVec3f  &start,  const  SbVec3f  &direction, float
                                     nearDistance = -1.0, float farDistance = -1.0)
     void                       setPickAll(SbBool flag)
     SbBool                     isPickAll() const
     const SoPickedPointList &  getPickedPointList() const
     SoPickedPoint *            getPickedPoint(int index = 0) const

          Methods from class SoPickAction:

     void                      setViewportRegion(const SbViewportRegion &newRegion)
     const SbViewportRegion &  getViewportRegion() const

          Methods from class SoAction:

     virtual void        apply(SoNode *node)
     virtual void        apply(SoPath *path)
     virtual void        apply(const SoPathList &pathList, SbBool obeysRules = FALSE)
     static SoType       getClassTypeId()
     virtual SoType      getTypeId()
     virtual SbBool      isOfType(SoType type)
     virtual void        invalidateState()

DESCRIPTION

       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
       SoPickedPoint instance.

       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.

       Callers can cause the action to compute all intersections along the ray (sorted closest to
       farthest)  by  setting  the pickAll flag to TRUE. By default, the action computes only the
       closest  intersection.  In  either  case,   the   intersections   are   returned   in   an
       SoPickedPointList.  Each  intersection  can  be  examined  by  accessing  the  appropriate
       SoPickedPoint  in  the  list.  The  SoPickedPoint  class  provides  methods  to  get   the
       intersection point, normal, and other info.

METHODS

                                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.

     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.

     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.

     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.

     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 nearDistance is 2.0, the intersection must occur past
          (start + 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.

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

     const SoPickedPointList &  getPickedPointList() const
          Returns list of picked points.

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

SEE ALSO

       SoPickedPoint, SoPickedPointList

                                                                           SoRayPickAction(3IV)()