PxShape

class PxShape : public PxRefCounted 

Abstract class for collision shapes.

Shapes are shared, reference counted objects.

An instance can be created by calling the createShape() method of the PxRigidActor class, or the createShape() method of the PxPhysics class.

Visualizations

Collision Filtering

void *userData: user can assign this to whatever, usually to create a 1:1 relationship with a user object.

virtual void setSimulationFilterData(const PxFilterData &data) = 0

Sets the user definable collision filter data.

Sleeping: Does wake up the actor if the filter data change causes a formerly suppressed collision pair to be enabled.

Default: (0,0,0,0)

See also

getSimulationFilterData()

virtual PxFilterData getSimulationFilterData() const = 0

Retrieves the shape’s collision filter data.

See also

setSimulationFilterData()

virtual void setQueryFilterData(const PxFilterData &data) = 0

Sets the user definable query filter data.

Default: (0,0,0,0)

See also

getQueryFilterData()

virtual PxFilterData getQueryFilterData() const = 0

Retrieves the shape’s Query filter data.

See also

setQueryFilterData()

virtual void setMaterials(PxMaterial *const *materials, PxU16 materialCount) = 0

Assigns material(s) to the shape.

Will remove existing materials from the shape.

Sleeping: Does NOT wake the associated actor up automatically.

Parameters

materials – [in] List of material pointers to assign to the shape. See PxMaterial
materialCount – [in] The number of materials provided.

virtual void setSoftBodyMaterials(PxFEMSoftBodyMaterial *const *materials, PxU16 materialCount) = 0

Assigns FEM soft body material(s) to the shape.

Will remove existing materials from the shape.

Sleeping: Does NOT wake the associated actor up automatically.

Parameters

materials – [in] List of material pointers to assign to the shape. See PxFEMSoftBodyMaterial
materialCount – [in] The number of materials provided.

virtual void setClothMaterials(PxFEMClothMaterial *const *materials, PxU16 materialCount) = 0

Assigns FEM cloth material(s) to the shape.

Will remove existing materials from the shape. Sleeping: Does NOT wake the associated actor up automatically.

Warning

Feature under development, only for internal usage.

Parameters

materials – [in] List of material pointers to assign to the shape. See PxFEMClothMaterial
materialCount – [in] The number of materials provided.

virtual PxU16 getNbMaterials() const = 0

Returns the number of materials assigned to the shape.

You can use getMaterials() to retrieve the material pointers.

See also

PxMaterial getMaterials()

Returns: Number of materials associated with this shape.

virtual PxU32 getMaterials(PxMaterial **userBuffer, PxU32 bufferSize, PxU32 startIndex = 0) const = 0

Retrieve all the material pointers associated with the shape.

You can retrieve the number of material pointers by calling getNbMaterials()

Note: The returned data may contain invalid pointers if you release materials using PxMaterial::release().

Parameters

userBuffer – [out] The buffer to store the material pointers.
bufferSize – [in] Size of provided user buffer.
startIndex – [in] Index of first material pointer to be retrieved

Returns

Number of material pointers written to the buffer.

virtual PxU32 getSoftBodyMaterials(PxFEMSoftBodyMaterial **userBuffer, PxU32 bufferSize, PxU32 startIndex = 0) const = 0

Retrieve all the FEM soft body material pointers associated with the shape.

You can retrieve the number of material pointers by calling getNbMaterials()

Note: The returned data may contain invalid pointers if you release materials using PxMaterial::release().

Parameters

userBuffer – [out] The buffer to store the material pointers.
bufferSize – [in] Size of provided user buffer.
startIndex – [in] Index of first material pointer to be retrieved

Returns

Number of material pointers written to the buffer.

virtual PxU32 getClothMaterials(PxFEMClothMaterial **userBuffer, PxU32 bufferSize, PxU32 startIndex = 0) const = 0

Retrieve all the FEM cloth material pointers associated with the shape.

You can retrieve the number of material pointers by calling getNbMaterials()

Note: The returned data may contain invalid pointers if you release materials using PxMaterial::release().

Warning

Feature under development, only for internal usage.

Parameters

userBuffer – [out] The buffer to store the material pointers.
bufferSize – [in] Size of provided user buffer.
startIndex – [in] Index of first material pointer to be retrieved

Returns

Number of material pointers written to the buffer.

virtual PxBaseMaterial *getMaterialFromInternalFaceIndex(PxU32 faceIndex) const = 0

Retrieve material from given triangle index.

The input index is the internal triangle index as used inside the SDK. This is the index returned to users by various SDK functions such as raycasts.

This function is only useful for triangle meshes or heightfields, which have per-triangle materials. For other shapes or SDF triangle meshes, the function returns the single material associated with the shape, regardless of the index.

Note

If faceIndex value of 0xFFFFffff is passed as an input for mesh and heightfield shapes, this function will issue a warning and return NULL.

Note

Scene queries set the value of PxQueryHit::faceIndex to 0xFFFFffff whenever it is undefined or does not apply.

Parameters: faceIndex – [in] The internal triangle index whose material you want to retrieve.
Returns: Material from input triangle

virtual void setContactOffset(PxReal contactOffset) = 0

Sets the contact offset.

Shapes whose distance is less than the sum of their contactOffset values will generate contacts. The contact offset must be positive and greater than the rest offset. Having a contactOffset greater than than the restOffset allows the collision detection system to predictively enforce the contact constraint even when the objects are slightly separated. This prevents jitter that would occur if the constraint were enforced only when shapes were within the rest distance.

Default: 0.02f * PxTolerancesScale::length

Sleeping: Does NOT wake the associated actor up automatically.

Parameters: contactOffset – [in] Range: [maximum(0,restOffset), PX_MAX_F32)

virtual PxReal getContactOffset() const = 0

Retrieves the contact offset.

See also

setContactOffset()

Returns: The contact offset of the shape.

virtual void setRestOffset(PxReal restOffset) = 0

Sets the rest offset.

Two shapes will come to rest at a distance equal to the sum of their restOffset values. If the restOffset is 0, they should converge to touching exactly. Having a restOffset greater than zero is useful to have objects slide smoothly, so that they do not get hung up on irregularities of each others’ surfaces.

Default: 0.0f

Sleeping: Does NOT wake the associated actor up automatically.

See also

getRestOffset setContactOffset

Parameters: restOffset – [in] Range: (-PX_MAX_F32, contactOffset)

virtual PxReal getRestOffset() const = 0

Retrieves the rest offset.

See also

setRestOffset()

Returns: The rest offset of the shape.

virtual void setDensityForFluid(PxReal densityForFluid) = 0

Sets the density used to interact with fluids.

To be physically accurate, the density of a rigid body should be computed as its mass divided by its volume. To simplify tuning the interaction of fluid and rigid bodies, the density for fluid can differ from the real density. This allows to create floating bodies, even if they are supposed to sink with their mass and volume.

Default: 800.0f

See also

getDensityForFluid

Parameters: densityForFluid – [in] Range: (0, PX_MAX_F32)

virtual PxReal getDensityForFluid() const = 0

Retrieves the density used to interact with fluids.

See also

setDensityForFluid()

Returns: The density of the body when interacting with fluid.

virtual void setTorsionalPatchRadius(PxReal radius) = 0

Sets torsional patch radius.

This defines the radius of the contact patch used to apply torsional friction. If the radius is 0 (and minTorsionalPatchRadius is 0 too, see setMinTorsionalPatchRadius), no torsional friction will be applied. If the radius is > 0, some torsional friction will be applied. This is proportional to the penetration depth so, if the shapes are separated or penetration is zero, no torsional friction will be applied. It is used to approximate rotational friction introduced by the compression of contacting surfaces.

Default: 0.0

Note

Will only be active, if the friction patch has a single anchor point only. This is for example the case, if a contact patch has a single contact point.

Note

Only supported in combination with solver type PxSolverType::eTGS.

Parameters: radius – [in] Range: [0, PX_MAX_F32)

virtual PxReal getTorsionalPatchRadius() const = 0

Gets torsional patch radius.

See setTorsionalPatchRadius for more info.

Returns: The torsional patch radius of the shape.

virtual void setMinTorsionalPatchRadius(PxReal radius) = 0

Sets minimum torsional patch radius.

This defines the minimum radius of the contact patch used to apply torsional friction. If the radius is 0, the amount of torsional friction that will be applied will be entirely dependent on the value of torsionalPatchRadius.

If the radius is > 0, some torsional friction will be applied regardless of the value of torsionalPatchRadius or the amount of penetration.

Default: 0.0

Note

Will only be active in certain cases, see setTorsionalPatchRadius for details.

Parameters: radius – [in] Range: [0, PX_MAX_F32)

virtual PxReal getMinTorsionalPatchRadius() const = 0

Gets minimum torsional patch radius.

See setMinTorsionalPatchRadius for more info.

Returns: The minimum torsional patch radius of the shape.

virtual PxU32 getInternalShapeIndex() const = 0

Gets internal shape id.

The internal shape id can be used to reference a specific shape when processing data on the gpu.

See also

PxScene evaluateSDFDistances()

Returns: The shape id

virtual void setFlag(PxShapeFlag::Enum flag, bool value) = 0

Sets shape flags.

Sleeping: Does NOT wake the associated actor up automatically.

Default: PxShapeFlag::eVISUALIZATION | PxShapeFlag::eSIMULATION_SHAPE | PxShapeFlag::eSCENE_QUERY_SHAPE

See also

PxShapeFlag getFlags()

Parameters

flag – [in] The shape flag to enable/disable. See PxShapeFlag.
value – [in] True to set the flag. False to clear the flag specified in flag.

virtual void setFlags(PxShapeFlags inFlags) = 0

Sets shape flags.

See also

PxShapeFlag getFlags()

virtual PxShapeFlags getFlags() const = 0

Retrieves shape flags.

See also

PxShapeFlag setFlag()

Returns: The values of the shape flags.

virtual bool isExclusive() const = 0

Returns true if the shape is exclusive to an actor.

See also

PxPhysics::createShape()

virtual void setName(const char *name) = 0

Sets a name string for the object that can be retrieved with getName().

This is for debugging and is not used by the SDK. The string is not copied by the SDK, only the pointer is stored.

Default: NULL

See also

getName()

Parameters: name – [in] The name string to set the objects name to.

virtual const char *getName() const = 0

retrieves the name string set with setName().

See also

setName()

Returns: The name associated with the shape.

inline virtual const char *getConcreteTypeName() const

Returns string name of dynamic type.

Returns: Class name of most derived type of this object.

inline PxShape(PxBaseFlags baseFlags)

inline PxShape(PxType concreteType, PxBaseFlags baseFlags)

inline virtual ~PxShape()

inline virtual bool isKindOf(const char *name) const: Returns whether a given type name matches with the type of this instance.

Pose Manipulation

virtual void setLocalPose(const PxTransform &pose) = 0

Sets the pose of the shape in actor space, i.e.

relative to the actors to which they are attached.

This transformation is identity by default.

The local pose is an attribute of the shape, and so will apply to all actors to which the shape is attached.

Sleeping: Does NOT wake the associated actor up automatically.

Note: Does not automatically update the inertia properties of the owning actor (if applicable); use the PhysX extensions method PxRigidBodyExt::updateMassAndInertia() to do this.

Default: the identity transform

See also

getLocalPose()

Parameters: pose – [in] The new transform from the actor frame to the shape frame. Range: rigid body transform

virtual PxTransform getLocalPose() const = 0

Retrieves the pose of the shape in actor space, i.e.

relative to the actor they are owned by.

This transformation is identity by default.

See also

setLocalPose()

Returns: Pose of shape relative to the actor’s frame.

Public Functions

virtual void release() = 0

Decrements the reference count of a shape and releases it if the new reference count is zero.

Note that in releases prior to PhysX 3.3 this method did not have reference counting semantics and was used to destroy a shape created with PxActor::createShape(). In PhysX 3.3 and above, this usage is deprecated, instead, use PxRigidActor::detachShape() to detach a shape from an actor. If the shape to be detached was created with PxActor::createShape(), the actor holds the only counted reference, and so when the shape is detached it will also be destroyed.

virtual void setGeometry(const PxGeometry &geometry) = 0

Adjust the geometry of the shape.

See also

PxGeometry PxGeometryType getGeometryType()

Note

The type of the passed in geometry must match the geometry type of the shape.

Note

It is not allowed to change the geometry type of a shape.

Note

This function does not guarantee correct/continuous behavior when objects are resting on top of old or new geometry.

Parameters: geometry – [in] New geometry of the shape.

virtual const PxGeometry &getGeometry() const = 0

Retrieve a reference to the shape’s geometry.

See also

PxGeometry PxGeometryType getGeometryType() setGeometry()

Warning

The returned reference has the same lifetime as the PxShape it comes from.

Returns: Reference to internal PxGeometry object.

virtual PxRigidActor *getActor() const = 0

Retrieves the actor which this shape is associated with.

Returns: The actor this shape is associated with, if it is an exclusive shape, else NULL

virtual PxU32 getReferenceCount() const = 0

Returns the reference count of the object.

At creation, the reference count of the object is 1. Every other object referencing this object increments the count by 1. When the reference count reaches 0, and only then, the object gets destroyed automatically.

Returns: the current reference count.

virtual void acquireReference() = 0

Acquires a counted reference to this object.

This method increases the reference count of the object by 1. Decrement the reference count by calling release()

template<class T> inline T *is()

template<class T> inline const T *is() const

inline PxType getConcreteType() const

Returns concrete type of object.

See also

PxConcreteType

Returns: PxConcreteType::Enum of serialized object

inline void setBaseFlag(PxBaseFlag::Enum flag, bool value)

Set PxBaseFlag

Parameters

flag – [in] The flag to be set
value – [in] The flags new value

inline void setBaseFlags(PxBaseFlags inFlags)

Set PxBaseFlags

See also

PxBaseFlags

Parameters: inFlags – [in] The flags to be set

inline PxBaseFlags getBaseFlags() const

Returns PxBaseFlags.

See also

PxBaseFlags

Returns: PxBaseFlags

inline virtual bool isReleasable() const

Whether the object is subordinate.

A class is subordinate, if it can only be instantiated in the context of another class.

See also

PxSerialization::isSerializable

Returns: Whether the class is subordinate

Protected Functions

inline virtual void onRefCountZero()

template<class T> inline bool typeMatch() const

Protected Attributes

PxType mConcreteType

PxBaseFlags mBaseFlags

PxU32 mBuiltInRefCount