ShapePath

Fields

NONE
VERTEX
LINE
TRIANGLE
TEXT_BOX
BOUNDING_SPHERE

Detailed Description

class ShapePath : public RED::Object

Access path to an unique shape instance.

@related Picking, function RED::IWindow::FramePicking, function RED::IWindow::FramePickingRectangle, Real-Time Tutorials: Picking, Picking using a Lasso, class RED::ShapePath::LeafData

A RED::ShapePath class instance is usually returned by a call to RED::IWindow::FramePicking or to RED::IWindow::FramePickingRectangle, while trying to find the primitives that are hit by a picking pyramid in a scene, ‘under’ the mouse.

An element that is returned in a shape path is uniquely identified in a scene graph by it’s path starting from the root of the camera that contains it down to the element itself. Identification using the full path is a must have to be able to separate instances of the same object.

In addition, a shape path may contain sub-shape geometrical information such as informations on the hit triangles, lines, texts or points. These informations are stored in RED::ShapePath::LeafData class instances that are stored as items in the path (see RED::ShapePath::GetItemList).

The path has a sorting information so that intersected elements can be classified in distance from a picking source such as a viewpoint. By default, all elements are sorted from the closest to the farthest on a return from RED::IWindow::FramePicking.

Public Types

enum LEAF_TYPE

Type of a geometrical item picked in a RED::ShapePath::LeafData.

Values:

enumerator NONE

Indicates no leaf geometrical item in a RED::ShapePath::LeafData.

enumerator VERTEX

Indicates an isolated vertex item in a RED::ShapePath::LeafData.

enumerator LINE

Indicates a line segment item in a RED::ShapePath::LeafData.

enumerator TRIANGLE

Indicates a triangle item in a RED::ShapePath::LeafData.

enumerator TEXT_BOX

Indicates a text string box item in a RED::ShapePath::LeafData.

enumerator BOUNDING_SPHERE

Indicates a bounding sphere being picked in e RED::ShapePath::LeafData.

Public Functions

SET_CID(CID_class_REDShapePath)
IMPLEMENT_AS()
ShapePath()

Default constructor.

virtual ~ShapePath()

Destructor.

ShapePath(const RED::ShapePath &iSrc)

Copy constructor.

Parameters:iSrc – Source of the copy.
RED_RC operator=(const RED::ShapePath &iSrc)

Assignment operator.

Parameters:iSrc – Source of the assignment.
Returns:RED_OK if the operation has succeeded,

RED_ALLOC_FAILURE if a memory allocation has failed.
bool operator==(const RED::ShapePath &iPath) const

Equality operator.

This method compares two shape paths: ‘this’ with iPath. The comparison is done for the source camera and for the list of shapes that compose the path. All RED::ShapePath::LeafData sub shape level entities are ignored in the comparison. Two identical shape paths - in the sense of this method - are pointing to the same shape instance in a scene graph. Nothing more.

Parameters:iPath – Comparison operand.
Returns:true if the two paths are equal, false otherwise.
bool operator<(const RED::ShapePath &iPath) const

Comparison operator.

This method compares two shape paths: ‘this’ with iPath. The comparison is done for the source camera and for the list of shapes that compose the path. All RED::ShapePath::LeafData sub shape level entities are ignored in the comparison.

Parameters:iPath – Comparison operand.
Returns:true if ‘this’ is strictly inferior to ‘iPath’; false otherwise.
void ClearPath()

Clears a path.

All paths parameters are reseted.

inline RED::Object *GetViewpoint() const

Gets the viewpoint for which this path has been set.

This information is optional and can be helpful in scenes with many cameras to track the scene graph from which a shape path is coming.

Returns:The viewpoint’s address.
inline void SetViewpoint(RED::Object *iViewpoint)

Sets the viewpoint related to this shape path.

Parameters:iViewpoint – Viewpoint address.
inline RED::Object *GetWindow() const

Gets the window for which this path has been set.

This information is optional. If defined, it’s used to RED::ShapePath::SortItems properly.

Returns:The window address.
inline void SetWindow(RED::Object *iWindow)

Sets the window related to this shape path.

Parameters:iWindow – Window address.
inline RED::Vector<RED::Object*> &GetShapeList()
Returns:The current list of shapes in the path.
inline const RED::Vector<RED::Object*> &GetShapeList() const
Returns:The current list of shapes in the path.
inline int GetShapesCount() const
Returns:The current size of our path.
inline RED::Object *GetFirstShape() const
Returns:The first shape stored in the path or NULL if the path is empty.
inline RED::Object *GetLastShape() const
Returns:The last shape stored in the path list or NULL if the path is empty.
RED_RC AddShape(RED::Object *iShape)

Adds a shape to the end of path.

Parameters:iShape – Shape to push at the end of the path list.
Returns:RED_OK when the operation succeeded,

RED_ALLOC_FAILURE if an internal allocation did fail,

RED_FAIL otherwise.
void RemoveShape(RED::Object *iShape)

Removes the shape provided shape from the path.

Parameters:iShape – Shape to remove from the path. All instances of that shape are removed from it.
void ClearShapeList()

Clears the path list of shape.

RED_RC GetPathMatrix(RED::Matrix &oMatrix, int iStateNumber = -1) const

Computes the transformation matrix for the path leaves.

This method calculates the cumulative transformation matrix of all shapes found in the path. This transformation is the transformation to apply to children of the last shape in the path.

See also \ref wf_picking and \ref wf_picking_using_a_lasso.

Parameters:
  • oMatrix – Path cumulative transformation matrix.
  • iStateNumber – Queried state number.
Returns:

RED_OK when the operation succeeded,

RED_BAD_PARAM if the method received an invalid parameter.
inline RED::Vector<LeafData> &GetItemList()
Returns:The list of items in the path.
inline const RED::Vector<LeafData> &GetItemList() const
Returns:The list of items in the path.
inline int GetItemsCount() const
Returns:The number of geometrical items we have for the leaf shape.
inline LeafData &GetFirstItem()
Returns:The first item in the list or an undefined value if the list is empty.
inline const LeafData &GetFirstItem() const

The first item in the list or an undefined value if the list is empty.

See also \ref wf_picking and \ref wf_picking_using_a_lasso.

Returns:The first item in the list or an undefined value if the list is empty.
inline LeafData &GetLastItem()
Returns:The last item in the list or an undefined value if the list is empty.
inline const LeafData &GetLastItem() const
Returns:The last item in the list or an undefined value if the list is empty.
RED_RC AddItem(int iPrimitiveNumber, LEAF_TYPE iPrimitiveType, float *iP0, float *iP1, float *iP2, float *iP3, float *iPick)

Adds a geometrical item related to the leaf in the path.

Stores the provided geometrical information in an item of the path geometrical data list. This item is assumed to be related to the leaf of the shape path.

Added information must be in OCS (object space).

Parameters:
  • iPrimitiveNumber – Number of the primitive in the path leaf shape’s list.
  • iPrimitiveType – The kind of geometrical item we carry on.
  • iP0 – (float3) first vertex of the primitive.
  • iP1 – (float3) second vertex of the primitive (when needed).
  • iP2 – (float3) third vertex of the primitive (when needed).
  • iP3 – (float3) fourth vertex of the primitive (when needed).
  • iPick – (float3) Hit point (when needed).
Returns:

RED_OK when the operation succeeded,

RED_BAD_PARAM if the method received an invalid parameter,

RED_ALLOC_FAILURE if an internal memory allocation did fail.

RED_RC AddItem(int iPrimitiveNumber, LEAF_TYPE iPrimitiveType, double *iP0, double *iP1, double *iP2, double *iP3, double *iPick)

Adds a geometrical item related to the leaf in the path.

Stores the provided geometrical information in an item of the path geometrical data list. This item is assumed to be related to the leaf of the shape path.

Added information must be in OCS (object space).

This routine takes double precision inputs.

Parameters:
  • iPrimitiveNumber – Number of the primitive in the path leaf shape’s list.
  • iPrimitiveType – The kind of geometrical item we carry on.
  • iP0 – (double3) first vertex of the primitive.
  • iP1 – (double3) second vertex of the primitive (when needed).
  • iP2 – (double3) third vertex of the primitive (when needed).
  • iP3 – (double3) fourth vertex of the primitive (when needed).
  • iPick – (double3) Hit point (when needed).
Returns:

RED_OK when the operation succeeded,

RED_BAD_PARAM if the method received an invalid parameter,

RED_ALLOC_FAILURE if an internal memory allocation did fail.

RED_RC GetWCSItem(LeafData &oWCSLeafData, const LeafData &iOCSLeafData, int iStateNumber = -1) const

Transforms a geometrical item in WCS.

Turns a ShapePath::LeafData contents in WCS. This uses the path cumulative transformation matrix to do the conversion.

Parameters:
  • oWCSLeafData – Resulting transformed data.
  • iOCSLeafData – Data to transform.
  • iStateNumber – Queried state number.
Returns:

RED_OK when the operation succeeded,

RED_BAD_PARAM if the method received an invalid parameter.
RED_RC SortItems(double &oMinDistance, int iStateNumber = -1)

Depth sorting of the geometrical items from the viewpoint, double precision.

Sorts all geometrical items we have from the viewpoint’s eye position, using the RED::ShapePath::LeafData::_pick distance to the eye as sorting criteria.

Please note that the RED::OPTIONS_VIEWPOINT_ORTHOGRAPHIC_EYE_AUTO_OFFSET applies to the definition of the camera eye position if its orthographic. Note that if RED::ShapePath::SetWindow has not been called on the shape path, the option is ignored. The offset value used is equal to RED_INVTOL units.

Please also note that RED::ShapePath::SetViewpoint must have been called for the method to work.

Parameters:
  • oMinDistance – Returns the minimal distance of the geometrical items to the viewpoint’s eye. If we have no geometrical items, the returned distance is DBL_MAX.
  • iStateNumber – Queried state number.
Returns:

RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_FAIL if we have no viewpoint being set.
RED_RC SortItems(float &oMinDistance, int iStateNumber = -1)

Depth sorting of the geometrical items from the viewpoint, simple precision.

Same method as RED::ShapePath::SortItems, that return a simple floating point distance.

Parameters:
  • oMinDistance – Returns the minimal distance of the geometrical items to the viewpoint’s eye. If we have no geometrical items, the returned distance is DBL_MAX.
  • iStateNumber – Queried state number.
Returns:

RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_FAIL if we have no viewpoint.
void ClearItems()

Clears the path list of items.

RED_RC BoxFilter(double iBXMin, double iBXMax, double iBYMin, double iBYMax, double iBZMin, double iBZMax, const RED::Matrix &iMatrix, int iStateNumber = -1)

Filters all the picking results that are outside of a given box.

All RED::ShapePath::LeafData items in the path are processed, and all those whose WCS hit point are found to be outside of the box are removed from the path contents.

Parameters:
  • iBXMin – Box boundaries.
  • iBXMax – Box boundaries.
  • iBYMin – Box boundaries.
  • iBYMax – Box boundaries.
  • iBZMin – Box boundaries.
  • iBZMax – Box boundaries.
  • iMatrix – Extra transformation of the box.
  • iStateNumber – Transaction number for which the operation occurs.
Returns:

RED_OK if the operation has suceeded,

RED_BAD_PARAM if the method has received an invalid parameter.
class LeafData

Data container for low level scene graph data.

@related Picking, function RED::IWindow::FramePicking, function RED::IWindow::FramePickingRectangle, Real-Time Tutorials: Picking, Picking using a Lasso

Information is usually stored in object space coordinate system through this class (OCS). Note that the data contained by these objects vary with the kind of picking operation that has occured and with the type of the data that was picked. The number of points detailing the picked primitive vary according to its type. The picked position result may be valid or not depending on the type of picking operation.

Public Functions

inline LeafData()

Default constructor.

Public Members

int _num

Geometrical item number in the leaf shape.

LEAF_TYPE _type

Type of the geometrical item.

RED::Vector3 _p0

First vertex of a geometrical item.

RED::Vector3 _p1

Second vertex of a geometrical item.

RED::Vector3 _p2

Third vertex of a geometrical item.

RED::Vector3 _p3

Fourth vertex of a geometrical item.

RED::Vector3 _pick

Picked position in object space.