SoRayPickAction(3)

📦 version 3.1.3, in fedora 43, fedora 44

💖 SoRayPickAction 💖

okay bestie, gather round, because today we're talking about SoRayPickAction from the Library Functions Manual — the class that does ray intersection with scene graphs. yes you heard me. rays. scene graphs. intersection. it's giving geometry detective energy and honestly? we're obsessed. 🕵️‍♀️✨

✨ SYNOPSIS ✨

#include <Inventor/actions/SoRayPickAction.h>

She Inherits SoPickAction. periodt. 💅

🌸 Public Member Functions

virtual SoType getTypeId (void) const
SoRayPickAction (const SbViewportRegion &viewportregion)
virtual ~SoRayPickAction ()
void setPoint (const SbVec2s &viewportPoint)
void setNormalizedPoint (const SbVec2f &normpoint)
void setRadius (const float radiusinpixels)
void setRay (const SbVec3f &start, const SbVec3f &direction, float neardistance=-1.0, float fardistance=-1.0)
void setPickAll (const SbBool flag)
SbBool isPickAll (void) const
const SoPickedPointList & getPickedPointList (void) const
SoPickedPoint * getPickedPoint (const int index=0) const
void computeWorldSpaceRay (void)
SbBool hasWorldSpaceRay (void) const
void setObjectSpace (void)
void setObjectSpace (const SbMatrix &matrix)
SbBool intersect (const SbVec3f &v0, const SbVec3f &v1, const SbVec3f &v2, SbVec3f &intersection, SbVec3f &barycentric, SbBool &front) const
SbBool intersect (const SbVec3f &v0, const SbVec3f &v1, SbVec3f &intersection) const
SbBool intersect (const SbVec3f &point) const
SbBool intersect (const SbBox3f &box, const SbBool usefullviewvolume=TRUE)
SbBool intersect (const SbBox3f &box, SbVec3f &intersection, const SbBool usefullviewvolume=TRUE)
const SbViewVolume & getViewVolume (void)
const SbLine & getLine (void)
SbBool isBetweenPlanes (const SbVec3f &intersection) const
SoPickedPoint * addIntersection (const SbVec3f &objectspacepoint, SbBool frontpick=TRUE)
void reset (void)

💜 Public Member Functions inherited from `SoPickAction`

void setViewportRegion (const SbViewportRegion &newregion)
const SbViewportRegion & getViewportRegion (void)
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 🌸

So The SoRayPickAction class does ray intersection with scene graphs. yes, that's literally the whole vibe. ✨

Okay so — for your app to actually interact with the geometry in a scene graph (like, you know, when a user clicks on a thing and you need to know which thing they clicked), you need to be able to do intersection testing for rays. That's the whole job. And that job is done by the SoRayPickAction class. no cap. 💅

You can yeet arbitrary rays through the scene for intersection detection using the setRay() method. go off, queen. 🎯

And because the most common thing ever is checking for intersections along the ray from the mouse cursor when someone clicks (iconic, relatable, we've all been there), she also comes with convenience methods for setting up a ray from the near plane to the far plane using 2D mouse cursor coords. see setPoint() and setNormalizedPoint(). there's a cute lil usage example for this case down below. 🖱️✨

⚠️ okay so listen bestie, this is THE classic mistake: when you're using a raypick action to intersect from a point under the mouse cursor after a mouseclick, people constantly try to apply it to a scenegraph that doesn't have a camera explicitly set up by the application programmer. and bestie… without a camera as part of the traversal, the raypick action literally has no idea which view volume to send the ray through. it's giving lost in the sauce. 😭

While we're on this topic — 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 that the viewer actually uses (which should always contain a camera node). so raypicks done from application code will fail when you do this:

// 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"

Meanwhile, this is the correct way to do it, slay:

// 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());

OR — if you do want the convenience of having the viewer set up a camera for you implicitly (which, valid, we love a shortcut ✨), you can get ahold of the root-node of the "complete" scenegraph by simply calling:

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

🎀 CONSTRUCTOR & DESTRUCTOR DOCUMENTATION 🎀

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

Constructor. hiii, nice to meet you. 💖

Some node types need a viewportregion to know exactly how they're positioned within the scene. and if you want an in-depth explanation of why the viewportregion argument is even needed, go check the docs for SoGetBoundingBox::SoGetBoundingBox(const SbViewportRegion &). iykyk. 📐

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

Destructor — she frees the temporary resources used by the action. clean up, close the tab, hydrate, goodbye. 💅✨

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

Okay bestie, this one is the type-ID checker. It hands you the type identification of an action that derives from a class inheriting SoAction. What's it even for? Run-time type checking and "downward" casting, periodt. 💅

Usage example, and yes it's verbatim:

void bar(SoAction * action)
{
  if (action->getTypeId() == SoGLRenderAction::getClassTypeId()) {
    // safe downward cast, know the type
    SoGLRenderAction * glrender = (SoGLRenderAction *)action;
  }
  return; // ignore if not renderaction
}

Now listen, if you're an application programmer who wants to extend the library with brand-new actions: this method needs to be overridden in all subclasses. Fr fr, all of them. It's typically done as part of setting up the full type system for extension classes, and that's usually accomplished with the pre-defined macros available through Inventor/nodes/SoSubAction.h: SO_ACTION_SOURCE, SO_ACTION_INIT_CLASS and SO_ACTION_CONSTRUCTOR.

Want the full lore on writing Coin extensions? Go read the SoAction class documentation. 📖

Returns the actual type id of an object derived from a class inheriting SoAction. Needs to be overridden in all subclasses.

Reimplemented from SoPickAction.

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

This API member is considered internal to the library, as it is not likely to be of interest to the application programmer. (Translation: not for you, bestie, it's giving backstage pass. 🎀)

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

Same energy: 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 a list of the elements used by action instances of this class upon traversal operations. 🦋

Reimplemented from SoPickAction.

`void SoRayPickAction::setPoint (const SbVec2s & viewportpoint)`

Sets the viewport-space point. That point gets calculated into a line running from the near clipping plane all the way to the far clipping plane, and the intersection ray follows that line. ✨

It's the convenient little way to detect object intersection right below the cursor. Obsessed.

`void SoRayPickAction::setNormalizedPoint (const SbVec2f & normpoint)`

Sets the viewport-space point that the ray gets sent through — except this 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 though: 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 it about your polygons, it's not that girl.

`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, completely independently of mouse cursor position upon clicks and scene graph camera settings. Main character ray energy, honestly.

`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. That's it, that's the whole vibe. 💖

`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 were picked during the last raypick action. So yeah, if you ask for index 5 and only 2 things got picked, you get NULL and that's on you bestie. 💀