SoRayPickAction Class Reference

Intersects objects with a ray cast into scene. More...

#include <Inventor/actions/SoRayPickAction.h>

Inheritance diagram for SoRayPickAction:

Public Member Functions
	SoRayPickAction (const SbViewportRegion &viewportRegion)
	Constructor takes viewport region to use for picking.
virtual	~SoRayPickAction ()
	Destructor.
void	setPoint (const SbVec2s &viewportPoint)
	Setting up the action before it is applied:
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.
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.
void	setPickAll (bool flag)
	Sets/returns whether the action will return all objects intersected or just the closest one.
bool	isPickAll () const
	Sets/returns whether the action will return all objects intersected or just the closest one.
const SoPickedPointList &	getPickedPointList () const
	Examining results after the action is applied:
SoPickedPoint *	getPickedPoint (int index=0) const
	Returns the indexed picked point from the list.
void	computeWorldSpaceRay ()
	If a ray was not defined with setRay(), this causes the world space pick ray to be computed from the screen space point and radius, using the current view specification from the state.
bool	hasWorldSpaceRay () const
	This returns TRUE if the action has had a world space ray set or computed.
void	setObjectSpace ()
	This is called by shapes to set up object space picking.
void	setObjectSpace (const SbMatrix &matrix)
bool	intersect (const SbVec3f &v0, const SbVec3f &v1, const SbVec3f &v2, SbVec3f &intersection, SbVec3f &barycentric, bool &front) const
	These intersect the current object-space ray with a variety of primitives: triangle, line, point, bounding-box.
bool	intersect (const SbVec3f &v0, const SbVec3f &v1, SbVec3f &intersection) const
	Line:
bool	intersect (const SbVec3f &point) const
	Point:
bool	intersect (const SbBox3f &box, bool useFullViewVolume=TRUE)
	Bounding box: just return whether the ray intersects it.
const SbViewVolume &	getViewVolume () const
	Returns an SbViewVolume that represents the object-space ray to pick along.
const SbLine &	getLine () const
	Returns SbLine that can be used for other intersection tests.
bool	isBetweenPlanes (const SbVec3f &intersection) const
	Returns TRUE if the given object-space intersection point is between the near and far planes of the object-space view volume, as well as any clipping planes that have been defined.
SoPickedPoint *	addIntersection (const SbVec3f &objectSpacePoint)
	Adds an SoPickedPoint instance representing the given object space point to the current list and returns a pointer to it.
Public Member Functions inherited from SoPickAction
void	setViewportRegion (const SbViewportRegion &newRegion)
	Sets current viewport region to use for action.
const SbViewportRegion &	getViewportRegion () const
	Returns current viewport region to use for action.
void	enableCulling (bool flag)
	Setting this flag to FALSE disables any pick culling that might take place (as in SoSeparators).
bool	isCullingEnabled () const
Public Member Functions inherited from SoAction
virtual	~SoAction ()
	Destructor.
virtual SoType	getTypeId () const =0
	Returns the type identifier for a specific instance.
bool	isOfType (SoType type) const
	Returns TRUE if this instance is of the type specified in type or is derived from that type.
virtual void	apply (SoNode *node)
virtual void	apply (SoPath *path)
virtual void	apply (const SoPathList &pathList, bool obeysRules=FALSE)
	Initiates an action on the graph defined either by a node, path, or list of paths.
virtual void	invalidateState ()
	Invalidates the current traversal state in the action, forcing it to be recreated when the action is next applied.
AppliedCode	getWhatAppliedTo () const
	Returns code indicating what action is being applied to.
SoNode *	getNodeAppliedTo () const
	These returns a pointer to the node, path, or path list the action is being applied to.
SoPath *	getPathAppliedTo () const
const SoPathList *	getPathListAppliedTo () const
	A single path list may be split into several, one for each different head node.
const SoPathList *	getOriginalPathListAppliedTo () const
bool	isLastPathListAppliedTo () const
PathCode	getPathCode (int &numIndices, const int *&indices)
	Returns path code based on where current node (the node at the end of the current path) lies with respect to the path(s) the action is being applied to.
void	traverse (SoNode *node)
	Does traversal of a graph rooted by a node.
bool	hasTerminated () const
	Returns TRUE if the traversal has reached a termination condition.
const SoPath *	getCurPath ()
	Returns a pointer to the path accumulated during traversal, i.e., the chain of nodes from the root of the traversed graph to the current node being traversed.
SoState *	getState () const
	Get the state from the action.
PathCode	getCurPathCode () const
	These methods maintain the current path accumulated so far during traversal.
void	pushCurPath (int childIndex)
void	popCurPath (PathCode prevPathCode)
virtual SoNode *	getCurPathTail ()
	This is virtual, so that SoCallbackAction can use current node.
void	usePathCode (int &numIndices, const int *&indices)
	called by inline getPathCode:
void	pushCurPath ()
	Optimized versions of push/pop when we know path codes won't change:
void	popPushCurPath (int childIndex)
void	popCurPath ()
const SoLightweightPath &	getCurrentLightweightPath () const
	Returns the current "light" path.
void	setCurrentLightweightPath (const SoLightweightPath &path)
	Sets the current "light" path.

Static Public Member Functions
static void	initClass ()
Static Public Member Functions inherited from SoPickAction
static void	initClass ()
Static Public Member Functions inherited from SoAction
static SoType	getClassTypeId ()
	Returns the type identifier for this class.
static void	nullAction (SoAction *, SoNode *)
	Null action method that can be stored in lookup table when desired.
static void	initClass ()
static void	initClasses ()
	Initialize ALL Inventor action classes.

Protected Member Functions
virtual void	beginTraversal (SoNode *node)
	Initiates action on graph.
Protected Member Functions inherited from SoPickAction
	SoPickAction (const SbViewportRegion &viewportRegion)
	Constructor takes viewport region.
virtual	~SoPickAction ()
	Destructor.
virtual void	beginTraversal (SoNode *node)
	Initiates action on graph.
Protected Member Functions inherited from SoAction
	SoAction ()
	Constructor.
virtual const SoEnabledElementsList &	getEnabledElements () const
	Returns the list of enabled elements for a given action subclass.
virtual void	beginTraversal (SoNode *node)
	Begins traversal of an action at the given node.
void	setTerminated (bool flag)
	Allows subclass instance to indicate that traversal has reached a termination condition.
virtual bool	shouldCompactPathLists () const
	This method is used when applying an action to an SoPathList.

Additional Inherited Members
Public Types inherited from SoAction
enum	AppliedCode { NODE , PATH , PATH_LIST }
	This enum is used to determine what the action is being applied to. More...
enum	PathCode { NO_PATH , IN_PATH , BELOW_PATH , OFF_PATH }
	This enum may be used during traversal of nodes to indicate where the node is with respect to the path being traversed. More...
Protected Attributes inherited from SoPickAction
SbViewportRegion	vpRegion
	Current viewport region.
Protected Attributes inherited from SoAction
SoState *	state
	Traversal state.
SoActionMethodList *	traversalMethods
	The list of what to do when.
Static Protected Attributes inherited from SoAction
static SoEnabledElementsList *	enabledElements
	Holds list of enabled elements for the SoAction class.
static SoActionMethodList *	methods
	... and the methods

Detailed 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.

See Also

SoPickedPoint, SoPickedPointList

Definition at line 97 of file SoRayPickAction.h.

Constructor & Destructor Documentation

SoRayPickAction()

SoRayPickAction::SoRayPickAction

(

const SbViewportRegion &

viewportRegion

)

Even though the picking operation may not involve a window per se, some nodes need this information to determine their size and placement.

~SoRayPickAction()

virtual SoRayPickAction::~SoRayPickAction ( )

virtual

Member Function Documentation

addIntersection()

SoPickedPoint * SoRayPickAction::addIntersection

(

const SbVec3f &

objectSpacePoint

)

If pickAll is TRUE, this inserts the instance in correct sorted order. If it is FALSE, it replaces the one instance in the list only if the new one is closer; if the new one is farther away, no instance is created and NULL is returned, meaning that no more work has to be done to set up the SoPickedPoint.

beginTraversal()

virtual void SoRayPickAction::beginTraversal ( SoNode *  node )

protectedvirtual

Reimplemented from SoPickAction.

computeWorldSpaceRay()

void SoRayPickAction::computeWorldSpaceRay

(

)

This is typically done when a camera is encountered during traversal.

getLine()

const SbLine & SoRayPickAction::getLine ( ) const

inline

The line's position is the starting point and the direction is the direction of the ray. Given an intersection with this ray, you can call isBetweenPlanes() to see if the intersection is between the near and far clipping planes.

Definition at line 232 of file SoRayPickAction.h.

getPickedPoint()

SoPickedPoint * SoRayPickAction::getPickedPoint

(

int

index = 0

)

const

getPickedPointList()

const SoPickedPointList & SoRayPickAction::getPickedPointList ( ) const

inline

Returns list of picked points.

Definition at line 160 of file SoRayPickAction.h.

getViewVolume()

const SbViewVolume & SoRayPickAction::getViewVolume ( ) const

inline

The projection point of the view volume is the starting point of the ray. The projection direction is the direction of the ray. The distance to the near plane is the same as the distance to the near plane for the ray. The distance to the far plane is the sum of the near distance and the depth of the view volume.

Definition at line 225 of file SoRayPickAction.h.

hasWorldSpaceRay()

bool SoRayPickAction::hasWorldSpaceRay

(

)

const

initClass()

static void SoRayPickAction::initClass ( )

static

intersect() [1/4]

bool SoRayPickAction::intersect	(	const SbBox3f &	box,
		bool	useFullViewVolume = TRUE
	)

If useFullViewVolume is TRUE, it intersects the picking view volume with the box. Otherwise, it uses just the picking ray, which is faster.

intersect() [2/4]

bool SoRayPickAction::intersect

(

const SbVec3f &

point

)

const

intersect() [3/4]

bool SoRayPickAction::intersect	(	const SbVec3f &	v0,
		const SbVec3f &	v1,
		const SbVec3f &	v2,
		SbVec3f &	intersection,
		SbVec3f &	barycentric,
		bool &	front
	)		const

Intersection with a triangle uses only the ray, while intersection with a line or point uses the cone or cylinder around the ray. The intersection with a bounding-box uses the cone/cylinder also, since the contents of the box may be lines or points. NOTE: you must call setObjectSpace() before calling any of these. Triangle: returns intersection point, barycentric coordinates, and whether the front side (defined by right-hand-rule) was hit.

intersect() [4/4]

bool SoRayPickAction::intersect	(	const SbVec3f &	v0,
		const SbVec3f &	v1,
		SbVec3f &	intersection
	)		const

isBetweenPlanes()

bool SoRayPickAction::isBetweenPlanes

(

const SbVec3f &

intersection

)

const

This test can be used to determine whether the point of intersection of the ray with an object is valid with respect to the clipping planes.

isPickAll()

bool SoRayPickAction::isPickAll ( ) const

inline

Definition at line 152 of file SoRayPickAction.h.

setNormalizedPoint()

void SoRayPickAction::setNormalizedPoint

(

const SbVec2f &

normPoint

)

setObjectSpace() [1/2]

void SoRayPickAction::setObjectSpace

(

)

It uses the current state matrices to determine how to map between world and object spaces. It should be called before calling any of the intersection methods. The second form takes a matrix to concatenate with the current objToWorld matrix. It can be used, for example, if a shape has sizing or positioning info built into it.

setObjectSpace() [2/2]

void SoRayPickAction::setObjectSpace

(

const SbMatrix &

matrix

)

setPickAll()

void SoRayPickAction::setPickAll ( bool  flag )

inline

Definition at line 149 of file SoRayPickAction.h.

setPoint()

void SoRayPickAction::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.

setRadius()

void SoRayPickAction::setRadius

(

float

radiusInPixels

)

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.

setRay()

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

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.

---

The documentation for this class was generated from the following file:

• C:/jh/mevislab/4.0.2_1/build/MeVis/ThirdParty/Sources/Inventor/include/Inventor/actions/SoRayPickAction.h