# class RED::ShapePath

Access path to an unique shape instance. More...

`#include <REDShapePath.h>`

Inherits: Object.

## Public classes:

class | LeafData |

## Public functions:

ShapePath ( ) | |

ShapePath ( const RED::ShapePath & iSrc ) | |

virtual | ~ShapePath ( ) |

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

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

RED_RC | AddShape ( RED::Object * iShape ) |

virtual void * | As ( const RED::CID & iCID ) |

template< class T_As > const T_As * | As ( ) const |

virtual const void * | As ( const RED::CID & iCID ) const |

template< class T_As > T_As * | As ( ) |

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

void | ClearItems ( ) |

void | ClearPath ( ) |

void | ClearShapeList ( ) |

LeafData & | GetFirstItem ( ) |

const LeafData & | GetFirstItem ( ) const |

RED::Object * | GetFirstShape ( ) const |

RED::Vector< LeafData > & | GetItemList ( ) |

const RED::Vector< LeafData > & | GetItemList ( ) const |

int | GetItemsCount ( ) const |

const LeafData & | GetLastItem ( ) const |

LeafData & | GetLastItem ( ) |

RED::Object * | GetLastShape ( ) const |

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

RED::Vector< RED::Object * > & | GetShapeList ( ) |

const RED::Vector< RED::Object * > & | GetShapeList ( ) const |

int | GetShapesCount ( ) const |

RED::Object * | GetViewpoint ( ) const |

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

RED::Object * | GetWindow ( ) const |

bool | operator< ( const RED::ShapePath & iPath ) const |

RED_RC | operator= ( const RED::ShapePath & iSrc ) |

bool | operator== ( const RED::ShapePath & iPath ) const |

void | RemoveShape ( RED::Object * iShape ) |

void | SetViewpoint ( RED::Object * iViewpoint ) |

void | SetWindow ( RED::Object * iWindow ) |

RED_RC | SortItems ( float & oMinDistance, int iStateNumber = -1 ) |

RED_RC | SortItems ( double & oMinDistance, int iStateNumber = -1 ) |

## Public static functions:

static RED::CID | GetClassID ( ) |

## Public enumerations:

enum | LEAF_TYPE { NONE = 0, VERTEX = 1, LINE = 2, TRIANGLE = 3, TEXT_BOX = 4, BOUNDING_SPHERE = 5 } |

## Protected variables:

RED::Vector< RED::Object * > | _path |

RED::Vector< LeafData > | _subpath |

RED::Object * | _vp |

RED::Object * | _window |

## Detailed description:

Access path to an unique shape instance.

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.

## Functions documentation

public RED::ShapePath::ShapePath | ( | ) |

Default constructor.

public RED::ShapePath::ShapePath | ( | const RED::ShapePath & | iSrc | ) |

Copy constructor.

Parameters:

iSrc: | Source of the copy. |

public virtual RED::ShapePath::~ShapePath | ( | ) |

Destructor.

public static RED::CID RED::ShapePath::GetClassID | ( | ) |

Reimplements: RED::Object::GetClassID.

public RED_RC RED::ShapePath::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_BAD_PARAM if the method received an invalid parameter,

RED_ALLOC_FAILURE if an internal memory allocation did fail.

public RED_RC RED::ShapePath::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_BAD_PARAM if the method received an invalid parameter,

RED_ALLOC_FAILURE if an internal memory allocation did fail.

public RED_RC RED::ShapePath::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_ALLOC_FAILURE if an internal allocation did fail,

RED_FAIL otherwise.

public virtual void * RED::ShapePath::As | ( | const RED::CID & | iCID | ) |

Converts the object to an instance of the given type.

Parameters:

iCID: | Requested class. |

Returns:

Reimplements: RED::Object::As.

template< class T_As > public const T_As * RED::ShapePath::As | ( | ) const |

Template version of the as const method.

Simply set *T* to be the class you want to retrieve an interface to.

Returns:

Reimplements: RED::Object::As.

public virtual const void * RED::ShapePath::As | ( | const RED::CID & | iCID | ) const |

Converts the object to an instance of the given type.

Parameters:

iCID: | Requested class. |

Returns:

Reimplements: RED::Object::As.

template< class T_As > public T_As * RED::ShapePath::As | ( | ) |

Template version of the as method.

Simply set *T* to be the class you want to retrieve an interface to.

Returns:

Reimplements: RED::Object::As.

public RED_RC RED::ShapePath::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_BAD_PARAM if the method has received an invalid parameter.

public void RED::ShapePath::ClearItems | ( | ) |

Clears the path list of items.

public void RED::ShapePath::ClearPath | ( | ) |

Clears a path.

All paths parameters are reseted.

public void RED::ShapePath::ClearShapeList | ( | ) |

Clears the path list of shape.

public LeafData & RED::ShapePath::GetFirstItem | ( | ) |

Returns:

public const LeafData & RED::ShapePath::GetFirstItem | ( | ) const |

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

See also Picking and Picking using a lasso.

Returns:

public RED::Object * RED::ShapePath::GetFirstShape | ( | ) const |

Returns:

public RED::Vector< LeafData > & RED::ShapePath::GetItemList | ( | ) |

Returns:

public const RED::Vector< LeafData > & RED::ShapePath::GetItemList | ( | ) const |

Returns:

public int RED::ShapePath::GetItemsCount | ( | ) const |

Returns:

public const LeafData & RED::ShapePath::GetLastItem | ( | ) const |

Returns:

public LeafData & RED::ShapePath::GetLastItem | ( | ) |

Returns:

public RED::Object * RED::ShapePath::GetLastShape | ( | ) const |

Returns:

public RED_RC RED::ShapePath::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 Picking and Picking using a lasso.

Parameters:

oMatrix: | Path cumulative transformation matrix. |

iStateNumber: | Queried state number. |

Returns:

public RED::Vector< RED::Object * > & RED::ShapePath::GetShapeList | ( | ) |

Returns:

public const RED::Vector< RED::Object * > & RED::ShapePath::GetShapeList | ( | ) const |

Returns:

public int RED::ShapePath::GetShapesCount | ( | ) const |

Returns:

public RED::Object * RED::ShapePath::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:

public RED_RC RED::ShapePath::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:

public RED::Object * RED::ShapePath::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:

public bool RED::ShapePath::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:

public RED_RC RED::ShapePath::operator= | ( | const RED::ShapePath & | iSrc | ) |

Assignment operator.

Parameters:

iSrc: | Source of the assignment. |

Returns:

public bool RED::ShapePath::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:

public void RED::ShapePath::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. |

public void RED::ShapePath::SetViewpoint | ( | RED::Object * | iViewpoint | ) |

Sets the viewpoint related to this shape path.

Parameters:

iViewpoint: | Viewpoint address. |

public void RED::ShapePath::SetWindow | ( | RED::Object * | iWindow | ) |

Sets the window related to this shape path.

Parameters:

iWindow: | Window address. |

public RED_RC RED::ShapePath::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_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.

public RED_RC RED::ShapePath::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_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.

## Variables documentation

List of shapes in the path.

Sub shape level path information.

Source viewpoint.

Source window.

## Enumerations documentation

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

Enumerator:

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

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

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

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

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

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