============
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] | The maxDistanceScale.Scale parameter is smaller than 0 or bigger than 1.    |
|                    | interval                                    |                                                                             |
+--------------------+---------------------------------------------+-----------------------------------------------------------------------------+
| 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    | Scene Queries must not be disabled on non-compartment cloth because they    |
|                    | must be false when using non-compartment    | are used internally to determine which Actors are colliding with the        |
|                    | CPU cloth                                   | 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 | An invalid painting value has been detected. Max Distances must not be      |
|                    | be >= 0 or equal to invalid                 | negative unless they are equal to the invalid value.                        |
+--------------------+---------------------------------------------+-----------------------------------------------------------------------------+
| eINVALID_PARAMETER | The NvParameterized::Interface object is of | The Clothing Module was initialized with a descriptor of the wrong type.    |
|                    | the wrong type                              |                                                                             |
+--------------------+---------------------------------------------+-----------------------------------------------------------------------------+
| eINVALID_PARAMETER | RenderMeshAssetAuthoring has more than      | For Clothing, the requirement on render mesh assets are exactly 1 part.     |
|                    | one part                                    |                                                                             |
+--------------------+---------------------------------------------+-----------------------------------------------------------------------------+
| eINVALID_PARAMETER | Mesh has no active vertices (see Physics    | A render mesh asset has been added to a clothing asset authoring that does  |
|                    | on/off channel)                             | not have a single Max Distance value larger than 0.                         |
+--------------------+---------------------------------------------+-----------------------------------------------------------------------------+
| eINVALID_OPERATION | updateRenderResources needs to be called    | ClothingActor::dispatchRenderResource() has been called before              |
|                    | before dispatchRenderResources.             | ClothingActor::updateRenderResource().                                      |
+--------------------+---------------------------------------------+-----------------------------------------------------------------------------+
| eINVALID_OPERATION | ClothDesc/SoftBodyDesc is invalid           | ClothDesc::checkValid() or SoftBodyDesc::chcekValid() returned an           |
|                    | (error code <c>)                            | error code.                                                                 |
+--------------------+---------------------------------------------+-----------------------------------------------------------------------------+
| eINVALID_OPERATION | PxScene::createCloth/SoftBody() returned    | Cloth/SoftBody was not created by the scene.                                |
|                    | NULL                                        |                                                                             |
+--------------------+---------------------------------------------+-----------------------------------------------------------------------------+
| eINVALID_OPERATION | Cloth/SoftBody Mesh generation failed,      | ClothMesh/SoftBodyMesh was not created, maybe a cooking error?              |
|                    | asset won't be useable                      |                                                                             |
+--------------------+---------------------------------------------+-----------------------------------------------------------------------------+
| eINVALID_OPERATION | Cannot simplify a tetrahedral mesh          | ClothingPhysicalMesh::simplify() cannot be called on a tetrahedral mesh.    |
+--------------------+---------------------------------------------+-----------------------------------------------------------------------------+
| eINTERNAL_ERROR    | Cannot create ClothingActor while           | ClothingAsset::createActor() was called while the simulation was running.   |
|                    | simulation is running                       | Scene::fetchResults() must be called first.                                 |
+--------------------+---------------------------------------------+-----------------------------------------------------------------------------+
| eINTERNAL_ERROR    | Cannot release ClothingActor while          | ClothingActor::release() was called while the simulation was running.       |
|                    | simulation is still running                 | Scene::fetchResults() must be called first.                                 |
+--------------------+---------------------------------------------+-----------------------------------------------------------------------------+
| eINTERNAL_ERROR    | Render mesh asset does not have either      | A Render Mesh asset must have positions as well as normals to be used by    |
|                    | position or normal for submesh i            | clothing.                                                                   |
+--------------------+---------------------------------------------+-----------------------------------------------------------------------------+
| eDEBUG_INFO        | The asset does not contain a bone with name | ClothingAsset::remapBone() was called on a non existing bone.               |
|                    | <name>                                      |                                                                             |
+--------------------+---------------------------------------------+-----------------------------------------------------------------------------+
| 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     | The corresponding ClothingAsset does not contain a material library.        |
|                    | asset                                       | This is an error state.                                                     |
+--------------------+---------------------------------------------+-----------------------------------------------------------------------------+
| eDEBUG_WARNING     | The asset contains n bones with name        | This happens when bone names are not unique. This could be considered an    |
|                    | <name>. All occurences were mapped.         | ill defined asset to start with, but it might still work more or less.      |
+--------------------+---------------------------------------------+-----------------------------------------------------------------------------+
| eDEBUG_WARNING     | APEX Clothing physx::PxFileBuf              | Calling ClothingAsset::serialize() is not supported as of 1.0 anymore.      |
|                    | serialization is obsolete. Use              | Use the parameterized serialization instead.                                |
|                    | NvParameterized serialization.              |                                                                             |
+--------------------+---------------------------------------------+-----------------------------------------------------------------------------+
| eDEBUG_WARNING     | Using substeps, this will cause problems    | Clothing is very time step sensitive. Using substeps will not allow it to   |
|                    | with clothing!                              | progress the animated part in between the substeps. This can lead to        |
|                    |                                             | jittery cloth.                                                              |
+--------------------+---------------------------------------------+-----------------------------------------------------------------------------+
| eDEBUG_WARNING     | ModuleClothingDesc.maxNumCompartments > 0!  | Cloth and Softbody simulation will be noticeably slower when using          |
|                    | On consoles performance is worse when using | compartments on the console platforms!                                      |
|                    | compartments for cloth and softbodies       |                                                                             |
+--------------------+---------------------------------------------+-----------------------------------------------------------------------------+
