Physics Material Properties for use with Simulation Engines#

Utility functions to define, apply, and bind physics material properties to collision geometry.

When UsdPhysicsMaterialAPI is applied on a UsdShadeMaterial it specifies various physical properties which should be used during simulation of the bound geometry.

In some cases it may be desirable to manage physics materials separately from visual materials, and in other cases it is useful to manage them as one prim.

The functions below can be used to create a new physics material, to apply physics properties to a visual material, and to bind a physics material to a rigid body or collider.

See UsdPhysicsMaterialAPI for details.

Note

When mixing visual and physical materials, be sure use both usdex::core::bindMaterial and usdex::core::bindPhysicsMaterial on the target geometry, to ensure the material is used in both rendering and simulation contexts.

Functions#

bool usdex::core::addPhysicsToMaterial(pxr::UsdShadeMaterial &material, const float dynamicFriction, const std::optional< float > staticFriction=std::nullopt, const std::optional< float > restitution=std::nullopt, const std::optional< float > density=std::nullopt)

Adds physical material parameters to an existing Material.

bool usdex::core::bindPhysicsMaterial(pxr::UsdPrim prim, const pxr::UsdShadeMaterial &material)

Binds a physics material to a given rigid body or collision geometry.

pxr::UsdShadeMaterial usdex::core::definePhysicsMaterial(pxr::UsdStagePtr stage, const pxr::SdfPath &path, const float dynamicFriction, const std::optional< float > staticFriction=std::nullopt, const std::optional< float > restitution=std::nullopt, const std::optional< float > density=std::nullopt)

Creates a Physics Material.

pxr::UsdShadeMaterial usdex::core::definePhysicsMaterial(pxr::UsdPrim parent, const std::string &name, const float dynamicFriction, const std::optional< float > staticFriction=std::nullopt, const std::optional< float > restitution=std::nullopt, const std::optional< float > density=std::nullopt)

Creates a Physics Material.

pxr::UsdShadeMaterial usdex::core::definePhysicsMaterial(pxr::UsdPrim prim, const float dynamicFriction, const std::optional< float > staticFriction=std::nullopt, const std::optional< float > restitution=std::nullopt, const std::optional< float > density=std::nullopt)

Creates a Physics Material.

Functions#

bool usdex::core::addPhysicsToMaterial(
pxr::UsdShadeMaterial &material,
const float dynamicFriction,
const std::optional<float> staticFriction = std::nullopt,
const std::optional<float> restitution = std::nullopt,
const std::optional<float> density = std::nullopt,
)#

Adds physical material parameters to an existing Material.

Used to apply UsdPhysicsMaterialAPI and related properties to an existing UsdShadeMaterial (e.g. a visual material).

Note

When mixing visual and physical materials, be sure use both usdex::core::bindMaterial and usdex::core::bindPhysicsMaterial on the target geometry, to ensure the material is used in both rendering and simulation contexts.

Parameters:

  • material – The material prim

  • dynamicFriction – The dynamic friction of the material

  • staticFriction – The static friction of the material

  • restitution – The restitution of the material

  • density – The density of the material

Returns:

Whether the physics material was successfully added to the material.

bool usdex::core::bindPhysicsMaterial(
pxr::UsdPrim prim,
const pxr::UsdShadeMaterial &material,
)#

Binds a physics material to a given rigid body or collision geometry.

Validates both the prim and the material, applies the UsdShadeMaterialBindingAPI to the target prim, and binds the material to the target prim with the “physics” purpose.

Note

The material is bound with the “physics” purpose, and with the default “fallback strength”, meaning descendant prims can override with a different material. If alternate behavior is desired, use the UsdShadeMaterialBindingAPI directly.

Note

We cannot bind materials to prims across different instance boundaries. This function returns an error if prim are not placed in an editable location.

Parameters:

  • prim – The prim that the material will affect

  • material – The material to bind to the prim

Returns:

Whether the material was successfully bound to the target prim.

pxr::UsdShadeMaterial usdex::core::definePhysicsMaterial(
pxr::UsdStagePtr stage,
const pxr::SdfPath &path,
const float dynamicFriction,
const std::optional<float> staticFriction = std::nullopt,
const std::optional<float> restitution = std::nullopt,
const std::optional<float> density = std::nullopt,
)#

Creates a Physics Material.

When UsdPhysicsMaterialAPI is applied on a UsdShadeMaterial it specifies various physical properties which should be used during simulation of the bound geometry.

See UsdPhysicsMaterialAPI for details.

Parameters:

  • stage – The stage on which to define the material

  • path – The absolute prim path at which to define the material

  • dynamicFriction – The dynamic friction of the material

  • staticFriction – The static friction of the material

  • restitution – The restitution of the material

  • density – The density of the material

Returns:

UsdShadeMaterial schema wrapping the defined UsdPrim

pxr::UsdShadeMaterial usdex::core::definePhysicsMaterial(
pxr::UsdPrim parent,
const std::string &name,
const float dynamicFriction,
const std::optional<float> staticFriction = std::nullopt,
const std::optional<float> restitution = std::nullopt,
const std::optional<float> density = std::nullopt,
)#

Creates a Physics Material.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

  • parent – Prim below which to define the physics material

  • name – Name of the physics material

  • dynamicFriction – The dynamic friction of the material

  • staticFriction – The static friction of the material

  • restitution – The restitution of the material

  • density – The density of the material

Returns:

UsdShadeMaterial schema wrapping the defined UsdPrim

pxr::UsdShadeMaterial usdex::core::definePhysicsMaterial(
pxr::UsdPrim prim,
const float dynamicFriction,
const std::optional<float> staticFriction = std::nullopt,
const std::optional<float> restitution = std::nullopt,
const std::optional<float> density = std::nullopt,
)#

Creates a Physics Material.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

  • prim – Prim to define the material. The prim’s type will be set to UsdShadeMaterial.

  • dynamicFriction – The dynamic friction of the material

  • staticFriction – The static friction of the material

  • restitution – The restitution of the material

  • density – The density of the material

Returns:

UsdShadeMaterial schema wrapping the defined UsdPrim