diff options
Diffstat (limited to 'NvCloth/docs/documentation/UsersGuide/Index.html')
| -rw-r--r-- | NvCloth/docs/documentation/UsersGuide/Index.html | 544 |
1 files changed, 544 insertions, 0 deletions
diff --git a/NvCloth/docs/documentation/UsersGuide/Index.html b/NvCloth/docs/documentation/UsersGuide/Index.html new file mode 100644 index 0000000..9ab48b5 --- /dev/null +++ b/NvCloth/docs/documentation/UsersGuide/Index.html @@ -0,0 +1,544 @@ + + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>Users guide — NVIDIA NvCloth Documentation</title> + <link rel="stylesheet" href="../_static/nvidia.css" type="text/css" /> + <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> + <link rel="stylesheet" href="../_static/custom.css" type="text/css" /> + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '0.0', + COLLAPSE_INDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="../_static/jquery.js"></script> + <script type="text/javascript" src="../_static/underscore.js"></script> + <script type="text/javascript" src="../_static/doctools.js"></script> + <link rel="top" title="NVIDIA NvCloth Documentation" href="../index.html" /> + <link rel="next" title="NVIDIA Copyright Notice" href="../CopyRight/Index.html" /> + <link rel="prev" title="Modules" href="../Modules/Index.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../CopyRight/Index.html" title="NVIDIA Copyright Notice" + accesskey="N">next</a></li> + <li class="right" > + <a href="../Modules/Index.html" title="Modules" + accesskey="P">previous</a> |</li> + <li><a href="../NvCloth.html">NVIDIA NvCloth Documentation</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="users-guide"> +<h1>Users guide<a class="headerlink" href="#users-guide" title="Permalink to this headline">¶</a></h1> +<p>In this section we describe how to set up NvCloth and guide you through some common features.</p> +<div class="section" id="setup"> +<h2>Setup<a class="headerlink" href="#setup" title="Permalink to this headline">¶</a></h2> +<p>Some setup is required before we can start simulating. +Here we give an overview of all the components needed. +The sections below will provide more details about each component.</p> +<dl class="docutils"> +<dt><strong>NvCloth library</strong></dt> +<dd>uses callbacks for things like memory allocations, which need to be initialized</dd> +<dt><strong>Factory</strong></dt> +<dd>interface object creating all other objects</dd> +<dt><strong>Solver</strong></dt> +<dd>manages simulation and time stepping</dd> +<dt><strong>Fabric</strong></dt> +<dd>contains information about cloth that can be shared between multiple instances</dd> +<dt><strong>Cloth</strong></dt> +<dd>contains the cloth instance data</dd> +</dl> +<div class="section" id="initializing-the-library"> +<h3>Initializing the Library<a class="headerlink" href="#initializing-the-library" title="Permalink to this headline">¶</a></h3> +<p>NvCloth uses user defined callbacks for memory allocation, error reporting, assert handling, and profile timings. +The callbacks need to be passed to the library using nv::cloth::InitializeNvCloth() before the rest of the library can be used. +The callbacks are straightforward to implement by providing classes with implementations for all the functions of physx::PxAllocatorCallback, physx::PxErrorCallback, physx::PxAssertHandler, and optionally physx::PxProfilerCallback. +Note that the allocations returned by the PxAllocatorCallback need to be 16 byte aligned.</p> +<p>The library doesn’t need any deinitialization.</p> +</div> +<div class="section" id="factory"> +<h3>Factory<a class="headerlink" href="#factory" title="Permalink to this headline">¶</a></h3> +<p>The Factory object lets you construct all the other components necessary for the simulation. +There are different factories, one for each platform (e.g. CPU, CUDA, etc.) +Components created with different platforms cannot be used together (e.g. a CPU cloth cannot be added to a GPU solver), but multiple factories (for different platforms) can be used at the same time. +A factory is created as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include <NvCloth/Factory.h></span> + +<span class="p">...</span> + +<span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">Factory</span><span class="o">*</span> <span class="n">factory</span> <span class="o">=</span> <span class="n">NvClothCreateFactoryCPU</span><span class="p">();</span> +<span class="k">if</span><span class="p">(</span><span class="n">factory</span><span class="o">==</span><span class="n">nullptr</span><span class="p">)</span> +<span class="p">{</span> + <span class="c1">//error</span> +<span class="p">}</span> + +<span class="p">...</span> +<span class="c1">//At cleanup:</span> +<span class="n">NvClothDestroyFactory</span><span class="p">(</span><span class="n">factory</span><span class="p">);</span> <span class="c1">//This works for all different factories.</span> +</pre></div> +</div> +<p>Different functions instead of NvClothCreateFactoryCPU() can be used to create factories for a different platform. +Some platforms may need additional arguments when creating the factory, like CUDA:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">//// CUDA</span> +<span class="cp">#include <NvCloth/Factory.h></span> +<span class="cp">#include <cuda.h></span> + +<span class="p">...</span> + +<span class="n">CUcontext</span> <span class="n">cudaContext</span><span class="p">;</span> +<span class="kt">int</span> <span class="n">deviceCount</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +<span class="n">CUresult</span> <span class="n">result</span> <span class="o">=</span> <span class="n">cuDeviceGetCount</span><span class="p">(</span><span class="o">&</span><span class="n">deviceCount</span><span class="p">);</span> +<span class="n">ASSERT</span><span class="p">(</span><span class="n">CUDA_SUCCESS</span> <span class="o">==</span> <span class="n">result</span><span class="p">);</span> +<span class="n">ASSERT</span><span class="p">(</span><span class="n">deviceCount</span> <span class="o">>=</span> <span class="mi">1</span><span class="p">);</span> + +<span class="n">result</span> <span class="o">=</span> <span class="n">cuCtxCreate</span><span class="p">(</span><span class="o">&</span><span class="n">cudaContext</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span> <span class="c1">//Pick first device</span> +<span class="n">ASSERT</span><span class="p">(</span><span class="n">CUDA_SUCCESS</span> <span class="o">==</span> <span class="n">result</span><span class="p">);</span> + +<span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">Factory</span><span class="o">*</span> <span class="n">factory</span> <span class="o">=</span> <span class="n">NvClothCreateFactoryCUDA</span><span class="p">(</span><span class="n">cudaContext</span><span class="p">);</span> +<span class="c1">//We need to call cuCtxDestroy(cudaContext); after destroying the factory.</span> +</pre></div> +</div> +<p>And DX11:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">//// DX11</span> +<span class="cp">#include <NvCloth/Factory.h></span> +<span class="cp">#include <d3d11.h></span> + +<span class="p">...</span> + +<span class="c1">//Setup DX11 context</span> +<span class="n">ID3D11Device</span><span class="o">*</span> <span class="n">DXDevice</span><span class="p">;</span> +<span class="n">ID3D11DeviceContext</span><span class="o">*</span> <span class="n">DXDeviceContext</span><span class="p">;</span> +<span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">DxContextManagerCallback</span><span class="o">*</span> <span class="n">GraphicsContextManager</span><span class="p">;</span> +<span class="n">D3D_FEATURE_LEVEL</span> <span class="n">featureLevels</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span><span class="n">D3D_FEATURE_LEVEL_11_0</span><span class="p">};</span> +<span class="n">D3D_FEATURE_LEVEL</span> <span class="n">featureLevelResult</span><span class="p">;</span> +<span class="n">HRESULT</span> <span class="n">result</span> <span class="o">=</span> <span class="n">D3D11CreateDevice</span><span class="p">(</span><span class="n">nullptr</span><span class="p">,</span> <span class="n">D3D_DRIVER_TYPE_HARDWARE</span><span class="p">,</span> <span class="n">nullptr</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">featureLevels</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">D3D11_SDK_VERSION</span><span class="p">,</span> <span class="o">&</span><span class="n">DXDevice</span><span class="p">,</span> <span class="o">&</span><span class="n">featureLevelResult</span><span class="p">,</span> <span class="o">&</span><span class="n">DXDeviceContext</span><span class="p">);</span> +<span class="n">ASSERT</span><span class="p">(</span><span class="n">result</span> <span class="o">==</span> <span class="n">S_OK</span><span class="p">);</span> +<span class="n">ASSERT</span><span class="p">(</span><span class="n">featureLevelResult</span> <span class="o">==</span> <span class="n">D3D_FEATURE_LEVEL_11_0</span><span class="p">);</span> +<span class="n">GraphicsContextManager</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DxContextManagerCallbackImpl</span><span class="p">(</span><span class="n">DXDevice</span><span class="p">);</span> +<span class="n">ASSERT</span><span class="p">(</span><span class="n">GraphicsContextManager</span> <span class="o">!=</span> <span class="n">nullptr</span><span class="p">);</span> + +<span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">Factory</span><span class="o">*</span> <span class="n">factory</span> <span class="o">=</span> <span class="n">NvClothCreateFactoryDX11</span><span class="p">(</span><span class="n">GraphicsContextManager</span><span class="p">);</span> +<span class="c1">//We need to release all DX objects after destroying the factory.</span> +</pre></div> +</div> +</div> +<div class="section" id="fabric-cloth"> +<h3>Fabric & Cloth<a class="headerlink" href="#fabric-cloth" title="Permalink to this headline">¶</a></h3> +<p>The data used for cloth simulation is divided into two objects. +The fabric object contains all reusable data like the constraint lengths and connections. +The cloth object contains all instance data like particle positions. +This way multiple cloths can share the same fabric data, reducing memory usage.</p> +<div class="section" id="fabric"> +<h4>Fabric<a class="headerlink" href="#fabric" title="Permalink to this headline">¶</a></h4> +<p>Creating the fabric is the most complicated part of the setup. +We have included helper functions as extension to simplify this step. +We can fill the nv::cloth::ClothMeshDesc meshDesc struct and pass it to the NvClothCookFabricFromMesh function if we use the cooking extension:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include <NvClothExt/ClothFabricCooker.h></span> + +<span class="p">...</span> + +<span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">ClothMeshDesc</span> <span class="n">meshDesc</span><span class="p">;</span> + +<span class="c1">//Fill meshDesc with data</span> +<span class="n">meshDesc</span><span class="p">.</span><span class="n">setToDefault</span><span class="p">();</span> +<span class="n">meshDesc</span><span class="p">.</span><span class="n">points</span><span class="p">.</span><span class="n">data</span> <span class="o">=</span> <span class="n">vertexArray</span><span class="p">;</span> +<span class="n">meshDesc</span><span class="p">.</span><span class="n">points</span><span class="p">.</span><span class="n">stride</span> <span class="o">=</span> <span class="k">sizeof</span><span class="p">(</span><span class="n">vertexArray</span><span class="p">[</span><span class="mi">0</span><span class="p">]);</span> +<span class="n">meshDesc</span><span class="p">.</span><span class="n">points</span><span class="p">.</span><span class="n">count</span> <span class="o">=</span> <span class="n">vertexCount</span><span class="p">;</span> +<span class="c1">//etc. for quads, triangles and invMasses</span> + +<span class="n">physx</span><span class="o">::</span><span class="n">PxVec3</span> <span class="n">gravity</span><span class="p">(</span><span class="mf">0.0f</span><span class="p">,</span> <span class="o">-</span><span class="mf">9.8f</span><span class="p">,</span> <span class="mf">0.0f</span><span class="p">);</span> +<span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">Vector</span><span class="o"><</span><span class="n">int32_t</span><span class="o">>::</span><span class="n">Type</span> <span class="n">phaseTypeInfo</span><span class="p">;</span> +<span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">Fabric</span><span class="o">*</span> <span class="n">fabric</span> <span class="o">=</span> <span class="n">NvClothCookFabricFromMesh</span><span class="p">(</span><span class="n">factory</span><span class="p">,</span> <span class="n">meshDesc</span><span class="p">,</span> <span class="n">gravity</span><span class="p">,</span> <span class="o">&</span><span class="n">phaseTypeInfo</span><span class="p">);</span> + +<span class="p">...</span> + +<span class="n">fabric</span><span class="o">-></span><span class="n">decRefCount</span><span class="p">();</span> +</pre></div> +</div> +<p>phaseTypeInfo contains information used later for setting up the constraint phases of the cloth. +We provide the gravity vector so the cooker can differentiate between horizontal and vertical constraints.</p> +<p>You have to release the fabric using the decRefCount() function. +Cloths that depend on the fabric also keep a reference, so it is safe to decrease the refcount when the fabric is still in use. +The fabric returned by NvClothCookFabricFromMesh (or by *Factory::createFabric) already has a reference count of 1. +The fabric will destroy itself when its reference count reaches 0. +All fabrics created by a factory need to be destroyed before that factory is destroyed (meaning indirectly that all cloths, which hold references to these fabrics, also need to be destroyed).</p> +<p>You can also manually provide all the cooked data using the Factory::createFabric function directly in case you have your own cooking code or if you do not cook at runtime.</p> +</div> +<div class="section" id="cloth"> +<h4>Cloth<a class="headerlink" href="#cloth" title="Permalink to this headline">¶</a></h4> +<p>We can now create a cloth instance from the fabric created in the previous step. +The cloth instance does not need to begin with the same particle positions the fabric was cooked in, so we need to provide the initial position of the particles:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">physx</span><span class="o">::</span><span class="n">PxVec4</span><span class="o">*</span> <span class="n">particlePositions</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// The w component is the inverse mass of the particle</span> + <span class="c1">// and can be to 0 to lock the particle / make it static.</span> +<span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">Cloth</span><span class="o">*</span> <span class="n">cloth</span> <span class="o">=</span> <span class="n">factory</span><span class="o">-></span><span class="n">createCloth</span><span class="p">(</span><span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">Range</span><span class="o"><</span><span class="n">physx</span><span class="o">::</span><span class="n">PxVec4</span><span class="o">></span><span class="p">(</span> <span class="n">particlePositions</span><span class="p">,</span> <span class="o">&</span> <span class="n">particlePositions</span> <span class="o">+</span> <span class="n">particleCount</span><span class="p">),</span> <span class="o">*</span><span class="n">fabric</span><span class="p">);</span> +<span class="c1">// particlePositions can be freed here.</span> + +<span class="p">...</span> + +<span class="n">NV_CLOTH_DELETE</span><span class="p">(</span><span class="n">cloth</span><span class="p">);</span> +</pre></div> +</div> +<p>Now we need to setup the phase configurations. +Phase configurations control the order in which the constraints are solved (e.g. first horizontal then vertical etc.) and the constrain properties like stiffness:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">PhaseConfig</span><span class="o">*</span> <span class="n">phases</span> <span class="o">=</span> <span class="k">new</span> <span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">PhaseConfig</span><span class="p">[</span><span class="n">fabric</span><span class="o">-></span><span class="n">getNumPhases</span><span class="p">()];</span> +<span class="k">for</span><span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">fabric</span><span class="o">-></span><span class="n">getNumPhases</span><span class="p">();</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">phases</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">mPhaseIndex</span> <span class="o">=</span> <span class="n">i</span><span class="p">;</span> <span class="c1">// Set index to the corresponding set (constraint group)</span> + + <span class="c1">//Give phases different configs depending on type</span> + <span class="k">switch</span><span class="p">(</span><span class="n">phaseTypeInfo</span><span class="p">[</span><span class="n">i</span><span class="p">])</span> + <span class="p">{</span> + <span class="k">case</span> <span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">ClothFabricPhaseType</span><span class="o">::</span><span class="nl">eINVALID:</span> + <span class="c1">//ERROR</span> + <span class="k">break</span><span class="p">;</span> + <span class="k">case</span> <span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">ClothFabricPhaseType</span><span class="o">::</span><span class="nl">eVERTICAL:</span> + <span class="k">break</span><span class="p">;</span> + <span class="k">case</span> <span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">ClothFabricPhaseType</span><span class="o">::</span><span class="nl">eHORIZONTAL:</span> + <span class="k">break</span><span class="p">;</span> + <span class="k">case</span> <span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">ClothFabricPhaseType</span><span class="o">::</span><span class="nl">eBENDING:</span> + <span class="k">break</span><span class="p">;</span> + <span class="k">case</span> <span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">ClothFabricPhaseType</span><span class="o">::</span><span class="nl">eSHEARING:</span> + <span class="k">break</span><span class="p">;</span> + <span class="p">}</span> + + <span class="c1">//For this example we give very phase the same config</span> + <span class="n">phases</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">mStiffness</span> <span class="o">=</span> <span class="mf">1.0f</span><span class="p">;</span> + <span class="n">phases</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">mStiffnessMultiplier</span> <span class="o">=</span> <span class="mf">1.0f</span><span class="p">;</span> + <span class="n">phases</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">mCompressionLimit</span> <span class="o">=</span> <span class="mf">1.0f</span><span class="p">;</span> + <span class="n">phases</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">mStretchLimit</span> <span class="o">=</span> <span class="mf">1.0f</span><span class="p">;</span> +<span class="p">}</span> +<span class="n">cloth</span><span class="o">-></span><span class="n">setPhaseConfig</span><span class="p">(</span><span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">Range</span><span class="o"><</span><span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">PhaseConfig</span><span class="o">></span><span class="p">(</span><span class="o">&</span><span class="n">phases</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="o">&</span><span class="n">phases</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">+</span> <span class="n">fabric</span><span class="o">-></span><span class="n">getNumPhases</span><span class="p">()));</span> +<span class="k">delete</span> <span class="p">[]</span> <span class="n">phases</span><span class="p">;</span> +</pre></div> +</div> +<p>Note that there might be more phase of each type. +Check if the gravity vector used for cooking is correct (and in the same space as the cooked mesh) when the vertical phases are missing.</p> +<p>There are more properties you can set on the cloth. +They will be described below in the Usage section.</p> +</div> +</div> +<div class="section" id="solver"> +<h3>Solver<a class="headerlink" href="#solver" title="Permalink to this headline">¶</a></h3> +<p>The solver represents something similar to a scene. +It has a list of cloths that will be simulated together and it contains some simulation properties. +Creating a solver is simple:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">Solver</span><span class="o">*</span> <span class="n">solver</span> <span class="o">=</span> <span class="n">factory</span><span class="o">-></span><span class="n">createSolver</span><span class="p">();</span> + +<span class="p">...</span> + +<span class="n">NV_CLOTH_DELETE</span><span class="p">(</span><span class="n">solver</span><span class="p">);</span> +</pre></div> +</div> +<p>We can add and remove cloths to/from the scene as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">solver</span><span class="o">-></span><span class="n">addCloth</span><span class="p">(</span><span class="n">cloth</span><span class="p">);</span> + +<span class="p">...</span> + +<span class="n">solver</span><span class="o">-></span><span class="n">removeCloth</span><span class="p">(</span><span class="n">cloth</span><span class="p">);</span> +</pre></div> +</div> +<p>Advancing the simulation is broken up in a couple of function calls:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">float</span> <span class="n">deltaTime</span> <span class="o">=</span> <span class="mf">1.0f</span><span class="o">/</span><span class="mf">60.0f</span><span class="p">;</span> +<span class="n">solver</span><span class="o">-></span><span class="n">beginSimulation</span><span class="p">(</span><span class="n">deltaTime</span><span class="p">);</span> +<span class="k">for</span><span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">solver</span><span class="o">-></span><span class="n">getSimulationChunkCount</span><span class="p">();</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">solver</span><span class="o">-></span><span class="n">simulateChunk</span><span class="p">(</span><span class="n">i</span><span class="p">);</span> +<span class="p">}</span> +<span class="n">solver</span><span class="o">-></span><span class="n">endSimulation</span><span class="p">();</span> +</pre></div> +</div> +<p>The simulateChunk() calls can be called concurrently from multiple threads to increase performance.</p> +</div> +<div class="section" id="retrieving-simulation-data"> +<h3>Retrieving simulation data<a class="headerlink" href="#retrieving-simulation-data" title="Permalink to this headline">¶</a></h3> +<p>We need to retrieve the new positions of the cloth particles after the simulation step to display the results:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">MappedRange</span><span class="o"><</span><span class="n">physx</span><span class="o">::</span><span class="n">PxVec4</span><span class="o">></span> <span class="n">particles</span> <span class="o">=</span> <span class="n">mCloth</span><span class="o">-></span><span class="n">getCurrentParticles</span><span class="p">();</span> +<span class="k">for</span><span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span><span class="o"><</span><span class="n">particles</span><span class="p">.</span><span class="n">size</span><span class="p">();</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> +<span class="p">{</span> + <span class="c1">//do something with particles[i]</span> + <span class="c1">//the xyz components are the current positions</span> + <span class="c1">//the w component is the invMass.</span> +<span class="p">}</span> +<span class="c1">//destructor of particles should be called before mCloth is destroyed.</span> +</pre></div> +</div> +</div> +</div> +<div class="section" id="usage"> +<h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2> +<p>Cloth instances have many properties that can be influence their behavior. +This section shows how to use some of the most common properties.</p> +<div class="section" id="common-cloth-properties"> +<h3>Common cloth properties<a class="headerlink" href="#common-cloth-properties" title="Permalink to this headline">¶</a></h3> +<p>We can set the gravity acceleration vector in global space:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">cloth</span><span class="o">-></span><span class="n">setGravity</span><span class="p">(</span><span class="n">physx</span><span class="o">::</span><span class="n">PxVec3</span><span class="p">(</span><span class="mf">0.0f</span><span class="p">,</span> <span class="o">-</span><span class="mf">9.8f</span><span class="p">,</span> <span class="mf">0.0f</span><span class="p">));</span> +</pre></div> +</div> +<p>This vector doesn’t have to be the same as provided to the cooker.</p> +<p>Sometimes it is desirable to dampen the particle motion:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">cloth</span><span class="o">-></span><span class="n">setDamping</span><span class="p">(</span><span class="mf">0.5f</span><span class="p">);</span> <span class="c1">//0.0f is default</span> +</pre></div> +</div> +<p>Note that the effect of the damping varies between local and global space simulation, as it dampens the local space motion only (so everything is damped if global space simulation is used as local and global space are equal in that case). +To create effects like air drag or underwater motion it is better to use the wind / air drag properties instead.</p> +<p>We can change the accuracy (and stiffness) of the cloth by increasing the solver frequency. +The solver frequency is used to calculate how many solver iterations are executed per frame (Solver::begin/endSimulation call):</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">cloth</span><span class="o">-></span><span class="n">setSolverFrequency</span><span class="p">(</span><span class="mf">60.0f</span><span class="p">);</span> <span class="c1">//default is 300</span> +</pre></div> +</div> +<p>There will be at least 1 iteration executed per frame, regardless of the value set. +Sometimes lowering the solver frequency helps to avoid instabilities and oscillations, while a higher solver frequency can help to increase stiffness and improve other behavior like collision detection. +It is common to set this value to a multiple of the fps target for the application.</p> +</div> +<div class="section" id="tethers"> +<h3>Tethers<a class="headerlink" href="#tethers" title="Permalink to this headline">¶</a></h3> +<p>Tethers are generated at the cooking stage and stored in the fabric. +They improve behavior and reduce stretchiness by adding long range constraints between particles and fixed points.</p> +<p>We can change some properties of the tethers in the cloth instance. +We can change the length of all tethers by setting the scale:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">cloth</span><span class="o">-></span><span class="n">setTetherConstraintScale</span><span class="p">(</span><span class="mf">1.2f</span><span class="p">);</span> <span class="c1">//Increase the length by 20%</span> +</pre></div> +</div> +<p>We can make the tethers more spring like, or even disable them by changing the stiffness:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">cloth</span><span class="o">-></span><span class="n">setTetherConstraintStiffness</span><span class="p">(</span><span class="mf">0.0f</span><span class="p">);</span> <span class="c1">//Disable tethers</span> +<span class="n">cloth</span><span class="o">-></span><span class="n">setTetherConstraintStiffness</span><span class="p">(</span><span class="mf">0.5f</span><span class="p">);</span> <span class="c1">//Springy tethers</span> +<span class="n">cloth</span><span class="o">-></span><span class="n">setTetherConstraintStiffness</span><span class="p">(</span><span class="mf">1.0f</span><span class="p">);</span> <span class="c1">//Default value</span> +</pre></div> +</div> +<p>The whole tether stage is skipped if the stiffness is set to 0 (increasing performance).</p> +</div> +<div class="section" id="collision-detection"> +<h3>Collision detection<a class="headerlink" href="#collision-detection" title="Permalink to this headline">¶</a></h3> +<p>NvCloth provides a couple of different methods to add collision to the simulation. +All collision primitives are defined in local space.</p> +<p>We can define up to 32 collision spheres per cloth:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">physx</span><span class="o">::</span><span class="n">PxVec4</span> <span class="n">spheres</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span> + <span class="n">physx</span><span class="o">::</span><span class="n">PxVec4</span><span class="p">(</span><span class="mf">0.0f</span><span class="p">,</span> <span class="mf">0.0f</span><span class="p">,</span> <span class="mf">0.0f</span><span class="p">,</span> <span class="mf">1.0f</span><span class="p">),</span> + <span class="n">physx</span><span class="o">::</span><span class="n">PxVec4</span><span class="p">(</span><span class="mf">0.0f</span><span class="p">,</span> <span class="mf">5.0f</span><span class="p">,</span> <span class="mf">0.0f</span><span class="p">,</span> <span class="mf">1.0f</span><span class="p">)</span> +<span class="p">};</span> +<span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">Range</span><span class="o"><</span><span class="k">const</span> <span class="n">physx</span><span class="o">::</span><span class="n">PxVec4</span><span class="o">></span> <span class="n">sphereRange</span><span class="p">(</span><span class="n">spheres</span><span class="p">,</span> <span class="n">spheres</span> <span class="o">+</span> <span class="mi">2</span><span class="p">);</span> +<span class="n">cloth</span><span class="o">-></span><span class="n">setSpheres</span><span class="p">(</span><span class="n">sphereRange</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">cloth</span><span class="o">-></span><span class="n">getNumSpheres</span><span class="p">());</span> +</pre></div> +</div> +<p>The last two arguments define which range of spheres defined previously is replaced (the parameters work the same across all Cloth::set’CollisionShape’ functions). +This can be useful if only a couple of collision primitives changed since previous frame. +Here we use the range [0, cloth->getNumSpheres()[ to ensure we replace all spheres that might have been defined previously. +To insert the spheres at the beginning we could use [0, 0[ and to insert at the end we use [cloth->getNumSpheres(), cloth->getNumSpheres()[.</p> +<p>We can connect spheres to create capsules:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">uint32_t</span> <span class="n">capsuleIndices</span><span class="p">[</span><span class="mi">2</span><span class="p">];</span> +<span class="n">capsuleIndices</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +<span class="n">capsuleIndices</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span> + +<span class="n">cloth</span><span class="o">-></span><span class="n">setCapsules</span><span class="p">(</span><span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">Range</span><span class="o"><</span><span class="n">uint32_t</span><span class="o">></span><span class="p">(</span><span class="n">capsuleIndices</span><span class="p">,</span> <span class="n">capsuleIndices</span> <span class="o">+</span> <span class="mi">2</span><span class="p">),</span> <span class="mi">0</span><span class="p">,</span> <span class="n">cloth</span><span class="o">-></span><span class="n">getNumCapsules</span><span class="p">());</span> +</pre></div> +</div> +<p>This connects sphere 0 and 1. +Indices always need to be provided in pairs. +Also note that the last two arguments specify indices of pairs. So cloth->getNumCapsules() will return 1 after the above snippet is executed.</p> +<p>We can also define up to 32 collision planes:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">physx</span><span class="o">::</span><span class="n">PxVec4</span> <span class="n">planes</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span> + <span class="n">physx</span><span class="o">::</span><span class="n">PxVec4</span><span class="p">(</span><span class="n">physx</span><span class="o">::</span><span class="n">PxVec3</span><span class="p">(</span><span class="mf">0.5f</span><span class="p">,</span> <span class="mf">0.4f</span><span class="p">,</span> <span class="mf">0.0f</span><span class="p">).</span><span class="n">getNormalized</span><span class="p">(),</span> <span class="mf">3.0f</span><span class="p">),</span> + <span class="n">physx</span><span class="o">::</span><span class="n">PxVec4</span><span class="p">(</span><span class="n">physx</span><span class="o">::</span><span class="n">PxVec3</span><span class="p">(</span><span class="mf">0.0f</span><span class="p">,</span> <span class="mf">0.4f</span><span class="p">,</span> <span class="mf">0.5f</span><span class="p">).</span><span class="n">getNormalized</span><span class="p">(),</span> <span class="mf">3.0f</span><span class="p">)</span> +<span class="p">};</span> + +<span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">Range</span><span class="o"><</span><span class="k">const</span> <span class="n">physx</span><span class="o">::</span><span class="n">PxVec4</span><span class="o">></span> <span class="n">planesR</span><span class="p">(</span><span class="n">planes</span><span class="p">,</span> <span class="n">planes</span> <span class="o">+</span> <span class="mi">2</span><span class="p">);</span> +<span class="n">cloth</span><span class="o">-></span><span class="n">setPlanes</span><span class="p">(</span><span class="n">planesR</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">cloth</span><span class="o">-></span><span class="n">getNumPlanes</span><span class="p">());</span> +</pre></div> +</div> +<p>This on its own will not make the cloth collide with anything as we first need to tell the solver that each plane is one convex shape:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">uint32_t</span> <span class="n">indices</span><span class="p">[</span><span class="mi">2</span><span class="p">];</span> +<span class="k">for</span><span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="mi">2</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> + <span class="n">indices</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="n">i</span><span class="p">;</span> +<span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">Range</span><span class="o"><</span><span class="n">uint32_t</span><span class="o">></span> <span class="n">indiceR</span><span class="p">(</span><span class="n">indices</span><span class="p">,</span> <span class="n">indices</span> <span class="o">+</span> <span class="mi">2</span><span class="p">);</span> +<span class="n">mCloth</span><span class="o">-></span><span class="n">setConvexes</span><span class="p">(</span><span class="n">indiceR</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">mCloth</span><span class="o">-></span><span class="n">getNumConvexes</span><span class="p">());</span> +</pre></div> +</div> +<p>The value stored in the indices array is a bit mask telling the solver which planes are part of the convex shape. Plane i is indicated by bit 1<<i. +We can easily construct convex shapes consisting of more planes by setting more bits (e.g. (1<<i) | (1<<j)).</p> +<p>We can also use arbitrary triangle meshes for collision:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">physx</span><span class="o">::</span><span class="n">PxVec3</span><span class="o">*</span> <span class="n">triangles</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">//Get triangle data from somewhere</span> + <span class="c1">//We can't use indexed meshes/vertex sharing,</span> + <span class="c1">// each triangle is defined with its own 3 vertexes</span> +<span class="n">nv</span><span class="o">::</span><span class="n">cloth</span><span class="o">::</span><span class="n">Range</span><span class="o"><</span><span class="k">const</span> <span class="n">physx</span><span class="o">::</span><span class="n">PxVec3</span><span class="o">></span> <span class="n">triangleR</span><span class="p">(</span><span class="o">&</span><span class="n">triangles</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="o">&</span><span class="n">triangles</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">+</span> <span class="n">triangleCount</span> <span class="o">*</span> <span class="mi">3</span><span class="p">);</span> +<span class="n">cloth</span><span class="o">-></span><span class="n">setTriangles</span><span class="p">(</span><span class="n">triangleR</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">cloth</span><span class="o">></span><span class="n">getNumTriangles</span><span class="p">());</span> +</pre></div> +</div> +<p>Note that the range arguments passed to setTriangles are counting whole triangles (3 PxVec3 vertexes each).</p> +<p>We can set the friction coefficient used for collision between cloth and collision shapes like this:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">cloth</span><span class="o">-></span><span class="n">setFriction</span><span class="p">(</span><span class="mf">0.5</span><span class="p">);</span> +</pre></div> +</div> +</div> +<div class="section" id="local-space-simulation"> +<h3>Local space simulation<a class="headerlink" href="#local-space-simulation" title="Permalink to this headline">¶</a></h3> +<p>Using local space simulation gives you more control over the simulation allowing you to improve the stability and response of the simulation. +We separate the global/render coordinate system from the particle simulation coordinate system in order to use local space simulation. +Graphics transforms should be adjusted to render the cloth in the correct location again.</p> +<p>We can use the following methods to let the simulation know that the cloth coordinate system has moved relative to the global coordinates:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">cloth</span><span class="o">-></span><span class="n">setTranslation</span><span class="p">(</span><span class="n">physx</span><span class="o">::</span><span class="n">PxVec3</span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="n">y</span><span class="p">,</span><span class="n">z</span><span class="p">));</span> +<span class="n">cloth</span><span class="o">-></span><span class="n">setRotation</span><span class="p">(</span><span class="n">physx</span><span class="o">::</span><span class="n">PxQuat</span><span class="p">(</span><span class="n">qx</span><span class="p">,</span><span class="n">qy</span><span class="p">,</span><span class="n">qz</span><span class="p">,</span><span class="n">qw</span><span class="p">));</span> +</pre></div> +</div> +<p>This will not change the particle positions, but will apply impulses so that the cloth reacts properly to the movement of the coordinate system. +Air drag and lift also reacts accordingly.</p> +<p>We can use an inertia multiplier to control the strength of these impulses. +Fast movements can cause problems like tunneling through collision shapes, self-intersection, instabilities and stretchy cloth. +Use smaller inertia multipliers if these issues are noticeable. +We can set these multipliers as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">//All values should be between 0.0 and 1.0</span> +<span class="n">cloth</span><span class="o">-></span><span class="n">setLinearInertia</span><span class="p">(</span><span class="n">physx</span><span class="o">::</span><span class="n">PxVec3</span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="n">y</span><span class="p">,</span><span class="n">z</span><span class="p">));</span> +<span class="n">cloth</span><span class="o">-></span><span class="n">setAngularInertia</span><span class="p">(</span><span class="n">physx</span><span class="o">::</span><span class="n">PxVec3</span><span class="p">(</span><span class="n">ax</span><span class="p">,</span><span class="n">ay</span><span class="p">,</span><span class="n">az</span><span class="p">));</span> +<span class="n">cloth</span><span class="o">-></span><span class="n">setCentrifugalInertia</span><span class="p">(</span><span class="n">physx</span><span class="o">::</span><span class="n">PxVec3</span><span class="p">(</span><span class="n">cx</span><span class="p">,</span><span class="n">cy</span><span class="p">,</span><span class="n">cz</span><span class="p">));</span> +</pre></div> +</div> +<p>If we want to move the cloth without applying any forces (in case of a world origin shift for example) we can teleport:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">cloth</span><span class="o">-></span><span class="n">teleport</span><span class="p">(</span><span class="n">physx</span><span class="o">::</span><span class="n">PxVec3</span><span class="p">(</span><span class="n">deltaX</span><span class="p">,</span> <span class="n">deltaY</span><span class="p">,</span> <span class="n">deltaZ</span><span class="p">));</span> +</pre></div> +</div> +<p>Or we can reset the inertia effects after using the setTranslation/setPosition functions:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">//Clear any pending inertia</span> +<span class="n">cloth</span><span class="o">-></span><span class="n">clearInertia</span><span class="p">();</span> +</pre></div> +</div> +</div> +<div class="section" id="drag-lift-and-wind"> +<h3>Drag lift and wind<a class="headerlink" href="#drag-lift-and-wind" title="Permalink to this headline">¶</a></h3> +<p>Cloth is simulated in a vacuum by default. +We can set the drag and lift coefficients to make the simulation more natural:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">cloth</span><span class="o">-></span><span class="n">setDragCoefficient</span><span class="p">(</span><span class="mf">0.5f</span><span class="p">);</span> +<span class="n">cloth</span><span class="o">-></span><span class="n">setLiftCoefficient</span><span class="p">(</span><span class="mf">0.6f</span><span class="p">);</span> +</pre></div> +</div> +<p>We can also add wind to the simulation:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">cloth</span><span class="o">-></span><span class="n">setWindVelocity</span><span class="p">(</span><span class="n">physx</span><span class="o">::</span><span class="n">PxVec3</span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="n">y</span><span class="p">,</span><span class="n">z</span><span class="p">));</span> +</pre></div> +</div> +<p>It is a good idea to vary this parameter continuously to simulate gusts, making the simulation more lively.</p> +</div> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../NvCloth.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Users guide</a><ul> +<li><a class="reference internal" href="#setup">Setup</a><ul> +<li><a class="reference internal" href="#initializing-the-library">Initializing the Library</a></li> +<li><a class="reference internal" href="#factory">Factory</a></li> +<li><a class="reference internal" href="#fabric-cloth">Fabric & Cloth</a><ul> +<li><a class="reference internal" href="#fabric">Fabric</a></li> +<li><a class="reference internal" href="#cloth">Cloth</a></li> +</ul> +</li> +<li><a class="reference internal" href="#solver">Solver</a></li> +<li><a class="reference internal" href="#retrieving-simulation-data">Retrieving simulation data</a></li> +</ul> +</li> +<li><a class="reference internal" href="#usage">Usage</a><ul> +<li><a class="reference internal" href="#common-cloth-properties">Common cloth properties</a></li> +<li><a class="reference internal" href="#tethers">Tethers</a></li> +<li><a class="reference internal" href="#collision-detection">Collision detection</a></li> +<li><a class="reference internal" href="#local-space-simulation">Local space simulation</a></li> +<li><a class="reference internal" href="#drag-lift-and-wind">Drag lift and wind</a></li> +</ul> +</li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="../Modules/Index.html" + title="previous chapter">Modules</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="../CopyRight/Index.html" + title="next chapter">NVIDIA Copyright Notice</a></p> +<div id="searchbox" style="display: none"> + <h3>Quick search</h3> + <form class="search" action="../search.html" method="get"> + <input type="text" name="q" size="18" /> + <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + <p class="searchtip" style="font-size: 90%"> + Enter search terms or a module, class or function name. + </p> +</div> +<script type="text/javascript">$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../CopyRight/Index.html" title="NVIDIA Copyright Notice" + >next</a></li> + <li class="right" > + <a href="../Modules/Index.html" title="Modules" + >previous</a> |</li> + <li><a href="../NvCloth.html">NVIDIA NvCloth Documentation</a> »</li> + </ul> + </div> + + <script type="text/javascript"> + $(document).ready(function() { + $(".toggle > *").hide(); + $(".toggle .header").show(); + $(".toggle .header").click(function() { + $(this).parent().children().not(".header").toggle(400); + $(this).parent().children(".header").toggleClass("open"); + }) + }); +</script> + + +<script type="text/x-mathjax-config"> + MathJax.Hub.Config({ + extensions: ["tex2jax.js"], + jax: ["input/TeX", "output/HTML-CSS"], + tex2jax: { + processEscapes: true, + skipTags: ["script","noscript","style","textarea"] + }, + "HTML-CSS": { availableFonts: ["TeX"] }, + TeX: { + Macros: { + Lrg: ['\\displaystyle{#1}', 1, ""] + } + } + }); +</script> + + +<script type="text/javascript" async + src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML"> +</script> + + + </body> +</html>
\ No newline at end of file |