PxShape

Defined in include/PxShape.h

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

• PxVisualizationParameter::eCOLLISION_AABBS

• PxVisualizationParameter::eCOLLISION_SHAPES

• PxVisualizationParameter::eCOLLISION_AXES

See also

PxPhysics.createShape() PxRigidActor.createShape() PxBoxGeometry PxSphereGeometry PxCapsuleGeometry PxPlaneGeometry PxConvexMeshGeometry PxTriangleMeshGeometry PxHeightFieldGeometry

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.

See also

PxPhysics.createMaterial() getMaterials()

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.

See also

PxPhysics.createFEMSoftBodyMaterial() getSoftBodyMaterials()

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.

See also

PxPhysics.createFEMClothMaterial() getClothMaterials()

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().

See also

PxMaterial getNbMaterials() 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().

See also

PxFEMSoftBodyMaterial getNbMaterials() 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().

See also

PxFEMClothMaterial getNbMaterials() 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.

See also

PxMaterial getNbMaterials() PxMaterial::release()

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.

See also

getContactOffset PxTolerancesScale setRestOffset

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.

This is not supported on the CPU, and the function will return PX_INVALID_U32;

Deprecated:

, use getGPUIndex() instead.

See also

PxScene evaluateSDFDistances()

Returns

The shape id

virtual PxShapeGPUIndex getGPUIndex() const = 0

Returns the GPU shape index.

See also

PxDirectGPUAPI::evaluateSDFDistances().

Note

This function only returns valid results if GPU dynamics is enabled.

Returns

The GPU index, or 0xFFFFFFFF if the shape is not attached to a PxActor that is inserted into a PxScene.

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.

See also

PxRigidActor::createShape() PxPhysics::createShape() PxRigidActor::attachShape() PxRigidActor::detachShape()

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.

See also

PxRigidStatic, PxRigidDynamic, PxArticulationLink

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