.TH "SoRayPickAction" 3 "Thu May 29 2014" "Version 4.0.0a" "Coin" \" -*- nroff -*- .ad l .nh .SH NAME SoRayPickAction \- .PP The \fBSoRayPickAction\fP class does ray intersection with scene graphs\&. .PP For interaction with the scene graph geometry, it is necessary to be able to do intersection testing for rays\&. This functionality is provided by the \fBSoRayPickAction\fP class\&. .SH SYNOPSIS .br .PP .PP \fC#include \fP .PP Inherits \fBSoPickAction\fP\&. .SS "Public Member Functions" .in +1c .ti -1c .RI "virtual \fBSoType\fP \fBgetTypeId\fP (void) const " .br .ti -1c .RI "\fBSoRayPickAction\fP (const \fBSbViewportRegion\fP &viewportregion)" .br .ti -1c .RI "virtual \fB~SoRayPickAction\fP ()" .br .ti -1c .RI "void \fBsetPoint\fP (const \fBSbVec2s\fP &viewportPoint)" .br .ti -1c .RI "void \fBsetNormalizedPoint\fP (const \fBSbVec2f\fP &normpoint)" .br .ti -1c .RI "void \fBsetRadius\fP (const float radiusinpixels)" .br .ti -1c .RI "void \fBsetRay\fP (const \fBSbVec3f\fP &start, const \fBSbVec3f\fP &direction, float neardistance=-1\&.0, float fardistance=-1\&.0)" .br .ti -1c .RI "void \fBsetPickAll\fP (const SbBool flag)" .br .ti -1c .RI "SbBool \fBisPickAll\fP (void) const " .br .ti -1c .RI "const \fBSoPickedPointList\fP & \fBgetPickedPointList\fP (void) const " .br .ti -1c .RI "\fBSoPickedPoint\fP * \fBgetPickedPoint\fP (const int index=0) const " .br .ti -1c .RI "void \fBcomputeWorldSpaceRay\fP (void)" .br .ti -1c .RI "SbBool \fBhasWorldSpaceRay\fP (void) const " .br .ti -1c .RI "void \fBsetObjectSpace\fP (void)" .br .ti -1c .RI "void \fBsetObjectSpace\fP (const \fBSbMatrix\fP &matrix)" .br .ti -1c .RI "SbBool \fBintersect\fP (const \fBSbVec3f\fP &v0, const \fBSbVec3f\fP &v1, const \fBSbVec3f\fP &v2, \fBSbVec3f\fP &intersection, \fBSbVec3f\fP &barycentric, SbBool &front) const " .br .ti -1c .RI "SbBool \fBintersect\fP (const \fBSbVec3f\fP &v0, const \fBSbVec3f\fP &v1, \fBSbVec3f\fP &intersection) const " .br .ti -1c .RI "SbBool \fBintersect\fP (const \fBSbVec3f\fP &point) const " .br .ti -1c .RI "SbBool \fBintersect\fP (const \fBSbBox3f\fP &box, const SbBool usefullviewvolume=TRUE)" .br .ti -1c .RI "SbBool \fBintersect\fP (const \fBSbBox3f\fP &box, \fBSbVec3f\fP &intersection, const SbBool usefullviewvolume=TRUE)" .br .ti -1c .RI "const \fBSbViewVolume\fP & \fBgetViewVolume\fP (void)" .br .ti -1c .RI "const \fBSbLine\fP & \fBgetLine\fP (void)" .br .ti -1c .RI "SbBool \fBisBetweenPlanes\fP (const \fBSbVec3f\fP &intersection) const " .br .ti -1c .RI "\fBSoPickedPoint\fP * \fBaddIntersection\fP (const \fBSbVec3f\fP &objectspacepoint, SbBool frontpick=TRUE)" .br .ti -1c .RI "void \fBreset\fP (void)" .br .in -1c .SS "Static Public Member Functions" .in +1c .ti -1c .RI "static \fBSoType\fP \fBgetClassTypeId\fP (void)" .br .ti -1c .RI "static void \fBaddMethod\fP (const \fBSoType\fP type, SoActionMethod method)" .br .ti -1c .RI "static void \fBenableElement\fP (const \fBSoType\fP type, const int stackindex)" .br .ti -1c .RI "static void \fBinitClass\fP (void)" .br .in -1c .SS "Protected Member Functions" .in +1c .ti -1c .RI "virtual const .br \fBSoEnabledElementsList\fP & \fBgetEnabledElements\fP (void) const " .br .ti -1c .RI "virtual void \fBbeginTraversal\fP (\fBSoNode\fP *node)" .br .in -1c .SS "Static Protected Member Functions" .in +1c .ti -1c .RI "static \fBSoEnabledElementsList\fP * \fBgetClassEnabledElements\fP (void)" .br .ti -1c .RI "static \fBSoActionMethodList\fP * \fBgetClassActionMethods\fP (void)" .br .in -1c .SS "Additional Inherited Members" .SH "Detailed Description" .PP The \fBSoRayPickAction\fP class does ray intersection with scene graphs\&. .PP For interaction with the scene graph geometry, it is necessary to be able to do intersection testing for rays\&. This functionality is provided by the \fBSoRayPickAction\fP class\&. \fBSoRayPickAction\fP can be used to pass arbitrary rays through the scene for intersection detections, by using the \fBsetRay()\fP method\&. .PP Because a very common operation is to check for intersections along the ray from the mousecursor upon mouseclicks, it also contains convenience methods for setting up a ray from the near plane to the far plane from the 2D mousecursor coordinates\&. See the \fBsetPoint()\fP and \fBsetNormalizedPoint()\fP methods\&. A simple usage example for this case is presented below\&. .PP Note that one common mistake when using a raypick action to intersect from a point under the mousecursor after a mouseclick is that one tries to apply it to a scenegraph that does not contain a camera \fIexplicitly\fP set up by the application programmer\&. Without a camera as part of the traversal, the raypick action does not know which view volume to send the ray through\&. .PP In this regard, be aware that the getSceneGraph() call in the So*-libraries' viewer classes will return the root of the user-supplied scenegraph, not the 'real' internal scenegraph root used by the viewer (which should always contain a camera node)\&. So raypicks done from the application code will fail when doing this: .PP .PP .nf // initializing viewer scenegraph SoSeparator * root = new SoSeparator; root->ref(); SoEventCallback * ecb = new SoEventCallback; ecb->addEventCallback(SoMouseButtonEvent::getClassTypeId(), event_cb, viewer); root->addChild(ecb); root->addChild(new SoCone); viewer->setSceneGraph( root ); // -- [snip] ------------------------- // attempting raypick in the event_cb() callback method SoRayPickAction rp( viewer->getViewportRegion() ); rp\&.setPoint(mouseevent->getPosition()); rp\&.apply(viewer->getSceneGraph()); // BUG: results will not be what you expected, as no camera was // part of the "user's scenegraph" .fi .PP .PP While this is the correct way to do it: .PP .PP .nf // initializing viewer scenegraph SoSeparator * root = new SoSeparator; root->ref(); // Need to set up our own camera in the "user scenegraph", or else // the raypick action will fail because the camera is hidden in the // viewer-specific root of the scenegraph\&. SoPerspectiveCamera * pcam = new SoPerspectiveCamera; root->addChild(pcam); SoEventCallback * ecb = new SoEventCallback; ecb->addEventCallback(SoMouseButtonEvent::getClassTypeId(), event_cb, viewer); root->addChild(ecb); root->addChild(new SoCone); viewer->setSceneGraph( root ); pcam->viewAll( root, viewer->getViewportRegion() ); // -- [snip] ------------------------- // attempting raypick in the event_cb() callback method SoRayPickAction rp( viewer->getViewportRegion() ); rp\&.setPoint(mouseevent->getPosition()); rp\&.apply(viewer->getSceneGraph()); .fi .PP .PP Or if you do want the convenience of having the viewer set up a camera for you implicitly, you can get hold of the root-node of the 'complete' scenegraph by simply calling: .PP .PP .nf SoNode * realroot = viewer->getSceneManager()->getSceneGraph(); .fi .PP .SH "Constructor & Destructor Documentation" .PP .SS "SoRayPickAction::SoRayPickAction (const \fBSbViewportRegion\fP &viewportregion)" Constructor\&. .PP Some node types need a \fIviewportregion\fP to know exactly how they are positioned within the scene\&. For an in-depth explanation of why the \fIviewportregion\fP argument is needed, see the documentation of SoGetBoundingBox::SoGetBoundingBox(const SbViewportRegion &)\&. .SS "SoRayPickAction::~SoRayPickAction (void)\fC [virtual]\fP" Destructor, free temporary resources used by action\&. .SH "Member Function Documentation" .PP .SS "\fBSoType\fP SoRayPickAction::getTypeId (void) const\fC [virtual]\fP" Returns the type identification of an action derived from a class inheriting \fBSoAction\fP\&. This is used for run-time type checking and 'downward' casting\&. .PP Usage example: .PP .PP .nf void bar(SoAction * action) { if (action->getTypeId() == SoGLRenderAction::getClassTypeId()) { // safe downward cast, know the type SoGLRenderAction * glrender = (SoGLRenderAction *)action; } return; // ignore if not renderaction } .fi .PP .PP For application programmers wanting to extend the library with new actions: this method needs to be overridden in \fIall\fP subclasses\&. This is typically done as part of setting up the full type system for extension classes, which is usually accomplished by using the pre-defined macros available through Inventor/nodes/SoSubAction\&.h: SO_ACTION_SOURCE, SO_ACTION_INIT_CLASS and SO_ACTION_CONSTRUCTOR\&. .PP For more information on writing Coin extensions, see the \fBSoAction\fP class documentation\&. .PP Returns the actual type id of an object derived from a class inheriting \fBSoAction\fP\&. Needs to be overridden in \fIall\fP subclasses\&. .PP Reimplemented from \fBSoPickAction\fP\&. .SS "void SoRayPickAction::addMethod (const \fBSoType\fPtype, SoActionMethodmethod)\fC [static]\fP" \fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP .SS "void SoRayPickAction::enableElement (const \fBSoType\fPtype, const intstackindex)\fC [static]\fP" \fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP .SS "const \fBSoEnabledElementsList\fP & SoRayPickAction::getEnabledElements (void) const\fC [protected]\fP, \fC [virtual]\fP" Returns a list of the elements used by action instances of this class upon traversal operations\&. .PP Reimplemented from \fBSoPickAction\fP\&. .SS "void SoRayPickAction::setPoint (const \fBSbVec2s\fP &viewportpoint)" Sets the viewport-space point\&. This point is calculated into a line from the near clipping plane to the far clipping plane, and the intersection ray follows the line\&. .PP This is a convenient way to detect object intersection below the cursor\&. .SS "void SoRayPickAction::setNormalizedPoint (const \fBSbVec2f\fP &normpoint)" Sets the viewport-space point which the ray is sent through\&. The coordinate is normalized, ranging from (0, 0) to (1, 1)\&. .PP \fBSee also:\fP .RS 4 \fBsetPoint()\fP .RE .PP .SS "void SoRayPickAction::setRadius (const floatradiusinpixels)" Sets the radius of the picking ray, in screen pixels\&. Default value is 5\&.0\&. .PP The radius of the intersection ray will only influence the pick operation's behavior versus lines and points, and has no effect on picking of shapes / polygons\&. .SS "void SoRayPickAction::setRay (const \fBSbVec3f\fP &start, const \fBSbVec3f\fP &direction, floatneardistance = \fC-1\&.0\fP, floatfardistance = \fC-1\&.0\fP)" Sets the intersection ray in world-space coordinates\&. .PP Use this method if you want to send any ray through the scene to detect intersections, independently of mouse cursor position upon clicks and scene graph camera settings\&. .SS "void SoRayPickAction::setPickAll (const SbBoolflag)" Lets you decide whether or not all the objects the ray intersects with should be picked\&. If not, only the intersection point of the object closest to the camera will be picked\&. .PP Default value of the 'pick all' flag is \fCFALSE\fP\&. .SS "SbBool SoRayPickAction::isPickAll (void) const" Returns whether only the closest object or all the objects the ray intersects with is picked\&. .PP \fBSee also:\fP .RS 4 \fBsetPickAll()\fP .RE .PP .SS "const \fBSoPickedPointList\fP & SoRayPickAction::getPickedPointList (void) const" Returns a list of the picked points\&. .SS "\fBSoPickedPoint\fP * SoRayPickAction::getPickedPoint (const intindex = \fC0\fP) const" Returns the picked point with \fIindex\fP in the list of picked points\&. .PP Returns \fCNULL\fP if less than \fIindex\fP + 1 points where picked during the last raypick action\&. .SS "void SoRayPickAction::computeWorldSpaceRay (void)" \fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP .SS "SbBool SoRayPickAction::hasWorldSpaceRay (void) const" \fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP .SS "void SoRayPickAction::setObjectSpace (void)" \fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP .SS "void SoRayPickAction::setObjectSpace (const \fBSbMatrix\fP &matrix)" \fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP .SS "SbBool SoRayPickAction::intersect (const \fBSbVec3f\fP &v0_in, const \fBSbVec3f\fP &v1_in, const \fBSbVec3f\fP &v2_in, \fBSbVec3f\fP &intersection, \fBSbVec3f\fP &barycentric, SbBool &front) const" \fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP .SS "SbBool SoRayPickAction::intersect (const \fBSbVec3f\fP &v0_in, const \fBSbVec3f\fP &v1_in, \fBSbVec3f\fP &intersection) const" \fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP .SS "SbBool SoRayPickAction::intersect (const \fBSbVec3f\fP &point_in) const" \fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP .SS "SbBool SoRayPickAction::intersect (const \fBSbBox3f\fP &box, const SbBoolusefullviewvolume = \fCTRUE\fP)" \fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP .SS "SbBool SoRayPickAction::intersect (const \fBSbBox3f\fP &box, \fBSbVec3f\fP &intersection, const SbBoolusefullviewvolume = \fCTRUE\fP)" \fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP .SS "const \fBSbViewVolume\fP & SoRayPickAction::getViewVolume (void)" \fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP .SS "const \fBSbLine\fP & SoRayPickAction::getLine (void)" \fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP .SS "SbBool SoRayPickAction::isBetweenPlanes (const \fBSbVec3f\fP &intersection_in) const" \fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP .SS "\fBSoPickedPoint\fP * SoRayPickAction::addIntersection (const \fBSbVec3f\fP &objectspacepoint_in, SbBoolfrontpick = \fCTRUE\fP)" \fIThis API member is considered internal to the library, as it is not likely to be of interest to the application programmer\&.\fP .SS "void SoRayPickAction::reset (void)" Truncates the internal picked points list\&. .PP \fBSince:\fP .RS 4 Coin 2\&.2 .RE .PP .SS "void SoRayPickAction::beginTraversal (\fBSoNode\fP *node)\fC [protected]\fP, \fC [virtual]\fP" This virtual method is called from \fBSoAction::apply()\fP, and is the entry point for the actual scenegraph traversal\&. .PP It can be overridden to initialize the action at traversal start, for specific initializations in the action subclasses inheriting \fBSoAction\fP\&. .PP Default method just calls \fBtraverse()\fP, which any overridden implementation of the method must do too (or call \fBSoAction::beginTraversal()\fP) to trigger the scenegraph traversal\&. .PP Reimplemented from \fBSoPickAction\fP\&. .SH "Author" .PP Generated automatically by Doxygen for Coin from the source code\&.