SoRayPickAction(3)

📦

version 4.0.10 · 4 versions

4.0.10 · fedora 43, fedora 44 (latest)
4.0.10 · epel 9
4.0.3 · fedora 43
4.0.7 · fedora 44

🎀 SoRayPickAction — the `Coin` manual page, bestie edition 💅

okay so picture this: you wanna know what the mouse is actually pointing at in your 3D scene. That's this whole class. Let's get into it 🫶

✨ NAME ✨

SoRayPickAction — the class that does ray intersection with scene graphs. literally its whole job. it shoots a ray at your scene graph and goes "yeah i hit that". iconic behavior honestly 💖

✨ SYNOPSIS ✨

#include <Inventor/actions/SoRayPickAction.h>

Inherits SoPickAction. yes she's part of a whole family tree, we'll get to the ancestors 🌸

Public Member Functions

virtual SoType getTypeId (void) const — returns her type id, standard Coin stuff
SoRayPickAction (const SbViewportRegion &viewportregion) — the constructor, takes a viewport region
virtual ~SoRayPickAction () — the destructor, cleans up after herself 💅
void setPoint (const SbVec2s &viewportPoint) — set the pick point from viewport pixel coords
void setNormalizedPoint (const SbVec2f &normpoint) — same but normalized, fancy
void setRadius (const float radiusinpixels) — how fat is the ray, in pixels
float getRadius (void) const — read the radius back out
void setRay (const SbVec3f &start, const SbVec3f &direction, float neardistance=-1.0, float fardistance=-1.0) — set a custom ray, go wild
void setPickAll (const SbBool flag) — do we want every hit or just the closest one?
SbBool isPickAll (void) const — are we in pick-all mode?
const SoPickedPointList & getPickedPointList (void) const — grab the whole list of picked points
SoPickedPoint * getPickedPoint (const int index=0) const — grab one picked point by index
void computeWorldSpaceRay (void) — do the math on the world space ray
SbBool hasWorldSpaceRay (void) const — did we compute one yet?
void setObjectSpace (void) — switch to object space
void setObjectSpace (const SbMatrix &matrix) — switch to object space with a matrix
SbBool intersect (const SbVec3f &v0, const SbVec3f &v1, const SbVec3f &v2, SbVec3f &intersection, SbVec3f &barycentric, SbBool &front) const — triangle intersection, full info edition
SbBool intersect (const SbVec3f &v0, const SbVec3f &v1, SbVec3f &intersection) const — line segment intersection
SbBool intersect (const SbVec3f &point) const — point intersection, is it in there or not
SbBool intersect (const SbBox3f &box, const SbBool usefullviewvolume=TRUE) — box intersection, do we check the full view volume
SbBool intersect (const SbBox3f &box, SbVec3f &intersection, const SbBool usefullviewvolume=TRUE) — box intersection but also tell me where
const SbViewVolume & getViewVolume (void) — get the view volume
const SbLine & getLine (void) — get the line (the ray itself)
SbBool isBetweenPlanes (const SbVec3f &intersection) const — is this intersection between the near and far planes?
SoPickedPoint * addIntersection (const SbVec3f &objectspacepoint, SbBool frontpick=TRUE) — add an intersection manually
void reset (void) — wipe it and start fresh ✨

Public Member Functions inherited from `SoPickAction`

void setViewportRegion (const SbViewportRegion &newregion)
const SbViewportRegion & getViewportRegion (void) const
void enableCulling (const SbBool flag)
SbBool isCullingEnabled (void) const

Public Member Functions inherited from `SoAction`

virtual ~SoAction (void)
virtual SbBool isOfType (SoType type) const
virtual void apply (SoNode *root)
virtual void apply (SoPath *path)
virtual void apply (const SoPathList &pathlist, SbBool obeysrules=FALSE)
void apply (SoAction *beingApplied)
virtual void invalidateState (void)
AppliedCode getWhatAppliedTo (void) const
SoNode * getNodeAppliedTo (void) const
SoPath * getPathAppliedTo (void) const
const SoPathList * getPathListAppliedTo (void) const
const SoPathList * getOriginalPathListAppliedTo (void) const
SbBool isLastPathListAppliedTo (void) const
PathCode getPathCode (int &numindices, const int *&indices)
void traverse (SoNode *const node)
SbBool hasTerminated (void) const
const SoPath * getCurPath (void)
SoState * getState (void) const
PathCode getCurPathCode (void) const
virtual SoNode * getCurPathTail (void)
void usePathCode (int &numindices, const int *&indices)
void pushCurPath (const int childindex, SoNode *node=NULL)
void popCurPath (const PathCode prevpathcode)
void pushCurPath (void)
void popPushCurPath (const int childindex, SoNode *node=NULL)
void popCurPath (void)
void switchToPathTraversal (SoPath *path)
void switchToNodeTraversal (SoNode *node)

Static Public Member Functions

static SoType getClassTypeId (void)
static void addMethod (const SoType type, SoActionMethod method)
static void enableElement (const SoType type, const int stackindex)
static void initClass (void)

Static Public Member Functions inherited from `SoPickAction`

static SoType getClassTypeId (void)
static void addMethod (const SoType type, SoActionMethod method)
static void enableElement (const SoType type, const int stackindex)
static void initClass (void)

Static Public Member Functions inherited from `SoAction`

static void initClass (void)
static void initClasses (void)
static SoType getClassTypeId (void)
static void nullAction (SoAction *action, SoNode *node)

Protected Member Functions

virtual const SoEnabledElementsList & getEnabledElements (void) const
virtual void beginTraversal (SoNode *node)

Protected Member Functions inherited from `SoPickAction`

SoPickAction (const SbViewportRegion &viewportregion)
virtual ~SoPickAction (void)

Protected Member Functions inherited from `SoAction`

SoAction (void)
virtual void endTraversal (SoNode *node)
void setTerminated (const SbBool flag)
virtual SbBool shouldCompactPathList (void) const

Static Protected Member Functions

static SoEnabledElementsList * getClassEnabledElements (void)
static SoActionMethodList * getClassActionMethods (void)

Static Protected Member Functions inherited from `SoPickAction`

static SoEnabledElementsList * getClassEnabledElements (void)
static SoActionMethodList * getClassActionMethods (void)

Static Protected Member Functions inherited from `SoAction`

static SoEnabledElementsList * getClassEnabledElements (void)
static SoActionMethodList * getClassActionMethods (void)

Additional Inherited Members

Public Types inherited from `SoAction`

enum AppliedCode { NODE = 0, PATH = 1, PATH_LIST = 2 }
enum PathCode { NO_PATH = 0, IN_PATH = 1, BELOW_PATH = 2, OFF_PATH = 3 }

Protected Attributes inherited from `SoPickAction`

SbViewportRegion vpRegion

Protected Attributes inherited from `SoAction`

SoState * state
SoActionMethodList * traversalMethods

🌸 Detailed Description 🌸

The SoRayPickAction class does ray intersection with scene graphs. (yes that's the name line again, it's her whole personality 💖)

so bestie, listen: if you wanna interact with the actual geometry in your scene graph, you need to be able to do intersection testing for rays. that's the whole vibe. and that functionality is exactly what the SoRayPickAction class hands you. no cap 🫶

You can use SoRayPickAction to send arbitrary rays through the scene for intersection detections, using the setRay() method. go off, do whatever ray stuff you want ✨

But — and this is the part everyone actually needs — a super common operation is checking for intersections along the ray from the mouse cursor when someone clicks. So this class also comes with convenience methods for setting up a ray from the near plane to the far plane straight from the 2D mouse cursor coordinates. See the setPoint() and setNormalizedPoint() methods. A simple usage example for this case is down below 👇

⚠️ okay here's the classic mistake, pay attention bestie: a very common goof when using a ray pick action to intersect from a point under the mouse cursor after a mouse click is trying to apply it to a scene graph that doesn't contain a camera explicitly set up by the application programmer. Without a camera as part of the traversal, the ray pick action literally does not know which view volume to send the ray through. it's giving "where do i even aim" 😭

In this regard, be aware that the getSceneGraph() call in the So*-libraries' viewer classes will return the root of the user-supplied scene graph, not the "real" internal scene graph root used by the viewer (which should always contain a camera node). So ray picks done from the application code will fail when doing this:

// initializing viewer scene graph
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 ray pick 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 scene graph"

💀 yeah. that BUG: comment is not a joke, it's a warning.

While this is the correct way to do it 👑:

// initializing viewer scene graph
SoSeparator * root = new SoSeparator;
root->ref();

// Need to set up our own camera in the "user scene graph", or else
// the ray pick action will fail because the camera is hidden in the
// viewer-specific root of the scene graph.
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 ray pick in the event_cb() callback method
SoRayPickAction rp( viewer->getViewportRegion() );
rp.setPoint(mouseevent->getPosition());
rp.apply(viewer->getSceneGraph());

see how we added pcam? that's the whole trick. main character camera energy 📸✨

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" scene graph by simply calling:

SoNode * realroot = viewer->getSceneManager()->getSceneGraph();

boom. realroot. the actual real one. 🦋

🧚 Constructor & Destructor Documentation 🧚

`SoRayPickAction::SoRayPickAction (const SbViewportRegion & viewportregion)`

Constructor. hi bestie 👋

Some node types need a viewportregion to know exactly how they are positioned within the scene. For an in-depth explanation of why the viewportregion argument is needed, see the documentation of SoGetBoundingBox::SoGetBoundingBox(const SbViewportRegion &). iykyk 📖

`SoRayPickAction::~SoRayPickAction (void )` [virtual]

Destructor — frees the temporary resources used by the action. she cleans up after herself, as she should 💅🧹

SoType SoRayPickAction::getTypeId (void) const [virtual]

okay so this one hands you back the type identification of any object derived from a class that inherits SoAction. it's what you use for runtime type checking and for casting "downward" (iykyk). it's reimplemented from SoPickAction, bestie.

SoType SoRayPickAction::getClassTypeId (void) [static]

a static method that returns the SoType object associated with objects of this class. that's it, that's the whole vibe. ✨

void SoRayPickAction::addMethod (const SoType type, SoActionMethod method) [static]

this API member is considered internal to the library, since it is not likely to be of interest to the application programmer. (translation: not for you, bestie, move along 💅)

void SoRayPickAction::enableElement (const SoType type, const int stackindex) [static]

same energy, same deal: this API member is considered internal to the library, as it is not likely to be of interest to the application programmer.

const SoEnabledElementsList & SoRayPickAction::getEnabledElements (void) const [protected], [virtual]

returns the list of enabled elements. reimplemented from SoPickAction. it's giving "here's the roster" 🎀

SoEnabledElementsList * SoRayPickAction::getClassEnabledElements (void) [static], [protected]

returns the list of enabled elements for this class.

so the enabledElements and methods variables are protected in the original OIV API. and ngl that is not such a good idea, since exposed static class member variables is a major grievance with regard to Win32 DLLs. this function is an extension for Coin, and it is not available in the original SGI Open Inventor v2.1 API. 🫶

SoActionMethodList * SoRayPickAction::getClassActionMethods (void) [static], [protected]

returns the list of action methods for this class.

and again, fr fr: the enabledElements and methods variables are protected in the original OIV API. this is not such a good idea, since exposed static class member variables is a major grievance with regard to Win32 DLLs. this function is an extension for Coin, and it is not available in the original SGI Open Inventor v2.1 API. same disclaimer, different function, we love consistency 😌

void SoRayPickAction::initClass (void) [static]

initializes the runtime type system for this class, and sets up the enabled elements and action method list. the whole "wake up bestie, you're alive now" moment ⭐

void SoRayPickAction::setPoint (const SbVec2s & viewportpoint)

sets the viewport-space point. this point gets calculated into a line that runs from the near clipping plane to the far clipping plane, and the intersection ray follows that line.

it's a super convenient way to detect object intersection below the cursor. 🖱️✨

void SoRayPickAction::setNormalizedPoint (const SbVec2f & normpoint)

sets the viewport-space point that the ray is sent through. the coordinate is normalized, ranging from (0, 0) to (1, 1).

see also

setPoint()

void SoRayPickAction::setRadius (const float radiusinpixels)

sets the radius of the picking ray, in screen pixels. default value is 5.0.

heads up bestie: 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. so don't come for the polygons, they don't care 💀

float SoRayPickAction::getRadius (void) const

gets the radius of the picking ray, in screen pixels. the little read-only twin of setRadius(). 🎀

void SoRayPickAction::setRay (const SbVec3f & start, const SbVec3f & direction, float neardistance = -1.0, float fardistance = -1.0)

sets the intersection ray in world space coordinates.

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. main character energy: this ray answers to nobody but you. 🔥

void SoRayPickAction::setPickAll (const SbBool flag)

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.

default value of the "pick all" flag is FALSE.

SbBool SoRayPickAction::isPickAll (void) const

returns whether only the closest object, or all the objects the ray intersects with, is picked.

see also

setPickAll()

const SoPickedPointList & SoRayPickAction::getPickedPointList (void) const

returns a list of the picked points. the whole lineup, no gatekeeping. 💖

SoPickedPoint * SoRayPickAction::getPickedPoint (const int index = 0) const

returns the picked point with index in the list of picked points.

returns NULL if less than index + 1 points where picked during the last ray pick action. (yes, "where" — that's the original wording, we're just quoting the queen 🙈)

void SoRayPickAction::computeWorldSpaceRay (void)