carb::blast::Blast

Defined in Blast.h

struct Blast

Plugin interface for the omni.blast extension.

Destructible Authoring Commands

const char *(*combinePrims)(const char **paths, size_t numPaths, float defaultContactThreshold, const DamageParameters *damageParameters, float defaultMaxContactImpulse)

Main entry point to combine a existing prims into a single destructible.

Param paths

[in] Full USD paths to prims that should be combined.

Param numPaths

[in] How many prims are in the paths array.

Param defaultContactThreshold

[in] How hard the prim needs to be hit to register damage during simulation.

Param damageParameters

[in] See DamageParameters description.

Param defaultMaxContactImpulse

[in] How much force can be used to push other prims away during a collision For kinematic prims only, used to allow heavy objects to continue moving through brittle destructible prims.

Return

true iff the prims were combined successfully.

const char *(*fracturePrims)(const char **paths, size_t numPaths, const char *defaultInteriorMaterial, uint32_t numVoronoiSites, float defaultContactThreshold, const DamageParameters *damageParameters, float defaultMaxContactImpulse, float interiorUvScale)

Main entry point to fracture an existing prim.

Param paths

[in] Full USD path(s) to prim(s) that should be fractured. They need to all be part of the same destructible if there are more than one.

Param numPaths

[in] How many prims are in the paths array.

Param defaultInteriorMaterial

[in] Material to set on newly created interior faces. (Ignored when re-fracturing and existing interior material is found.)

Param numVoronoiSites

[in] How many pieces to split the prim into.

Param defaultContactThreshold

[in] How hard the prim needs to be hit to register damage during simulation.

Param damageParameters

[in] See DamageParameters description.

Param defaultMaxContactImpulse

[in] How much force can be used to push other prims away during a collision. For kinematic prims only, used to allow heavy objects to continue moving through brittle destroyable prims.

Param interiorUvScale

[in] Scale to apply to UV frame when mapping to interior face vertices.

Return

path to the new prim if the source prim was fractured successfully, nullptr otherwise.

void (*setRandomSeed)(int32_t seed)

Set the random number generator seed for fracture operations.

Param seed

[in] the new seed.

bool (*resetBlastData)(const char *path)

Reset the Blast data (partial or full hierarchy) starting at the given path.

The destructible will be rebuilt with only appropriate data remaining.

Param path

[in] The path to a chunk, instance, or base destructible prim.

Return

true iff the operation could be performed on the prim at the given path.

bool (*createExternalAttachment)(const char *path, float defaultMaxContactImpulse, float relativePadding, bool externalBondsUnbreakable)

Modify a blast asset that is stored in the destructible at the given path, so that support chunks which touch static geometry are bound to the world.

All previous world bonds will be removed.

Returns true if the destructible’s NvBlastAsset was modified, but note this is not “if and only if.” If world bonds are removed and replaced with the exact same world bonds (e.g. the blast mesh was not moved since the last time this function was called), then this function will still return true. Note also that if path == NULL, this function always returns true.

Param path

[in] The USD path of the blast container.

Param defaultMaxContactImpulse

[in] Controls how much force physics can use to stop bodies from penetrating.

Param relativePadding

[in] A relative amount to grow chunk bounds in order when calculating world attachment.

Return

true if the destructible’s NvBlastAsset was modified (or if path == NULL).

bool (*removeExternalAttachment)(const char *path)

Remove all external bonds from the given blast asset.

Param path

[in] The USD path of the blast container.

Return

true if the destructible’s NvBlastAsset was modified (or if path == NULL).

bool (*recalculateBondAreas)(const char *path)

Recalculates the areas of bonds.

This may be used when a destructible is scaled.

Param path

[in] Path to the chunk, instance, or base destructible prim.

Return

true iff the operation was successful.

bool (*selectChildren)(const char **paths, size_t numPaths)

Finds all children of the chunks in the given paths, and sets kit’s selection set to the paths of those children.

Param paths

[in] Full USD path(s) to chunks.

Param numPaths

[in] How many paths are in the paths array.

Return

true iff the operation was successful.

bool (*selectParent)(const char **paths, size_t numPaths)

Finds all parents of the chunks in the given paths, and sets kit’s selection set to the paths of those parents.

Param paths

[in] Full USD path(s) to chunks.

Param numPaths

[in] How many paths are in the paths array.

Return

true iff the operation was successful.

bool (*selectSource)(const char **paths, size_t numPaths)

Finds all source meshes for chunks in the given paths, and sets kit’s selection set to the paths of those meshes.

Param paths

[in] Full USD path(s) to chunks.

Param numPaths

[in] How many paths are in the paths array.

Return

true iff the operation was successful.

void (*setInteriorMaterial)(const char **paths, size_t numPaths, const char *interiorMaterial)

Sets the material for the interior facets of the chunks at the given paths.

Param paths

[in] Full USD path(s) to chunks.

Param numPaths

[in] How many paths are in the paths array.

Param interiorMaterial

[in] Path to the prim holding the material prim to use.

Return

true iff the operation was successful.

const char *(*getInteriorMaterial)(const char **paths, size_t numPaths)

Gets the material for the interior facets of the chunks at the given paths.

Param paths

[in] Full USD path(s) to chunks.

Param numPaths

[in] How many paths are in the paths array.

Return

the material path if all meshes found at the given paths have the same interior materials. If more than one interior material is found among the meshes found, the empty string (“”) is returned. If no interior material is found, nullptr is returned.

bool (*rebuildInteriorUVs)(const char *path, float interiorUvScale)

Recalculates UV coordinates for the interior facets of chunk meshes based upon the UV scale factor given.

If the path given is a chunk, UVs will be recalculated for the chunk’s meshes. If the path is an instance or base prim, all chunk meshes will have their interior facets’ UVs recalculated.

Param path

[in] Path to the chunk, instance, or base destructible prim.

Param interiorUvScale

[in] the scale to use to calculate UV coordinates. A value of 1 will cause the texture to map to a region in space roughly the size of the whole destructible’s largest width.

Return

true iff the operation was successful.

void (*createDestructibleInstance)(const char *path, const DamageParameters *damageParameters, float defaultContactThreshold, float defaultMaxContactImpulse)

Creates a destructible instance with default values from the given destructible base.

Param path

[in] Path to the destructible base to instance.

Param damageParameters

[in] The damage characteristics to assign to the instance (see DamageParameters).

Param defaultContactThreshold

[in] Rigid body parameter to apply to actors generated by the instance. The minimum impulse required for a rigid body to generate a contact event, needed for impact damage.

Param defaultMaxContactImpulse

[in] Rigid body parameter to apply to actors generated by the instance. The maximum impulse that a contact constraint on a kinematic rigid body can impart on a colliding body.

Global Simulation Commands

void (*setSimulationParams)(int32_t maxNewActorsPerFrame)

Sets the maximum number of actors which will be generated by destruction each simulation frame.

Used to reduce per-frame computation. If actors are not generated in a particular frame because this limit is reached, they will be produced on some subsequent frame.

Param maxNewActorsPerFrame

[in] The maximum number of actors generated per frame.

Damage Application

void (*createDamageEvent)(const char *hitPrimPath, const DamageEvent *damageEvents, size_t numDamageEvents)

Create a destruction event during simulation.

Param hitPrimPath

[in] The full path to the prim to be damaged (may be a blast actor prim or its collision shape)/

Param damageEvents

[in] An array of DamageEvent structs describing the damage to be applied (see DamageEvent).

Param numDamageEvents

[in] The size of the damageEvents array.

Debug Visualization Functions

void (*setExplodeViewRadius)(const char *path, float radius)

Set the cached explode view radius for the destructible prim associated with the given path.

The prim must have DestructionSchemaDestructibleInstAPI applied. The instance will be rendered With its chunks pushed apart by the radius value.

Param path

[in] Full USD path to a destructible instance.

Param radius

[in] The distance to move apart the instance’s rendered chunks.

float (*getExplodeViewRadius)(const char **paths, size_t numPaths)

Gives the cached explode view radius for the destructible instances associated with the given paths, if the cached value for all instances is the same.

Param paths

[in] Array of USD paths to destructible instances.

Param numPaths

[in] The length of the paths array.

Return

The cached explode view radius for all valid destructible instances at the given paths, if that value is the same for all instances. If there is more than one radius found, this function returns -1.0f. If no valid instances are found, this function returns 0.0f.

int32_t (*getMaxViewDepth)(const char **paths, size_t numPaths)

Calculate the maximum depth for all chunks in the destructible prim associated with the given paths.

Param paths

[in] Array of USD paths to destructible prims.

Param numPaths

[in] The length of the paths array.

Return

the maximum chunk depth for all destructibles associated with the given paths. Returns 0 if no destructibles are found.

int32_t (*getViewDepth)(const char **path, size_t numPaths)

Calculates what the view depth should be, factoring in internal override if set.

/return return what the view depth should be.

Param paths

[in] Array of USD paths to destructible prims.

Param numPaths

[in] The length of the paths array.

void (*setViewDepth)(const char **paths, size_t numPaths, const char *depth)

Set the view depth for explode view functionality.

Param paths

[in] Array of USD paths to destructible prims.

Param numPaths

[in] The length of the paths array.

Param depth

[in] Either a string representation of the numerical depth value, or “Leaves” to view leaf chunks.

bool (*setDebugVisualizationInfo)(const char *mode, const char *type)

Set the debug visualization mode & type.

If mode != debugVisNone, an anonymous USD layer is created which overrides the render meshes for blast objects which are being visualized.

Param mode

[in] Supported modes: “debugVisNone”, “debugVisSelected”, “debugVisAll”

Param type

[in] Supported modes: “debugVisSupportGraph”, “debugVisMaxStressGraph”, “debugVisCompressionGraph”, “debugVisTensionGraph”, “debugVisShearGraph”, “debugVisBondPatches”

Return

true iff a valid mode is selected.

Debug Damage Functions

void (*setDebugDamageParams)(float amount, float impulse, float radius)

Set parameters for the debug damage tool in kit.

This is applied using Shift + B + (Left Mouse). A ray is cast from the camera position through the screen point of the mouse cursor, and intersected with scene geometry. The intersection point is used to find nearby destructibles using to damage.

Param amount

[in] The base damage to be applied to each destructible, as an acceleration in m/s^2.

Param impulse

[in] An impulse to apply to rigid bodies within the given radius, in kg*m/s. (This applies to non-destructible rigid bodies too.)

Param radius

[in] The distance in meters from the ray hit point to search for rigid bodies to affect with this function.

void (*applyDebugDamage)(const carb::Float3 *worldPosition, const carb::Float3 *worldDirection)

Apply debug damage at the position given, in the direction given.

The damage parameters set by setDebugDamageParams will be used.

Param worldPosition

[in] The world position at which to apply debug damage.

Param worldPosition

[in] The world direction of the applied damage.

Notice Handler Functions

These can be called at any time to enable or disable notice handler monitoring.

When enabled, use BlastUsdMonitorNoticeEvents to catch unbuffered Usd/Sdf commands. It will be automatically cleaned up on system shutdown if enabled.

void (*blastUsdEnableNoticeHandlerMonitor)()

void (*blastUsdDisableNoticeHandlerMonitor)()

Destructible Path Utilities

These functions find destructible base or instance prims from any associated prim path.

const char *(*getDestructibleBasePath)(const char *path)

Param path

[in] Any path associated with a destructible base prim.

Return

the destructible prim’s path if found, or nullptr otherwise.

const char *(*getDestructibleInstancePath)(const char *path)

Param path

[in] Any path associated with a destructible instance prim.

Return

the destructible prim’s path if found, or nullptr otherwise.

Blast SDK Cache

This function pushes the Blast SDK data that is used during simulation back to USD so it can be saved and then later restored in the same state.

This is also the state that will be restored to when sim stops.

void (*blastCachePushBinaryDataToUSD)()

Blast Stress

This function modifies settings used to drive stress calculations during simulation.

param path

[in] Any path associated with a destructible instance prim.

param gravityEnabled

[in] Controls if gravity should be applied to stress simulation of th destructible instance.

param rotationEnabled

[in] Controls if rotational acceleration should be applied to stress simulation of th destructible instance.

param residualForceMultiplier

[in] Multiplies the residual forces on bodies after connecting bonds break.

param settings

[in] Values used to control the stress solver.

return

true is stress settings were updated, false otherwise.

bool (*blastStressUpdateSettings)(const char *path, bool gravityEnabled, bool rotationEnabled, float residualForceMultiplier, const StressSolverSettings &settings)