Introduction
Overview
Classes
The APEX Clothing module primarily deals with the following kinds of objects:
- ModuleClothing
- Main hook to the clothing module
- ClothingAsset
- Created through the clothing asset authoring pipeline
- Contains all information to simulate and render one clothing piece
- ClothingActor
- Instance of a clothing asset
- ClothingPreview
- Like an ClothingActor without simulation
In case of writing a custom authoring tool, the following objects are involved additionally:
- ClothingAssetAuthoring
- Creates, edits and serializes clothing assets that can be loaded from a stream at runtime
- ClothingIsoMesh
- Intermediate class for the multi layered clothing approach
- ClothingPhysicalMesh
- Holds the physics mesh for the simulation
- Provides mesh simplification
- RenderMeshAssetAuthoring
- Part of the APEX framework
- Used to give graphics meshes to the clothing module
- RenderMeshBuilder
- Input to the RenderMeshAssetAuthoring
- Has to be sub classed and implemented to create the mesh triangles
- RenderMeshPartData
- Input to the RenderMeshAssetAuthoring
- Clothing Asset uses just one part
Deprecated classes
These classes have been deprecated because they are no longer needed. The Material Library has been merged into the ClothingAsset. They are still here for compatibility.
The biggest need for the ClothingMaterialLibrary is to load old .acml files. Whenever you create an ClothingAsset from an old .aca file, it will try to load the referenced .acml file immediately through the NRP.
- ClothingMaterialLibrary
- Is an Asset
- Contains ClothingMaterials
- Created by loading a stream from ClothingMaterialLibraryAuthoring
- Referenced by name in the ClothingAsset
- Gets requested through the named resource provider
- ClothingMaterialLibraryAuthoring
- Is an AssetAuthoring
- Allows adding and removing individual materials
- Creates and serializes a list of ClothingMaterials
- ClothingMaterial
- Stores settings for cloth behavior
Runtime Usage
After loading an ClothingAsset it can be used to instance an ClothingActor from it. A clothing actor simulates exactly one piece of cloth in a scene. It is important that each component of the character is synchronized at all times. Components of a character are:
Graphics mesh of the non-simulated part of the character
Clothing actor for the simulated part of the character
- Rigid body collision representation of the character
- A rigid body skeleton can be stored in the ClothingAsset. It will then be animated with the character automatically by APEX.
Animated character bones
Graphics mesh, simulation mesh and rigid body skeletons are all skinned and transformed with the character bone poses when the character is animated.
Main Loop
Roughly the main loop contains the following steps:
- Set current LoD settings (not all of this needs to be in the main loop)
- Scene::setViewMatrix
- ( Actor::forceLod )
- Feed global pose and the current bone poses to the ClothingActor
- ClothingActor::updateState
- Simulate the APEX Scene
- Scene::simulate
- Scene::fetchResults
- Render the non-simulated part of the character
- Skin and render through game engine
- Render APEX actors
- RenderDataProvider::lockRenderResources
- Renderable::updateRenderResources
- Renderable::dispatchRenderResources
- RenderDataProvider::unlockRenderResources
Errors and Warnings
Some methods that are deprecated also emit a PxErrorCode::eINVALID_PARAMETER.
| PxErrorCode | MESSAGE | Explanation |
|---|---|---|
| eINVALID_PARAMETER | <name> is not a valid descriptor class | A clothing actor or asset preview has been created with a wrong descriptor. |
| eINVALID_PARAMETER | windAdaption must be bigger or equal than 0 | Wind adaption cannot be negative! |
| eINVALID_PARAMETER | Index must be smaller than materials array | Index out of bounds for setting the clothing material. |
| eINVALID_PARAMETER | boneMatrices[i] is not finite! | The i’th matrix in the clothing actor descriptor has one or more non-finite elements. |
| eINVALID_PARAMETER | globalPose is not finite! | The global pose from the clothing actor descriptor is not finite. |
| eINVALID_PARAMETER | lodWeights must be >= 0 | One or more lodWeight values in the clothing actor descriptor is negative. |
| eINVALID_PARAMETER | maxDistanceBlendTime must be positive | The maxDistanceBlendTime in the clothing actor descriptor is negative. |
| eINVALID_PARAMETER | maxDistanceScale.Scale ust be in the [0, 1] interval | The maxDistanceScale.Scale parameter is smaller than 0 or bigger than 1. |
| eINVALID_PARAMETER | windParams.Adaption must be positive or zero | Wind adaption cannot be negative in the clothing actor description. |
| eINVALID_PARAMETER | shapeDesc.flags.SF_DISABLE_SCENE_QUERIES must be false when using non-compartment CPU cloth | Scene Queries must not be disabled on non-compartment cloth because they are used internally to determine which Actors are colliding with the cloth. |
| eINVALID_PARAMETER | ClothingActorDesc is invalid | The clothing actor descriptor is not valid. |
| eINVALID_PARAMETER | Skew on matrices is not allowed, aborting | A matrix with skew (determinant != 1) has been detected. Invalid input. |
| eINVALID_PARAMETER | newBindPosesCount must be bigger than n | Not enough new bindposes were provided. |
| eINVALID_PARAMETER | Max Distance at vertex %d (submesh %d) must be >= 0 or equal to invalid | An invalid painting value has been detected. Max Distances must not be negative unless they are equal to the invalid value. |
| eINVALID_PARAMETER | The NvParameterized::Interface object is of the wrong type | The Clothing Module was initialized with a descriptor of the wrong type. |
| eINVALID_PARAMETER | RenderMeshAssetAuthoring has more than one part | For Clothing, the requirement on render mesh assets are exactly 1 part. |
| eINVALID_PARAMETER | Mesh has no active vertices (see Physics on/off channel) | A render mesh asset has been added to a clothing asset authoring that does not have a single Max Distance value larger than 0. |
| eINVALID_OPERATION | updateRenderResources needs to be called before dispatchRenderResources. | ClothingActor::dispatchRenderResource() has been called before ClothingActor::updateRenderResource(). |
| eINVALID_OPERATION | ClothDesc/SoftBodyDesc is invalid (error code <c>) | ClothDesc::checkValid() or SoftBodyDesc::chcekValid() returned an error code. |
| eINVALID_OPERATION | PxScene::createCloth/SoftBody() returned NULL | Cloth/SoftBody was not created by the scene. |
| eINVALID_OPERATION | Cloth/SoftBody Mesh generation failed, asset won’t be useable | ClothMesh/SoftBodyMesh was not created, maybe a cooking error? |
| eINVALID_OPERATION | Cannot simplify a tetrahedral mesh | ClothingPhysicalMesh::simplify() cannot be called on a tetrahedral mesh. |
| eINTERNAL_ERROR | Cannot create ClothingActor while simulation is running | ClothingAsset::createActor() was called while the simulation was running. Scene::fetchResults() must be called first. |
| eINTERNAL_ERROR | Cannot release ClothingActor while simulation is still running | ClothingActor::release() was called while the simulation was running. Scene::fetchResults() must be called first. |
| eINTERNAL_ERROR | Render mesh asset does not have either position or normal for submesh i | A Render Mesh asset must have positions as well as normals to be used by clothing. |
| eDEBUG_INFO | The asset does not contain a bone with name <name> | ClothingAsset::remapBone() was called on a non existing bone. |
| eDEBUG_WARNING | numMatrices too big | ClothingActor::updateState() was called with a matrix array that is too big. Some matrices were ignored. |
| eDEBUG_WARNING | No Clothing Material Library present in asset | The corresponding ClothingAsset does not contain a material library. This is an error state. |
| eDEBUG_WARNING | The asset contains n bones with name <name>. All occurences were mapped. | This happens when bone names are not unique. This could be considered an ill defined asset to start with, but it might still work more or less. |
| eDEBUG_WARNING | APEX Clothing physx::PxFileBuf serialization is obsolete. Use NvParameterized serialization. | Calling ClothingAsset::serialize() is not supported as of 1.0 anymore. Use the parameterized serialization instead. |
| eDEBUG_WARNING | Using substeps, this will cause problems with clothing! | Clothing is very time step sensitive. Using substeps will not allow it to progress the animated part in between the substeps. This can lead to jittery cloth. |
| eDEBUG_WARNING | ModuleClothingDesc.maxNumCompartments > 0! On consoles performance is worse when using compartments for cloth and softbodies | Cloth and Softbody simulation will be noticeably slower when using compartments on the console platforms! |