QuesaPick.h

Discussion

Functions

( TQ3Status ) Q3HitPath_EmptyData (
    TQ3HitPath *hitPath
);

Discussion

Release the memory allocated by a previous call to Q3Pick_GetPickDetailData.

Parameter Descriptions

hitPath

The hit-path data to release.

function result

Success or failure of the operation.

( TQ3Status ) Q3MeshEdgePart_GetEdge (
    TQ3MeshEdgePartObject meshEdgePartObject,
    TQ3MeshEdge *edge
);

Discussion

Get the mesh edge that corresponds to a mesh edge part.

Parameter Descriptions

meshEdgePartObject

The mesh edge to query.

edge

Receives the mesh edge that corresponds to meshEdgePartObject.

function result

Success or failure of the operation.

( TQ3Status ) Q3MeshFacePart_GetFace (
    TQ3MeshFacePartObject meshFacePartObject,
    TQ3MeshFace *face
);

Discussion

Get the mesh face that corresponds to a mesh face part.

Parameter Descriptions

meshFacePartObject

The mesh face to query.

face

Receives the mesh face that corresponds to meshFacePartObject.

function result

Success or failure of the operation.

( TQ3Status ) Q3MeshPart_GetComponent (
    TQ3MeshPartObject meshPartObject,
    TQ3MeshComponent *component
);

Discussion

Get the mesh component that contains a mesh part object.

Parameter Descriptions

meshPartObject

The mesh part to query.

component

Receives the mesh component that contains meshPartObject.

function result

Success or failure of the operation.

( TQ3ObjectType ) Q3MeshPart_GetType (
    TQ3MeshPartObject meshPartObject
);

Discussion

Get the type of a mesh part object.

Returns kQ3MeshPartTypeMeshFacePart, kQ3MeshPartTypeMeshEdgePart, or kQ3MeshPartTypeMeshVertexPart. If the type can not be determined, returns kQ3ObjectTypeInvalid.

Parameter Descriptions

meshPartObject

The mesh part to query.

function result

The type of the mesh part.

( TQ3Status ) Q3MeshVertexPart_GetVertex (
    TQ3MeshVertexPartObject meshVertexPartObject,
    TQ3MeshVertex *vertex
);

Discussion

Get the mesh vertex that corresponds to a mesh vertex part.

Parameter Descriptions

meshVertexPartObject

The mesh vertex to query.

vertex

Receives the mesh vertex that corresponds to meshVertedPartObject.

function result

Success or failure of the operation.

( TQ3Status ) Q3Pick_EmptyHitList (
    TQ3PickObject pick
);

Discussion

Empty the hit list of a pick object.

Parameter Descriptions

pick

The pick object to update.

function result

Success or failure of the operation.

( TQ3Status ) Q3Pick_GetData (
    TQ3PickObject pick,
    TQ3PickData *data
);

Discussion

Get the common state of a pick object.

Parameter Descriptions

pick

The pick object to query.

data

Receives the common state of the pick object.

function result

Success or failure of the operation.

( TQ3Status ) Q3Pick_GetEdgeTolerance (
    TQ3PickObject pick,
    float *edgeTolerance
);

Discussion

Get the edge tolerance of a pick object.

Parameter Descriptions

pick

The pick object to query.

edgeTolerance

Receives the edge tolerance of the pick object.

function result

Success or failure of the operation.

( TQ3Status ) Q3Pick_GetNumHits (
    TQ3PickObject pick,
    TQ3Uns32 *numHits
);

Discussion

Get the number of hits of a pick object.

Parameter Descriptions

pick

The pick object to query.

numHits

Receives the number of hits of a pick object.

function result

Success or failure of the operation.

( TQ3Status ) Q3Pick_GetPickDetailData (
    TQ3PickObject pick,
    TQ3Uns32 index,
    TQ3PickDetail pickDetailValue,
    void *detailData
);

Discussion

Get the data for a pick result.

When the kQ3PickDetailMaskPath data is requested, it must be disposed of by the caller using Q3HitPath_EmptyData.

Pick results are indexed from 0, and the number of available pick results is returned by Q3Pick_GetNumHits.

Parameter Descriptions

pick

The pick object to query.

index

The index of the hit to query.

pickDetailValue

The type of data requested from the hit.

detailData

Receives the data from the hit.

function result

Success or failure of the operation.

( TQ3Status ) Q3Pick_GetPickDetailValidMask (
    TQ3PickObject pick,
    TQ3Uns32 index,
    TQ3PickDetail *pickDetailValidMask
);

Discussion

Get the available data mask for a pick result.

Pick results are indexed from 0, and the number of available pick results is returned by Q3Pick_GetNumHits.

Parameter Descriptions

pick

The pick object to query.

index

The index of the hit to query.

pickDetailValidMask

Receives the available data mask for the hit.

function result

Success or failure of the operation.

( TQ3ObjectType ) Q3Pick_GetType (
    TQ3PickObject pick
);

Discussion

Get the type of a pick object.

Returns kQ3ObjectTypeInvalid if the pick type is unknown.

Parameter Descriptions

pick

The pick to query.

function result

The type of the pick object.

( TQ3Status ) Q3Pick_GetVertexTolerance (
    TQ3PickObject pick,
    float *vertexTolerance
);

Discussion

Get the vertex tolerance of a pick object.

Parameter Descriptions

pick

The pick object to query.

vertexTolerance

Receives the vertex tolerance of the pick object.

function result

Success or failure of the operation.

( TQ3Status ) Q3Pick_SetData (
    TQ3PickObject pick,
    const TQ3PickData *data
);

Discussion

Set the common state of a pick object.

Parameter Descriptions

pick

The pick object to update.

data

The new common state for the pick object.

function result

Success or failure of the operation.

( TQ3Status ) Q3Pick_SetEdgeTolerance (
    TQ3PickObject pick,
    float edgeTolerance
);

Discussion

Set the edge tolerance of a pick object.

Parameter Descriptions

pick

The pick object to update.

edgeTolerance

The new edge tolerance of the pick object.

function result

Success or failure of the operation.

( TQ3Status ) Q3Pick_SetVertexTolerance (
    TQ3PickObject pick,
    float vertexTolerance
);

Discussion

Set the vertex tolerance of a pick object.

Parameter Descriptions

pick

The pick object to update.

vertexTolerance

The new vertex tolerance of the pick object.

function result

Success or failure of the operation.

( TQ3Status ) Q3ShapePart_GetShape (
    TQ3ShapePartObject shapePartObject,
    TQ3ShapeObject *shapeObject
);

Discussion

Get the shape object that contains a shape part object.

Parameter Descriptions

shapePartObject

The shape part to query.

shapeObject

Receives the shape object that contains shapePartObject.

function result

Success or failure of the operation.

( TQ3ObjectType ) Q3ShapePart_GetType (
    TQ3ShapePartObject shapePartObject
);

Discussion

Get the type of a shape part object.

Parameter Descriptions

shapePartObject

The shape part to query.

function result

The type of the shape part.

( TQ3Status ) Q3WindowPointPick_GetData (
    TQ3PickObject pick,
    TQ3WindowPointPickData *data
);

Discussion

Get the data of a window-point pick object.

Parameter Descriptions

pick

The pick object to query.

data

Receives the data of the pick object.

function result

Success or failure of the operation.

( TQ3Status ) Q3WindowPointPick_GetPoint (
    TQ3PickObject pick,
    TQ3Point2D *point
);

Discussion

Get the pick point of a window-point pick object.

Parameter Descriptions

pick

The pick object to query.

point

Receives the pick point of the pick object.

function result

Success or failure of the operation.

( TQ3PickObject ) Q3WindowPointPick_New (
    const TQ3WindowPointPickData *data
);

Discussion

Create a new window-point pick object.

Parameter Descriptions

data

The data for the pick object.

function result

The new pick object.

( TQ3Status ) Q3WindowPointPick_SetData (
    TQ3PickObject pick,
    const TQ3WindowPointPickData *data
);

Discussion

Set the data for a window-point pick object.

Parameter Descriptions

pick

The pick object to update.

data

The new data for the pick object.

function result

Success or failure of the operation.

( TQ3Status ) Q3WindowPointPick_SetPoint (
    TQ3PickObject pick,
    const TQ3Point2D *point
);

Discussion

Set the pick point of a window-point pick object.

Parameter Descriptions

pick

The pick object to update.

point

The new pick point for the pick object.

function result

Success or failure of the operation.

( TQ3Status ) Q3WindowRectPick_GetData (
    TQ3PickObject pick,
    TQ3WindowRectPickData *data
);

Discussion

Get the data of a window-rect pick object.

Parameter Descriptions

pick

The pick object to query.

data

Receives the data of the pick object.

function result

Success or failure of the operation.

( TQ3Status ) Q3WindowRectPick_GetRect (
    TQ3PickObject pick,
    TQ3Area *rect
);

Discussion

Get the pick rect of a window-rect pick object.

Parameter Descriptions

pick

The pick object to query.

rect

Receives the pick rect of the pick object.

function result

Success or failure of the operation.

( TQ3PickObject ) Q3WindowRectPick_New (
    const TQ3WindowRectPickData *data
);

Discussion

Create a new window-rect pick object.

Parameter Descriptions

data

The data for the pick object.

function result

The new pick object.

( TQ3Status ) Q3WindowRectPick_SetData (
    TQ3PickObject pick,
    const TQ3WindowRectPickData *data
);

Discussion

Set the data of a window-rect pick object.

Parameter Descriptions

pick

The pick object to update.

data

The new data for the pick object.

function result

Success or failure of the operation.

( TQ3Status ) Q3WindowRectPick_SetRect (
    TQ3PickObject pick,
    const TQ3Area *rect
);

Discussion

Set the pick rect of a window-rect pick object.

Parameter Descriptions

pick

The pick object to update.

rect

The new pick rect of the pick object.

function result

Success or failure of the operation.

( TQ3Status ) Q3WorldRayPick_GetData (
    TQ3PickObject pick,
    TQ3WorldRayPickData *data
);

Discussion

Get the data of a world-ray pick object.

Parameter Descriptions

pick

The pick object to query.

data

Receives the data for the pick object.

function result

Success or failure of the operation.

( TQ3Status ) Q3WorldRayPick_GetRay (
    TQ3PickObject pick,
    TQ3Ray3D *ray
);

Discussion

Get the pick ray of a world-ray pick object.

Parameter Descriptions

pick

The pick object to query.

ray

Receives the ray of the pick object.

function result

Success or failure of the operation.

( TQ3PickObject ) Q3WorldRayPick_New (
    const TQ3WorldRayPickData *data
);

Discussion

Create a new world-ray pick object.

Parameter Descriptions

data

The data for the pick object.

function result

The new pick object.

( TQ3Status ) Q3WorldRayPick_SetData (
    TQ3PickObject pick,
    const TQ3WorldRayPickData *data
);

Discussion

Set the data of a world-ray pick object.

Parameter Descriptions

pick

The pick object to update.

data

The new data for the pick object.

function result

Success or failure of the operation.

( TQ3Status ) Q3WorldRayPick_SetRay (
    TQ3PickObject pick,
    const TQ3Ray3D *ray
);

Discussion

Set the pick ray of a world-ray pick object.

Parameter Descriptions

pick

The pick object to update.

ray

The new ray for the pick object.

function result

Success or failure of the operation.

Typedefs

typedef TQ3Uns32 TQ3PickDetail;

Discussion

A 32-bit integer used as a set of flags. See TQ3PickDetailMasks for enumerated constants that can be combined in this data type.

Structs

typedef struct TQ3HitPath {
    TQ3GroupObject                              rootGroup;
    TQ3Uns32                                    depth;
    TQ3GroupPosition                            *positions;
} TQ3HitPath;

Discussion

Hit path data.

Returned by Q3Pick_GetPickDetailData for the kQ3PickDetailMaskPath pick selector. Disposed of by Q3HitPath_EmptyData.

rootGroup holds the top level group which encloses the picked object. positions holds an array for each nested group within the submit sequence, indicating the position that was submitted at each level. This array contains depth values.

E.g., assuming 'object' is the picked object, then submitting:

group1(object)

would produce a rootGroup field of group 1, a depth field of 1, and positions[0] would contain the position of object within group1.

Submitting:

group1(group2(object))

would produce a rootGroup field of group1, a depth field of 2, positions[0] would hold the position of group2 within group1, and positions[1] would hold the position of object within group2.


Note that the contents of the position array are only valid if the submitted groups are unchanged since they were submitted for picking.

If these groups have had items added or removed since they were submitted, the positions array will no longer be valid.

Field Descriptions

rootGroup

Top level group which was submitted.

depth

Number of valid entries within positions.

positions

Array of group positions leading to the picked object.

typedef struct TQ3PickData {
    TQ3PickSort                                 sort;
    TQ3PickDetail                               mask;
    TQ3Uns32                                    numHitsToReturn;
} TQ3PickData;

Discussion

Describes the common state for a pick object.

Field Descriptions

sort

The type of sorting, if any, to performed on the results.

mask

The type of pick information to be returned.

numHitsToReturn

The number of hits to return. Set to kQ3ReturnAllHits to retrieve all hits.

typedef struct TQ3WindowPointPickData {
    TQ3PickData                                 data;
    TQ3Point2D                                  point;
    float                                       vertexTolerance;
    float                                       edgeTolerance;
} TQ3WindowPointPickData;

Discussion

Describes the state for a window-point pick object.

Field Descriptions

data

The common state for the pick.

point

The pick point in local window coordinates. Note that on Win32, this means relative to the HWND which contains the view.

vertexTolerance

The vertex tolerance. Only relevant to picking Point objects.

edgeTolerance

The edge tolerance. Only relevant to picking one-dimensional objects such as Lines and PolyLines.

typedef struct TQ3WindowRectPickData {
    TQ3PickData                                 data;
    TQ3Area                                     rect;
} TQ3WindowRectPickData;

Discussion

Describes the state for a window-rect pick object.

Field Descriptions

data

The common state for the pick.

rect

The pick rect in local window coordinates.

typedef struct TQ3WorldRayPickData {
    TQ3PickData                                 data;
    TQ3Ray3D                                    ray;
    float                                       vertexTolerance;
    float                                       edgeTolerance;
} TQ3WorldRayPickData;

Discussion

Describes the state for a world-ray pick object.

Field Descriptions

data

The common state for the pick.

ray

The pick ray in world coordinates.

vertexTolerance

The vertex tolerance. Only relevant to picking Point objects.

edgeTolerance

The edge tolerance. Only relevant to picking one-dimensional objects such as Lines and PolyLines.

Enumerations

typedef enum TQ3PickDetailMasks {
    kQ3PickDetailNone                           = 0,
    kQ3PickDetailMaskPickID                     = (1 << 0),
    kQ3PickDetailMaskPath                       = (1 << 1),
    kQ3PickDetailMaskObject                     = (1 << 2),
    kQ3PickDetailMaskLocalToWorldMatrix         = (1 << 3),
    kQ3PickDetailMaskXYZ                        = (1 << 4),
    kQ3PickDetailMaskDistance                   = (1 << 5),
    kQ3PickDetailMaskNormal                     = (1 << 6),
    kQ3PickDetailMaskShapePart                  = (1 << 7),
    kQ3PickDetailMaskPickPart                   = (1 << 8),
    kQ3PickDetailMaskUV                         = (1 << 9),
    kQ3PickDetailSize32                         = 0xFFFFFFFF
} TQ3PickDetailMasks;

Discussion

Bitfield indicating the type of data to be returned by picks.

Constants

kQ3PickDetailNone

No pick details are required.

kQ3PickDetailMaskPickID

The picking ID of the picked object.

kQ3PickDetailMaskPath

The path through the model hierarchy to the picked object.

kQ3PickDetailMaskObject

The picked object.

kQ3PickDetailMaskLocalToWorldMatrix

The local-to-world matrix for the picked object.

kQ3PickDetailMaskXYZ

The picked location in world coordinates.

kQ3PickDetailMaskDistance

The distance between the picked location and the pick origin.

kQ3PickDetailMaskNormal

The surface normal at the picked location.

kQ3PickDetailMaskShapePart

The shape part of the picked object.

kQ3PickDetailMaskPickPart

The picked object, edge, or vertex.

kQ3PickDetailMaskUV

The UV coordinate of the picked location.

typedef enum TQ3PickSort {
    kQ3PickSortNone                             = 0,
    kQ3PickSortNearToFar                        = 1,
    kQ3PickSortFarToNear                        = 2,
    kQ3PickSortSize32                           = 0xFFFFFFFF
} TQ3PickSort;

Discussion

The order in which pick results should be sorted.

Constants

kQ3PickSortNone

The pick hit list should not be sorted.

kQ3PickSortNearToFar

The pick hit list should be sorted from near to far.

kQ3PickSortFarToNear

The pick hit list should be sorted from far to near.

#defines

#define kQ3ReturnAllHits                        0

Discussion

This value can be placed in the numHitsToReturn field of the TQ3PickData structure to indicate that we want information about all hits.

© 1999-2008 Quesa Developers (Last Updated 5/10/2008)