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:

  1. Set current LoD settings (not all of this needs to be in the main loop)
    • Scene::setViewMatrix
    • ( Actor::forceLod )
  2. Feed global pose and the current bone poses to the ClothingActor
    • ClothingActor::updateState
  3. Simulate the APEX Scene
    • Scene::simulate
    • Scene::fetchResults
  4. Render the non-simulated part of the character
    • Skin and render through game engine
  5. 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!

Table Of Contents

Previous topic

Programmers Guide

Next topic

Runtime Interfaces