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:

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!